Craft · November 16, 2026 · 8 min read

Stop reasons are your agent loop's control flow: handling every way a model turn ends

Every model response says why it stopped, and that one field decides whether your loop runs a tool, continues, retries or gives up. Here is what Anthropic, OpenAI and Gemini actually return, and a small dispatcher that handles all of it.

Some links are affiliate links; we may earn a commission at no extra cost to you. As an Amazon Associate I earn from qualifying purchases. Disclosure

The first agent loop most people write looks something like this: call the model, check whether there is a tool call in the output, run it if there is, otherwise print the text and stop. It works in the demo. Then one day the model writes half a JSON argument and gets cut off, or a server-side search tool hits its iteration limit, or a safety filter declines the request with a perfectly normal 200 status, and the loop treats all of those as "done." The user gets a truncated answer, or nothing, and your logs say the run succeeded.

The fix is not clever. Every major model API tells you why a turn ended, in a field you are probably already receiving and ignoring. Treat that field as the real control flow of your loop, not the presence or absence of a tool call, and a whole class of quiet failures turns into explicit branches you can test. This post walks through what the three big APIs return today and how to turn it into one small dispatcher.

Anthropic: stop_reason on every message

Anthropic's Messages API puts a stop_reason on every successful response, and its handling stop reasons guide is the most complete map of the territory. There are seven values. end_turn means the model finished naturally. tool_use means it wants you to run a tool and send back the result. max_tokens means it ran into the max_tokens limit you set. stop_sequence means it emitted one of your custom stop strings, and the response's stop_sequence field tells you which one. pause_turn means a server-side tool loop, such as web search, hit its iteration limit. refusal means the model declined, and model_context_window_exceeded means the response filled the model's whole context window.

A few of these deserve more attention than the table gives them. The guide is explicit that refusal comes back as a normal HTTP 200, not an error, and that a stop_details object names the policy category that triggered it. stop_details is null for every other stop reason, so it is cheap to log unconditionally. The suggested handling is to retry on a fallback model, which the guide says usually works across the current Claude lineup.

pause_turn is the one that bites agent builders who lean on server tools. The default server-side limit is 10 iterations per request, and when the model hits it the response can contain a server_tool_use block with no matching result. The right move is to append the response to your messages unchanged and send the request again. The guide adds a detail that is easy to miss: if the response includes a container, send its ID back too, because otherwise the next request starts a new container and the files from earlier in the turn are gone.

max_tokens is more dangerous inside a tool loop than in a chat app. If the cut-off happens in the middle of a tool_use block, the arguments are incomplete, and Anthropic's advice is to retry the request with a higher max_tokens rather than try to repair the partial call. For plain text, you can either raise the limit or continue the response with a follow-up request.

Then there is the strange one: an end_turn with an empty body. The guide describes responses of two or three tokens with no content, usually right after tool results, and gives two common causes. One is putting a text block after your tool_result blocks in the same user message, which teaches the model that a user message follows every tool call, so it ends its turn to fit the pattern. The other is sending the model's completed response back without adding anything. The fix is structural: send tool results alone, and if you still get an empty turn, add a new user message asking it to continue rather than resending the same history.

OpenAI: status plus incomplete_details

OpenAI's Responses API does not have a single stop reason string. The create response reference gives every response a status that is one of completed, failed, in_progress, cancelled, queued or incomplete. When the status is incomplete, an incomplete_details object carries a reason, and the reference lists four: max_output_tokens, max_messages, content_filter and steered. The last one is new territory; the reference says it means the response stopped at a safe output boundary after a WebSocket response.steer event, and that the server can then create a successor response automatically with the queued input.

Tool calls are not a status at all. A completed response simply contains function_call items in its output array, each with a call_id, and the function calling guide shows the loop: run the function, append a function_call_output item with the same call_id, and call the API again. So in an OpenAI loop, "should I run tools" is a question about the output items, and "did the turn end cleanly" is a question about status. You need both checks.

The reasoning guide adds the cost angle. If a reasoning model hits max_output_tokens before it produces any visible text, you can still pay for the input and reasoning tokens and get back an incomplete response with nothing usable in it. An agent that retries that blindly with the same limit pays twice for the same empty result. We covered the budgeting side of this in reasoning models in agent loops.

Two of the statuses only matter if you use background mode: queued and in_progress mean the work is not done yet, and cancelled means someone stopped it. If you run long turns that way, our post on background responses and webhooks covers how to wait for the terminal state properly.

Gemini: finishReason per candidate

