Tool Error Handling
Tools fail. Without error handling, an AI either proceeds unaware of the failure or repeats the same call indefinitely.
Make Error Messages Actionable
To an AI, an error message is the input that determines the next move. Include not just the cause but the options available.
# No clue
Error: failed
# Actionable
Error: File 'config/settings.json' not found.
Check the path, or inspect the directory contents with list_files.Avoid returning raw stack traces. They carry volume but rarely point to a next action.
Never Hide a Failure
The most dangerous design returns a normal-looking result after a failure.
| Design | How the AI reads it | Outcome |
|---|---|---|
| Returns an empty array on failure | Interprets it as “no matches” | Proceeds on a wrong conclusion |
| Returns an error on failure | Recognizes the failure | Retries or escalates to a human |
“Nothing was found” and “retrieval failed” are different states. Return them distinguishably.
Match Retries to Error Type
Not every error resolves through retry.
| Error type | Example | Retry |
|---|---|---|
| Transient fault | Network drop, congestion, timeout | Effective, a few attempts with backoff |
| Bad input | Invalid parameter, wrong path | Retry after correcting the input |
| Insufficient permission | Access denied | Ineffective, escalate to a human |
| Target does not exist | Deleted resource | Ineffective, revisit the plan |
Retrying an access denial changes nothing. Only transient faults reward a retry.
Cap and Escalate
Set a retry ceiling and hand off to a human once it is exceeded. Without a cap, retries combine with the self-correction loop and can repeat the same failure for a long time.
Summary
- Error messages should carry both the failure and a clue about the next action
- Returning a normal-looking result on failure lets the AI proceed on a wrong conclusion
- Retries help only for transient faults, not for permission problems
- Cap retries and escalate to a human beyond the limit