Structured error responses for MCP tools
How tools report failure so an agent can recover: MCP isError results versus JSON-RPC protocol errors, is_error in the Messages API and the Agent SDK, error categories with isRetryable and a readable message, business-rule refusals, expired handles, and why a failed query must never come back as an empty result.
Implement structured error responses for MCP tools
~8 min read · 12 practice questions ·
What the exam expects
- Return a tool failure as a result flagged
isError: true(MCP) oris_error: true(Messages APItool_result) so the agent loop keeps running and Claude can react, and tell it apart from a JSON-RPC protocol error. - Classify failures as transient, validation, business or permission, and return
errorCategory,isRetryableand a human-readable message. - Explain why a uniform "Operation failed" wastes retries, and give business-rule violations a non-retryable flag plus a customer-safe explanation.
- Distinguish an access failure from a valid empty result at the tool contract.
- Report expired or unknown handles as actionable errors, and know what the Agent SDK does with an uncaught handler exception.
Key terms: tool execution error (a failure reported inside the tool result with isError: true); protocol error (a JSON-RPC error about the request itself); errorCategory (transient, validation, business or permission); isRetryable (whether repeating the same request could succeed); valid empty result (a query that ran and matched nothing).
Key facts
- Detail
- Unknown tool, malformed request, server errors; JSON-RPC error such as
-32602
- Detail
- API failures, input validation, business logic; result with
isError: true
- Detail
- SHOULD pass tool execution errors; MAY pass protocol errors
- Detail
tool_resultwithis_error: trueand the error text incontent
- Detail
- Claude retries 2-3 times with corrections before apologizing
- Detail
- Becomes an error result with the raw message; the loop continues
- Detail
- Tool execution error that says so; state retention in the creation tool's description
- Detail
errorCategory,isRetryable, human-readable description (exam-guide guidance)
- Detail
- Servers MUST validate all tool inputs
- Why should a validation failure be a tool execution error rather than a JSON-RPC error?
- What happens when an Agent SDK tool handler throws an uncaught exception?
- When is returning an empty list correct?
- Why does an expired handle need its own error message?
The questions are free to read. Answers with their sources and self-grading are included with the pack.
Keep reading with the Claude Certified Architect - Foundations pack
- Core concepts
- Exam traps
- Worked scenario
The pack includes:
- All 30 lessons of the Claude Certified Architect - Foundations guide, with reading progress
- Interactive decision walks and step-by-step sequence steppers
- Inline practice questions and one-click topic practice (12 questions for this lesson)
- An official source cited for every claim
- An AI tutor that answers from the guide
- Unlimited timed practice exams
Practice for the Claude Certified Architect - Foundations exam
Certifyforce is an independent study resource and is not affiliated with, endorsed by or sponsored by Anthropic. Claude is a trademark of Anthropic.