Skip to content
TEN Brief Ten verified stories a day 2026.11.21 KO

이 기사는 한국어로도 읽을 수 있습니다 →

Tech · 14 min read · Explainer

Gemini API Tool Retrieval: how to turn it on, what it costs

Tool Retrieval in the Gemini API lets an agent hold back the parameter schemas of its tools and load only the ones the model decides it needs, at the moment it needs them. Google released it in preview on November 19, 2026, and it works only in the Interactions API (v1beta). Turning it on takes two changes: add a tool_search tool to the tools array, and set defer_loading: true on each function tool or remote MCP server to hold back. There is no separate charge; standard input and output token rates for the model apply. It is not free of tokens, though. A schema, once loaded, is billed as input for the rest of the conversation, and the tools array has to be resent with every request. Google published no token-savings, accuracy or latency numbers at launch.

A craftsperson seen from behind lifting one hand plane from a wall pegboard holding dozens of neatly arranged tools in a sunlit woodworking shop

The three lines

  • Setup — in an Interactions API (v1beta) request, add tool_search to tools and set defer_loading: true on the functions or remote MCP server to hold back. generateContent is not supported
  • Cost — no surcharge, standard token rates. A loaded schema is billed as input until the conversation ends and cannot be unloaded. The tools array is resent on every request
  • Limits — preview, no GA date. Google gave no savings, accuracy or latency figures. Agents with few tools, or that use most tools every time, may see no gain

Key questions

How to use Tool Retrieval in the Gemini API
**Add a `tool_search` tool to the tools array of an Interactions API request and set `defer_loading: true` on the tools to hold back.** | Step | What to do | Note | |---|---|---| | 1 | Check the API | Interactions API, v1beta. generateContent is not supported | | 2 | Add the search tool | One entry in tools with type tool_search | | 3 | Mark deferred tools | defer_loading: true on each function tool | | 4 | Defer a whole MCP server | defer_loading: true on the mcp_server tool. Remote servers only | | 5 | Frequently used tools | Leave them undeferred (Google guidance) | | 6 | Verify | In interaction.steps, look for tool_search_call, tool_search_result, then function_call |
Gemini Tool Retrieval pricing
**There is no separate charge. Standard input and output token rates for the model you call apply. The feature still consumes tokens.** | Cost item | Detail | Basis | |---|---|---| | Feature fee | None | Google blog | | tool_search block | Small fixed token block; size not published | Google blog | | Listing line per deferred tool | Name plus short description; about 26 tokens in early testing | PPC Land citing documentation (single source) | | Loaded schemas | Billed as input for the rest of the conversation | All four sources agree | | Server-side search | One extra model call per search, reported as total_tool_use_tokens at the input rate | i-SCOOP, PPC Land |
Which Gemini models support Tool Retrieval
**The Google blog says Gemini 3.6 and later, including all Gemini 4 models. One report says the documentation lists four model codes, so the list is not settled.** | Source | Supported models as stated | |---|---| | Google blog (2026-11-19) | Gemini 3.6 and later, including all Gemini 4 models | | Documentation as cited by PPC Land | gemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash, gemini-3.6-flash. Other models return a 400 error | | i-SCOOP | 3.6 Flash, 3.8 Flash and four Gemini 4 models (Hydrogen, Neon, Argon, Carbon) | | This article | Unresolved. Test the model code you plan to use |

Tool Retrieval in the Gemini API lets an agent hold back the schemas of its tools and load only the ones the model asks for, when it asks. Google released it in preview on November 19, 2026. You turn it on by adding a tool_search tool to the tools array and setting defer_loading: true on the tools you want held back. There is no separate charge.

An agent with five tools does not need this. The problem appears when an agent grows to 100 or 200 tools, usually because someone attached a few MCP servers. Every tool carries a parameter definition, its schema, and every schema is sent as input on every request. You pay, each turn, for the model to read manuals for tools it will not touch. This piece covers how to enable the feature, how much it can save, and when it costs more than it saves. It is based on Google's blog post and three write-ups that analysed it. Where Google gave no number, or the sources disagree, the text says so.

1. How to turn it on — one tool_search entry and defer_loading: true

Google's post, PPC Land, i-SCOOP and AlphaSignal all describe the same setup.

