Implement structured error responses for MCP tools

MCP tools report problems through two different channels, and choosing the wrong one hides the failure from Claude. Protocol errors are JSON-RPC level errors (unknown tool, malformed arguments, a server that crashed) and signal that the request itself could not be processed. Tool execution errors are different: the tool ran, but the operation failed (a payment gateway timed out, a refund violated policy). For execution errors, the MCP pattern is to return a normal CallToolResult with isError: true and the details inside content, so the model sees the failure and can reason about what to do next.

If you instead let the handler throw, many SDKs surface a terse protocol error or a generic message and you lose control of the payload. Catch the error yourself and return structured content:

return {
  isError: true,
  content: [{ type: "text", text: JSON.stringify({
    errorCategory: "transient",
    isRetryable: true,
    message: "Payment gateway timed out after 30s"
  }) }]
};

The isError flag is what tells the agent this result is a failure rather than data. The JSON inside content is what tells it how to react.

Not all failures deserve the same response, so categorize them. Four categories cover almost every MCP tool:

• Transient: timeouts, service unavailable (503), rate limits (429). The same call may succeed if tried again. Retryable.
• Validation: malformed or out-of-range input, such as a badly formatted order ID or a missing required field. Retrying the identical call fails again; the agent must correct the input first.
• Business: the operation is well-formed and authorized but violates a policy, such as a refund above the auto-approval limit or an item outside the return window. Not retryable; the agent must explain or escalate.
• Permission: the caller is not authorized or lacks the required scope. Not retryable by the agent; it needs escalation or different credentials.

Putting the category in the response as errorCategory lets the agent branch correctly instead of guessing from a prose string. It also lets you log and alert on each class separately: a spike in transient errors is an infrastructure problem, while a spike in validation errors usually means a prompt or schema issue.

The agentic loop keeps calling tools until Claude decides it is done. If a failed call looks recoverable, the model may retry it. That is exactly right for a transient timeout and exactly wrong for a business rule violation, where every retry burns another iteration, more tokens, and more latency while producing the identical failure.

A boolean isRetryable (some teams spell it retriable) removes the guesswork. Transient errors set it true, often with a retryAfterMs hint; validation, business, and permission errors set it false. When the model sees isRetryable: false it stops retrying and moves to the appropriate fallback: fix the input, explain the policy, or escalate. Returning this metadata is what converts a blind retry loop into a deliberate decision, and it is the main reason structured errors save real money at scale.

A good error payload carries everything the agent needs in one object: a machine-readable category, a retryability flag, a developer-facing message, and, for business rules, a customer-facing explanation the agent can relay verbatim.

// business rule violation
return {
  isError: true,
  content: [{ type: "text", text: JSON.stringify({
    errorCategory: "business",
    isRetryable: false,
    message: "Refund of $650 exceeds the $500 auto-approval limit",
    customerMessage: "This refund needs a supervisor to approve it. I can connect you with someone who can help right now."
  }) }]
};

Separating message from customerMessage matters: the first drives the agent's internal logic and your logs, the second gives the agent safe, on-brand wording so it does not leak an internal threshold or invent an explanation. Keep the field names identical across every tool so the agent learns one consistent shape rather than a different schema per tool.

A query that runs successfully and finds nothing is not an error. lookup_order returning zero orders for a valid customer is a successful result: isError is false and the content is an empty list. A tool that could not run at all, for example because the order service timed out, is a failure: isError is true with a transient category.

Conflating the two is a common and costly bug. If you mark empty results as errors, the agent retries queries that were already answered, or worse, concludes the data is unavailable and escalates unnecessarily. If you return empty success on a real failure, the agent believes no data exists and produces confidently wrong output, for example a research report that silently omits a whole subtopic because one search timed out. Always distinguish an access failure, which needs a retry decision, from a valid empty result, which is a definitive answer of none.

In multi-agent systems, error handling has two layers. A subagent should recover locally from transient failures it can resolve, for example retrying a timed-out search once or twice with backoff, so the coordinator never sees noise it cannot act on. Only errors the subagent cannot resolve should propagate upward.

When a subagent does propagate, it should not send a bare "failed" status. It returns structured context: the failure category, what it attempted (the exact query or operation), any partial results it did gather, and possible alternatives. That lets the coordinator make an intelligent recovery decision, whether to retry with a narrower query, route to a different source, or proceed with partial coverage and annotate the gap, rather than terminating the entire workflow on a single failure. This is the tool-level foundation of the error-propagation strategies used across a coordinator-subagent research system.