Structured Error Responses

Official Exam Guide Objectives

Task 2.2: Implement structured error responses for MCP tools.

Knowledge of

• The MCP isError flag pattern for communicating tool failures back to the agent
• The distinction between transient errors (timeouts, service unavailability), validation errors (invalid input), business errors (policy violations), and permission errors
• Why uniform error responses (generic "Operation failed") prevent the agent from making appropriate recovery decisions
• The difference between retryable and non-retryable errors, and how returning structured metadata prevents wasted retry attempts

Skills in

• Returning structured error metadata including errorCategory (transient/validation/permission), isRetryable boolean, and human-readable descriptions
• Including retriable: false flags and customer-friendly explanations for business rule violations so the agent can communicate appropriately
• Implementing local error recovery within subagents for transient failures, propagating to the coordinator only errors that cannot be resolved locally along with partial results and what was attempted
• Distinguishing between access failures (needing retry decisions) and valid empty results (representing successful queries with no matches)

What You Need to Know

What a failing MCP tool hands back determines whether the agent can do anything sensible about it. "Operation failed" tells a model nothing it can act on: not what broke, not whether another attempt would help, not what to try instead.

The protocol provides isError for exactly this. Setting it marks the response as a failure rather than a result, which is the difference between an agent reasoning about recovery and an agent treating the error text as the answer it asked for.

The Four Error Categories

Every tool failure falls into one of four categories. Each one calls for a different response, and telling them apart is only possible if the response says which it is.

1. Transient Errors Timeouts, service unavailability, rate limits. Nothing is wrong with the request; the system on the other end is briefly out of reach. Recovery: wait, then send the same call again.

{
  "isError": true,
  "content": [{
    "type": "text",
    "text": "Service temporarily unavailable"
  }],
  "errorCategory": "transient",
  "isRetryable": true,
  "description": "The order database is under load and refused the connection. Nothing is wrong with this request; sending it again shortly should work."
}

2. Validation Errors Malformed input, absent required fields, values outside the permitted range. Here the request itself is at fault. Recovery: correct the input, then send it again.

{
  "isError": true,
  "content": [{
    "type": "text",
    "text": "Invalid order ID format"
  }],
  "errorCategory": "validation",
  "isRetryable": true,
  "description": "Order IDs take the form #NNNNN, for example #12345. This call supplied 'order-abc'. Reformat the identifier and send it again."
}

3. Business Errors A policy violation, a limit exceeded, a rule that forbids what was asked. The call is well-formed and the system understood it perfectly — and refused. Recovery: do NOT retry, because the rule will apply identically next time. The agent needs a different route entirely.

{
  "isError": true,
  "content": [{
    "type": "text",
    "text": "Refund exceeds policy limit"
  }],
  "errorCategory": "business",
  "isRetryable": false,
  "description": "£750 is above the £500 ceiling for automatic refunds, so this one needs a manager to approve it. Hand the refund details to a human agent."
}

isRetryable: false is doing the important work there. A policy does not relent on the second attempt, so anything short of a different path — escalation, usually — just burns calls arriving at the same refusal. Writing the description in terms a customer could hear also lets the agent explain the outcome rather than reporting an error code.

4. Permission Errors Access denied, credentials insufficient, authorisation refused. The obstacle is who is asking rather than what is being asked. Recovery: escalate, or come back with different credentials.

{
  "isError": true,
  "content": [{
    "type": "text",
    "text": "Access denied"
  }],
  "errorCategory": "permission",
  "isRetryable": false,
  "description": "Financial records are outside what this service account may read. Pass the request to a senior agent whose access covers the financial system."
}

What isRetryable Really Signals

The flag answers one narrow question: could any retry ever succeed? It does not claim the identical call will work. Transient and validation errors both carry isRetryable: true and reach success by different routes — the transient one by resending unchanged once the service recovers, the validation one only after the agent repairs the input, turning order-abc into #12345. Business and permission errors share isRetryable: false for the complementary reason: a rule that blocks the request blocks it every time, and a credential problem is solved by a different principal rather than a different wording. So read isRetryable for whether to try again at all, and errorCategory for what trying again would have to involve — resend, self-correct, escalate, or route around.

Access Failure vs Valid Empty Result

Of everything in this domain, this is the distinction to nail. The exam tests it directly.

Access failure: the query never ran. Something timed out, authentication was refused, the service was unreachable. Whether the data exists is unknown, because nothing got far enough to look.

Valid empty result: the query ran and the answer is nothing. The system was reached, the search executed, and no record matched. Retrying repeats a successful operation to obtain the same correct answer.

Blur the two and recovery logic stops working. Here's how that plays out:

