# Structured error responses for MCP tools

*Claude Certified Architect - Foundations Study Guide · Tool Design & MCP Integration · Last updated October 22, 2026 · https://www.certifyforce.com/study-guide/claude-certified-architect-foundations/tool-design-and-mcp-integration/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.

- Certification: Claude Certified Architect - Foundations
- Exam section: Tool Design & MCP Integration
- Study guide: https://www.certifyforce.com/study-guide/claude-certified-architect-foundations

**Official exam objective:**

> Implement structured error responses for MCP tools

## What the exam expects

- Return a tool failure as a result flagged `isError: true` (MCP) or `is_error: true` (Messages API `tool_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`, `isRetryable` and 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

| Fact | Detail | Source |
|---|---|---|
| Protocol errors | Unknown tool, malformed request, server errors; JSON-RPC error such as `-32602` | [MCP tools spec](https://modelcontextprotocol.io/specification/2026-07-28/server/tools) |
| Tool execution errors | API failures, input validation, business logic; result with `isError: true` | [MCP tools spec](https://modelcontextprotocol.io/specification/2026-07-28/server/tools) |
| What clients pass to the model | SHOULD pass tool execution errors; MAY pass protocol errors | [MCP tools spec](https://modelcontextprotocol.io/specification/2026-07-28/server/tools) |
| Messages API flag | `tool_result` with `is_error: true` and the error text in `content` | [Handle tool calls](https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls) |
| Invalid or missing parameters | Claude retries 2-3 times with corrections before apologizing | [Handle tool calls](https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls) |
| SDK uncaught handler exception | Becomes an error result with the raw message; the loop continues | [Custom tools](https://code.claude.com/docs/en/agent-sdk/custom-tools) |
| Expired or unknown handle | Tool execution error that says so; state retention in the creation tool's description | [MCP tools spec](https://modelcontextprotocol.io/specification/2026-07-28/server/tools) |
| Structured error fields | `errorCategory`, `isRetryable`, human-readable description (exam-guide guidance) | [Exam guide](https://everpath-course-content.s3-accelerate.amazonaws.com/instructor%2F6nizmqk8tpzpfjvt6qmmav7rh%2Fpublic%2F1783542750%2FClaude+Certified+Architect+%E2%80%93+Foundations+Exam+Guide.pdf) |
| Server input validation | Servers MUST validate all tool inputs | [MCP tools spec](https://modelcontextprotocol.io/specification/2026-07-28/server/tools) |

## Check yourself

- 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?

## Sources

- [Tools (MCP specification 2026-07-28)](https://modelcontextprotocol.io/specification/2026-07-28/server/tools)
- [Handle tool calls](https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls)
- [Give Claude custom tools](https://code.claude.com/docs/en/agent-sdk/custom-tools)
- [Writing effective tools for AI agents](https://www.anthropic.com/research/writing-tools-for-agents)
- [Tutorial: Build a tool-using agent](https://platform.claude.com/docs/en/agents-and-tools/tool-use/build-a-tool-using-agent)
- [How we built our multi-agent research system](https://www.anthropic.com/research/multi-agent-research-system)
- [Claude Certified Architect – Foundations Exam Guide v1.0](https://everpath-course-content.s3-accelerate.amazonaws.com/instructor%2F6nizmqk8tpzpfjvt6qmmav7rh%2Fpublic%2F1783542750%2FClaude+Certified+Architect+%E2%80%93+Foundations+Exam+Guide.pdf)

## About the full unit

The "Core concepts", "Exam traps" and "Worked scenario" sections of this unit, its 12 linked practice questions, and unlimited timed mock exams are included with the Claude Certified Architect - Foundations pack (USD $19): https://www.certifyforce.com/practice-exams