Amey-Thakur MCP error handling
An agent's recovery is only as good as the error it receives. A generic failure produces a blind retry loop; a specific, actionable error produces a corrected call. Error text here is an interface, not a log line.
Method
- Say what went wrong and what would fix it. Missing required parameter start_date beats invalid input, because the agent can act on the first and only guess at the second.
- Distinguish retryable from permanent. Rate limits and timeouts invite a retry; validation failures and permission denials never should, and an agent cannot tell without being told.
- Return validation errors per field. Which parameter, what was wrong, what is acceptable, so the retry is corrected rather than repeated (see mcp-tool-design).
- Never leak internals. Stack traces, queries, and infrastructure detail enter the model's context and possibly its output (see error-messages).
- Include retry timing when known. A rate limit that states when to retry prevents both hammering and unnecessary abandonment.
- Fail fast on unrecoverable conditions. An agent looping on a permanently failing call burns budget and context, so the error must close the loop.
- Keep errors stable and documented. Agents and prompts come to depend on error shapes, so changing them silently breaks integrations.
Boundaries
Good errors improve recovery; they cannot fix a tool that fails for the wrong reasons. Error text is model-visible, so it must be safe to disclose. Retry policy belongs with the caller, and the server's job is to give it enough to decide (see timeouts-and-retries).