A tool returns an empty array after a customer lookup. The agent retries 3 times, then escalates to a human. Analysis reveals the customer's account simply does not exist.

Nothing malfunctioned. The lookup worked, found no such customer, and reported that accurately. What went wrong is that "reached the database, no match" and "never reached the database" arrived looking identical, so the agent applied its failure handling to a success — three wasted calls and a human pulled in to confirm an answer it already had.

So shape the responses to make the two unmistakable: an empty answer from a query that ran should share no surface with a query that never ran at all.

// Valid empty result — NOT an error
{
  "isError": false,
  "content": [{
    "type": "text",
    "text": "The search ran and matched nothing for 'john@example.com'. No such customer exists — this is an answer, not a failure."
  }],
  "resultCount": 0
}

// Access failure — IS an error
{
  "isError": true,
  "content": [{
    "type": "text",
    "text": "Could not reach customer database"
  }],
  "errorCategory": "transient",
  "isRetryable": true,
  "description": "The customer database did not answer within 5 seconds, so the search never ran. Whether a match exists is still unknown."
}

Error Propagation in Multi-Agent Systems

Across several agents, the governing principle is that failures are handled as low down as possible and only travel upward when they cannot be:

1. Subagents implement local recovery for transient failures. A search that times out is retried by the search subagent, without the coordinator ever learning it happened.
2. Only propagate errors that cannot be resolved locally. Once local recovery is exhausted, the failure goes up — at that point it is genuinely the coordinator's decision.
3. Include partial results and what was attempted. Bare failure is not enough to decide with: "I searched 3 of 5 sources successfully. Sources 4 and 5 timed out. Here are partial results from the 3 successful sources."

Two anti-patterns are ruled out by this. Swallowing an error and reporting an empty success hides the failure from the only component able to compensate for it. Aborting the entire workflow on one subagent's failure discards work that succeeded and was recoverable. Both leave the coordinator deciding without the information it needed.

Deep Dive

MCP's two error-reporting mechanisms

The MCP specification distinguishes two separate error channels, and mixing them up is a common source of bugs. Protocol errors are standard JSON-RPC errors for transport/routing problems: unknown tools, invalid arguments, server errors. Tool execution errors are reported inside a successful tool result with isError: true, covering API failures, invalid input data, and business logic errors. A tool that exists and was called correctly but then fails internally should return a normal JSON-RPC success envelope with isError: true in the payload — not a protocol-level error. This is the mechanical basis for the whole error-category taxonomy in this lesson: every one of the four categories (transient, validation, business, permission) is a tool execution error, never a protocol error.

Sourcemodelcontextprotocol.io › toolsfetched 2026-07-30

isError in MCP maps to is_error in the Messages API

The MCP spec's isError flag has a direct analogue in Anthropic's own Messages API: a client tool_result block carries an optional is_error boolean, set true when tool execution failed, and Claude "incorporate[s] this error into its response to the user." When Claude connects to a remote MCP server through the Messages API's MCP connector (rather than a client-side tool loop), results come back as mcp_tool_result content blocks that carry the same boolean, e.g. {"type": "mcp_tool_result", "is_error": false, "content": [...]}. Whichever path you're building against, the pattern is identical: a boolean flag inside the result, not an HTTP-style status code, tells the model whether to treat the payload as a success or a failure to reason about.

Sourcesplatform.claude.com › handle-tool-callsplatform.claude.com › mcp-connectorfetched 2026-07-30

structuredContent and outputSchema turn ad-hoc JSON into a contract

Rather than hand-rolling errorCategory/isRetryable/description inside a text string (as the Appendix A build steps do for simplicity), MCP has a first-class field for this: structuredContent, a JSON object returned alongside the result. For backwards compatibility, a tool that returns structured content should also serialise the same JSON into a TextContent block. If the tool declares an outputSchema, the contract tightens further: the server MUST provide structured results conforming to it, and the client SHOULD validate results against it. Declaring an outputSchema for your error payload is how you guarantee every failure response actually has errorCategory, isRetryable, and description — instead of trusting every code path to remember to include them.

Sourcemodelcontextprotocol.io › toolsfetched 2026-07-30

The spec says a human SHOULD be able to deny tool invocations

MCP's design guidance states there "SHOULD always be a human in the loop with the ability to deny tool invocations." This is the protocol-level justification for treating permission errors as a distinct, non-retryable category rather than something to route around automatically: the spec's whole trust model assumes a human can say no, so a tool that returns a permission error is reporting that the system said no, and the correct response is escalation, not a workaround.

Sourcemodelcontextprotocol.io › toolsfetched 2026-07-30

