Error Handling for Tools

Tools must return informative, structured error messages that help the model 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: 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 returns 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 escalate to a human.