# How to Set Up Gemini API Tool Retrieval: Models, Pricing, Limits

> Google put Tool retrieval in preview in the Gemini Interactions API on November 19, 2026. See the models, the steps, how it is billed and its limits.

Source: https://www.epifive.com/blog/gemini-api-tool-retrieval-set-up · Published 2026-11-21 · EpiFive

## Key takeaways

- Tool retrieval is a preview feature of the Gemini Interactions API, announced in the changelog on November 19, 2026.
- Add a tool_search tool and set defer_loading to true on the functions or MCP servers you want loaded on demand.
- It needs v1beta, the Interactions API and a supported model such as gemini-4-hydrogen or gemini-3.6-flash.
- There is no separate fee, but each server-side search adds an internal model call billed at the input rate.
- Loaded schemas stay in context for the rest of the conversation, so keep frequently used tools undeferred.

Google added Tool retrieval (Preview) to the Gemini Interactions API, according to its API changelog entry dated November 19, 2026. Instead of sending every function schema with every request, you mark tools with `defer_loading: true`, add a `{"type": "tool_search"}` tool, and Gemini loads a schema only when the model needs it. To start, use the `v1beta` API version with a supported model and the Interactions API.

## What Tool retrieval is

Agents with large tool libraries pay for them in tokens. Every request carries the name, description and parameter schema of each tool, and Google's guide says tool selection accuracy drops as the candidate list grows. Tool retrieval changes what the model sees at the start of a request. For each deferred tool it sees the name and description, but not the parameter schema. When the model decides it needs a tool, the schema is retrieved and the model emits the function call, all in one request in the default mode.

Google's changelog describes the change this way: the Interactions API can now search your tool library and load function schemas on demand, so large tool sets no longer have to be sent in full on every request. Google's announcement on its blog frames the benefits as fewer input tokens, better tool selection and lower latency. Those benefits are Google's claims; the blog itself advises measuring against your own traffic.

There are three ways to handle tools after this release, and the guide compares them:

| | Static loading | Server-side retrieval | Client-side retrieval |
|---|---|---|---|
| Who searches | Nobody (all schemas sent) | Gemini | Your app |
| Extra round trips | None | None | One per search |
| Best for (per the guide) | Fewer than 20 stable tools | Large known libraries and MCP servers | Dynamic registries, namespaces, per-user tools |

Server-side retrieval is the default. The guide recommends it for latency-sensitive apps because the search runs within a single API call.

## Who it is for and availability

Tool retrieval is for developers building agents on the Gemini API who have many tools, or who connect remote MCP servers that expose many tools. It is not a consumer feature and has no app setting.

| Item | What Google documents |
|---|---|
| Status | Preview; the API surface may change before general availability |
| API surface | Interactions API only; `generateContent` does not support it |
| API version | `v1beta` |
| Supported models | `gemini-4-carbon`, `gemini-4-neon`, `gemini-4-hydrogen`, `gemini-4-argon`, `gemini-3.8-flash`, `gemini-3.6-flash` |
| Price | No separate charge; standard model token rates apply |
| Regions and plans | The pages we opened do not list region or plan limits for this feature |

The changelog states support as "Gemini 3.6 and later models, including all Gemini 4 models." The guide's model list is the more specific one, so check it before you pick a model.

For context on price, the Gemini API pricing page lists `gemini-3.6-flash` at $0.75 per 1M input tokens and $3.75 per 1M output tokens on the Standard paid tier through December 31, 2026, rising to $1.50 and $7.50 from January 1, 2027, as of November 21, 2026. The page labels that model the "previous generation Flash model." Because Tool retrieval adds no fee of its own, its cost is whatever your chosen model charges.

## Requirements

- A Gemini API key and the Interactions API (not `generateContent`).
- The `v1beta` API version. The guide shows the client setup as `genai.Client(http_options={"api_version": "v1beta"})` in Python and `new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } })` in JavaScript.
- A supported model from the list above.
- For stateless use (`store=False`), an SDK version that supports the new step types (`tool_search_call` and `tool_search_result`).
- Function tools with full `parameters` defined. The guide says that without them the model cannot call the tool after retrieval.

## How to set up Tool retrieval, step by step

### Server-side retrieval (default)