Claude's own malformed-call retries are a different mechanism from isRetryable

Don't conflate two different retry behaviours. If Claude's tool call itself is invalid or missing required parameters, Claude automatically "retries 2-3 times with corrections before apologizing to the user" — this happens at the model level, before your tool code even runs successfully. isRetryable in your structured error response is a different signal: it fires after your tool executed and failed, telling the agent whether attempting the same (or a corrected) request again could ever succeed. A validation error your tool returns (bad input format) is isRetryable: true because the agent can fix the input and resubmit — that's a deliberate, agent-driven retry, distinct from Claude's automatic malformed-call correction loop.

Sourceplatform.claude.com › handle-tool-callsfetched 2026-07-30

The Agent SDK converts uncaught handler exceptions to error results automatically

If you build your MCP tool with the Claude Agent SDK's custom-tools API, "a handler error doesn't stop the agent loop" — the SDK's in-process MCP server catches uncaught exceptions in your handler and converts them into error results for you. That's a safety net, not a substitute for the structured-error design in this lesson: an uncaught exception becomes a generic error, but explicitly returning isError: true with your own errorCategory/isRetryable/description payload is how you compose the specific message the agent actually needs to recover intelligently, rather than falling back on whatever the SDK's default exception serialisation produces.

Sourcecode.claude.com › custom-toolsfetched 2026-07-30

Quick Reference

Exam Traps

Practice Scenario

Build Exercise

Build Structured Error Responses for All Four Categories

Difficulty: Intermediate (2/4)

45 minutes

1. Create an MCP tool that queries a mock customer database with simulated failure modes

Why: Simulating failure modes in a controlled environment lets you observe how agents behave when errors lack structure. The exam tests your understanding of how poor error responses cause wasted retries and incorrect escalations.

You should see: An MCP server running with a customer_lookup tool that accepts a customer identifier and a failure_mode parameter to trigger specific error conditions on demand.

2. Implement four error response types: transient (simulated timeout), validation (invalid input format), business (refund exceeds policy limit), and permission (access denied)

Why: Each error category demands a different recovery strategy. The exam tests whether you can identify which category an error belongs to and what recovery action is appropriate. Transient errors are retryable; business errors never are.

You should see: Four distinct error responses, each with isError: true, a specific errorCategory value, the correct isRetryable boolean, and a descriptive message explaining what went wrong and what to do next.

3. Include structured metadata in each error: errorCategory, isRetryable boolean, and a human-readable description

Why: Structured metadata is what enables intelligent recovery. Without these fields, the agent cannot distinguish a transient timeout from a permanent policy violation. The exam specifically tests whether you know that isRetryable: false means the agent must take an alternative path, not retry.

You should see: Each error response parses to a JSON object containing exactly three fields: errorCategory (one of transient, validation, business, permission), isRetryable (boolean), and description (a sentence explaining the error and suggesting recovery).

4. Implement a valid empty result response (isError: false, resultCount: 0) clearly distinguished from an access failure

Why: This is one of the most critical distinctions in Domain 2. Confusing access failures with valid empty results causes wasted retries and incorrect escalations. The exam tests this directly — an agent retrying a successful empty query is the canonical anti-pattern.

You should see: Two structurally different responses: a valid empty result with isError: false and resultCount: 0 (indicating the query ran successfully but found nothing), and an access failure with isError: true, errorCategory: transient, and isRetryable: true.

5. Write an agent loop that reads the error metadata and takes appropriate action: retry for transient, fix input for validation, escalate for business, and request credentials for permission

Why: The agent loop demonstrates the practical outcome of structured error metadata. Each error category maps to a specific recovery action, and the loop must branch correctly. This is exactly the kind of decision logic the exam expects you to design.

You should see: An agent loop that parses the error metadata, branches on errorCategory, retries transient errors up to 3 times with backoff, reformats input for validation errors, escalates business errors to a human, and requests elevated credentials for permission errors.

Sources

• Claude Certified Architect Foundations Exam Guide — Domain 2, Task Statement 2.2 — Anthropic
• MCP Specification — Tool Results — Model Context Protocol
• Building Effective Agents — Anthropic — Anthropic
• MCP Specification — Tools (2025-06-18) — Model Context Protocol
• Handling tool calls — Anthropic API Documentation — Anthropic
• MCP connector — Anthropic API Documentation — Anthropic
• Agent SDK — Custom Tools — Anthropic

Appendix A — Build Exercise Step Hints

Progressive hints revealed by the "Stuck? Get a nudge" control on each step.

Step 1. Create an MCP tool that queries a mock customer database with simulated failure modes

