“`finishReason`: `TOO_MANY_TOOL_CALLS`” — a ceiling counted by the API, not by your loop

"finishReason": "TOO_MANY_TOOL_CALLS"

Your framework did not stop that run. Gemini did — on the server, as a property of the response, because the model called tools too many times in a row. It arrives as a value of finishReason on the candidate — a field the reference marks Output only, carried in the response body rather than signalled as a failure — so if your code does not read that field it reads an empty answer and reports nothing at all. There is no max_iterations of yours in this, because the count is not yours.

In ten seconds. Every other ceiling on this site is counted by the agent library on your machine. This one is counted by the model API, so none of your caps describe it and raising them changes nothing.

Read candidates[0].finishReason on every response. When it is TOO_MANY_TOOL_CALLS, also read finishMessage — the reference says that field is populated only when finishReason is set, which makes it the detail channel for exactly this case.

What the reference says, quoted

From Generating content, in the FinishReason enum — which that page introduces with Defines the reason why the model stopped generating tokens.:

TOO_MANY_TOOL_CALLS Model called too many tools consecutively, thus the system exited execution.

A note on how much of this is quoted and how much is ours. The sentence above is the whole of what that reference page says about this enum value: the string occurs twice in the 1,232,466 bytes we fetched — once in the rendered enum table, once in the page’s own embedded data — and carries that one definition both times. Everything after this paragraph is our reading of the consequences, not the vendor’s text, and it is marked off from the quotes for that reason.

Read the sentence closely, because every clause in it is load-bearing. Consecutively: the count is of tool calls in a row, not of tool calls in the session, so a run that interleaves tool calls with ordinary text is counted differently from one that chains them. The system: the subject of the sentence is not your program. Exited execution: something above your code decided to stop, and it did so by ending generation rather than by raising.

Why none of your caps describe it

Lay it against the ceilings that do have pages here. Pydantic AI counts model requests and raises UsageLimitExceeded. Google’s own ADK counts model calls against max_llm_calls and raises. The OpenAI Agents SDK counts turns and raises MaxTurnsExceeded. LangGraph counts supersteps against recursion_limit. Four different nouns, one shared shape: a number in your configuration, in your process, raising an exception you can catch.

This one has none of those properties. It is not in your configuration, it is not counted in your process, and it does not raise. That matters in a specific and expensive way: an agent loop whose error handling is a try/except around the model call has nothing to catch: the stop is reported as data on the response, not as a failure of the request. The loop sees a response, returned normally, with the reason sitting in a field on it. It simply has no useful content, and the loop’s next move depends entirely on whether anyone wrote a branch for a response that arrives intact and carries no answer.

It also means this is a ceiling that can end a run on Google’s count while your own instrumentation shows you nowhere near any limit you set. If you are looking at a run that died well short of its timeout with every configured cap untouched, a server-side stop is on the list of things that can do that, and finishReason is where the evidence is.

Reading the field properly

The reference defines the field on the candidate object like this:

finishReason enum (FinishReason) Optional. Output only. The reason why the model stopped generating tokens. If empty, the model has not stopped generating tokens.

And the companion field, which is the one most code never touches:

finishMessage string Optional. Output only. Details the reason why the model stopped generating tokens. This is populated only when finishReason is set.

Two practical consequences. The emptiness of finishReason is itself meaningful — it is the streaming case, a chunk from a generation still in progress, and treating empty as “finished normally” is a bug. And finishMessage exists precisely for the occasions when the enum value alone is not enough to act on, which is every occasion of the kind this page is about. Log it. It costs one line and it is the only per-incident detail the API offers you.

The two neighbours you will confuse this with

The same enum carries two other tool-related values, quoted here because the three are easy to conflate in a log and are not the same problem:

UNEXPECTED_TOOL_CALL Model generated a tool call but no tools were enabled in the request. MALFORMED_FUNCTION_CALL The function call generated by the model is invalid.

UNEXPECTED_TOOL_CALL is a request-construction bug on your side: the model tried to call a tool and your request declared none, which typically means a tools array got lost between your agent framework and the wire. MALFORMED_FUNCTION_CALL is a different failure again, and has its own page here. Only the value on this page is about how many times in a row, and only this one is relieved by making the model need fewer consecutive calls.

What to do about it

