Error Handling for Search Tools in Function-Calling Loops
What to return to the model when a search call fails, times out, or comes back empty.
How it works
A function-calling loop treats a tool's return value as just another piece of context the model reasons over, which means error states need to be represented as structured, model-readable text rather than allowed to throw an unhandled exception that crashes the agent turn. The design question is what shape an error takes — a distinct field the model can recognize, versus a message indistinguishable from a legitimate empty result.
Example
Instead of letting a timeout propagate as an unhandled exception, a well-designed wrapper catches it and returns {status: "error", reason: "timeout", message: "Search timed out after 5s — consider a narrower query or trying again."} so the model can decide whether to retry with a different query, rather than receiving a blank tool response it might interpret as 'no results exist.'
Pitfalls
- Returning an empty array for both 'genuinely no results' and 'the API call failed' gives the model no way to distinguish the two, and it will often treat both as confirmation that nothing relevant exists.
- Letting a raw stack trace or provider error message reach the model as tool output wastes tokens and can confuse the model into treating internal error text as search content.
- Not capping retries on a failing tool call can trap an agent loop in a repeated failure cycle that burns the turn budget without ever surfacing the problem to a human.