Task statement 2.2 · Tool design and MCP integration

Implement structured error responses for MCP tools

When lookup_order or process_refund fails, the support agent never sees your logs. It sees only the result your MCP server sends back, so that result decides whether the agent tries again, asks the customer for a correction, explains a policy, or escalates.

Why it's tested

The tempting fixes here all look responsible. Returning "Operation failed" for every failure is tidy, but the agent can no longer tell a timeout from a refusal, so it retries what policy forbids or abandons a call that would have worked. Retrying with backoff inside the tool, then reporting "unavailable", hides what was tried. Returning an empty order list after a timeout is worse, because the agent then tells a customer with real orders that they have none.

KnowledgeTwo ways a tool call can fail

MCP messages use JSON-RPC, a format in which every request gets exactly one reply: a result or an error. A server can therefore report a failed tools/call in two ways. A protocol error is a JSON-RPC error, such as {"code": -32602, "message": "Unknown tool: lookup_invoice"}, and the spec keeps it for unknown tools, malformed requests and server errors. A tool execution error is an ordinary result with isError: true, and it covers what goes wrong once the tool runs: a failed API call, invalid input, or a business rule that says no. Clients SHOULD pass tool execution errors to the model but only MAY pass protocol errors, so a failure the agent should recover from belongs in a result with isError: true.

The client turns that result into a Claude API tool_result block, whose only fields are tool_use_id, content and is_error. Everything the model learns about the failure therefore travels in content, and a field added beside it has nowhere to go. A tool that also returns structuredContent (a JSON object) should repeat it as serialized text for the same reason.

  1. Claude requests a tool in a tool_use block.
  2. The agent's MCP client sends tools/call to your server.
  3. The server checks the arguments, then calls the backend.
  4. The backend answers, refuses, or stays silent.
  5. The server replies with a result (with or without isError: true) or a JSON-RPC error.
  6. Claude receives a tool_result and chooses its next move from that text alone.

Interactive · five outcomes

Sequence diagram of one MCP tool call. Claude sends tool_use to the agent, the agent's MCP client sends tools/call to the support MCP server, the server calls the order and refund systems, and the reply travels back to Claude as a tool_result. Buttons switch between a timeout, an invalid order number, a refund over the limit, an empty order history and an unknown tool name. Claude Agent (MCP client) Support MCP server Orders + refunds 1 tool_use lookup_order 1 tool_use process_refund 1 tool_use lookup_invoice 2 tools/call order 10024871 2 tools/call order 1002487 2 tools/call refund $650 2 tools/call customer 4471 2 tools/call lookup_invoice 3 query order 10024871 3 not sent: only 7 digits 3 check refund policy 3 query orders of 4471 3 not run: unknown tool 4 ✕ no reply in 5 s 4 (no backend call) 4 ✕ over the $500 limit 4 0 rows, query succeeded 5 result · isError: true 5 result · isError: false 5 JSON-RPC error −32602 errorCategory: transient · isRetryable: true errorCategory: validation · isRetryable: false errorCategory: business · retriable: false not an error: orders: [] with a note no result, so no isError 6 tool_result · is_error: true 6 tool_result · orders: [] 6 client MAY pass it on Claude's next move Calls lookup_order again. If it fails twice, tells the customer and escalates. Asks the customer to check the number, then calls with the corrected 8 digits. Stops retrying, calls escalate_to_human, and tells the customer a specialist will review it. Tells the customer no orders were found and asks whether they used another email. Sees the error only if the client passes it on. Otherwise it cannot recover.

Choose what goes wrong on the call.

Transient: the order service does not answer within 5 s.

Validation: the customer gave a 7-digit order number.

Business: a $650 refund is over the $500 limit.

Valid empty result: customer 4471 has no orders.

Protocol error: the server has no tool called lookup_invoice.

Only the reply in message 5 changes between cases. The 7-digit order number never reaches the backend, yet it returns as a result with isError: true, because the tool ran and rejected its input. Only the unknown tool name becomes a JSON-RPC error, which the client may or may not show Claude.