Why: Simulating failure modes in a controlled environment lets you observe how agents behave when errors lack structure. The exam tests your understanding of how poor error responses cause wasted retries and incorrect escalations.

You should see: An MCP server running with a customer_lookup tool that accepts a customer identifier and a failure_mode parameter to trigger specific error conditions on demand.

import { McpServer } from "@modelcontextprotocol/server";
import * as z from "zod/v4";

const server = new McpServer({ name: "customer-db", version: "1.0.0" });

server.registerTool(
  "customer_lookup",
  {
    description:
      "Looks up a customer by email or ID. Supports failure simulation via the mode parameter.",
    inputSchema: z.object({
      identifier: z.string().describe("Customer email or ID"),
      mode: z
        .enum(["success", "not_found", "timeout", "invalid", "business", "permission"])
        .default("success"),
    }),
  },
  async ({ identifier, mode }) => {
    // Implementation in next steps
    return { content: [{ type: "text", text: `Mode: ${mode}` }] };
  }
);

from typing import Literal

from mcp.server import MCPServer

mcp = MCPServer("customer-db")

Mode = Literal["success", "not_found", "timeout", "invalid", "business", "permission"]


@mcp.tool()
def customer_lookup(identifier: str, mode: Mode = "success") -> str:
    """Look up a customer by email or ID. Supports failure simulation via mode.

    Args:
        identifier: Customer email or ID
        mode: Which scenario to simulate
    """
    # Implementation in next steps
    return f"Mode: {mode}"

Step 2. Implement four error response types: transient (simulated timeout), validation (invalid input format), business (refund exceeds policy limit), and permission (access denied)

Why: Each error category demands a different recovery strategy. The exam tests whether you can identify which category an error belongs to and what recovery action is appropriate. Transient errors are retryable; business errors never are.

You should see: Four distinct error responses, each with isError: true, a specific errorCategory value, the correct isRetryable boolean, and a descriptive message explaining what went wrong and what to do next.

// A tool execution error is a *successful* JSON-RPC result carrying
// isError: true — not a protocol error. Protocol errors (unknown tool,
// malformed request) use ProtocolError, and the model never sees them.
if (mode === "timeout") {
  return {
    isError: true,
    content: [{ type: "text", text: JSON.stringify({
      errorCategory: "transient",
      isRetryable: true,
      description: "Customer database timed out after 5 seconds. The request is valid and should succeed on retry."
    }) }]
  };
}
if (mode === "invalid") {
  return {
    isError: true,
    content: [{ type: "text", text: JSON.stringify({
      errorCategory: "validation",
      isRetryable: true,
      description: `Invalid identifier format: ${identifier}. Expected email (user@domain.com) or ID (CUST-NNNNN).`
    }) }]
  };
}
if (mode === "business") {
  return {
    isError: true,
    content: [{ type: "text", text: JSON.stringify({
      errorCategory: "business",
      isRetryable: false,
      description: "Refund of \u00a3750 exceeds the \u00a3500 automatic limit. Escalate to a manager with refund details."
    }) }]
  };
}
if (mode === "permission") {
  return {
    isError: true,
    content: [{ type: "text", text: JSON.stringify({
      errorCategory: "permission",
      isRetryable: false,
      description: "Current service account lacks access to financial records. Escalate to a senior agent."
    }) }]
  };
}

# Raising an ordinary exception is the Python SDK's tool-execution-error
# channel: the result comes back with is_error=True and your message in
# content. MCPError is the other channel — a JSON-RPC protocol error the
# model never sees. The categories below ride in the message as JSON.
if mode == "timeout":
    raise ToolFailure(
        "transient",
        True,
        "Customer database timed out after 5 seconds. "
        "The request is valid and should succeed on retry.",
    )
if mode == "invalid":
    raise ToolFailure(
        "validation",
        True,
        f"Invalid identifier format: {identifier}. "
        "Expected email (user@domain.com) or ID (CUST-NNNNN).",
    )
if mode == "business":
    raise ToolFailure(
        "business",
        False,
        "Refund of \u00a3750 exceeds the \u00a3500 automatic limit. "
        "Escalate to a manager with refund details.",
    )
if mode == "permission":
    raise ToolFailure(
        "permission",
        False,
        "Current service account lacks access to financial records. "
        "Escalate to a senior agent.",
    )

Step 3. Include structured metadata in each error: errorCategory, isRetryable boolean, and a human-readable description

Why: Structured metadata is what enables intelligent recovery. Without these fields, the agent cannot distinguish a transient timeout from a permanent policy violation. The exam specifically tests whether you know that isRetryable: false means the agent must take an alternative path, not retry.

