Returning Errors as Results
The most important principle of tool error handling is: return errors as tool results, never throw exceptions that break the agentic loop. When a tool fails, return a structured error message that tells the model what went wrong and what it can do about it.
For example, instead of crashing when a database query fails, return: 'Database connection timed out after 5 seconds. The database may be temporarily unavailable. Try again in a moment or use an alternative data source.' This gives the model enough context to make an intelligent recovery decision.
Error Categories and Model Guidance
Structure error responses to help the model choose the right recovery action. Include: the error type (transient vs. permanent), what caused it, and suggested next steps.
Transient errors (timeouts, rate limits) suggest retrying. Permanent errors (invalid parameters, not found) suggest trying a different approach. Permission errors suggest escalating to the user. Include this guidance in the error message so the model can act appropriately.
is_error Flag in Tool Results
The Claude API supports an is_error flag on tool_result content blocks. When set to true, it signals to the model that the tool call failed. The model can then adjust its behavior — it might retry, try an alternative tool, or inform the user.
Always use is_error: true for genuine failures. Do not use it for empty results (no search results found is a valid result, not an error). The distinction between 'no results' and 'error' matters for how the model interprets the response.
Key Concept
Errors Are Information, Not Crashes
When a tool fails, the error message is valuable information that helps the model recover. Treat tool errors as informative results, not catastrophic failures. A well-crafted error message with the error type, cause, and recovery suggestions enables Claude to self-correct. A bare exception message or a crash gives it nothing to work with.
Exam Traps
Using is_error for empty results
An empty search result is not an error — it means the query had no matches. Reserve is_error for actual failures (timeouts, permission denied, server errors). The model handles 'no results found' differently from 'search failed.'
Returning generic error messages
A message like 'An error occurred' gives the model no information to act on. Include specific details: what failed, why, and what the model should try next.
Silently swallowing errors
Returning a fake success result when a tool fails misleads the model. It will make decisions based on incorrect information. Always report failures honestly.
Check Your Understanding
An agent calls a 'get_user_profile' tool with a user ID that doesn't exist. The database returns no results. How should the tool respond?
Build Exercise
Build Robust Tool Error Handling
What you'll learn
- Return structured error results from tools
- Distinguish between errors and empty results
- Use the is_error flag correctly
- Help the model recover from tool failures
Create a tool that calls an external API and can fail. Implement error handling that returns a structured error message with type, cause, and suggested recovery.
WHY: Structured error messages give the model the information it needs to recover.
YOU SHOULD SEE: On failure, the tool returns a descriptive error with recovery suggestions.
Implement the distinction between 'no results' (successful but empty) and 'error' (something broke). Test both cases.
WHY: The model needs to differentiate between 'nothing found' (try different search terms) and 'search broken' (wait and retry).
YOU SHOULD SEE: Empty results return is_error: false with a descriptive message. Failures return is_error: true.
Add retry logic inside the tool for transient errors (timeouts, rate limits). Only surface the error to the model after retries are exhausted.
WHY: The tool should handle recoverable errors internally before bothering the model.
YOU SHOULD SEE: Transient errors are retried 2-3 times. Only persistent failures reach the model.
Test with Claude: create a scenario where the tool fails and observe how the model responds to your error messages. Refine messages based on model behavior.
WHY: The quality of error messages directly affects model recovery. Test and iterate.
YOU SHOULD SEE: The model adapts its behavior based on error type — retrying for transient errors, trying alternatives for permanent ones.
Sources
- Tool Use: Handling Tool Errors— Anthropic Documentation
- Tool Use Best Practices— Anthropic Documentation