The Agent Reads the Error
When an MCP server tool call fails, the error message becomes part of the agent's context. The agent reads the error and decides what to do next. Should it retry? Try a different approach? Ask the user for help? The decision depends entirely on what the error message tells it.
An error message that says "Error: ECONNREFUSED" tells the agent that a connection was refused, but not why or what to do about it. An error message that says "Error: Cannot connect to PostgreSQL at localhost:5432. The database server may not be running, or the port may be incorrect. Check that PostgreSQL is started and the connection settings match your database configuration." gives the agent enough information to explain the problem to the user and suggest specific fixes.
Good Errors Enable Recovery
The best error messages for AI-consumed tools follow a pattern: what happened, why it might have happened, and what could fix it. "Query returned 0 rows. The table 'users' exists but may be empty, or the WHERE clause 'created_at > 2026-12-01' may not match any records. Try broadening the date range or checking the table contents." This gives the agent enough context to try a modified query without asking the user.
Error categorization also helps. If the error indicates a permission issue, the agent knows retrying won't help. If it indicates a temporary network issue, retrying might succeed. If it indicates invalid parameters, the agent can try different parameters. Clear categorization enables smarter recovery strategies.
Bad Errors Cause Loops
Vague error messages like "Internal server error" or "Something went wrong" give the agent no information to work with. It might retry the same failing call (wasting tokens), try a slightly different approach that fails for the same reason, or give up entirely when a simple parameter adjustment would have fixed the problem.
The worst pattern is when errors are swallowed entirely, returning no indication that something went wrong. The agent receives an empty or partial result and proceeds as if it's correct. This leads to cascading errors downstream.
For MCP Server Builders
If you're building an MCP server, invest in error messages. Every error path should return a message that would help a language model understand the problem and suggest a fix. Think of your errors as instructions for a junior developer who doesn't have access to your logs or your database. What would they need to know to diagnose and fix the issue?
Include the relevant context in the error: what operation was attempted, what parameters were used, what the expected behavior was, and what actually happened. This context costs a few extra lines of code but dramatically improves how agents interact with your server.
Related Reading
- How to Debug an AI Agent That Keeps Making Mistakes
- Why MCP Server Quality Varies So Much (And How to Evaluate)
- How AI Agents Decide When to Ask for Human Help
Browse MCP servers on Skillful.sh. Search 137,000+ AI tools.