Gemini API - agents - tool calling - AI development
4 min lectura

Gemini Tool Retrieval: Load Agent Tool Schemas Only When Needed

Google added Tool Retrieval preview to the Gemini Interactions API. See a deferred read-only tool, a cost test, and the permission boundary.

Gemini Tool Retrieval: Load Agent Tool Schemas Only When Needed

A small-business agent might have functions for order lookup, inventory, refunds, shipping quotes, and policy search. Sending the full parameter schema of 50 functions with every request consumes context even when the user needs only one. On November 19, 2026, Google announced Tool Retrieval for the Gemini API. The agent sees tool names and descriptions first, then loads detailed parameters when a tool is relevant. Google lists the feature as a preview in the Interactions API for Gemini 3.6 and later models.

What the API now does

Add a tool_search tool and mark less common functions with defer_loading: true. During an interaction, Gemini can search its available functions, load the selected schema, and emit a function call. The search, result, and call appear in interaction.steps, which gives developers a way to inspect tool selection. With Google's hosted retrieval, you do not have to build or host a separate index. A client-side option exists if your app already has a tool registry or per-user filtering, but it adds a round trip for each search.

This is most compelling for large catalogs. With only two tiny functions, the fixed input overhead of tool search may outweigh any savings. Google says Tool Retrieval has no separate fee, while ordinary model tokens still cost money. Schemas that are eventually loaded are billed as input for the remainder of the conversation.

Try a read-only function first

With the current Gemini Python SDK and an API key configured, this example follows the shape in Google's announcement. It declares a harmless test-order lookup, not a payment or refund action:

from google import genai

client = genai.Client()
tools = [
    {"type": "tool_search"},
    {
        "type": "function",
        "name": "lookup_order",
        "description": "Read the status of a test order by ID.",
        "defer_loading": True,
        "parameters": {
            "type": "object",
            "properties": {"order_id": {"type": "string"}},
            "required": ["order_id"],
        },
    },
]

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Look up the status of test order A-1042.",
    tools=tools,
)
for step in interaction.steps:
    print(step.type)

The snippet passed a local Python syntax check. We did not run it against the API or verify preview access on an account. If the model emits lookup_order, your backend must still check that the requesting user may see that order, run the function, and return the result. Tool discovery is not authorization.

Measure the tradeoff on your own traffic

  1. Prepare 20 representative test requests, including common and rare tool needs. Hold the model, prompt, and tool library constant.
  2. Compare a run with complete schemas against one with tool_search and deferred long-tail functions. Record input tokens, latency, selected function, and whether the task was completed correctly.
  3. Keep high-frequency functions loaded up front. Deferring every function can add a search step to ordinary requests.
  4. Enforce per-user permissions on your server before any sensitive action, even when the right tool was found.

Choose based on the tasks and costs you observe. Google's announcement describes lower token use and better tool selection at scale; it does not establish how much your particular agent will save. Deferred remote MCP servers are also supported, according to Google, but test their authentication, permissions, and added latency separately before production use.

Primary source: Google, “Introducing Tool Retrieval in the Gemini API”, November 19, 2026. Access, model support, and billing claims come from Google. The read-only test and measurement plan are editorial adaptations.

Comentarios

Aún no hay comentarios. Sé el primero.

Deja un comentario