“finishReason: 'tool-calls'” — the AI SDK call that stops after one step

finishReason: 'tool-calls'

This is not an error and nothing threw. Your tool ran, the call returned, and the finish reason is the loop telling you why it came back: it stopped while there were still tool results sitting in the last step. In the AI SDK the stop condition for that situation has a documented default, and the default is one step — so a call you wrote expecting a tool call and then an answer gives you the tool call and the return.

Where this value comes from

Two sentences in the generateText reference settle it. On the result field:

The reason the model finished generating the text.

and on the parameter that governs when the loop comes back:

Condition for stopping the generation when there are tool results in the last step. When the condition is an array, any of the conditions can be met to stop the generation. Default: isStepCount(1).

Both quoted verbatim from the AI SDK reference page for generateText, fetched 6 October 2026 (HTTP 200, 867,450 bytes). The same page lists the enumerated values of finishReason as 'stop', 'length', 'content-filter', 'tool-calls', 'error' and 'other'.

Read them together and the shape is not a bug: the stop condition is evaluated exactly in the situation you are in — tool results in the last step — and its default is satisfied by the first step. The loop had every reason to return, and 'tool-calls' is the field that records which reason.

The loop’s own exit list

The AI SDK’s loop-control page gives the same parameter a one-line job description:

The `stopWhen` parameter controls when to stop execution when there are tool results in the last step.

and then enumerates every way out:

The loop continues until: - A finish reasoning other than tool-calls is returned, or - A tool that is invoked does not have an execute function, or - A tool call needs approval, or - A stop condition is met

Quoted verbatim from Loop Control, fetched 6 October 2026 (HTTP 200, 647,527 bytes). The same page documents isStepCount as a condition that “stops after a specified number of steps” and hasToolCall as one that “stops when any of the specified tools is called”.

That list is worth keeping, because four different situations all end your run and only one of them is the step count. A tool with no execute function and a tool call awaiting approval are both deliberate hand-backs to your code — the loop is asking you to do something, not giving up. finishReason is how you tell a hand-back from a ceiling.

Confirm it in ten seconds

Read the finish reason, not the text. Branch on finishReason === 'tool-calls' at the call site. That one condition separates “the loop came back with work in its hands” from the values that mean the model itself was done.
Look at what the steps recorded. The reference documents the steps field as “Response information for every step. You can use this to get information about intermediate steps, such as the tool calls or the response headers.” One step in that array, with a tool call in it, is the whole diagnosis.
Then set the condition you actually meant. Pass stopWhen explicitly. The documented default is isStepCount(1), and a default is only wrong when you wanted something else — so say what you wanted, in the call, where the next reader can see it.

The take-away even if you never see this string: in this SDK a multi-step agent is a configured loop, not an implied one. The step budget is an argument with a documented default, and the finish reason is the receipt.

Why a bigger step count moves the wall

The AI SDK ships a higher default where the loop is the point: the loop-control page states that “By default, ToolLoopAgent stops after 20 steps using isStepCount(20)”. One step and twenty steps are two different stop conditions on the same mechanism, and there is nothing special about either number.

So do the arithmetic before you pick one. A step is a pass of the loop — a model call, possibly a tool call, a result — and the number you need is the number of passes your task genuinely has. If the task needed three and you gave it one, raising it to three is the right fix and the matter ends. If you do not know the number, the step count is not the thing to tune: raising it buys the same loop more passes at the same price per pass, and a loop whose stopping condition is never satisfied will spend whatever you give it. hasToolCall exists for exactly that case — stop on the tool that means finished, rather than on a count you guessed.

The restructure: make each step leave something behind

Two changes, in order of how much they buy.

Treat the finish reason as control flow. A run that came back at 'tool-calls' is a run that has results and no conclusion. Branch on it: continue the loop with the accumulated messages — the reference documents responseMessages as “The accumulated response messages of all steps that were generated during the call.” — or record it as unfinished. What you should not do is read the text field and pass it downstream, because the model had not yet been asked to conclude anything.

