Structured error responses for MCP tools
Implement structured error responses for MCP tools.
This subtopic (2.2) sits in Tool Design & MCP Integration (D2) on Anthropic's Claude Certified Architect — Foundations (CCA-F) exam. The bank holds 23 practice questions here — 6 easy, 12 medium, and 5 hard — with 5 free to try, answers and explanations included. 3 of the free questions are below; the rest are in the practice stream.
What the exam tests here
- retryable vs non-retryable errors — structured metadata prevents wasted retries
- MCP isError flag pattern for communicating tool failures
- distinguishing access failures from valid empty results
- error categories — transient, validation, business, permission
Free practice questions: Structured error responses for MCP tools
A customer asks about a recent order. The agent calls lookup_order with the customer ID, but the underlying database query times out before returning. Your MCP tool currently returns an empty array in this case, and the agent tells the customer they have no recent orders. How should lookup_order signal this condition?
Show answer & explanation
Correct answer: C. Return a structured error with a retryable failure code distinct from the empty-result response shape.
MCP tools must distinguish access failures from valid empty results using structurally different responses, so the model never confuses 'no orders exist' with 'lookup failed'. The warning-field approach still overloads the empty-array shape. Raising an exception bypasses the agent's judgment and forces escalation when a retry might resolve it. Null with prompt-based interpretation relies on probabilistic compliance for a deterministic data-integrity concern.
Your process_refund MCP tool encounters a database timeout mid-execution. The tool returns a response to the agent. What is the correct way to signal this failure using the MCP isError pattern?
Show answer & explanation
Correct answer: A. Return a result object with isError set to true and the error details in the content field
MCP's isError flag pattern requires setting isError: true on the tool result object, with error details in content — this lets the agent reason about the failure explicitly. 'Throw an exception' bypasses structured error flow and may crash the tool loop. 'Return a successful result with an error_code' hides the failure from the agent's error-handling logic. 'Omit the isError field' means the agent treats the response as success.
The get_customer MCP tool returns a result with isError set to true. The support agent continues processing without detecting the failure and calls lookup_order using a null customer ID. What architectural change would prevent this downstream error?
Show answer & explanation
Correct answer: B. Have the agent inspect isError in the tool result before using the content in any subsequent call.
The MCP isError flag signals tool failure; the agent must check it before acting on the result. Checking isError before passing content to lookup_order prevents the null ID from propagating. 'Set isError to false' hides the failure rather than surfacing it. 'PostToolUse hook for auto-retry' handles transient failures but not missing customer IDs. 'Block lookup_order in system prompt' is probabilistic and does not detect the specific isError condition.
2 more free questions on this subtopic in the practice stream, plus 18 in the full bank. Keep practicing →