You should see: Each error response parses to a JSON object containing exactly three fields: errorCategory (one of transient, validation, business, permission), isRetryable (boolean), and description (a sentence explaining the error and suggesting recovery).

function buildErrorResponse(category: string, retryable: boolean, description: string) {
  return {
    isError: true,
    content: [{ type: "text", text: JSON.stringify({
      errorCategory: category,
      isRetryable: retryable,
      description: description
    }) }]
  };
}

import json


class ToolFailure(RuntimeError):
    """Carries the structured payload through the SDK's exception channel.

    The SDK turns any raised exception into a result with is_error=True and
    str(exc) as the content, so the JSON below is what the agent reads back.
    """

    def __init__(self, category: str, retryable: bool, description: str):
        super().__init__(
            json.dumps(
                {
                    "errorCategory": category,
                    "isRetryable": retryable,
                    "description": description,
                }
            )
        )

Step 4. Implement a valid empty result response (isError: false, resultCount: 0) clearly distinguished from an access failure

Why: This is one of the most critical distinctions in Domain 2. Confusing access failures with valid empty results causes wasted retries and incorrect escalations. The exam tests this directly — an agent retrying a successful empty query is the canonical anti-pattern.

You should see: Two structurally different responses: a valid empty result with isError: false and resultCount: 0 (indicating the query ran successfully but found nothing), and an access failure with isError: true, errorCategory: transient, and isRetryable: true.

if (mode === "not_found") {
  return {
    isError: false,
    content: [{ type: "text", text: JSON.stringify({
      resultCount: 0,
      message: `No customer found matching ${identifier}. The query executed successfully but returned no matches.`
    }) }]
  };
}
// Compare with the timeout (access failure):
if (mode === "timeout") {
  return {
    isError: true,
    content: [{ type: "text", text: JSON.stringify({
      errorCategory: "transient",
      isRetryable: true,
      description: "Connection timed out. The query did not execute."
    }) }]
  };
}

if mode == "not_found":
    # Returning normally leaves is_error false: the query ran, and the answer
    # is "nothing matched". The agent must not retry this.
    return {
        "resultCount": 0,
        "message": (
            f"No customer found matching {identifier}. "
            "The query executed successfully but returned no matches."
        ),
    }

# Compare with the timeout (access failure) — raising flips is_error to true:
if mode == "timeout":
    raise ToolFailure("transient", True, "Connection timed out. The query did not execute.")

Step 5. Write an agent loop that reads the error metadata and takes appropriate action: retry for transient, fix input for validation, escalate for business, and request credentials for permission

Why: The agent loop demonstrates the practical outcome of structured error metadata. Each error category maps to a specific recovery action, and the loop must branch correctly. This is exactly the kind of decision logic the exam expects you to design.

You should see: An agent loop that parses the error metadata, branches on errorCategory, retries transient errors up to 3 times with backoff, reformats input for validation errors, escalates business errors to a human, and requests elevated credentials for permission errors.

async function handleToolResult(result: any) {
  if (!result.isError) {
    const data = JSON.parse(result.content[0].text);
    if (data.resultCount === 0) {
      console.log("Valid empty result — no matches found. Do NOT retry.");
      return;
    }
    console.log("Success:", data);
    return;
  }
  const error = JSON.parse(result.content[0].text);
  switch (error.errorCategory) {
    case "transient":
      console.log("Retrying after delay...");
      break;
    case "validation":
      console.log("Fixing input format and retrying...");
      break;
    case "business":
      console.log("Escalating to human agent:", error.description);
      break;
    case "permission":
      console.log("Requesting elevated credentials...");
      break;
  }
}

def handle_tool_result(result) -> None:
    if not result.is_error:
        data = json.loads(result.content[0].text)
        if data.get("resultCount") == 0:
            print("Valid empty result — no matches found. Do NOT retry.")
            return
        print("Success:", data)
        return

    error = json.loads(result.content[0].text)
    category = error["errorCategory"]
    if category == "transient":
        print("Retrying after delay...")
    elif category == "validation":
        print("Fixing input format and retrying...")
    elif category == "business":
        print("Escalating to human agent:", error["description"])
    elif category == "permission":
        print("Requesting elevated credentials...")

Appendix B — Interactive Study Prompts

Two prompts to paste into Claude. B1 drills the judgement the exam actually measures; B3 reviews the code you wrote for the Build Exercise above. The exam simulator between them is the interactive quiz on this page.

B1. Concept Check — Discrimination Drill

B2. Exam Simulator

B3. Build Coach — Code Review

The Build Exercise and its hint ladder are already on this page. This prompt is for the one thing the page cannot do: review the code you actually wrote.