Tool calls: the round-trip loop, schema validation, and the guard against runaway agents

A support agent ships. A customer types “cancel my last order.” The model confidently emits a tool call: POST /orders/{id}/cancel with id: "ord_9f3c" — an id it never saw, fabricated to look plausible. The handler ran eval-style: it trusted the arguments and fired the request. Wrong customer’s order, cancelled. Worse, the next week a different bug had the model re-calling a failing lookup_order tool 40 times in one turn before anyone killed it — $9 of tokens for a question that had no answer. Both bugs share one root cause: the loop trusted the model.

The round-trip loop is a contract, not a function

Tool calling makes a model behave like a function you call, but the wiring is inverted: the model is the caller and your code is the callee. You declare the tools; the model decides when to invoke one and emits a structured request; your code runs it. The model never executes anything itself.

The canonical shape is a while loop keyed on the response’s stop_reason:

1. Send the request with your tools array and the user message.
2. The model responds with stop_reason: "tool_use" and one or more tool_use blocks (each has a tool name and a JSON arguments object).
3. Execute each tool. Format outputs as tool_result blocks.
4. Send a new request with the full history plus those tool_result blocks.
5. Repeat while stop_reason is still "tool_use". Exit on "end_turn" (final answer), "max_tokens", "stop_sequence", or "refusal".

The load-bearing detail seniors internalize: step 4 is a brand-new model call. A three-tool task is four model invocations, each re-sending the whole growing transcript. This is why tool latency dominates — and why the loop guard below is not optional.

Tools are JSON-schema declarations

Each tool is a name, a description, and an input_schema — a JSON Schema object describing the arguments. The model reads the schema the same way a developer reads a function signature. The schema is doing real work: it both tells the model how to call the tool and gives you the contract to validate against before you execute.

Schemas are not free. A typical tool definition costs roughly 500 tokens; ten tools is ~5,000 tokens of overhead on every request in the loop, since the full tools array is re-sent each round. A 10-tool agent running a 6-step task pays that 5,000-token tax six times. This is the first place prompt caching earns its keep — caching the static tools block can cut input cost 40–80% and improve time-to-first-token.

Parallel calls cut latency — but not every chain can use them

Modern models (Claude 4-class) will, when several independent tools are needed, emit multiple tool_use blocks in a single response. You run them concurrently and return all the tool_result blocks together. That collapses three sequential round trips into one — a real latency win, because each round trip is a fresh model call of hundreds of ms to seconds.

The catch is dependency. Parallelism only helps when the calls are independent (get_weather(NYC) and get_weather(SF)). A chain where call two needs the output of call one (find_user then cancel_user_order) is inherently serial and cannot be parallelized — the model has to see the first result before it can fill the second tool’s arguments. You can set disable_parallel_tool_use: true to force one tool per turn when your execution layer can’t safely run things concurrently.

Validate arguments — never trust them

The model emits plausible JSON, not correct JSON. It can hallucinate an id, invent an enum value the schema never listed, omit a required field, or pass a string where a number belongs. The opening disaster — a fabricated ord_9f3c fed straight into a cancel endpoint — is the canonical failure: the handler treated model output as trusted input.

The senior discipline is a hard gate before execution:

• Schema-validate the arguments against the tool’s input_schema (a validator like Pydantic or jsonschema). Reject malformed shapes outright; never eval or blindly destructure them.
• Authorize and existence-check the referenced entities. A well-formed id is still untrusted — confirm the order exists and belongs to this caller before acting on it.
• On rejection, return a tool_result with an error, not an exception that breaks the loop. The model reads the error and can self-correct on the next turn — that feedback path is the whole point of returning structured tool errors.

Treat tool arguments exactly like any other untrusted user input crossing a trust boundary, because that is precisely what they are.

The max-iteration guard against runaway loops

Without a turn cap, a confused model loops forever: it calls lookup_order, gets an error, calls it again with the same arguments, gets the same error, and repeats. Each iteration is a full model call billing the entire accumulating transcript — costs and tokens climb with every step. This is a real outage and a real bill (one stuck turn quietly burned $9 of tokens before a human intervened).

Two guards, both mandatory in production:

1. A hard iteration cap — for step in range(MAX_STEPS) (often 8–15). Hit the cap, stop the loop, return a graceful failure to the user. Never while True.
2. Loop / repeat detection — if the model calls the same tool with the same arguments twice in a row, that is a stuck signal. Break, or inject a message telling it the call already failed so it stops repeating.