A newcomer reading about agents meets sentences like "the model calls the roof API". Case UW-T02, one of this site's own cases, shows why that sentence is wrong. In its first turn the underwriting agent's model asks for a tool named get_roof_report. No such tool exists. The catalog has get_roof_assessment. If the model really called things, something would have happened: an error from a server, a request to an endpoint that does not exist, perhaps a request to one that does. Instead, nothing happened at all. The application looked the name up, found nothing, executed nothing, and sent back a short message:
{"ok": false, "error": {"code": "unknown_tool", "message": "No tool named 'get_roof_report' is offered. Use only the tools in the catalog you were given.", "retryable": false}, "meta": {"tool": "get_roof_report", "attempt_number": 0, "duration_ms": 0, "evidence_ids": []}}
The model read it, asked for get_roof_assessment in its next turn, and the run went on. attempt_number 0 is the whole story: zero attempts, because the model's request was only text, and the text named nothing the application was willing to run.
A tool is a capability the model may request; the model proposes a call, and application code validates and executes it. Functions looked at the code that runs. This page is about the conversation around it: what the model is given, what it writes, how the result finds its way back to the right request, and when the asking stops.
A request, not a call#
The mechanism has a name in vendor documentation, function calling, also called tool use. In plain words: the application tells the model which tools exist, and the model may answer with a structured request for one of them instead of, or as well as, ordinary text.
A tiny example. The application sends, together with the conversation, one definition:
{"name": "get_roof_assessment", "description": "Look up the roof age that the roof-data provider assessed for one submission. Reads only; changes nothing.", "input_schema": {"type": "object", "properties": {"submission_id": {"type": "string", "pattern": "^SUB-[0-9]{4}$"}}, "required": ["submission_id"], "additionalProperties": false}}
(The description is shortened; the full one is in tools.py, and Schemas takes the definition apart.) The model, when it wants the roof age, answers with a request:
{"id": "call_01", "name": "get_roof_assessment", "arguments": {"submission_id": "SUB-1004"}}
That is the tool call: a name the model chose from the offered list, arguments it filled in, and a tool call id. The tool call id is a label for this one request, so that the answer can be matched to it later. The model's turn ends there. It has not received anything yet, and it will not continue until the application sends something back.
Before AI. The closest pre-AI pattern is a command message. A front end puts {"command": "RecordPayment", "orderId": 77, "correlationId": "c-91"} on a queue; a handler in the back end validates it, checks permissions, executes it or rejects it, and publishes a reply with the same correlation id. The sender never touches the database. A tool call is a command written by a model, and the tool call id is its correlation id.
The loop#
One request and one answer would be enough if a task needed one tool. The underwriting agent needs several, and it cannot know which until it has read the earlier results: the eligibility check needs the roof age from the provider. So the application runs a loop. Each pass through the loop is one turn of the model.
- The application sends the conversation so far, plus the tool definitions, to the model.
- The model answers with one or more tool calls, or with a final answer and no calls.
- If there are no calls, the loop stops: the model has finished.
- Otherwise, for each call, the application validates, authorizes and executes it, and appends the tool result to the conversation under the call's id.
- Back to step 1, until the model stops or a limit is reached.
A tool result is what the application sends back to the model for one call: the function's return value wrapped in this site's result envelope, or an error. It is keyed by the same id the model gave the call. That key is the only thing that connects an answer to its question, so it must be copied exactly.
This pattern, a model in a loop with tools between its turns, is called the agent loop. Here is the version that runs in the example, quoted from loop.py, function run (the excerpt is the loop itself; setup and the returned summary are left out):
for turn in range(1, max_turns + 1):
turns = turn
m_span = tracer.start("model_turn", f"model turn {turn}", root, turn=turn)
reply = model.respond(messages, definitions)
tracer.end(m_span, **{"tool_calls": [c["name"] for c in reply["tool_calls"]]})
messages.append(reply)
if not reply["tool_calls"]:
stopped = "final_answer"
break
for call in reply["tool_calls"]:
envelope = executor.execute(world, caller, call["name"], call["arguments"], call["id"], tracer, root, run_id)
messages.append({"role": "tool", "tool_call_id": call["id"], "name": call["name"], "content": envelope})
Read it for who acts. model.respond is the only line where the model takes part, and all it returns is a message. executor.execute is the application's execution adapter: it looks the name up, validates the arguments against the schema, checks the caller's scope, and only then runs the function. The for line holds the limit: at most max_turns passes, 8 by default. And the message the loop appends carries tool_call_id, copied from the call.
The message shape here is neutral and small: roles user, assistant and tool, tool calls as id, name, arguments. The docstring of loop.py says it is modelled on, not identical to, the message formats of provider APIs. The real shapes come later on this page.
Diagram: The tool-calling loop · case UW-004, four model turns
Time runs down the page. The model only ever writes messages; the application and its adapter do everything else. Each result goes back under the id of the call it answers. The loop ends when the model writes an answer with no tool call.
- Application (the loop) to Model (scripted stand-in): Request + five tool definitions. The broker email, submission SUB-1004, run id run-7f3a and the idempotency key, with the definitions.
- Model (scripted stand-in) to Application (the loop): call_01, call_02, call_03 (three reads). Parallel tool calls: roof assessment, guidance search, similar decisions. Each has its own id.
- Application (the loop) to Execution adapter: Execute each call. One call at a time in this example, in the order the model wrote them.
- Execution adapter to Functions and the world: Validate, authorize, run. Only now does code touch the world.
- Application (the loop) to Model (scripted stand-in): Three results, keyed by call id. Each result is appended under the id of the call it answers.
- Model (scripted stand-in) to Application (the loop): call_04 check_eligibility. The model uses the roof age it read; the rules answer escalate, R-ROOF-03.
- Model (scripted stand-in) to Application (the loop): call_05 record_recommendation. The one write. The adapter checks scope uw.recommend and the idempotency key; one row is stored.
- Model (scripted stand-in) to Application (the loop): Final answer, no tool call. Recommend escalate, citing R-ROOF-03. With no call in the message, the loop stops.
- Application (the loop): Stop: a person decides. The recommendation waits in the underwriter cockpit with status awaiting_underwriter.
The model's side: a scripted stand-in#
The example has no model. Its place is taken by a class, ScriptedModel in model_stand_in.py, which reads the conversation and writes what a careful model would write. The model here is a scripted stand-in, so these results show how the tool layer works, not how good any model is. Two parts of it matter for the protocol. The first numbers the calls:
def _call(self, name: str, arguments: dict[str, Any]) -> dict[str, Any]:
self._next_id += 1
return {"id": f"call_{self._next_id:02d}", "name": name, "arguments": arguments}
The second writes the first turn: three reads requested together.
# Turn: the three reads, requested together (parallel tool calls).
if not any(n in names for n in ("get_roof_assessment", "get_roof_report", "find_similar_decisions")):
roof = {"bad_arguments": ("get_roof_assessment", {"submission_id": int(sid[4:])}),
"unknown_tool": ("get_roof_report", {"submission_id": sid})}.get(
self.variant, ("get_roof_assessment", {"submission_id": sid}))
batch = [self._call(*roof)]
if self.variant != "shortcut":
batch.append(self._call("search_guidance", {"query": query, "top_k": 5}))
batch.append(self._call("find_similar_decisions", {"submission_id": sid}))
return say(*batch)
(Both quoted verbatim from ScriptedModel, the second from its method respond, with the leading indentation removed; the loop excerpt above is dedented the same way.) Note the variants. For case UW-T01 the stand-in writes the submission id as a number, and for UW-T02 it asks for a tool that does not exist. Those are the mistakes the application must survive, scripted so they happen every time.
Case UW-004, turn by turn#
Here is the default case run through the loop, in a scratch copy of the example. The script below was written for this page; it runs loop.run on one case and prints each message of the conversation on one line. A successful run proves three things: the model asked for three tools in one turn, every result came back under the id of its request, and the loop stopped because the model wrote a final answer, not because it hit the limit.
import json
import sys
import loop
from run_cases import load_cases
max_turns = int(sys.argv[2]) if len(sys.argv) > 2 else loop.MAX_TURNS
result = loop.run(load_cases(sys.argv[1])[0], max_turns=max_turns)
for i, m in enumerate(result["messages"], 1):
if m["role"] == "user":
print(f"{i:2} user request text, {len(m['content'])} characters")
elif m["role"] == "assistant" and m["tool_calls"]:
calls = ", ".join(f"{c['id']} {c['name']}" for c in m["tool_calls"])
print(f"{i:2} assistant tool calls: {calls}")
elif m["role"] == "assistant":
print(f"{i:2} assistant final answer: {json.loads(m['content'])['recommendation']}")
else:
env = m["content"]
status = "ok" if env["ok"] else "error " + env["error"]["code"]
print(f"{i:2} tool {m['tool_call_id']} {m['name']}: {status}")
print("stopped:", result["stopped"], "| turns:", result["turns"])
cd examples/uw-tools
/opt/homebrew/bin/python3 show_messages.py UW-004
1 user request text, 809 characters
2 assistant tool calls: call_01 get_roof_assessment, call_02 search_guidance, call_03 find_similar_decisions
3 tool call_01 get_roof_assessment: ok
4 tool call_02 search_guidance: ok
5 tool call_03 find_similar_decisions: ok
6 assistant tool calls: call_04 check_eligibility
7 tool call_04 check_eligibility: ok
8 assistant tool calls: call_05 record_recommendation
9 tool call_05 record_recommendation: ok
10 assistant final answer: escalate
stopped: final_answer | turns: 4
Ten messages, four model turns. Message 1 is the application's request: the broker's email, the submission SUB-1004, the run id run-7f3a and the idempotency key to use for the write. Message 2 holds three calls at once. Messages 3 to 5 are their results, each under its own id. In message 6 the model has read "22 years" from call_01 and asks for the eligibility check with both roof ages; the result says escalate under rule R-ROOF-03. Message 8 asks for the one write, record_recommendation. Message 10 is the final answer, and since it holds no tool call, the loop ends. The model recommends; a person decides. The stored row waits with status awaiting_underwriter for the underwriter in the cockpit.
The lab below steps through this run. The message list grows turn by turn, and a bar marks who acts at each step: model, application, adapter or person. Use Back and Next, or the arrow keys, and pick another case to see a different path. The table after it holds the same steps.
| Step | Who acts | What happens |
|---|---|---|
| 1 | application | Sends the request (broker email, submission, run id and idempotency key) with the tool definitions |
| 2 | model | Proposes three calls in one turn: call_01 get_roof_assessment, call_02 search_guidance, call_03 find_similar_decisions |
| 3 to 8 | adapter, then application | Executes each call (validate, authorize, execute) and appends each result under its call id; the roof result says 22 years, EV-ROOF-0412 |
| 9 to 11 | model, adapter, application | call_04 check_eligibility: outcome escalate, rule R-ROOF-03 |
| 12 to 14 | model, adapter, application | call_05 record_recommendation: one row, status awaiting_underwriter |
| 15 | model | Final answer: recommend escalate, cite R-ROOF-03; no tool call, so the loop ends |
| 16 | application | Stops the loop; the underwriter decides in the cockpit |
Several calls in one turn#
Message 2 asked for three tools at once. These are parallel tool calls: several independent requests written in one model turn, each with its own id. They save turns, and every turn is a full round trip to the model. The three reads do not depend on each other, so there is no reason to ask for them one at a time.
"Parallel" describes how the model wrote them, not how they must run. As documented on 2026-11-17, Anthropic's documentation says parallel tool use is on by default and that the API does not prescribe an execution order: running the calls concurrently or one after another is your choice. It also says all results of such a turn should go back in one user message. The example runs them one after another, in the order the model wrote them, so the trace is the same on every run. That is a choice for teaching. A production adapter would often run the three reads concurrently, because the slowest one, the roof-data provider, then sets the waiting time instead of the sum of all three.
The matching by id is what makes either choice safe. Gemini's documentation, read the same day, says results of parallel calls may be returned in any order because each one is matched by its id. Get the ids wrong and the model reads the guidance search as the roof result.
You can also turn parallel calls off. OpenAI's guide, as documented on 2026-11-17, says parallel_tool_calls: false limits the model to zero or one tool call per turn; Anthropic's puts disable_parallel_tool_use: true inside its tool_choice object. Turning it off is a way to force a strict order, at the cost of more turns.
Forcing a tool, or forbidding one#
By default the model decides whether to call a tool at all. Sometimes the application knows better. A step that only extracts fields from an email should always call the extraction tool. A final summary step should call nothing. The request field for this is called tool choice, and the three providers read for this page offer similar options under different spellings, as documented on 2026-11-17:
| Intent | Anthropic tool_choice | OpenAI tool_choice | Gemini (Interactions API) tool_choice |
|---|---|---|---|
| The model decides (default) | auto | "auto" | auto |
| Must call some tool | any | "required" | any |
| Must call this tool | {"type": "tool", "name": "..."} | {"type": "function", "name": "..."} | any with a restricted list of allowed tools |
| Must not call any tool | none | "none" | none |
One documented restriction changes how this table can be used today. Anthropic's "Define tools" page, read on 2026-11-17, says forced tool use is not supported on several current models: on Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 and Claude Mythos 5.1, any and tool return a 400 error. auto and none still work. The page suggests auto with strict tool use, which guarantees schema-valid inputs, or structured outputs when a fixed JSON shape is needed. It also says the two forcing options fail with manual extended thinking. A design that depends on forcing a tool therefore depends on the model behind it, and a model upgrade can turn a working request into an error.
Production pitfall. Forbidding a tool by request option is a convenience, not a control.noneasks the model not to call tools; it does not stop your loop from executing a call that arrives anyway, through a bug, a different code path or another model. The control is the registry and the adapter: a tool the application does not offer for this step cannot run, whatever the model writes. That is howUW-T08stays safe: the broker asks to update the roof age, and no tool that changes a submission exists.
What the model never sees#
The model sees three things: the tool definitions, the conversation, and the results the application chose to send. Everything else stays in the application. That boundary is a security property and a design tool, so it is worth listing what lies outside it in the example.
| Kept from the model | Where it lives | Why it matters |
|---|---|---|
| The Python function and its body | functions.py | The model knows a tool only by its definition |
The World: provider connection, stored rows, clock | passed by loop.run | The model cannot fill in or replace the context a function runs in |
| The caller's identity and scopes | tools.py CALLER_SCOPES, checked by the adapter | Permission is decided by code, not argued by the model |
| Retries and attempts | the adapter; visible only in the trace | The model sees one result per call, even after two attempts |
| Audit events | World.audit | A refused write is recorded for people, never shown to the model |
| Exception text and stack traces | caught by the adapter | The model gets a message written per error code |
| Secrets such as provider credentials | never in any message | What the model reads it can repeat |
One item is a deliberate exception in this example. The idempotency key appears in the request text, and the model copies it into the record_recommendation call. The example's README notes that a stricter design injects the key in the adapter, so the model never sees it. Safety discusses that choice.
Common confusion. "The model never sees it" does not mean "the model cannot influence it". The model chooses the arguments, and arguments reach the function. That is why arguments are validated and authorized in code even though the function's body is hidden.
Diagram: What the model sees, and what stays in the application
Read left to right. The first column is everything the model ever reads. The other columns are the application's: what decides whether a call runs, what does the work, and what is recorded for people. Click a box for the example's version.
- 1 · Seen by the model
- Tool definitions: The model's whole knowledge of each tool.
- Tool results: One result per call, written by the adapter: data, or an error with a code and a message.
- 2 · Decides what runs
- Registry and scopes: A name not in the registry is unknown_tool; a caller without the scope is not_authorized.
- 3 · Does the work
- Functions and the World: The code that runs and the context it runs in, passed by the application.
- Attempts and retries: The adapter may try a call twice; the model sees one result.
- 4 · Recorded for people
- Audit events and traces: Refusals and writes are audited; every call and attempt is a span in the run's trace.
When the loop goes wrong#
Three failures show up on the first day of running a loop, and the example has a case or a run for each.
An unknown tool. In UW-T02 the model asks for get_roof_report. The application must look the name up in its own registry and never dispatch on a name it does not know, for example by building a method name from the text. It answers unknown_tool with attempt_number 0, and the model recovers in its next turn.
Bad arguments. In UW-T01 the model sends {"submission_id": 1004}, a number. The adapter validates before it executes and answers invalid_arguments with the failing path, /submission_id: expected string, got integer. Anthropic's documentation, as documented on 2026-11-17, describes the same recovery: return the error in a tool result marked is_error, and the model will typically try again with corrections. Here is that run, from the same script:
/opt/homebrew/bin/python3 show_messages.py UW-T01
1 user request text, 809 characters
2 assistant tool calls: call_01 get_roof_assessment, call_02 search_guidance, call_03 find_similar_decisions
3 tool call_01 get_roof_assessment: error invalid_arguments
4 tool call_02 search_guidance: ok
5 tool call_03 find_similar_decisions: ok
6 assistant tool calls: call_04 get_roof_assessment
7 tool call_04 get_roof_assessment: ok
8 assistant tool calls: call_05 check_eligibility
9 tool call_05 check_eligibility: ok
10 assistant tool calls: call_06 record_recommendation
11 tool call_06 record_recommendation: ok
12 assistant final answer: escalate
stopped: final_answer | turns: 5
One more turn and one more call than UW-004, and the same final answer. The error cost a turn; it did not cost the run.
A loop that does not end. A model that keeps asking for tools would run forever without a limit. The example's loop stops after max_turns. The run below gives the same case a limit of two turns, so it stops before the write. A successful run shows stopped: max_turns and no final answer:
/opt/homebrew/bin/python3 show_messages.py UW-004 2
1 user request text, 809 characters
2 assistant tool calls: call_01 get_roof_assessment, call_02 search_guidance, call_03 find_similar_decisions
3 tool call_01 get_roof_assessment: ok
4 tool call_02 search_guidance: ok
5 tool call_03 find_similar_decisions: ok
6 assistant tool calls: call_04 check_eligibility
7 tool call_04 check_eligibility: ok
stopped: max_turns | turns: 2
The loop ended with evidence gathered and nothing recorded. That is the safe direction to fail in: no recommendation reaches the underwriter, and the run's summary says why. What the application does next (report, retry the run, hand it to a person) is a decision for the harness around the loop.
What this is not. This page explains the protocol and the minimum loop. The runtime around it, with stop conditions, saved state, budgets and the choice between writing the loop and letting an SDK run it, is the agent harness: Harness Engineering covers it, including a loop in which every exit has a name. Messages between agents, rather than between a model and its tools, belong to https://a2a.sammuthu.com.
The same protocol, three providers#
Every provider read for this page implements the same five steps. They differ in field names, in where the id lives, and in which role carries the result. The shapes below are the documented shape; not run here. They are written from each provider's documentation as read on 2026-11-17, trimmed to one call and one result for SUB-1004. The ids are illustrative; each provider generates its own.
Anthropic Messages API
{"role": "assistant", "content": [
{"type": "tool_use", "id": "toolu_01", "name": "get_roof_assessment", "input": {"submission_id": "SUB-1004"}}
]}
{"role": "user", "content": [
{"type": "tool_result", "tool_use_id": "toolu_01", "content": "{\"ok\": true, \"data\": {\"roof_age_years\": 22}}"}
]}
The response that carries tool_use blocks has stop_reason "tool_use". The result goes in a user message; tool_result blocks must come first in it, before any text, and must immediately follow the assistant message that asked. An error result adds "is_error": true. The arguments are an object named input.
OpenAI Responses API
{"type": "function_call", "call_id": "call_01", "name": "get_roof_assessment", "arguments": "{\"submission_id\": \"SUB-1004\"}"}
{"type": "function_call_output", "call_id": "call_01", "output": "{\"ok\": true, \"data\": {\"roof_age_years\": 22}}"}
The call is an output item and the result an input item, matched by call_id. The arguments are a JSON-encoded string that your code must parse, not an object. The guide says the output should typically be a string, and that a response may contain several function_call items.
Gemini Interactions API
{"type": "function_call", "id": "fc_01", "name": "get_roof_assessment", "arguments": {"submission_id": "SUB-1004"}}
{"type": "function_result", "call_id": "fc_01", "name": "get_roof_assessment", "result": [{"type": "text", "text": "{\"ok\": true, \"data\": {\"roof_age_years\": 22}}"}]}
These are steps of the Interactions API, which the Gemini documentation now uses on its default function-calling page; the older generateContent shape, with functionCall and functionResponse parts, is on a separate page. The result step names the function and carries the call's id as call_id, with the result as a list of content blocks.
Three differences matter in code. The arguments arrive as an object from two providers and as a string from one, so parsing can fail before validation even starts. The result travels in a user message for one provider and as a separate item or step for the others. And the field holding the id is named differently each time: id and tool_use_id, call_id, id and call_id. The idea under the names is the same: copy the id. Frameworks describes each provider's API in its own section, and MCP's tools/call, the standard way to reach tools in another process, has its own pages starting at MCP architecture.
In a coding agent. A coding agent runs the same loop with different tools. Asked to fix a failing test, the model requestssearch_codeandread_filein one turn, thenedit_file, thenrun_tests, and reads each result by its id. The harness executes the reads at once and stops to ask the person beforegit_push, because that call writes where others will see it. Whatever the model writes, the harness decides which requests run.
Running parallel calls: order, dependencies and writesConcurrency is your choice; the model's batch is not a transaction and not a dependency graph
A batch of calls in one turn carries no promise that the calls are independent. The model wrote them together because it believed they were. Usually it is right; sometimes it puts check_eligibility next to get_roof_assessment, and the eligibility check then runs without the provider's figure. The application cannot detect that from the batch. It can make it harmless: the rules treat a missing provider figure as missing, not as zero, and the model will see a weaker result and can ask again.
Writes in a batch need a rule. Running a write concurrently with the reads it depends on can store a recommendation built on half the evidence. A defensible policy is: execute reads concurrently, execute writes alone and last, and if a batch mixes them, run the reads first. The example never puts the write in a batch; its stand-in asks for it in a turn of its own.
A batch is not a transaction either. If two of three calls succeed and one times out, all three results go back: two ok, one timeout. The model decides what to do with a partial picture. Rolling back the two successful reads would be meaningless; rolling back a successful write would need its own compensating write, which belongs to https://reliable.sammuthu.com.
Finally, concurrency changes the trace. Spans of concurrent calls overlap, and their order in a log depends on timing. Keep the call id on every span and sort by it when a test compares traces; the example runs calls in order partly so that its traces are byte-identical between runs.
What forcing a tool costsPrefilled turns, skipped thinking, cache invalidation, and model-dependent support
Anthropic's documentation, read on 2026-11-17, lists three side effects of forcing a tool. With any or tool the API prefills the assistant turn, so the model writes no explanation before the call. Forcing a tool skips thinking on every model that accepts it: the response starts with the call. And changing tool_choice between requests invalidates cached message blocks when prompt caching is used; tool definitions and the system prompt stay cached.
Each of these is a reason to force a tool only for narrow, mechanical steps: extract these fields, classify this email. For a step that needs judgment, forcing removes the reasoning that would have made the call a good one.
The documented restriction on several current models turns this into a portability question. A pipeline written for a model that accepts any will fail with a 400 error after an upgrade to one that does not. Two ways around it are documented: auto with strict tool use, which guarantees that a call, if made, matches the schema; or structured outputs, which skip the tool and constrain the final answer's shape directly. Neither guarantees that a call is made. If the application needs the call, it must check after the turn and react, for example by asking again with an instruction, or by failing the step.
OpenAI documents a further option, allowed_tools, which restricts the model to a subset of the tools without changing the tools list; its guide says this helps prompt caching. Gemini's documentation also has an allowed_tools setting. Restricting the subset per step is close to what the example's registry does per caller, with one difference: a request option asks the model; the registry decides what can run.
Call ids: who makes them, what they are notNever derive an idempotency key from a call id, and never trust an id to be unique across runs
The model, or the provider's API on its behalf, generates the tool call id. Your code copies it into the result and should treat it as opaque. Gemini's documentation for the generateContent shape, read on 2026-11-17, says the id is now always returned for Gemini 3 models, which implies older setups could see calls without one; code that matches results by position instead of by id breaks quietly when parallel calls arrive.
A call id identifies one request in one conversation. It is the wrong key for a write. If the model asks for record_recommendation, reads a timeout, and asks again, the second request has a new call id; a key derived from the call id would let both writes through. The example's key, SUB-1004:run-7f3a:recommendation, is built by the application from the submission and the run, so every attempt and every repeated request of that one logical write shares it.
Call ids are not unique across runs either: the stand-in starts at call_01 in every run, and providers promise uniqueness only where their documentation says so. For tracing, pair the call id with the run id. On this site one trace covers one run, each tool call is a span carrying its call id, and each attempt is a child span with its attempt number.
Stopping: the model's reason, and yoursFinal answer, turn limit, budget and refusal are different exits and need different handling
The loop has at least two kinds of exit. The model's: it writes an answer without tool calls, which providers report as a stop reason; Anthropic's documentation names "tool_use" for a response that requests client tools, and other values exist for other endings. The application's: a turn limit, a time or token budget, a cancelled run, a refused write. Each needs a different next step, so each should leave a different, named record. The example records stopped as final_answer or max_turns.
A turn limit is a safety net, not a target. Set it from the longest legitimate path plus a margin: the example's longest cases (UW-T01, UW-T02, UW-T07, UW-T08) need five model turns, and the limit is eight. A run that hits the limit is evidence that something is wrong (a model repeating a failed call, a tool that always returns a cursor), and it should be visible in operations, not silently retried.
The most important exit property is the direction of failure. When the loop stops early, nothing should be half-written. In the example the only write is the last step, so an early stop leaves no row. Where a workflow has several writes, order them so that an interrupted run leaves the system in a state a person can understand, or make the run resumable. Named exits, budgets and resumable runs are the subject of https://harness.sammuthu.com.
Checklist for Monday#
| Check | Why |
|---|---|
| The loop dispatches only on names found in the registry, and answers unknown names with a result, not an exception | UW-T02: a wrong name costs one turn and executes nothing |
| Every result carries the call's id, copied exactly; matching never relies on position | Parallel calls may be answered in any order |
| Arguments are parsed and validated before execution, even when the provider promises schema-valid output | The adapter, not the request option, is the control |
| Reads in a batch may run concurrently; writes run alone and last | A batch is neither a dependency graph nor a transaction |
| The loop has a turn limit and records why it stopped | An unbounded loop is a cost and a safety problem |
| Forced tool choice is used only where the model and settings support it, and the code checks that the call was made | Support differs between models, as documented on 2026-11-17 |
| The idempotency key of a write comes from the application, not from the call id | A repeated request has a new call id |
In one breath#
The model never calls anything: the application sends it tool definitions, the model answers with requests made of a name, arguments and an id, and the application validates, authorizes and executes each one and sends the result back under the same id. That repeats in a loop until the model writes an answer without calls or the application's limit stops it. Several calls can come in one turn, a request option can force or forbid tools where the model supports it, and everything that decides what runs stays in code the model never sees.
You can now read any provider's tool-calling messages and write the loop that answers them. What you have taken for granted is the definition the model reads: how does a name, a description and a schema tell the model what submission_id must look like, and which constraints does the provider enforce while generating? That is Schemas.