ItemValueNote
ReleasedNovember 19, 2026Preview. No general-availability date
APIInteractions APIv1beta. generateContent does not support it (PPC Land, i-SCOOP)
Search toolAn entry in tools with type tool_searchOne per request (PPC Land)
Deferred functiondefer_loading: true on the function toolThe model sees only its name and description
Deferred MCP serverdefer_loading: true on the mcp_server toolDefers every tool on that server. Remote servers only
Short descriptionshort_description (optional)Used in the listing in place of the full description (PPC Land)
Callclient.interactions.create(model, input, tools)The samples use gemini-4-hydrogen
AuthorsLucia Loher, product manager for the Gemini API, and Nora Kassner, research scientist at Google DeepMindGoogle blog

The fragment below is a condensed form of the official samples the sources show. Fields other than tool_search, defer_loading and mcp_server are placeholders, so it will not run as written.

The tools array of the request holds four kinds of entry.

  1. The search tool: {"type": "tool_search"}. It is required to load deferred tools
  2. A function tool used constantly: "type": "function" with name, description and parameters, left undeferred
  3. A function tool used occasionally: the same declaration plus "defer_loading": True, which holds the schema back
  4. A remote MCP server: a "type": "mcp_server" entry with "defer_loading": True, which defers every tool on that server (see the docs for its other fields)

The call takes the form client.interactions.create(model="gemini-4-hydrogen", input=..., tools=tools).

Inside a single request, this is what happens.

OrderWhoWhatName in steps
1DeveloperSends the request with tool_search and the deferred tools—
2ModelSees the name and description of each deferred tool, not its parameters—
3ModelNames the tools it needs and requests them; the arguments are a list of function namestool_search_call
4APIReturns the full declaration, parameters includedtool_search_result
5ModelCalls the function using the loaded schemafunction_call
6Developer codeRuns the function and returns the resultfunction_result

Steps 3 to 5 complete within one request, and every step is recorded in interaction.steps. PPC Land points out that the documented "search" is closer to a selection from a list the model already holds. Each line of that list is the tool's name plus its short_description, or the first sentence of its description if there is none. The first sentence of a description therefore decides whether a tool gets picked. A team whose tool descriptions read like "order-related function" should rewrite them before switching this on.

The search can also run on your side instead of Google's.

Server-side (default)Client-side
Setup{"type": "tool_search"}tool_search with "execution": "client" plus name, description and parameters
Where search runsGoogleYour application
What you buildNothing; no index to create or hostThe lookup logic that finds and returns tools
Good forA large, stable tool libraryPer-user access control, adding tools mid-conversation
PriceAn extra model call per search (i-SCOOP, PPC Land)One extra round trip per search
Deferring a whole MCP serverYesNo (i-SCOOP)
Mixing modesNot allowed in one requestSame

AlphaSignal adds that with client-side search you still need authorization checks and audit logging at execution time. Hiding a tool from a list is not the same as blocking its use.

2. How much it saves — Google gave no number

Start with what is and is not established. At launch Google published no measured token savings, no tool-selection accuracy and no latency figures. The numbers in circulation come from different places.

NumberWho said itWhat it is
About 26 tokens per idle (deferred) toolPPC Land, citing early testing in Google's documentationSingle source. Not in the Google blog post
100 deferred tools add about 2,600 tokens, about $0.004, per requestPPC LandIts own arithmetic: 26 tokens times $1.50 per million input tokens
150-tool example: 240,000 to 19,800 tokens, down 92%The i-SCOOP authorNot a Google figure. Own calculation; not exactly reproducible from the stated assumptions
5-tool example: 8,000 to 8,100 tokensThe i-SCOOP authorOwn calculation, showing a small agent can come out slightly worse
A tool schema averages 300 to 600 tokensi-SCOOP, citing a third party (Unblocked, May 2026)An outside estimate
Tool definitions for five MCP servers run about 55,000 tokensi-SCOOP, citing AnthropicAnother vendor's estimate

The 26 and 2,600 figures check out against each other: 26 × 100 = 2,600 tokens, and at $1.50 per million that is 2,600 × 1.50 ÷ 1,000,000 = $0.0039.

To get a feel for the scale, here is a worked example. It is arithmetic on assumptions we chose, not a measurement. The assumptions: 150 tools; 400 tokens per schema (the middle of the 300 to 600 estimate); 26 tokens per deferred listing line; a four-turn conversation in which two tools are loaded on the first turn and kept. The tool_search block, whose size is unpublished, and the extra model call for search are left out.

ItemEverything declared up frontEverything deferred
Tool definitions per request150 × 400 = 60,000 tokensListing: 150 × 26 = 3,900 tokens
Over four turns60,000 × 4 = 240,000 tokens3,900 × 4 = 15,600 tokens
Two loaded schemasIncluded above2 × 400 × 4 = 3,200 tokens
Total240,000 tokens18,800 tokens, plus the search block and search calls
Input cost at an assumed $1.50 per million$0.36About $0.03, plus the omitted items