1. Create a client that uses `v1beta`, as shown above.
2. Add `{"type": "tool_search"}` to the `tools` array. Do not set `name`, `description` or `parameters` on a server-side `tool_search`; the guide says those are only for client-side execution.
3. On each function you want to hold back, set `defer_loading: true`. The guide's Python example declares a function with `"type": "function"`, a `name` (`convert_currency`), a `description` and `"defer_loading": True`, plus its parameters.
4. Call the Interactions API. The guide's Python call is:

```python
interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Convert 100 USD to EUR.",
    tools=tools,
)
```

5. Read `interaction.steps`. Google says you will see a `tool_search_call` and a `tool_search_result`, which the API resolves internally, followed by a `function_call`. Your application runs only the `function_call`, then returns a `function_result` as usual.
6. Check `interaction.steps` for a `function_call` on every response. The guide says not to rely on `status` alone, because it is not always `requires_action` when a function call is returned.

Optional: add `short_description` to a deferred function. The guide describes it as a compact summary shown during retrieval instead of the full `description`, valid only on deferred functions. It suggests naming the service at the start of the text.

### Deferring a remote MCP server

Set `defer_loading: true` on an `mcp_server` tool next to a server-side `tool_search`. The guide says this defers every tool the server exposes. When the model calls one, the API runs it on the remote server and returns `mcp_server_tool_call` and `mcp_server_tool_result` steps. Connection setup is covered in the Remote MCP section of Google's function-calling documentation.

### Client-side retrieval

Use this when you want your own registry, embeddings or permission filters, or want to add tools mid-conversation. The API reference for `ToolSearch` says `execution` takes `server` (default) or `client`, and that `name`, `description` and `parameters` are set only for client-side execution.

