2.2 Structured error responses for MCP tools
MCP signals a tool failure with the isError flag (Model Context Protocol). The payload is where the value is.
Error taxonomy
| Category | Examples | Agent should |
|---|---|---|
| Transient | Timeout, service unavailable, 503 | Retry, possibly with exponential backoff |
| Validation | Malformed order ID, missing field | Correct the input and retry |
| Business | Policy violation, refund over limit, ineligible return | Stop retrying; explain to the customer |
| Permission | Not authorised for this record | Stop retrying; escalate |
Structured error metadata
{
"isError": true,
"errorCategory": "business",
"isRetryable": false,
"retriable": false,
"message": "Refunds above $500 require human approval.",
"customerFacing": "I can't process this refund amount myself — I'll bring in a colleague who can approve it.",
"attempted": { "tool": "process_refund", "amount": 649.0 }
}
Return errorCategory (transient / validation / permission / business), an isRetryable boolean, and a human-readable description. For business rule violations add retriable: false plus a customer-friendly explanation so the agent can communicate appropriately rather than looping.
A generic "Operation failed" prevents the agent from making an appropriate recovery decision. It cannot tell a 2-second blip from a policy refusal, so it either retries a permanent failure or gives up on a transient one. Retryable vs non-retryable metadata prevents wasted retry attempts.
Local recovery before propagation
Subagents should recover locally from transient failures and propagate to the coordinator only errors they cannot resolve — carrying partial results and what was attempted. See Domain 5.3.
Access failure ≠ empty result
| Meaning | Agent response | |
|---|---|---|
| Access failure | The query could not run (timeout, auth, outage) | Needs a retry decision |
| Valid empty result | The query ran and matched nothing | A fact — report it, do not retry |
Collapsing these into one response is a frequent distractor and a real-world bug.
Quiz
- Question 1
process_refund fails in four distinguishable ways: the payment processor times out, the request omits a required field, the order falls outside the 30-day return window, and the service credential lacks refund scope. All four currently return {"isError": true, "message": "Operation failed"}. The agent retries all four identically and tells the customer to try again later. Which redesign most directly restores correct agent behaviour?
- Question 2
lookup_order returns {"orders": []} in two different situations: the customer genuinely has no orders in the requested window, and the order index is unreachable so the query never ran. The agent tells customers "you have no orders in that period" in both cases. What is the correct fix?
- Question 3
get_customer fails two ways: a three-second gateway timeout under peak load, and a permanent "customer not found". Both return isError with a human-readable message. The agent retries "not found" up to five times, adding about 15 seconds to conversations that were always going to need a different approach. What is the minimum change?
- Question 4
A refund is refused because the order falls outside the return window. The tool returns {"isError": true, "errorCategory": "business", "message": "POLICY_VIOLATION: rule RET-30 evaluated false"}. The agent relays that string to customers verbatim. What should the response carry?
Links
- https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls
- https://platform.claude.com/docs/en/agents-and-tools/tool-use/troubleshooting-tool-use
- https://code.claude.com/docs/en/mcp
- https://en.wikipedia.org/wiki/Model_Context_Protocol
- https://en.wikipedia.org/wiki/Exponential_backoff