Google lanzó el 19 de noviembre Tool Retrieval en la API de Gemini, disponible en vista previa en la Interactions API. La función deja que un agente mantenga su biblioteca completa de herramientas en reserva y cargue los esquemas de parámetros solo cuando la tarea del momento los necesita.

El problema que ataca aparece cuando un agente se conecta a decenas o cientos de herramientas. Mandar el esquema completo de cada una en cada solicitud suma rápido. Infla la cuenta de tokens de entrada, agrega latencia y baja la precisión al elegir herramienta a medida que crece la lista de candidatas, según Google.

¿Cómo se activa Tool Retrieval?

Para encenderla hay que agregar una herramienta tool_search a la solicitud y marcar con defer_loading: true las herramientas que se quieren dejar en reserva. El modelo sigue viendo el nombre y la descripción de cada herramienta diferida, así que sabe qué tiene disponible, pero los esquemas de parámetros quedan fuera del contexto. Cuando el modelo necesita una, la pide por nombre, la API carga el esquema completo y el modelo llama a la función. Todo ocurre dentro de la misma solicitud.

Código
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,
)

En esa única llamada a la API, el modelo busca issue_refund, la API carga su esquema y el modelo emite el function_call. Los tres pasos quedan registrados en interaction.steps, lo que permite revisar qué herramientas consideró el modelo al depurar nombres o descripciones.

Código
"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}
 }
]

Desde ahí sigue el function calling de siempre. El código de la aplicación ejecuta el reembolso y devuelve un function_result.

Sin índice que construir ni alojar

Gemini hace la búsqueda en el servidor, así que no hay un índice que montar. Los únicos cambios en el código son la herramienta nueva y una marca en las herramientas que se quieren diferir. Google recomienda dejar cargadas desde el inicio las herramientas de uso frecuente y diferir el resto.

La función convive con el caché de prefijo. Los esquemas diferidos no aparecen al comienzo del prompt, y los que el modelo carga se agregan más adelante en la conversación, de modo que el prefijo cacheado no cambia de un turno a otro.

Tool Retrieval también funciona con los servidores MCP remotos de la API de Gemini. Basta con poner defer_loading: true en una herramienta mcp_server y cada herramienta que expone ese servidor se carga bajo demanda. Así se puede conectar un servidor grande sin listar sus herramientas una por una.

¿Cómo funciona la búsqueda del lado del cliente?

Quien mantenga su propio registro de herramientas, un índice de embeddings o un filtro de permisos por usuario puede declarar el tool_search con "execution": "client" y definir sus propios parámetros de búsqueda. Esta modalidad agrega un viaje de ida y vuelta por cada búsqueda, porque la consulta la ejecuta la aplicación. Las herramientas no necesitan declararse al comienzo, así que se pueden exponer herramientas nuevas a mitad de conversación, por ejemplo cuando el usuario conecta una integración.

Código
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),
    }],
)

¿Cuánto cuesta y con qué modelos funciona?

Tool Retrieval no tiene cobro aparte. Los tokens de entrada y salida se facturan a la tarifa normal del modelo que se llama. Activar tool_search suma un bloque pequeño y fijo de tokens de entrada, y cada esquema que el modelo carga se cobra como entrada por el resto de la conversación, igual que una herramienta declarada desde el principio.

El ahorro aparece cuando los esquemas que nunca se cargan pesan más que los que sí se cargan, que según Google es el caso habitual en bibliotecas grandes. La propia empresa recomienda medirlo contra el tráfico real de cada aplicación.

La función corre con Gemini 3.6 y modelos posteriores, incluidos todos los modelos Gemini 4, dentro de la Interactions API.

Documentación y soporte