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.
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.
| Item | Value | Note |
|---|---|---|
| Released | November 19, 2026 | Preview. No general-availability date |
| API | Interactions API | v1beta. generateContent does not support it (PPC Land, i-SCOOP) |
| Search tool | An entry in tools with type tool_search | One per request (PPC Land) |
| Deferred function | defer_loading: true on the function tool | The model sees only its name and description |
| Deferred MCP server | defer_loading: true on the mcp_server tool | Defers every tool on that server. Remote servers only |
| Short description | short_description (optional) | Used in the listing in place of the full description (PPC Land) |
| Call | client.interactions.create(model, input, tools) | The samples use gemini-4-hydrogen |
| Authors | Lucia Loher, product manager for the Gemini API, and Nora Kassner, research scientist at Google DeepMind | Google 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.
- The search tool:
{"type": "tool_search"}. It is required to load deferred tools - A function tool used constantly:
"type": "function"withname,descriptionandparameters, left undeferred - A function tool used occasionally: the same declaration plus
"defer_loading": True, which holds the schema back - 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.
| Order | Who | What | Name in steps |
|---|---|---|---|
| 1 | Developer | Sends the request with tool_search and the deferred tools | — |
| 2 | Model | Sees the name and description of each deferred tool, not its parameters | — |
| 3 | Model | Names the tools it needs and requests them; the arguments are a list of function names | tool_search_call |
| 4 | API | Returns the full declaration, parameters included | tool_search_result |
| 5 | Model | Calls the function using the loaded schema | function_call |
| 6 | Developer code | Runs the function and returns the result | function_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 runs | Your application | |
| What you build | Nothing; no index to create or host | The lookup logic that finds and returns tools |
| Good for | A large, stable tool library | Per-user access control, adding tools mid-conversation |
| Price | An extra model call per search (i-SCOOP, PPC Land) | One extra round trip per search |
| Deferring a whole MCP server | Yes | No (i-SCOOP) |
| Mixing modes | Not allowed in one request | Same |
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.
| Number | Who said it | What it is |
|---|---|---|
| About 26 tokens per idle (deferred) tool | PPC Land, citing early testing in Google's documentation | Single source. Not in the Google blog post |
| 100 deferred tools add about 2,600 tokens, about $0.004, per request | PPC Land | Its 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 author | Not a Google figure. Own calculation; not exactly reproducible from the stated assumptions |
| 5-tool example: 8,000 to 8,100 tokens | The i-SCOOP author | Own calculation, showing a small agent can come out slightly worse |
| A tool schema averages 300 to 600 tokens | i-SCOOP, citing a third party (Unblocked, May 2026) | An outside estimate |
| Tool definitions for five MCP servers run about 55,000 tokens | i-SCOOP, citing Anthropic | Another 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.
| Item | Everything declared up front | Everything deferred |
|---|---|---|
| Tool definitions per request | 150 × 400 = 60,000 tokens | Listing: 150 × 26 = 3,900 tokens |
| Over four turns | 60,000 × 4 = 240,000 tokens | 3,900 × 4 = 15,600 tokens |
| Two loaded schemas | Included above | 2 × 400 × 4 = 3,200 tokens |
| Total | 240,000 tokens | 18,800 tokens, plus the search block and search calls |
| Input cost at an assumed $1.50 per million | $0.36 | About $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 go | When | How much | Basis |
|---|---|---|---|
| tool_search block | Every request | Small fixed block; size not published | Google blog |
| Listing line for each deferred tool | Every request | Number of tools × about 26 tokens | PPC Land, citing documentation |
| Loaded schemas | Every request after loading, until the conversation ends | The full schema size | All four sources |
| Server-side search | Each search | One extra model call, reported as total_tool_use_tokens and billed at the input rate | i-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.
| Situation | Why it loses | Who says so |
|---|---|---|
| An agent with a handful of tools | The search block and search call outweigh what deferral saves. A four-function agent is unlikely to benefit | AlphaSignal; i-SCOOP's five-tool example |
| Fewer than 20 stable tools | Declaring them all is simpler and cheaper | i-SCOOP's recommendation |
| An agent that uses most of its tools in most conversations | Everything gets loaded anyway, with search cost added | i-SCOOP |
| Deferring frequently used tools | Every conversation pays for a search it did not need | Google blog: keep frequent tools undeferred |
| Client-side search | Each search adds a round trip and slows the response | All 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.
| Trap | What happens | What to do |
|---|---|---|
| Resending the tools array | Tool declarations do not carry over to the next request, even with previous_interaction_id | Send the full tools array on every request (documentation as cited by PPC Land) |
| Tools named in system instructions | The 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 match | Returns text, not a structured error | Detect it from the content, not an error code |
| Loaded schemas | Cannot be unloaded | Consider splitting long conversations into sessions |
| Preview status | The API surface may change before general availability | Allow for change in production code |
| Unsupported model | A 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.
| Source | As stated | Missing or added |
|---|---|---|
| Google blog | Gemini 3.6 and later, including all Gemini 4 models | No model codes |
| AlphaSignal | Same as the Google blog | — |
| PPC Land, citing documentation | gemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash, gemini-3.6-flash | No Gemini 4 Carbon, no 3.7 Flash. Other models return a 400 error |
| i-SCOOP | 3.6 Flash, 3.8 Flash and four Gemini 4 models | Includes 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.
| Company | Feature | Released | Deferral flag | Figures the company published |
|---|---|---|---|---|
| Anthropic | Tool Search Tool | November 24, 2025 (beta) | defer_loading: true | 85% 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 |
| OpenAI | Tool search | March 5, 2026, with GPT-5.4 | Same flag | 47% fewer tokens across 250 tasks on 36 MCP servers |
| Tool Retrieval | November 19, 2026 (preview) | defer_loading: true | None 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
| Item | Established | Not established |
|---|---|---|
| Release | Preview on November 19, 2026, Interactions API only | A general-availability date |
| Setup | Add tool_search, set defer_loading: true (four sources agree) | Direct comparison with Google's documentation page |
| Supported models | Blog: 3.6 and later, all Gemini 4 models | Why the documentation lists four codes; how Carbon, Neon and 3.7 Flash actually behave |
| Idle-tool cost | About 26 tokens, per PPC Land citing documentation | Absent from the Google blog; variation with description length |
| Savings | No Google figure | The 92% is i-SCOOP's calculation; our table is arithmetic on assumptions |
| Accuracy | No Google figure | How much tool selection improves on Gemini |
| Latency | No measurement | Whether less input or the added search step dominates |
| Search method | The model picks from names and descriptions | How server-side matching works; only AlphaSignal calls it semantic search |
| Search cost | An extra model call, per two sources citing documentation | Not mentioned in the Google blog |
| Search block size | A small fixed block | The token count |
| Tool limit | No stated cap | The practical ceiling |
| Other vendors | Reports of 85% for Anthropic and 47% for OpenAI | The 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
- Google — Introducing Tool Retrieval in the Gemini API (Lucia Loher, Nora Kassner, 2026-11-19)
- PPC Land — Google shrinks idle tools in Gemini agents to about 26 tokens each (Luis Rijo, 2026-11-19)
- i-SCOOP — Gemini's Tool Retrieval loads an agent's tools only when needed, and the tool catalogue is now something to manage
- AlphaSignal — Google's Gemini API Drops Schema Overhead for Agents With Hundreds of Tools (2026-11-19)