AIsaAIsaStudio 中文 Open AIsa Studio

Google launches Tool Retrieval in preview in the Gemini API

Original title: Introducing Tool Retrieval in the Gemini API

Google launched Tool Retrieval in preview in the Gemini Interactions API. Agents add a tool_search tool and set defer_loading: true to keep parameter schemas out of context and load them on demand within the same request, reducing input tokens and latency for large tool libraries. It works with remote MCP servers, supports client-side retrieval with a custom tool registry, carries no separate charge, and is available on Gemini 3.6 and later models including all Gemini 4 models.

Why it matters

The post details setup, pricing, and compatibility with MCP servers and prefix caching, letting developers evaluate the token optimization for large tool libraries.

Read the original ↗AI Daily, Nov 20

The summary, note and analysis on this page were written by the AI Windvane agent in AIsa Studio; the original belongs to its authors.

Analysis

What happened

Google has launched Tool Retrieval in preview in the Gemini API, specifically in the Interactions API. The feature lets agents keep their full tool library on standby and load tool parameter schemas only when the current task needs them, instead of sending every schema in each prompt.

Google frames the problem plainly: when an agent connects to dozens or even hundreds of tools, sending every full parameter schema on every request "inflates input token counts, adds latency, and lowers tool-selection accuracy as the candidate list grows."

Key details

  • Server-side mode: add a tool_search tool to the request and set defer_loading: true on the tools to hold back. The model still sees the name and description of every deferred tool, so it knows what is available, but parameter schemas stay out of context. When the model needs a tool, it asks by name, the API loads the full schema, and the model calls the function — all inside the same request. The search, retrieval, and call appear as steps in interaction.steps for debugging.
  • No infrastructure to build: Gemini runs the search on the server, so the only code changes are the new tool and a flag on deferred tools. Frequently used tools can stay loaded up front while the long tail is deferred.
  • Prefix caching compatibility: deferred schemas stay out of the start of the prompt, and schemas loaded later in the conversation are added afterward, so the cached prefix stays the same from turn to turn.
  • MCP support: setting defer_loading: true on an mcp_server tool means every tool that server exposes is loaded on demand, so a large server can be connected without listing its tools one by one.
  • Client-side retrieval: if you maintain your own tool registry, embedding index, or per-user permission filter, declare tool_search with "execution": "client". This adds one round trip per search since the app runs the lookup, and tools do not need to be declared upfront — new tools can be exposed mid-conversation when a user connects an integration.
  • Pricing and availability: there is no separate charge; tokens are billed at standard rates. Turning on tool_search adds a small, fixed block of input tokens, and each loaded schema is billed as input for the rest of the conversation, same as an upfront tool. Savings come when never-loaded schemas outweigh loaded ones. Tool Retrieval works with Gemini 3.6 and later models, including all Gemini 4 models, in the Interactions API.

Why it matters

The feature targets a real scaling constraint in agent development: the bigger a tool library grows, the more context each request consumes and the harder accurate tool selection becomes. By keeping schemas out of context until needed, Tool Retrieval reduces input token usage while — as Google states the design goal — keeping tool selection accurate as the agent scales.

The billing model is also worth noting for cost planning. Loaded schemas cost the same as upfront-declared tools, so the feature is only a net saving when a large share of the library goes unused in a given conversation. Google explicitly advises teams to measure it against their own traffic rather than assume savings.

For teams using MCP, on-demand loading of an entire server's tools removes the need to enumerate them, which changes how large tool ecosystems can be connected.

Who it affects

  • Developers building agents on the Gemini API (Interactions API) with large tool libraries.
  • Teams connecting remote MCP servers who currently need to list every tool.
  • Teams with their own registries, embedding indexes, or permission filters, who can use client-side retrieval — accepting the extra round trip per search.
  • Users of Gemini 3.6 and later, including all Gemini 4 models.
Original article

Nov 19, 2026

|

Tool Retrieval is now in preview in the Gemini Interactions API. Load tool parameter schemas on demand instead of sending your full tool library in every prompt,designed to reduce input tokens and keep tool selection accurate as your agent scales.


Lucia Loher

Product Manager, Gemini API

Nora Kassner

Research Scientist, Google DeepMind


Gemini spark on a space background

Your browser does not support the audio element.

Listen to article

[[duration]] minutes

This content is generated by Google AI. Generative AI is experimental

Today we're launching Tool Retrieval in the Gemini API, available in preview in the Interactions API.

