Domain 2 · Tool Design & MCP

Structured errors & retry loops

Tools fail — networks blip, inputs are wrong, records don't exist. What separates a brittle agent from a self-healing one is how the failure is reported back. A structured error tells the model exactly what happened and whether trying again could help. Watch an agent recover — or give up — based on the error you hand it.

errorCategoryisRetryable human-readable messagevalidation-retry loop

Explain like I'm 10

When something goes wrong, "Error 0x5F" is like a grown-up just saying "nope" and walking away — you have no idea what to do. A structured error is like "I couldn't find that order — double-check the number and try again." Now you know what broke and whether trying again will help. Good error messages let Claude fix its own mistakes instead of getting stuck.

Three fields turn a dead-end into a recovery

A good tool error is itself a little tool-result the model can reason over. The pattern the exam expects has three parts:

Field	Purpose	Example
`errorCategory`	A machine-readable bucket so the model (and your code) can branch.	`"NOT_FOUND"`, `"VALIDATION"`, `"RATE_LIMIT"`, `"AUTH"`
`isRetryable`	Should the agent try again, or is retrying pointless?	`true` for a timeout; `false` for "order doesn't exist"
`message`	Human-readable guidance the model uses to decide its next move.	"No order 99999. Confirm the ID with the customer."

Hand the agent an error — see what it does

tool failure

The validation–retry loop

For structured output and tool args, the strongest pattern is a bounded loop: the model produces a call → your code validates it against the schema → on failure you return a VALIDATION error naming the exact problem → the model corrects and resubmits. This recovers from malformed JSON and missing fields automatically. The guardrail (Domain 1) still applies: cap the retries (e.g. 3) so a persistently confused model doesn't loop forever.

Exam trap: returning a raw stack trace or a bare "failed" is the wrong answer — the model can't tell retry from give up, so it either spins pointlessly or abandons a recoverable task. The right answer always pairs a category + isRetryable + a human-readable next step, inside a bounded retry loop.

Takeaways: design tool errors as structured payloads with errorCategory, isRetryable, and a human-readable message. Retryable failures (timeouts, validation) let the agent self-correct; non-retryable ones (not-found, auth) tell it to stop and ask. Wrap it in a bounded validation–retry loop. Raw stack traces are a dead end — never hand them to the model.

Curated companion: Anthropic — Writing tools for agents.