Error Propagation in Tool Responses

Key Takeaways

• Always return a typed error object inside the tool response envelope — include error_code, message, and retryable flag — so Claude can reason about failure rather than hallucinate over a data gap.
• Distinguish between hard errors (schema violation, auth failure) and soft errors (partial data, rate-limit) in your tool contract; Claude needs this signal to decide whether to retry, escalate, or degrade gracefully.
• Never let a tool silently return success on failure — treating errors as a first-class response type is the MCP equivalent of an API gateway fault contract: explicit, versioned, and machine-readable.
• Memory anchor: tool error handling in MCP = api-gateway-fault-contract — your tool's error schema is as load-bearing as its success schema; design both before writing a single line of handler code.