Under these assumptions the input spent on tool definitions falls by roughly 92%, in line with i-SCOOP's direction. What the table really shows is not a savings rate but where the saving comes from. It comes only from schemas that are never loaded. The cut is large because the conversation uses 2 of 150 tools. If it used 100 of 150, the right-hand column would approach the left, with search cost added on top. Google says the same thing: savings arrive when the schemas you do not load outweigh the ones you do, and you should measure against real traffic.

Caching cuts both ways. Google's post and AlphaSignal say deferring schemas keeps the start of the prompt identical from request to request, so prefix caching keeps working. i-SCOOP raises the opposite risk: deferring schemas can shrink a medium-sized prompt below the minimum length for caching, so the cache discount disappears. How cached input is priced is covered in our September 5, 2026 explainer, "What prompt caching is — from the second call, your input costs one-fortieth."

3. Pricing — no surcharge, but tokens leave in four places

All four sources agree on the headline: the feature has no fee of its own, and the standard input and output rates of the model you call apply. Those standard rates attach in four places.

Where tokens goWhenHow muchBasis
tool_search blockEvery requestSmall fixed block; size not publishedGoogle blog
Listing line for each deferred toolEvery requestNumber of tools × about 26 tokensPPC Land, citing documentation
Loaded schemasEvery request after loading, until the conversation endsThe full schema sizeAll four sources
Server-side searchEach searchOne extra model call, reported as total_tool_use_tokens and billed at the input ratei-SCOOP, PPC Land

The third row matters most. A schema, once loaded, cannot be unloaded (PPC Land). It is counted as input for the remainder of the conversation exactly as if it had been declared up front. In a long conversation that pulls in one tool after another, later requests end up looking much like the undeferred case. The longer the conversation, the further the real saving falls below what the first few turns suggest.

The fourth row is where the sources differ in emphasis. Google's post says only that the search happens "inside that single API call" and does not mention an extra call. i-SCOOP and PPC Land, citing the documentation, say each server-side search adds a model call. The surest check is to read total_tool_use_tokens in your own usage data.

Token rates for Gemini 4 Hydrogen are set out in our November 16, 2026 piece, "Gemini 4 Hydrogen pricing — free, but you cannot pick it; the API costs twice 3.8 Flash."

4. When it costs more than it saves — five things to check first

Tool Retrieval is not a switch that always pays. These are the losing cases and traps the sources identify.

SituationWhy it losesWho says so
An agent with a handful of toolsThe search block and search call outweigh what deferral saves. A four-function agent is unlikely to benefitAlphaSignal; i-SCOOP's five-tool example
Fewer than 20 stable toolsDeclaring them all is simpler and cheaperi-SCOOP's recommendation
An agent that uses most of its tools in most conversationsEverything gets loaded anyway, with search cost addedi-SCOOP
Deferring frequently used toolsEvery conversation pays for a search it did not needGoogle blog: keep frequent tools undeferred
Client-side searchEach search adds a round trip and slows the responseAll four sources

The shape that fits is the opposite one. AlphaSignal's example is an agent with five core tools and a long tail of 50 occasional ones: leave the five alone and defer the 50.

There are behavioural traps as well as cost traps.

TrapWhat happensWhat to do
Resending the tools arrayTool declarations do not carry over to the next request, even with previous_interaction_idSend the full tools array on every request (documentation as cited by PPC Land)
Tools named in system instructionsThe model may call them without searching, and the next request fails with an error beginning "Server side tool call context must be circulated"Do not defer tools named in system instructions or in another tool's output
A search with no matchReturns text, not a structured errorDetect it from the content, not an error code
Loaded schemasCannot be unloadedConsider splitting long conversations into sessions
Preview statusThe API surface may change before general availabilityAllow for change in production code
Unsupported modelA 400 error (documentation as cited by PPC Land)Test the model code first

On latency, Google's own post points in two directions. Its summary box says the feature reduces latency, while the body makes the general point that more tools add latency. No source gives a measurement. Less input speeds things up and an extra search step slows them down, so the net effect has to be measured.

5. MCP servers and supported models — defer a whole server; the model list is disputed

An MCP (Model Context Protocol) server is a standard way to expose a bundle of tools. Attach one server and dozens of tools arrive together, which is the most common way tool schemas balloon. We covered the protocol itself in an earlier Korean-language explainer on August 28, 2026, and its agent-to-agent counterpart in "What A2A is — MCP connects agents to tools, A2A connects agents to agents" on August 30, 2026.