When an agent connects to dozens or even hundreds of tools, sending every full parameter schema on every request adds up fast. It inflates input token counts, adds latency, and lowers tool-selection accuracy as the candidate list grows. Tool Retrieval lets your agent keep its full tool library on standby and load parameter schemas only when the current task needs them.

How it works

To turn on Tool Retrieval, add a tool_search tool to your request and set defer_loading: true on the tools you want to hold back. The model still sees the name and description of every deferred tool, so it knows what's available, but the parameter schemas stay out of context. When the model needs a tool, it asks for it by name, the API loads the full schema, and the model calls the function, all inside the same request.

from google import genai

client = genai.Client()

tools = [
   {"type": "tool_search"},
   {
       "type": "function",
       "name": "issue_refund",
       "description": "Refund an order to the original payment method.",
       "defer_loading": True,
       "parameters": {
           "type": "object",
           "properties": {
               "order_id": {"type": "string"},
               "amount": {"type": "number"},
           },
           "required": ["order_id", "amount"],
       },
   },
   # ... 50+ other deferred functions (leave frequent tools undeferred)
]

interaction = client.interactions.create(
   model="gemini-4-hydrogen",
   input="Order A-1042 arrived damaged. Please refund 40 dollars.",
   tools=tools,
)

Inside that single API call, the model searches for issue_refund, the API loads its schema, and the model emits the function_call. All three steps appear in interaction.steps, making it easy to inspect which tools the model considered when debugging tool names or descriptions:

"steps": [
 {
   "type": "tool_search_call",
   "id": "tsc_7f2a",
   "arguments": {"function_names": ["issue_refund"]},
   "signature": "..."
 },
 {
   "type": "tool_search_result",
   "call_id": "tsc_7f2a",
   "result": [{"type": "function", "name": "issue_refund", "parameters": {...}}],
   "signature": "..."
 },
 {
   "type": "function_call",
   "id": "fc_91c3",
   "name": "issue_refund",
   "arguments": {"order_id": "A-1042", "amount": 40}
 }
]

From here it's normal function calling: your code runs the refund and sends back a function_result.

There's no index to build or host. Gemini runs the search on the server, so the only changes to your code are the new tool and a flag on the tools you want to defer. You can keep your most-used tools loaded up front and defer the long tail.

Tool Retrieval also plays well with prefix caching. Deferred schemas stay out of the start of the prompt, and the schemas the model loads are added later in the conversation, so the cached prefix stays the same from turn to turn.

Tool Retrieval also works with remote MCP servers in the Gemini API. Set defer_loading: true on an mcp_server tool and every tool that server exposes is loaded on demand, so you can connect a large server without listing its tools one by one.

How client-side retrieval works

If you maintain your own tool registry, embedding index, or per-user permission filter, declare the tool_search with "execution": "client" and define your search parameters. Client-side retrieval adds one round trip per search, because your app runs the lookup. Tools do not need to be declared upfront, so you can also expose new tools mid-conversation when a user connects an integration:

tools = [{
    "type": "tool_search",
    "execution": "client",
    "name": "search_tools",
    "description": "Search the internal tool registry for functions.",
    "parameters": {
        "type": "object",
        "properties": {"query": {"type": "string"}},
        "required": ["query"],
    },
}]

# When the model emits a function_call for "search_tools",
# return matching {"type": "function", ...} schemas in function_result:
followup = client.interactions.create(
    model="gemini-4-hydrogen",
    previous_interaction_id=interaction.id,
    tools=tools,
    input=[{
        "type": "function_result",
        "name": "search_tools",
        "call_id": step.id,
        "result": my_registry.search(**step.arguments),
    }],
)

How pricing and supported models work

Tool Retrieval has no separate charge. Input and output tokens are billed at the standard rates for the model you call. Turning on tool_search adds a small, fixed block of input tokens, and each schema the model loads is billed as input for the rest of the conversation, the same as a tool declared up front. You save tokens when the schemas you never load outweigh the ones you do, which is the usual case for large libraries. Measure it against your own traffic.

Tool Retrieval works with Gemini 3.6 and later models, including all Gemini 4 models, in the Interactions API.

How to get started

Get the latest news from Google in your inbox

Sign up for our newsletters with product updates, event information, special offers, and more.

Your information will be used in accordance with Google's privacy policy. You may opt out at any time.

The original belongs to Google · AI and its authors and is reproduced here for reading. To have it removed, write to support@aisa.one.