Implement structured error responses for MCP tools
What you should be able to do
- Signal failure with the MCP isError flag rather than a success payload that reads as data.
- Separate transient, validation, business and permission errors, and return the category as metadata.
- Carry retryability in the result payload — your own convention, not an MCP protocol field — so the agent stops retrying what will never succeed.
- Recover transient failures locally inside a subagent and propagate only what cannot be resolved, with partial results.
- Tell an access failure apart from a valid empty result.
Exam traps (5)
Return a single clear message like "Operation failed" for every error path.
One string cannot distinguish a timeout worth retrying from a policy refusal that never will, so the agent applies one strategy to four different situations.
Error handling is a decision the agent makes. Give it the fields — category, retryability, explanation — that the decision needs.
Retry any failure a few times with backoff — it costs little and often works.
Validation and business errors are deterministic: the retries burn latency and budget to arrive at the same refusal, and the customer waits through all of it.
Retry only what is marked retryable. The tool is what knows.
Treat an empty result set as a failure so the agent knows to look elsewhere.
A successful query with no matches is a fact about the world. Reporting it as an error triggers retries and escalation over an answer that was already correct.
Empty is a result. Only a failure to execute is an error.
Propagate every subagent error to the coordinator so nothing is hidden.
The coordinator ends up handling transient blips it has no better information about, and the run fails on something a local retry would have cleared.
Recover locally where you can; escalate what you cannot, with partial results and what was already attempted.
Return the raw exception text so the agent has full detail.
Stack traces and connection strings reach the model and often the customer, while the fields that would drive a decision are still missing.
Structured metadata for the agent, a human-readable explanation for the person — never the raw internals.
Primary sources
- MCP — toolschecked 2026-08-15
- MCP — server conceptschecked 2026-08-15
Know cold
- isError / isRetryable
- Error taxonomy
- Retry
- Exponential backoff
- Graceful degradation / fallback
14 practice questions in the bank are tagged to this task statement.
Practise this task in context: open it inside the interactive study guide, which carries the concept cards, the mock quiz and the practice simulation.