Lesson 2 · 5 min

Tool Error Contracts

Return errors that teach Claude how to recover.

Tool errors should be machine-readable and actionable. Include an error_code, a message, and a hint field. "404: file not found" is worse than {code: "NOT_FOUND", hint: "List files first with ls()"}.

Production scenario

Real-world example: Query tool against a multi-tenant warehouse

A SQL tool used by an analytics agent returns errors in a fixed shape:

{
  "error_code": "TABLE_NOT_FOUND",
  "message": "Table 'order_events' does not exist in schema 'public'.",
  "hint": "Tables in this workspace live in schema 'analytics'. Try analytics.order_events."
}

The model reads hint and retries with the right schema on the next call. The same task would have looped on "table not found" indefinitely with a bare error string.

Why this matters: errors are conversational signals to the agent. error_code lets your code branch, message lets a human read the log, hint teaches the model how to recover.

Knowledge points in this lesson

Errors should be machine-readable
Include error_code, message, hint
Hints should suggest a next action
Don't leak internals in error messages
Codes should be stable across versions

Quick check

Tool Design & MCPSelect all that apply

Which fields belong in a good tool error response? (Select all that apply)