2.2 Implement structured error responses for MCP tools

Key points

1. 1

   MCP has two error channels. Protocol errors are JSON-RPC errors for unknown tools or malformed requests. Tool execution errors (API failures, invalid data, business-logic refusals) go inside the tool result with isError: true so the model can see and reason about them. On the Claude API the equivalent is is_error: true on the tool_result block.

2. 2

   Four error categories the exam uses: transient (timeouts, 503, rate limits), validation (invalid input format), business (policy violations such as an expired refund window) and permission (missing scope or credentials).

3. 3

   Return structured metadata: an errorCategory, an isRetryable boolean and a human-readable description. Uniform errors ("Operation failed") prevent the agent from choosing a recovery and typically cause wasted identical retries.

4. 4

   Only transient errors are retryable with the same input. Validation errors need a corrected input; permission and business errors need escalation or explanation. Mark business violations retriable: false and include a customer-friendly explanation ("refunds are available within 30 days of delivery; this order was delivered 45 days ago") so the agent can communicate the policy and alternatives.

5. 5

   If you cannot change the agent's prompt, the error contract is your lever: a technical message for the agent plus a separate customerMessage that is safe to relay stops raw exceptions and stack traces reaching customers.

6. 6

   Distinguish an access failure from a valid empty result. A successful query with no matches should be a normal result that says so ({"orders": [], "matched": 0}); a 403 or timeout must be isError: true with a category and retryability. Collapsing both into [] makes the agent tell customers they have no orders during an outage.

7. 7

   Inside subagents, recover transient failures locally with bounded backoff. Propagate to the coordinator only errors that cannot be resolved locally, and include the failure type, what was attempted and any partial results so the coordinator can pick an alternative or proceed with known gaps.

8. 8

   Anti-patterns the exam uses as distractors: returning success with empty content to keep the pipeline moving, throwing so the server crashes, retrying permission errors with backoff, retrying every error inside the server and then returning a generic failure, terminating the whole job on one subagent error, and mapping errors to bare HTTP codes.

9. 9

   Write instructive error text that says what went wrong and what to try next ("Rate limit exceeded. Retry after 60 seconds."). Error messages are part of the tool interface and steer the model toward correct usage.

Read the source

• MCP specification — Tools (error handling)
• Handle tool calls (is_error)
• How we built our multi-agent research system