Tool Errors — Letting the Model Recover

~14 min · tools, error-handling

Level 0Apprentice

0 XP0/100 lessons0/14 achievements

0/120 XP to next level120 XP to go0% complete

Tools fail. The model has to know what to do.

When a tool returns an error, the model receives the error as a tool_result and decides what to do. Without guidance, the model often retries the same call (especially on transient errors), gives up too early, or invents data to fill in for the failed result. Each behavior is a bug; each is fixable in the prompt.

Error-shape conventions

Return errors as structured JSON the model can read: {"error": "<code>", "message": "<text>", "retry": true|false, "hint": "<what to try>"}. This gives the model both a parseable signal and a human-readable hint.

Prompt instructions for error recovery

If a tool returns retry: true, retry once with the same arguments.
If a tool returns retry: false, try a different approach or escalate.
If a tool returns 'not found,' do not invent data; tell the user the lookup failed.
If a tool errors twice, stop and surface the failure.

Code

Structured tool error·json

{
  "error": "customer_not_found",
  "message": "No customer matches CUST-9999.",
  "retry": false,
  "hint": "Check the customer ID format. Ask the user to confirm."
}

External links

Exercise

Inject a deliberate tool error into your agent loop on five different tools. Observe model behavior. Add explicit error-recovery instructions. Re-run.

Progress

Progress is local-only — sign in to sync across devices.

← PreviousMulti-Tool Orchestration Next →Streaming Output — Partial JSON and the Pipeline

Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)

No comments yet — be the first.