“`finishReason`: `UNEXPECTED_TOOL_CALL`” — the model called a tool your request never offered

"finishReason": "UNEXPECTED_TOOL_CALL"

Nothing threw. The HTTP status was 200, the response body is well formed, and the candidate in it simply stops, with finishReason set to UNEXPECTED_TOOL_CALL. Of the twenty-two values in Gemini’s FinishReason enum, this is the one that does not describe something that happened to the output. It describes a mismatch between what the model produced and what your request allowed.

In ten seconds. Read candidates[0].finishReason, and read finishMessage on the same candidate beside it. Then print the tools array off the request you actually sent — not the one in your config file. If the model tried to call a function and that array is absent or empty, you have found it.

And the honest part: Google publishes one sentence about this value, in one row of one enum, and nothing else in any Gemini document we could read. This page quotes that sentence, says exactly what it does not tell you, and keeps the check (which follows from the sentence) separate from the causes (which do not).

What the reference says, quoted

From the Gemini API reference for generateContent, in the FinishReason enum. The enum is introduced with one line:

Defines the reason why the model stopped generating tokens.

And the row for this value, which is the whole of what Google says it means:

UNEXPECTED_TOOL_CALL Model generated a tool call but no tools were enabled in the request.

That is the complete documentation. Not a summary of it — the complete text. There is no prose section for this value, no example, no error code, and no entry for it in the troubleshooting page. The sentence is, at least, not circular: it names a cause rather than restating the value’s own name, which is more than several of its neighbours in the same enum manage. What it does not do is tell you what “enabled” means.

This is the one value in the enum that points at your request

Worth dwelling on, because it changes where you look. Every other stop in this family describes the generation: a ceiling was hit, content was filtered, an image came back wrong, the model called too many tools. This one says the model did something your request had not provided for. The field is Output only, on the response, and the condition it reports is in the input.

The practical consequence: the response is the wrong place to debug this. There is nothing in the candidate to inspect except the value itself. The evidence is in the request body, and if a wrapper, an agent framework or a history-replay step built that body for you, the request you can read in your own source is not necessarily the request that went out. That substitution — reasoning from the config you wrote instead of the bytes that were sent — is the trap, and it is ours to name rather than Google’s.

“Enabled” is not a field, and the docs do not say which state it means

The request body has two fields about tools, and neither of them uses the word “enabled”. From the same reference, the first:

tools[] Optional. A list of Tools the Model may use to generate the next response.

with the type spelled out immediately after it:

A Tool is a piece of code that enables the system to interact with external systems to perform an action, or set of actions, outside of knowledge and scope of the Model. Supported Tools are Function and codeExecution.

and the second:

toolConfig Optional. Tool configuration for any Tool specified in the request. Refer to the Function calling guide for a usage example.

So the request can be in at least three different states that a reader might reasonably call “no tools enabled”: tools absent entirely; tools present but an empty array; or tools populated while the calling mode forbids a call. The documented sentence distinguishes none of them. The modes exist and are documented — on a different page, in different vocabulary. From the function-calling guide:

Control how the model uses tools using tool_choice in generation_config: auto (Default): Model decides whether to call a function or respond directly. any: Model is constrained to always predict a function call. none: Model is prohibited from making function calls. validated: Model ensures function schema adherence.

Read those two documents side by side and a second gap opens. The reference tells you to “Refer to the Function calling guide for a usage example” of toolConfig — and the string toolConfig appears zero times in that guide’s 983,355 bytes. The guide controls the same behaviour through tool_choice inside generation_config. Two surfaces, two field names, one cross-reference that no longer lands. We are not going to guess which name your endpoint honours; we are going to tell you to look at the wire, which works either way.

And the mode named none is the interesting one, because its documented meaning is about the model’s prediction — “Model is prohibited from making function calls” — while the enum row is about tools not being “enabled”. Whether those two sentences describe the same state is not stated anywhere we could read. It is a reasonable guess. It is not documentation, and this page will not dress it up as any.

The ten-second check

Three reads, in this order. The first two are on the response, the third is the one that actually answers the question.

curl -s "https://generativelanguage.googleapis.com/v1beta/models/$MODEL:generateContent" \ -H "x-goog-api-key: $GEMINI_API_KEY" \ -H "content-type: application/json" \ -d @request.json \ | jq '.candidates[0] | {finishReason, finishMessage, partTypes: [.content.parts[]? | keys[0]]}'

The second field in that output is the one most handlers never read. From the reference, on the candidate:

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

“Details the reason” is all the reference says about its contents, so we cannot tell you what yours will hold — but it is populated exactly when the value you are chasing is set, and it costs one line to log. Log it. If there is a per-request detail to be had anywhere in this response, that is the only field documented to carry one.

Then the read that settles it — dump the request as it left your process, not as you wrote it:

jq '{hasTools: (has("tools")), toolCount: (.tools | length), declared: [.tools[]?.functionDeclarations[]?.name], toolConfig: .toolConfig, toolChoice: .generationConfig.tool_choice}' request.json

If hasTools is false or toolCount is 0, the sentence at the top of this page has described your bug and you are done reading. If the array is populated, go and look at the last two fields instead, and at whether the model was reaching for a name that is not in declared.

What to change

Ordered by how often each one is the answer in our own runs — which is our experience and not Google’s documentation, and we would rather say so than imply a ranking the docs do not publish.

