Designing error messages for AI agents

The core principle

For an agent, the error message is the documentation. Agents frequently discover a requirement only from a runtime error — never from the docs. A human reads an error, forms a hypothesis, and goes hunting. An agent takes the error text literally and acts on it. So:

• A vague error → wasted tool calls.
• A misleading error → the agent confidently does the wrong thing.
• A silent failure → the agent thinks it succeeded and moves on (the worst case).

Across 3,500+ agent runs, the lowest-scoring tools rarely lost on missing features. They lost on errors that gave the agent nowhere to go. The highest-scoring tools let agents self-correct in seconds — because the error string named the fix.

The spec: every error answers four questions in its own body