More precise than the guide. The guide presents errorCategory and isRetryable as if they were MCP fields. MCP defines only isError, so these are keys you write inside the text content, or in structuredContent with a text copy. Since the 2025-11-25 revision, which the current 2026-07-28 revision keeps, invalid input returns isError: true and clients may pass protocol errors to the model (checked 2026-09-30). Exam answer: return isError: true with errorCategory, isRetryable and a human-readable description.

KnowledgeFour categories, four next moves

The isError flag says that something failed, but not what to do next, so the guide sorts failures into four categories. A transient error, such as a timeout or service unavailability, may succeed if the same call is sent again. A validation error means invalid input, so the identical call fails again and the agent must fix the argument first. A business error is a policy violation, and a permission error means this agent may not take the action at all, so neither changes on a retry. A uniform "Operation failed" hides which of the four happened, so the agent cannot choose a recovery.

The guide's fields carry that decision: errorCategory, an isRetryable boolean saying whether the same call can succeed, and a human-readable description of what happened and what to try. For business-rule violations the guide writes retriable: false plus a customer-friendly explanation the agent can relay. Both spellings answer the same question. A validation error gets isRetryable: false because the flag describes the identical call, and the corrected call is a new one. This metadata prevents wasted retries. Each card shows the text content of one failed call.

transientretry as is

Timeouts, service unavailable.