1. Declare a `tool_search` tool with `"execution": "client"`, plus a `name` (the guide's example is `search_tool_registry`), a `description` and the search `parameters`.
2. Turn 1: the model calls your search function.
3. Your code runs its own lookup and returns complete function declarations in `function_result.result`. Return objects, not JSON strings.
4. Turn 2: send the `function_result` with `previous_interaction_id`. The returned tools do not need to be in the initial `tools` array.
5. Turn 3: the model calls the discovered tool.

This mode costs one round trip per search.

### Multi-turn and stateless use

The guide gives these rules:

- Resend the full `tools` array on every request, including follow-up `function_result` turns, because the API does not persist tool declarations.
- With `store=False`, append every model-generated step to your history unchanged, keep `tool_search_call` and `tool_search_result` in order before the `function_call`, and preserve the `signature` fields on `tool_search_call`, `tool_search_result`, `thought` and `function_call` steps.

### How to turn it off

Remove `defer_loading` from the tools and drop the `tool_search` entry. The tools are then sent in full again (static loading). The guide describes no separate switch.

## Limitations

From Google's guide:

- Interactions API on `v1beta` only.
- Server-side and client-side retrieval cannot be combined in one request, and you can include one `tool_search` entry per request.
- `defer_loading` works only with server-side retrieval.
- The model may issue several searches in one turn.
- Loaded tools stay in context for the rest of the conversation and cannot be unloaded.
- A search that matches nothing returns a text response, not a structured error.

Best practices the guide lists: leave core, frequently used tools loaded and defer the long tail; do not defer tools named in system instructions or tool outputs, since the model may call them without searching; prefix related tool names by service (for example `billing_` and `crm_`); and for client-side retrieval, list the searchable namespaces in the description.

Common errors the guide names:

| Problem | Fix per the guide |
|---|---|
| `defer_loading` without `tool_search` | Include `tool_search` on every request, or remove `defer_loading` |
| Missing `tool_search_call` in stateless requests | Replay all search steps unchanged |
| Missing `signature` | Append response steps to history without modifying them |
| Unsupported model | Use a model from the supported list |

## Privacy and admin notes

The pages we opened say nothing specific about data use or retention for Tool retrieval; it runs inside the Interactions API, so the Gemini API terms for that API apply. Check Google's terms for your tier before sending sensitive data.

Two billing points matter for budgets. Per the guide, deferred tools add only their name and short description to input tokens, and parameter schemas are not billed until loaded. But each loaded schema is appended to the conversation and billed as input for the rest of it, and each server-side search triggers an extra internal model call reported in `total_tool_use_tokens` at the input rate. Google's blog adds that `tool_search` itself adds a small fixed block of input tokens. The guide says retrieval saves money with large libraries and few tools used per request, and that small libraries, or long contexts that search every turn, may be cheaper with static loading.

Caching: retrieved schemas are appended rather than changing the prompt prefix, so implicit caching still applies. The guide warns that deferring tools can shrink a prompt below the model's minimum cacheable size.

For related reading on how Google's newest model is billed, see [How to Use Gemini 4 Neon](https://www.epifive.com/blog/gemini-4-neon-use-pricing-availability).

## See also

- [Sarvam AI Token Factory: Models, Pricing and the Sovereign AI Debate](https://www.epifive.com/blog/sarvam-ai-token-factory-chinese-models-explained)
- [How to use GPT-6.2 Astra and Sol in the API: pricing and limits](https://www.epifive.com/blog/gpt-6-2-astra-sol-api-pricing-limits)
- [Claude Tool Use in Python: Build a Simple Agent Loop Step by Step](https://www.epifive.com/blog/claude-tool-use-python-agent-loop)

## What we checked

- Opened the Gemini API changelog (redirected to aistudio.google.com/docs/changelog) on 2026-11-21: the November 19, 2026 "Tool retrieval (Preview)" entry confirms `defer_loading: true`, the `{"type": "tool_search"}` tool, `execution: "client"`, MCP support and "Gemini 3.6 and later models, including all Gemini 4 models."
- Opened the Tool retrieval guide (aistudio.google.com/docs/tool-retrieval) on 2026-11-21: source of the `v1beta` requirement, the supported model list, the modes table, the pricing notes, limitations and error list. The guide did not display the full tools array in the page text we read, so we describe its fields instead of reproducing it.
- Cross-checked the `ToolSearch` schema in the Interactions API reference: `execution` values `server` (default) and `client`, `defer_loading` on function and MCP server tools, and `short_description` for deferred functions all match the guide.
- Opened Google's blog post on Tool retrieval: matches the guide on server and client modes, `interaction.steps` contents and caching; the savings are Google's claims and we did not measure them.
- Opened the Gemini API pricing page: `gemini-3.6-flash` Standard paid-tier prices quoted above. It showed no separate Tool retrieval price (we read about the first 100,000 of 117,956 characters).
- Not tested with a live API key; no request was run and no output was observed. Steps follow Google's documentation as of 2026-11-21, and the feature is in preview, so details may change.

Last tested: 2026-11-21

## Sources

- [Gemini API release notes, November 19, 2026 entry](https://ai.google.dev/gemini-api/docs/changelog#2026-11-19-tool-retrieval-preview)
- [Tool retrieval guide](https://aistudio.google.com/docs/tool-retrieval)
- [Gemini API tool retrieval for efficient agent scaling (Google blog)](https://blog.google/innovation-and-ai/technology/developers-tools/gemini-api-tool-retrieval/)
- [Gemini Interactions API reference](https://aistudio.google.com/api-reference/interactions-api.md.txt)
- [Gemini API pricing](https://aistudio.google.com/docs/pricing)
- [Function calling and Remote MCP](https://ai.google.dev/gemini-api/docs/function-calling#mcp)

## Frequently asked questions

### What is Tool retrieval in the Gemini API?

It is a preview feature of the Interactions API that lets Gemini search your tool library and load a function's parameter schema only when the model needs it, instead of sending every schema on every request. You turn it on by adding a tool_search tool and setting defer_loading to true on the tools you want to hold back.

### Which models support Tool retrieval?

Google's changelog says it works with Gemini 3.6 and later models, including all Gemini 4 models, in the Interactions API. The Tool retrieval guide lists gemini-4-carbon, gemini-4-neon, gemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash and gemini-3.6-flash.

### Does Tool retrieval cost extra?

Google's guide says there is no separate charge. Tokens bill at the model's standard input, cached and output rates. Each server-side search triggers an extra internal model call that is reported in total_tool_use_tokens and billed at the input rate.

### Can I use it with generateContent?

No. The guide says it is available only in the Interactions API on v1beta, and generateContent does not support it.

### Can I unload a tool after the model loads it?

No. The guide lists as a limitation that loaded tools stay in context for the rest of the conversation and cannot be unloaded.