Setting defer_loading: true on an mcp_server tool defers every tool on that server. Two conditions apply. It works only with remote MCP servers (all four sources) and only with server-side search (i-SCOOP). In that case, per i-SCOOP, the API also executes the tools itself and reports mcp_server_tool_call and mcp_server_tool_result steps. PPC Land notes that remote MCP support in the Interactions API was itself added on July 7, 2026.

The supported-model list is where the sources diverge.

SourceAs statedMissing or added
Google blogGemini 3.6 and later, including all Gemini 4 modelsNo model codes
AlphaSignalSame as the Google blog—
PPC Land, citing documentationgemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash, gemini-3.6-flashNo Gemini 4 Carbon, no 3.7 Flash. Other models return a 400 error
i-SCOOP3.6 Flash, 3.8 Flash and four Gemini 4 modelsIncludes Neon and Carbon

"All Gemini 4 models" and "four model codes" cannot both be literally true. The documentation list may not yet reflect newer models such as Gemini 4 Neon, or the blog wording may simply be broad. We could not establish which. The quickest way to find out is to call the model code you intend to use and see whether it returns a 400.

6. Compared with Anthropic and OpenAI — the same flag, and Google is third

Google's post names no other company. The comparison below is drawn from PPC Land and i-SCOOP.

CompanyFeatureReleasedDeferral flagFigures the company published
AnthropicTool Search ToolNovember 24, 2025 (beta)defer_loading: true85% fewer tokens (about 77,000 to 8,700). Tool-selection accuracy from 49% to 74% on Opus 4 and from 79.5% to 88.1% on Opus 4.5
OpenAITool searchMarch 5, 2026, with GPT-5.4Same flag47% fewer tokens across 250 tasks on 36 MCP servers
GoogleTool RetrievalNovember 19, 2026 (preview)defer_loading: trueNone published

Three points follow. First, all three vendors use a flag with the same name, which makes a curated tool catalogue easier to carry from one API to another. Second, each figure comes from that company's own tests and they are not directly comparable (PPC Land). Even the description of OpenAI's 47% varies: i-SCOOP presents it as a benchmark result at equal accuracy, PPC Land as internal tests. Third, the accuracy numbers deserve more attention than the savings. If Anthropic's figures hold, a model shown dozens of tools at once picked the wrong one about half the time. Deferred loading is a way to stop the model getting confused before it is a way to cut the bill. The absence of any such accuracy figure is the largest gap in Google's announcement.

Why a large context window should not simply be filled is the subject of our August 14, 2026 explainer, "What is a context window — a model does not read all million tokens."

7. Frequently asked questions

I use generateContent. Can I keep it? No. According to PPC Land and i-SCOOP, Tool Retrieval works only in the Interactions API (v1beta). Using it means moving those calls to the Interactions API.

Is it free? There is no feature fee. That does not mean no tokens. Standard rates apply to the search block, the listing line for each deferred tool, any schema that gets loaded and each server-side search call.

How many tools before it is worth it? Google gives no threshold. i-SCOOP recommends declaring everything when you have fewer than 20 stable tools, and AlphaSignal says a four-function agent is unlikely to benefit. Google's own test is a ratio, not a count: the schemas you do not load must outweigh the ones you do.

Which tools should I defer? Keep frequently used tools undeferred, as Google advises. Also keep any tool named in your system instructions or in another tool's output; if it is deferred, the model may try to call it without searching and the request fails. The rarely used long tail is what to defer.

Can the tool list change during a conversation? With client-side search, yes: tools can be added mid-conversation, and it is also the mode for services where different users may reach different tools. Server-side search suits a large library that does not change.

Can a loaded schema be dropped later in the conversation? No. Once loaded it counts as input until the conversation ends.

If I chain requests with previous_interaction_id, can I skip the tools array? No. Per the documentation as cited by PPC Land, tool declarations do not persist between requests. Send the full array every time.

Can I defer a locally hosted MCP server? The sources confirm only remote MCP servers, and only with server-side search.

Is it ready for production? It is a preview with no general-availability date, and PPC Land notes the API surface may change. If you adopt it, put it behind a switch and compare input tokens and tool-selection errors on the same traffic with it off and on.

8. What remains open