Persist each step as it completes. Write one record per entry in steps, with its tool call and its result, before you decide what to do next. Then a run that stops early has still deposited the passes that worked, and the next attempt is a continuation rather than a restart.

And the change underneath both, which is not an AI SDK setting: make one step do more. A tool call that handles one item and a tool call that handles forty cost the same single pass of the loop. Runs that need twenty steps are usually not hard, they are iterative — the model walking a list by hand because nothing it was given could walk the list itself. Give it a tool that takes the whole list, and the step count stops tracking the item count.

What is behind this site

There is a written guide: the step-and-turn arithmetic as a formula you can run against a brief before you launch it, the reasons raising a cap does not finish the job, and batch.py, one standard-library file that collapses a per-item loop into a single pass. It is $19, on a storefront that delivers the files automatically and carries a 30-day money-back guarantee (checked 2 October 2026). One working way to pay today is 19 USDC on Base, and delivery is manual: you email the transaction hash and the files come back as a reply. This page is free, ungated, and sells nothing on its own.

The short version: finishReason: 'tool-calls' means the loop returned while there were tool results in the last step, and for generateText the documented stop condition for that situation is Default: isStepCount(1). Nothing failed — a one-step loop did exactly one step. Branch on the finish reason, set stopWhen explicitly, persist every step as it lands, and prefer a stop condition that names the finishing tool over a step count you guessed.

Nearby

recursion_limit, max_iter, max_turns: one wall under four names — what each framework calls this ceiling and what each does on contact.
Reached max steps. — smolagents, where the same ceiling is recorded rather than raised, and a capped run returns looking like a finished one.
Max turns (10) exceeded — the OpenAI Agents SDK, which does raise, and carries the finished work on the exception.
Recursion limit of 25 reached without hitting a stop condition — LangGraph, which raises and can resume the thread from its last checkpoint.
max_turns, timeout, context: three walls, one run — which of the three you actually hit, and how to tell them apart.

This page counts anonymous readership with one counter, the file at /measure.js, and each of the events below is sent at most once per load. Once the page is ready it sends one view event. With it go the page path, the domain of the page you came from — only the domain, and nothing at all if you came from this site — how long the page has been open, counting only the time it was actually in front of you and not the time it sat in a background tab, whether you have scrolled, and any campaign or outreach code in the link you followed. A second event, which we call a human candidate, is sent only once the page has also received a real input event from you — a mouse movement, a touch, a scroll or a key press — and has been visible in the foreground for ten seconds in all; a program that fetches the page, or opens it and sits there, cannot produce one. A third, “engaged”, is stricter still: it is sent only after the human-candidate event, once the page has been in front of you for ninety seconds in all and you have scrolled far enough to reach a marker we put where the explaining part of this page ends; a reader who stops short of that marker never produces one. The second and third events carry the same fields as the first. If you switch away from the tab or close it, an event that has just become due may be sent as you leave. If this page has a button or a copy control that says it records a click, pressing it sends the name of that event and nothing else. Following a link to buy the guide sends one further event, also at most once per load, carrying that event’s name and a single word for which of the two checkouts you were sent to — the Gumroad listing or the payment page on this site — and nothing else: not the address you followed, not which page you were reading, not how long you had been there. Everything is sent to this site only, with no cookie attached. No cookie is read or written, nothing is put in your browser’s local or session storage, and no identifier is made from your device. Earlier versions of this page kept the campaign codes of your first visit in local storage under the name llab_attr; this page neither reads nor deletes that entry, so if it is there it stays until you clear this site’s data. An outreach code is minted per recipient, which would let us tell one reader from another; it is sent with each event and, unlike on earlier versions of this page, it is no longer removed from the address bar after it is read — if you copy the address, the code goes with it. Earlier versions also asked this domain for Vercel’s analytics script at /_vercel/insights/script.js, which on 26 September 2026 returned HTTP 404 on every host we publish; this page no longer asks for it. Your browser and the network attach things the page does not send: the identification string your browser gives, your IP address and the time of the request. The host that serves this page keeps its own request logs; those are its record and not ours.