Gemini puts a finishReason on each candidate, and the generateContent reference lists a long enum. The common ones are STOP, which covers both a natural stop and a stop sequence, and MAX_TOKENS. Then come the filters: SAFETY, RECITATION, LANGUAGE, BLOCKLIST, PROHIBITED_CONTENT, SPII, and a set of image-specific values. A companion finishMessage field gives detail and is only populated when a finish reason is set.

The values agent builders should care about most are the tool-related ones. MALFORMED_FUNCTION_CALL means the function call the model generated was invalid. UNEXPECTED_TOOL_CALL means the model tried to call a tool when none were enabled in the request. TOO_MANY_TOOL_CALLS means the model called too many tools in a row and the system stopped execution. MISSING_THOUGHT_SIGNATURE means the request was missing at least one thought signature, which in practice points at a loop that dropped part of the model's previous turn when it rebuilt the history. And CONTINUATION says the response hit the per-request token limit but generation is not finished, so it can be resumed with the returned continuation_token. The reference notes that max_output_tokens is cumulative across those continuation hops and has to be increased or omitted on each one.

Notice what is not in the list: there is no value that means "the model wants to call a function." Like OpenAI, Gemini signals tool calls through the content itself, as functionCall parts. A loop that only reads finishReason will miss them.

One dispatcher instead of scattered ifs

The three APIs disagree on names, but they agree on the shape of the decision. Every turn ends in one of a handful of outcomes: the model is done, the model wants tools, the provider paused and wants you to continue, the output was cut off, the model or a filter declined, or something is structurally wrong with your request. It is worth normalizing provider responses into that small set at the edge of your code, so the loop itself only ever branches on your own outcome type.

Here is what that looks like for Anthropic, written as a plain match on the stop reason. The OpenAI and Gemini adapters map into the same outcomes.

def classify(resp):
    r = resp.stop_reason
    if r == "tool_use":
        return "run_tools"
    if r == "pause_turn":
        return "continue"
    if r == "max_tokens":
        last = resp.content[-1] if resp.content else None
        return "retry_bigger" if last and last.type == "tool_use" else "truncated"
    if r == "model_context_window_exceeded":
        return "compact"
    if r == "refusal":
        return "fallback"
    if r == "end_turn" and not resp.content:
        return "nudge"
    return "done"

For OpenAI, the adapter checks status first: anything other than completed or incomplete is either still running or a failure, and incomplete maps on incomplete_details.reason, with max_output_tokens becoming truncated and content_filter becoming a refusal. Only if the response completed does it look for function_call items to decide between run tools and done. For Gemini, MAX_TOKENS is truncated, CONTINUATION is continue, the filter family is a refusal, the malformed and missing-signature values are bugs in your request, and otherwise you look for functionCall parts.

The point of the extra layer is that each outcome gets one tested handler. Truncation appends a visible note or raises the limit once. Context overflow triggers compaction, which we covered in context compaction for agent loops. A refusal switches models or surfaces a clear message instead of an empty bubble. A malformed call goes back to the model as an error it can correct, the same way you would feed back any failed tool call.

Put a ceiling on every retry branch

Stop reasons make retries tempting, and retries are where loops burn money. Every branch that sends another request needs its own counter. Anthropic's own pause_turn example caps continuation at five requests and returns the last response if it is still paused. Do the same for truncation retries, nudge retries after empty turns and fallback attempts after refusals, and fold all of them into the run-level budget you already enforce. If you do not have one yet, our post on budget caps for agent runs is a good starting point.

It also pays to record the stop reason on every span. The OpenTelemetry GenAI conventions recommend a gen_ai.response.finish_reasons attribute for exactly this, which we walked through in tracing agent runs. Once it is in your traces, a dashboard of stop reasons per day becomes one of the most useful health checks you have. A sudden rise in max_tokens usually means a prompt or a tool result got longer. A rise in refusals or filter reasons after a model change tells you to check the new model before your users do.

Streaming changes where you read it

If you stream, the stop reason arrives late. Anthropic's guide says stop_reason is null in the initial message_start event and only shows up in the message_delta event near the end. That means a streaming UI should render text as it arrives but hold off on deciding what to do next until the final event lands. Treat the stream as display and the final message as the decision.

The short version

Do not let "no tool call" stand in for "finished." Read the stop field on every turn, map every provider's values into a small set of outcomes your loop understands, give each outcome a handler with a retry ceiling, and log the raw value so you can see when the distribution shifts. It is maybe fifty lines of code, and it turns the failures that used to look like success into branches you can see and test.

If you want a broader grounding in building reliable systems around foundation models, including evaluation and failure handling, AI Engineering by Chip Huyen is a solid companion read.

Newsletter

The daily agent toolkit.

New tools, MCP servers and frameworks, in one short email every morning. Free, no spam. Sign up and get the free AI agent cost cheat sheet (PDF).