Branch on finishReason before you touch the text. One dispatch, every response, with an explicit arm for a response that arrives intact and carries no answer. This single habit converts a silent empty result into a diagnosable event.
Reduce the length of the chain, not the number of tools. The count is of consecutive calls, so the lever is how many calls the model must make back-to-back before it can say something. A tool that answers the whole question costs one call; three tools that each answer a third of it cost three.
Collapse loops into batch tools. The classic shape that produces long consecutive chains is one call per item over a list. A tool that takes the list and returns the list replaces forty consecutive calls with one, and is the same fix that raising the cap moves the wall argues for in the general case.
Break the chain with a checkpoint. If the work genuinely needs many steps, have the model summarise partial progress into a message and continue in a fresh request. A new request starts a new consecutive run.
Persist each tool result as it lands. A chain cut off at step nine should cost you step nine, not steps one through nine. The earlier results are the ones you already received, and keeping them is your storage’s job rather than this field’s.

Provenance

One document, for this page: the Gemini API reference page Generating content on Google’s own developer site — 1,232,466 bytes, HTTP 200, no redirects, fetched 4 October 2026 for this page. The page carries its own date, Last updated 2026-09-23 UTC, and its own licence: “Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License”. Every string in a quote block above is from that fetch, and the enum definitions are reproduced word for word rather than paraphrased. We read that one reference page and nothing else on that host: not the function-calling guide, not the SDK source, not the Vertex AI documentation, and nothing here describes them.

There is a written guide: the finishReason dispatch above as a checklist against your own response handling, the batch-tool rewrite that collapses a per-item chain into one call, and the checkpoint pattern for work that genuinely needs more consecutive steps than a single request will carry.

No page on this site has a checkout widget of its own. There is a written guide behind this host and it is on sale at $19 on a storefront that delivers the files automatically and carries a 30-day money-back guarantee: buy it there; the guide can also be paid for with 19 USDC on Base at the payment page, where delivery is by hand as a reply to your email. Every page on this site, including this one, is free to read in full, with no sign-up and nothing gated.

The short version: TOO_MANY_TOOL_CALLS is Gemini stopping the generation server-side because, in its own words, the model “called too many tools consecutively, thus the system exited execution”. The reason arrives as a field on the response rather than as a request failure, and none of your framework’s caps are involved, so raising them does nothing. Read candidates[0].finishReason on every response and log finishMessage beside it. Then shorten the consecutive chain: collapse per-item loops into batch tools, checkpoint long work into a fresh request, and persist each tool result as it lands.

Nearby

finishReason: MALFORMED_FUNCTION_CALL — the other way a Gemini tool loop ends with no answer: not a count at all, but a tool call the API could not accept.
Max number of llm calls limit of `500` exceeded — Google’s other ceiling, the one that is in your config and does raise.
recursion_limit, max_iter, max_turns: one wall under several names — why the reflex to raise the number is the smaller half of the fix.
The next request would exceed the request_limit of 50 — the contrasting shape: a cap in your process that raises where you can catch it.
Why an agent run dies before its timeout — the ceilings that fire while your clock still has room on it.

This page counts anonymous readership, and it carries one counter rather than the two that the older pages on this host carry. Each load sends the page path, the address of the page you came from, how long the page was open, whether you scrolled, and any campaign or outreach code in the link you followed; a second “engaged” event is sent once, ten seconds after the page opens — whether or not the tab is in front of you — or as soon as you scroll a quarter of it. The campaign codes from the first link you arrived on are kept in this browser’s local storage, and a later visit that arrives with no codes of its own is counted against them; a link carrying its own codes is used for that visit, and the stored first touch is never replaced. An outreach code is removed from the address bar after it is read. Because this page sends one view event rather than two, a view count taken from it is directly comparable to a load, which is not true of the eighteen pages published before it — those send two, and any rate measured against them reads half its true value. No name is attached to any of this: the only identifier the code can send is an outreach token minted per recipient, and no link carrying one has ever been sent for this page. No cookie; the local storage above does that job. The page also asks this domain for an analytics script at /_vercel/insights/script.js; on 26 September 2026 that address returned HTTP 404 on every host we publish, so no script from another company was served or ran — the page goes on asking, so this stops being true the moment that address starts answering, without a byte of this page changing. 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.

“finishReason: TOO_MANY_TOOL_CALLS” — a ceiling counted by the API, not by your loop