Structured error responses for MCP tools
What this covers
- Return errors the agent can act on rather than a uniform failure
- Separate transient, validation, business, and permission errors
- Distinguish an access failure from a valid empty result
- Treat
isErroras the MCP-standard flag anderrorCategoryandisRetryableas conventions you define and document - Include a customer-friendly explanation with a business rule violation, because that text reaches a person
- Recover transient failures locally and propagate only what could not be resolved, with partial results
process plate / 2.2
Choose recovery from the result
Turn the category dial. A structured tool result sends the caller toward retry, corrected input, explanation, escalation, or ordinary success.
process reading / transient
Retry only if safe and within budget.
A temporary failure may recover locally; do not turn one failed attempt into a coordinator-wide failure immediately.
Read the complete diagram as text
- First distinguish a failed call from a successful call that found nothing.
- For failures, expose a documented category and whether the caller may retry.
- Retry transient failures locally, correct validation input, explain business rules, and escalate permission failures.
- Propagate unresolved failures with partial results and a record of what was attempted.
Key terms
- Retry
- Trying a failed operation again under defined limits.
Uniform errors make recovery harder
"Operation failed" tells the agent that something went wrong and nothing about what to do next. Retry? Ask the user for different input? Apologize and escalate? Every one of those is plausible, so the agent guesses.
A delivery notice reading only "delivery unsuccessful" leaves you guessing: wait for tomorrow's attempt, correct the address, or stop waiting entirely. The reason is what decides, and each of those next steps is wrong for the other two situations.
The Model Context Protocol (MCP) isError flag communicates that a call failed. Structured metadata explains what kind of failure occurred. Fields such as errorCategory and isRetryable are a useful application convention, not standardized MCP field names; define and document their schema for your tools.
Four categories worth separating
- Transient — timeouts, service unavailable. Worth retrying.
- Validation — the input was wrong. Retrying the same call is pointless; change the input.
- Business — a policy was violated. Not an error to fix, a rule to communicate.
- Permission — the caller may not do this. Retrying won't grant access.
If every error has the same format, the agent cannot tell which failures should be retried and which require a different response.
The fields that matter
Return errorCategory, an isRetryable boolean, and a human-readable description. The boolean is what prevents wasted retry attempts — the agent does not have to infer retryability from prose.
For business rule violations, mark them not retryable and include a customer-friendly explanation, because that text often ends up in front of a person. "Refunds are not available more than 90 days after delivery" tells the customer what happened; "Operation failed" does not.
Of the four fields below, only isError is standard MCP. The other three are this application's own convention, named and documented alongside the tools that return them:
{
"isError": true,
"errorCategory": "business",
"isRetryable": false,
"message": "Refunds are not available more than 90 days after delivery."
}The agent reads isRetryable and stops retrying. The person reads message. One result serves both, which is why the human-readable text isn't optional.
Recover locally, propagate selectively
A subagent should handle transient failures itself. Send unresolved failures to the coordinator with partial results and a record of what was attempted. The coordinator can then choose the next step without starting over.
Empty is not an error
A query that ran correctly and matched nothing is a success. Reporting it as a failure sends the agent into recovery behavior for a result that is simply the answer. Keep "I could not reach the data" and "there is no such data" firmly apart.
isErrorerrorCategoryisRetryablepartial results
Field note — common misconceptions
- MythThat an error message is enough if it is human-readable
- ActuallyAn
isRetryableboolean spares the agent inferring retryability from prose that varies. - MythThat an empty result is a kind of failure
- ActuallyA query that ran and matched nothing is a success;
isErroris for data you could not reach. - MythThat every failure should propagate to the coordinator
- ActuallyA subagent retries transient failures itself and propagates what it could not resolve locally.
Guided review
Review this lesson as a study deck
Review the lesson's main ideas in five guided slides, then test yourself with three flashcards.
Open Task 2.2 study deckCross-domain reasoning
Connect this idea
Reliability connects the whole workflow
A reliable workflow must know when to stop, enforce required steps, return useful errors, validate results, and keep failures visible across agent handoffs.
Applied practice
Practice this lesson in a lab
Use a related lab to create a decision, implementation or diagram, evidence record, and review.
- Lab 1 · Manual tool-use loop
Build the application-controlled loop behind a small note assistant, then make every stop state visible.
- Lab 5 · Design and test an MCP server
Design narrow MCP capabilities for a synthetic note catalog and test every trust boundary.