When a tool call fails, why return an is_error tool result rather than letting the exception propagate?

## Two places a tool failure can go When the code behind a tool raises, the harness has exactly two choices. It can let the exception propagate — the agent run aborts, the caller gets a stack trace, and the conversation stops mid-turn with an unanswered tool call in it. Or it can catch the failure, serialize it into the tool result that the pending call is waiting for, and mark that result as an error so the model knows the content describes a failure rather than data. Those are not two styles of the same thing. The first removes the model from the loop; the second keeps it in. Everything else follows from that. ## Why keeping the model in the loop is usually right A large share of tool failures are things the model caused and can fix. It passed a date in the wrong format, referenced a record that does not exist, called the read-only tool for a write, filtered on a field the schema does not have. Given a clear error, the model corrects the argument and calls again — recovery that would otherwise have to be hand-coded in the harness for every tool and every failure shape. A second class of failure is not fixable but is still worth knowing about. The billing API is down, the permission was denied, the query timed out. The model cannot repair those, but it can route around them: try a different source, degrade to a partial answer, or tell the user plainly that the step failed. The alternative — a run that dies silently — produces the worst outcome in an agent product, which is a user who never finds out that half the work did not happen. ## What the error flag buys you Marking the result as an error is a small, load-bearing detail. Without it, the failure text sits in the transcript looking exactly like ordinary tool output, and models will sometimes read `Error: user 8831 not found` as a fact about user 8831 rather than as a failed lookup. The flag disambiguates that: this turn is a failure report about the call, not content returned by it. It is also the signal your own telemetry keys off — error rate per tool is one of the most useful agent metrics you can collect, and it is free if failures are tagged consistently. ## The message is what actually determines recovery A flagged result whose body is `Internal error` is almost as useless as a swallowed exception. Useful error text does three things. It names what was wrong in the model's own vocabulary — the argument, the value, the constraint. `start_date must be YYYY-MM-DD; got "last Tuesday"` produces a corrected call on the next turn. `ValidationError at line 214` does not. It says whether retrying could plausibly help. "The upstream service is unavailable; the wrapper already retried three times" stops the model from burning its remaining turns on the same call. Without that sentence, a model faced with an unexplained failure will very often just try again. It says what state the world is in, especially after a partial or side-effecting call. "The transfer request was submitted but the confirmation read timed out; status is unknown" is the difference between an agent that checks and one that duplicates the transfer. What error text must not do is leak internals the model has no business seeing — stack traces, SQL with credentials, internal hostnames, raw tokens. That material adds no recovery value and now lives in the transcript. ## When propagating really is correct Not every failure belongs in front of the model. Programmer errors in the harness — a tool wired up wrong, a serialization bug, a misconfigured client — should fail loudly at development time rather than being smoothed into a polite message the model apologizes about. Failures that violate a hard safety or policy boundary should terminate the run, not invite the model to find another route. And infrastructure faults that make the whole run meaningless — the model provider itself is down, the sandbox died — are the harness's to handle. The useful rule is that the model should see failures it could plausibly act on, and the harness should own everything else. "Could the model do something different because of this?" is the question that decides. ## Consequences downstream Because the failure lands in the conversation, it stays in the conversation. Repeated flagged errors accumulate and can crowd the window and bias the model toward pessimism; a run that has seen four failures in a row often gives up early. That argues for terse errors, for collapsing repeated identical failures, and for a loop-level guard that stops after N consecutive failed calls rather than letting the model rediscover the same wall on every turn.