Tool errors and trust boundaries

Who fixes which failure, and what you are allowed to believe.

4 min read · Lesson 5 of 10 in this domain

Two independent ideas share this lesson because both are about placing responsibility correctly. On errors, split by who can fix it: a network timeout is the tool's problem and belongs in an internal retry, while a malformed argument is the agent's problem and must surface with enough detail to correct — a generic "tool failed" guarantees the next attempt repeats the mistake. On trust, remember that MCP annotations such as a read-only hint are declared by the server about itself. They are a claim, not a guarantee, so a policy that skips confirmation must rest on your trust in the vendor rather than on the label — and a server running locally is not thereby trustworthy, since a local process has full access to the machine.

• Split errors by who can actually fix them. Transient failures (network timeouts) are the tool's problem — retry inside the tool. Syntax errors need the agent to reason and correct its input, so surface them with specific validation detail.
• Making the agent handle predictable infrastructure failures burns turns and tokens on work code does better.
• A generic "Tool execution failed" strips the information needed to self-correct, guaranteeing another failed attempt.
• In the Messages API a failed tool returns a tool_result with is_error: true — never omit the block, and never return an empty string (indistinguishable from a successful empty result).
• MCP annotations are self-reported, untrusted metadata. A readOnlyHint is a label the server chose for itself, not a guarantee. Base any confirmation-bypass policy on explicit vendor trust — not on the label, and not on the server running locally (local ≠ trustworthy).

Source: MCP — Architecture overview · Independent study aid, not affiliated with or endorsed by Anthropic.