{"errorCategory": "transient",
 "isRetryable": true,
 "description": "Order service did
  not answer in 5 s. Nothing
  changed. Safe to call again."}
validationfix, then retry

Invalid input: the tool rejected an argument.

{"errorCategory": "validation",
 "isRetryable": false,
 "description": "order_id must be
  8 digits; got '1002487'. Ask the
  customer to check the number."}
businessno retry

Policy violation: a valid request that a rule refuses.

{"errorCategory": "business",
 "retriable": false,
 "customerMessage": "Refunds are
  available for 90 days after
  delivery. This order arrived
  112 days ago."}
permissionno retry

This agent is not allowed to take the action.

{"errorCategory": "permission",
 "isRetryable": false,
 "description": "This agent's key
  lacks refund:write. Escalate
  to a human agent."}

SkillThe same timeout, written two ways

A customer asks about order 10024871, and the order service times out. The agent says "something went wrong" and closes the conversation, although a second call would have worked. The cause is the payload: isError: true with the text "Operation failed" cannot tell a timeout from a refusal. The fix keeps the flag and adds the category, the retry answer, what was attempted, and what to do next.

What the tool returns

// result of tools/call
{
  "content": [{ "type": "text",
    "text": "Operation failed." }],
  "isError": true
}
// result of tools/call
{
  "content": [{ "type": "text",
    "text": "{\"errorCategory\": \"transient\", …}" }],
  "structuredContent": {
    "errorCategory": "transient",
    "isRetryable": true,
    "attempted": "lookup_order(10024871)",
    "description": "No answer in 5 s. Safe to call again."
  },
  "isError": true
}

What the agent does next

  1. Cannot tell a timeout from a refusal, so it guesses.
  2. Tells the customer "something went wrong".
  3. Closes the case without the order details.
  1. Reads transient and isRetryable: true, so another call is worth making.
  2. Calls lookup_order again with the same order number.
  3. If that also fails, tells the customer and escalates with attempted attached.

"Operation failed"

Structured payload

The flag says something broke, and the text says nothing else, so every recovery is a guess. Same outage, same isError: true. The metadata sits in structuredContent and, serialized, in the text block, so the model can read it.

SkillAn access failure is not an empty result

Suppose the agent calls lookup_order for customer 4471. If the query could not reach the order database, that is an access failure, and the agent must decide whether to retry. If the query succeeded with no matches, that is a valid empty result, and the agent can say so. A tool that returns an empty list in both cases makes them identical, so return the access failure with isError: true and the empty result as a success with an explicit empty list.

Access failure

The query did not run

{ "content": [{ "type": "text", "text":
    "{\"errorCategory\": \"transient\",
      \"isRetryable\": true, \"description\":
      \"Order database unreachable.\"}" }],
  "isError": true }

Next move: decide whether to retry.

Valid empty result

The query ran and matched nothing

{ "content": [{ "type": "text", "text":
    "{\"customerId\": \"4471\", \"orders\": [],
      \"note\": \"Search succeeded. No
      orders for this customer.\"}" }],
  "isError": false }

Next move: tell the customer, perhaps asking for another email.

SkillRecover locally, pass on only what is left

The support agent here is a single agent with no subagents, so this skill applies once it delegates, as a coordinator does in Domain 1. Suppose it hands order history to a subagent that must fetch three orders. When one lookup_order call times out, the subagent retries it itself, because a transient failure often clears and the coordinator gains nothing from hearing about it. If the retry also fails, the subagent propagates to the coordinator only what it could not resolve: its partial results, what it attempted, and the error. The coordinator can then continue with two orders, try the third later, or tell the customer, none of which a bare failure would allow.

// subagent → coordinator, after one local retry
{ "orders": [ { "order_id": "10024871", … }, { "order_id": "10024877", … } ],
  "unresolved": [ { "order_id": "10024880", "errorCategory": "transient",
      "isRetryable": true, "attempted": "lookup_order twice, 5 s timeout each" } ] }
Before any retry, ask: Would the identical call succeed if it were sent again?
Yes, the failure is transientCall again, and pass the failure on only if it persists.
No, an argument is wrongFix the argument, often by asking the customer, then call.
No, policy or permission refuses itStop. Explain the refusal to the customer, or escalate.
Takeaway
  • A tool that ran and failed, including on invalid input, returns isError: true, not a JSON-RPC error.
  • Put errorCategory, isRetryable and the description inside the text the model reads, never beside it.
  • A query that ran and found nothing is a success, not an error.

check yourself

0 / 3 answered

process_refund returns isError: true with the text "Refund failed" in two cases: the payment gateway's two-minute nightly maintenance (HTTP 503), and refunds above the $500 limit. During maintenance the agent tells customers their refund was denied. Customers wait in live chat, and the agent must reply within 15 seconds.Which change most directly lets the agent recover from the maintenance failures?

Select one.

When the CRM is down, get_customer returns {"customers": []} as a normal result. The agent then says no account exists and creates a new one, and 40 duplicate accounts appeared last week. Customers who really have no account must still be offered one.Which TWO changes best stop the duplicates while keeping the new-account path?

Select two.

process_refund expects amount_cents as an integer, but the agent sometimes sends "45.00". Your server rejects these with a JSON-RPC error (-32602, "Invalid params"). The agent's client does not show protocol errors to the model, so the agent repeats the call until its turn limit. You can change only the support MCP server.Which change most directly lets the agent correct its own call?

Select one.

sources

  1. Model Context Protocol, Tools specification, "Error Handling" and "Structured Content" (revision 2026-07-28, current): protocol errors for unknown tools, malformed requests and server errors; isError: true for API failures, input validation errors and business logic errors; clients SHOULD pass tool execution errors to the model and MAY pass protocol errors; a tool returning structuredContent SHOULD also return it as serialized JSON text. Checked 2026-09-30.
  2. Model Context Protocol, 2025-11-25 changelog: input validation errors should be returned as tool execution errors, not protocol errors. Checked 2026-09-30.
  3. Claude Platform Docs, "Handle tool calls": the tool_result fields tool_use_id, content and is_error, and the advice to write instructive error messages instead of "failed". Checked 2026-09-30.
  4. Anthropic Engineering, "Writing effective tools for agents": error responses that communicate "specific and actionable improvements" instead of opaque error codes or tracebacks. Checked 2026-09-30.
  5. The four categories, the errorCategory / isRetryable / retriable field names, "Operation failed", access failures versus valid empty results, and local recovery in subagents: Claude Certified Architect — Foundations Exam Guide v1.0, Domain 2.2. Scenario and tool names: the guide's Scenario 1. The $500 refund limit is this course's scenario detail.