ItemEstablishedNot established
ReleasePreview on November 19, 2026, Interactions API onlyA general-availability date
SetupAdd tool_search, set defer_loading: true (four sources agree)Direct comparison with Google's documentation page
Supported modelsBlog: 3.6 and later, all Gemini 4 modelsWhy the documentation lists four codes; how Carbon, Neon and 3.7 Flash actually behave
Idle-tool costAbout 26 tokens, per PPC Land citing documentationAbsent from the Google blog; variation with description length
SavingsNo Google figureThe 92% is i-SCOOP's calculation; our table is arithmetic on assumptions
AccuracyNo Google figureHow much tool selection improves on Gemini
LatencyNo measurementWhether less input or the added search step dominates
Search methodThe model picks from names and descriptionsHow server-side matching works; only AlphaSignal calls it semantic search
Search costAn extra model call, per two sources citing documentationNot mentioned in the Google blog
Search block sizeA small fixed blockThe token count
Tool limitNo stated capThe practical ceiling
Other vendorsReports of 85% for Anthropic and 47% for OpenAIThe original posts; whether the conditions are comparable

In practice the order is this. Confirm your calls go through the Interactions API. Split your tools into those used constantly and those used occasionally. Put defer_loading: true only on the occasional ones and add tool_search. Rewrite the first sentence of each tool description so that it says, in one line, what the tool does. Then compare input tokens and total_tool_use_tokens on real traffic before and after. Google has not published a savings figure, so the only number that counts is the one you measure.

For related background, see "What are Agent Skills? The folder-based standard for teaching AI agents tasks, now at the Linux Foundation" (October 24, 2026), which applies the same load-only-when-needed idea to instructions rather than tools.

Sources

  1. Google — Introducing Tool Retrieval in the Gemini API (Lucia Loher, Nora Kassner, 2026-11-19)
  2. PPC Land — Google shrinks idle tools in Gemini agents to about 26 tokens each (Luis Rijo, 2026-11-19)
  3. i-SCOOP — Gemini's Tool Retrieval loads an agent's tools only when needed, and the tool catalogue is now something to manage
  4. AlphaSignal — Google's Gemini API Drops Schema Overhead for Agents With Hundreds of Tools (2026-11-19)

Verification

Published
Last modified
Cross-check
Checked against 4 independent sources.
Unverified
  • We did not open the Tool Retrieval page in Google's developer documentation (ai.google.dev) directly. Documentation details (about 26 tokens per idle tool, the four model codes, resending the tools array, the error string, the short_description field) follow what PPC Land and i-SCOOP reported from it.
  • The figure of about 26 tokens per idle tool comes from PPC Land alone, citing early-testing numbers in the documentation. It does not appear in the Google blog post.
  • The 150-tool example of 240,000 versus 19,800 tokens (a 92% cut) is the i-SCOOP author's own calculation, not a Google figure. Recomputing with the author's stated assumptions (400-token schemas, 25 tokens per name and description, a 500-token search block, two tools used over four turns) did not reproduce 19,800 exactly. The worked table in section 2 uses our own assumptions and is arithmetic, not a measurement.
  • Supported-model lists differ by source. The Google blog says Gemini 3.6 and later including all Gemini 4 models; the documentation as cited by PPC Land lists four model codes without Carbon or 3.7 Flash; i-SCOOP includes Neon and Carbon. We could not confirm which matches current behaviour.
  • Google does not describe how server-side search matches tools. AlphaSignal calls it semantic search over function descriptions; the Google blog, PPC Land and i-SCOOP say the method is not disclosed.
  • That each server-side search is billed as an extra model call comes from i-SCOOP and PPC Land, citing documentation. The Google blog post says only that the search happens within a single API call.
  • The token size of the tool_search block, any maximum number of deferred tools and a general-availability date are not published. Google also gave no measured token savings, accuracy or latency at launch.
  • The Anthropic and OpenAI figures (85% reduction, accuracy from 49% to 74%, 47% reduction) are those companies' own test results as relayed by PPC Land and i-SCOOP. We did not open the original posts. i-SCOOP describes the OpenAI 47% as a benchmark result, PPC Land as internal tests.
  • Only part of the i-SCOOP article was read verbatim; the rest was checked through a summary. Retention periods (55 days paid, one day free), the step-replay requirement with store=false, and the experimental label and region limits for the Interactions API on Google Cloud appear only in that summary and are not asserted in the body. The i-SCOOP publication date (shown as November 20, 2026) is also not confirmed.
  • The code fragment in this article is a condensed form of the official samples shown by the sources. Fields other than tool_search, defer_loading, mcp_server, execution and client.interactions.create are placeholders; it is not runnable as written.
Authoring
Reviewed by a person before publication. The full process is described in the Editorial.

Ten stories, once each morning

We send the three-line summaries only; the full pieces stay on the site. One-click unsubscribe, any time.

Related