Error Handling for Tools
definition
Tools must return informative, structured error messages that help the agent understand what went wrong and decide what to do next, rather than throwing opaque exceptions that crash the agent loop. Well-designed error handling includes error codes, human-readable descriptions, and suggested retry strategies that the model can reason about — the difference between "Error 500" and "Rate limited: retry after 30 seconds" determines whether an agent recovers gracefully or loops forever.
Tools must return informative, structured error messages that help the agent understand what went wrong and decide what to do next, rather than throwing opaque exceptions that crash the agent loop. Well-designed error handling includes error codes, human-readable descriptions, and suggested retry strategies that the model can reason about — the difference between "Error 500" and "Rate limited: retry after 30 seconds" determines whether an agent recovers gracefully or loops forever. The most effective pattern is returning errors as structured data within the tool's normal response schema rather than raising exceptions, keeping the agent in its reasoning loop where it can choose to retry, try an alternative tool, or ask for help. This concept connects to error recovery for the agent-level patterns for handling failures, idempotent tools for ensuring safe retries, and resilient tool contracts for designing tools that degrade gracefully.