Send the tools. If the model is genuinely expected to call a function, the tools array belongs on every request in the conversation, not only the first. A multi-turn loop that builds turn two from stored history and forgets to re-attach the declarations produces exactly this: a model that has just seen itself call tools in the history, and a request that no longer offers any.
Stop asking for a call you have forbidden. If the calling mode is set to the documented “Model is prohibited from making function calls” state while your prompt or system instruction still tells the model to use a tool, you have given two contradictory instructions. Pick one. Removing “call get_weather when asked about weather” from a prompt is usually the cheaper half.
Check the declarations survived serialisation. From the reference, on Tool:
Optional. A list of FunctionDeclarations available to the model that can be used for function calling.
A tools array of length one whose single Tool carries an empty functionDeclarations is an array that looks populated in a length check and offers the model nothing. Count the declarations, not the tools.
Handle it as a response state, not an exception. Nothing here raises. The reference is explicit that a function call is the model’s output rather than an action:
The model or system does not execute the function. Instead the defined function may be returned as a FunctionCall with arguments to the client side for execution.
So a client built around try/except and a retry decorator sees a clean 200 with a candidate whose content is missing or short, and reports success. Branch on finishReason before you touch parts.

Where the documentation is silent, plainly

Said flatly, because the alternative is inventing it. On this value, Google does not publish:

What “enabled” means as a request state — no field carries that name, and the three candidate states above are not distinguished.
Whether partial content is returned. The candidate may or may not carry the offending functionCall part. Nothing states which, so inspect content.parts rather than assuming either.
Whether the attempted call is visible at all, and therefore whether you can learn which tool the model reached for. The reference defines the part type — “A predicted FunctionCall returned from the model that contains a string representing the FunctionDeclaration.name with the arguments and their values” — but says nothing about its presence in this case.
What finishMessage contains for this value.
Whether the call is billed, and whether it is retryable in the sense that the same request could succeed on a second attempt.
Anything at all outside the enum. The guide that teaches function calling never mentions finishReason; neither does the troubleshooting page. The counts are in the provenance note below. If you went looking for a prose explanation of this value and found nothing, that is because there is nothing, not because you missed it.

Its two neighbours, and why the distinction is the diagnosis

Three values in this enum end a tool-using run with no usable answer, and they are fixed in three different places. All three sentences are quoted from the same enum:

UNEXPECTED_TOOL_CALL — “Model generated a tool call but no tools were enabled in the request.” The request did not offer the tool. Fix the request.
MALFORMED_FUNCTION_CALL — “The function call generated by the model is invalid.” The tool was offered; the call itself could not be accepted. Fix the schema or the prompt.
TOO_MANY_TOOL_CALLS — “Model called too many tools consecutively, thus the system exited execution.” The tools worked and the chain was too long. Shorten the chain; no cap of yours is involved.

One field, three causes, and the only thing that separates them is the string you did not read. That is the same shape as every other ending catalogued on this site: a run that dies well before its timeout, or one that finishes fifty turns with nothing written, is usually a limit or a rejection being reported somewhere your instrumentation is not looking. Here the notice was in the response the whole time.

Provenance

Every sentence inside a quote block above was read out of a copy of the document it is attributed to that was already stored in this lab’s repository before this page was written. Nothing was fetched to write this page — not one request left the machine — and nothing here is quoted from memory. The copies, with the byte count of the file actually read:

Gemini API reference, generateContent — 1,232,462 bytes, fetched 4 October 2026 at HTTP 200, carrying its own date Last updated 2026-09-23 UTC. The schema that enumerates FinishReason.
Gemini API docs, Thinking — 286,274 bytes, same fetch, Last updated 2026-09-25 UTC. The only document that defines what a thought signature is.
Gemini API docs, Function calling — 983,355 bytes, same fetch, Last updated 2026-09-23 UTC.
Gemini API docs, Troubleshooting — 105,225 bytes, same fetch, Last updated 2026-10-01 UTC.

The reference page carries its own licence: “Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License”. Three of those four files were also searched for the string UNEXPECTED_TOOL_CALL: it appears once in the reference — the enum row quoted at the top of this page — and zero times in the function-calling guide, zero times in the thinking guide and zero times in the troubleshooting page. The string finishReason itself appears zero times in all three of those guides. Those counts are the evidence for every claim of silence on this page; they were produced by searching the four files named above and nothing else. We did not read the SDK source for any language, and nothing above describes it. Where this page reasons past the documentation it says so in the sentence that does it.

There is a written guide: the full finishReason dispatch as a table you can hold against your own response handler, the request-logging pattern that makes “the bytes I sent” readable instead of inferred, and the multi-turn loop that re-attaches tool declarations on every request rather than only the first.

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: finishReason: UNEXPECTED_TOOL_CALL arrives on a successful HTTP 200 and means, in the only sentence Google publishes about it, that the “Model generated a tool call but no tools were enabled in the request”. It is the one value in the enum that describes your request rather than the output, so the response is the wrong place to debug it — print the tools array off the request that actually left your process, and count functionDeclarations rather than tools. Log finishMessage beside finishReason; it is documented to be populated whenever a reason is set, though not what it holds. The docs do not define what “enabled” means, do not say whether the attempted call is returned, and do not mention this value anywhere outside that one enum row.

Nearby

finishReason: MALFORMED_FUNCTION_CALL — the tool was offered and the call still could not be accepted; same field, different half of the handshake.
finishReason: TOO_MANY_TOOL_CALLS — the chain that worked and ran too long, stopped server-side where none of your caps apply.
finishReason: MISSING_THOUGHT_SIGNATURE — the other Gemini stop that blames the request you sent rather than the answer you got back.
Max number of llm calls limit of `500` exceeded — Google’s other ceiling, the one that is in your config and does raise.
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 sixteen pages on this host that send two — any rate measured against those 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: UNEXPECTED_TOOL_CALL” — the model called a tool your request never offered