Un agente con seis herramientas no tiene ningún problema. Un agente con sesenta o seiscientas herramientas paga un impuesto en cada solicitud. Cada herramienta que un desarrollador expone, como consultar un pedido o emitir un reembolso, viaja con un esquema de parámetros que lista sus argumentos, sus tipos y cuáles son obligatorios. Enviar cada esquema en cada turno hace crecer el mensaje, hace crecer la factura y obliga al modelo a elegir la herramienta correcta de una lista cada vez más larga.
Google nombra esos tres costos con claridad en su texto de lanzamiento: conteos de tokens de entrada inflados, latencia agregada y menor precisión en la selección de herramientas a medida que crece la lista de candidatas. Tool Retrieval, lanzado el 19 de noviembre de 2026 en vista previa en la API Gemini Interactions, es su respuesta. Este artículo explica qué hace la función, en qué se diferencian sus dos modos, cuánto cuesta en la práctica y dónde están sus límites documentados.
Gemini Tool Retrieval
Sitio oficialUna función en vista previa de la API Gemini para agentes con bibliotecas grandes de herramientas. Caso de uso principal: mantener decenas o cientos de herramientas disponibles para un agente sin enviar cada esquema completo de parámetros en cada solicitud.
Funciones clave: una herramienta tool_search más un indicador defer_loading: true en cada herramienta retenida; búsqueda del lado del servidor a cargo de Gemini sin ningún índice que el desarrollador deba construir ni alojar; un modo del lado del cliente para equipos con su propio registro, su propio índice de incrustaciones o su propio filtro de permisos; carga diferida para un servidor MCP remoto completo en un solo ajuste; y un registro visible de pasos en interaction.steps que muestra qué herramientas buscó y cargó el modelo.
Ventajas: las herramientas frecuentes pueden quedarse cargadas desde el inicio mientras la cola larga espera en reserva; los esquemas cargados se agregan más adelante en la conversación, por lo que el prefijo en caché al inicio del mensaje se mantiene estable de un turno a otro, según Google. Límites: la función está en vista previa y solo en la API Interactions; Google no publica cifras propias de ahorro, latencia ni precisión; y un esquema una vez cargado se queda cargado por el resto de la conversación.
Qué es
Una declaración de herramienta tiene dos trabajos. Le dice al modelo que una herramienta existe, y le dice al modelo exactamente cómo llamar a esa herramienta. Tool Retrieval separa esos trabajos en el tiempo. La parte de existencia, un nombre y una descripción corta, está presente desde el inicio. La parte de llamada, el esquema completo de parámetros, llega solo cuando el modelo decide que necesita esa herramienta para la tarea que tiene delante.
Esa distinción es toda la función. El modelo nunca queda ciego ante su biblioteca. Puede ver qué está disponible y razonar sobre qué herramienta encaja. Lo que no carga, turno tras turno, es la lista detallada de argumentos de cada herramienta que probablemente nunca tocará en esta conversación.
Google aconseja la división obvia. Mantén las herramientas que más usas cargadas desde el inicio de la forma normal. Difiere la cola larga, las herramientas que importan de vez en cuando y que cuestan tokens en cada otro turno mientras esperan.
Cómo funciona la recuperación del lado del servidor
Activar la función toma dos cambios, y Google recalca que no hay ningún índice que construir ni alojar porque Gemini ejecuta la búsqueda en el servidor. Agrega una herramienta tool_search a la solicitud. Luego ajusta defer_loading: true en cada herramienta que quieras retener. La documentación permite exactamente una herramienta tool_search por solicitud y exige la versión v1beta de la API, según la cobertura de esa documentación.
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,
)
El ejemplo de arriba es el ejemplo de reembolso del propio Google, acortado solo en la línea de comentario sobre el conteo que carga. Un cliente reporta que el pedido A-1042 llegó dañado y pide un reembolso de 40 dólares. Dentro de esa única llamada a la API, tres pasos ocurren en orden. El modelo emite un tool_search_call que pide issue_refund. La API responde con un tool_search_result que carga el esquema completo. El modelo luego emite un function_call normal con el identificador del pedido y el monto completos. Desde ahí es una llamada de función ordinaria: tu código ejecuta el reembolso y devuelve un function_result.
Los tres pasos aparecen en interaction.steps. Ese registro importa más de lo que parece a primera vista. Cuando un agente elige la herramienta equivocada o no elige la correcta, los pasos muestran qué herramientas consideró el modelo, lo que hace visibles los nombres débiles y las descripciones débiles como los errores que a menudo son. Nombrar herramientas ya era un oficio discreto en la construcción de agentes. Esta función lo vuelve un oficio registrado.
El modo del lado del cliente, para tu propio registro
No todos los equipos quieren que Google ejecute la búsqueda. Un equipo puede ya mantener su propio registro de herramientas, su propio índice de incrustaciones o un filtro de permisos que decide qué herramientas puede alcanzar un usuario dado. Para esos equipos Google ofrece la recuperación del lado del cliente. Declara la herramienta tool_search con "execution": "client" y define tus propios parámetros de búsqueda, como una sola cadena query.
El intercambio es claro. Tu aplicación ejecuta la búsqueda y devuelve las declaraciones de funciones que coinciden en un function_result, en una solicitud de seguimiento que apunta a la anterior. Eso cuesta un viaje de ida y vuelta extra por búsqueda. A cambio, las herramientas no necesitan declararse desde el inicio en absoluto, por lo que una herramienta nueva puede aparecer en mitad de una conversación cuando un usuario conecta una integración nueva. Los dos modos no se pueden mezclar en una sola solicitud.
Ese segundo punto se conecta con el trabajo que esta revista ha cubierto todo el mes. Los servidores MCP grandes plantean el mismo problema a mayor escala, ya sea que el servidor cargue cerca de veinte herramientas de análisis con acceso de escritura o 84 herramientas de tiendas de aplicaciones en una sola aplicación para Mac. Una biblioteca que crece por conexión, en lugar de por lanzamiento de código, necesita una regla de carga que crezca con ella.
Servidores MCP y el prefijo en caché
Los servidores MCP remotos obtienen la versión más simple de la función. Ajusta defer_loading: true en una herramienta mcp_server y cada herramienta que ese servidor expone se carga a demanda. No hay necesidad de listar las herramientas de un servidor grande una por una solo para diferirlas.
La caché obtiene un beneficio más discreto, y Google explica el mecanismo en lugar de solo afirmar el resultado. Los esquemas diferidos se quedan fuera del inicio del mensaje. Los esquemas que el modelo sí carga se agregan más adelante en la conversación. El tramo de apertura del mensaje, el prefijo del que depende la caché, por lo tanto se mantiene igual de un turno a otro. Un diseño que insertara cada esquema cargado cerca de la parte superior rompería esa caché y podría costar más de lo que ahorra.
Cuánto cuesta
No hay cargo separado por Tool Retrieval, y esa frase necesita el resto de esta sección para significar algo. Los tokens de entrada y de salida se facturan a las tarifas estándar del modelo que llamas. Lo que cambia es qué tokens existen.
| Parte de facturación | Qué cuenta |
|---|---|
La herramienta tool_search en sí | Un bloque fijo pequeño de tokens de entrada; Google no da su tamaño en el texto de lanzamiento |
| Cada línea de lista de una herramienta diferida | Unos 26 tokens por herramienta en las primeras pruebas, reportados desde la documentación |
| Cada esquema que carga el modelo | Facturado como entrada por el resto de la conversación, igual que una herramienta declarada desde el inicio |
| Cada búsqueda del lado del servidor | Un paso más del modelo sobre el contexto con los esquemas cargados, reportado como tokens de uso de herramientas y facturado a la tarifa de entrada, según la documentación |
| Cada búsqueda del lado del cliente | Un viaje de ida y vuelta extra entre tu aplicación y la API |
Haz la cuenta aproximada solo sobre la línea de lista. A unos 26 tokens por línea, una biblioteca de 100 herramientas diferidas agrega unos 2 600 tokens de entrada a una solicitud antes de que se cargue ningún esquema. Ese es un costo real, y también es claramente menor de lo que serían 100 esquemas completos, aunque Google no da ningún tamaño promedio de esquema que permita a nadie expresar la brecha como un número. El consejo final del propio Google es el honesto: ahorras tokens cuando los esquemas que nunca cargas superan a los que sí cargas, lo que llama el caso habitual para bibliotecas grandes, y deberías medir el efecto contra tu propio tráfico.
Los límites en la documentación
El texto de lanzamiento es corto. La documentación, tal como se reporta en una cobertura detallada de ella, carga reglas que dan forma al uso real y que merecen un espacio aquí.
Un esquema cargado no se puede descargar. Una vez que el modelo carga una herramienta en una conversación larga, ese esquema se queda en el contexto y sigue facturando por el resto de la conversación. La lista completa de herramientas también viaja cada vez: la API no carga las declaraciones de herramientas de una solicitud a la siguiente, por lo que la matriz completa de herramientas sale con cada solicitud de una conversación.
Una herramienta nombrada en tus instrucciones del sistema, o en la salida de otra herramienta, no debería diferirse, según la documentación. El modelo puede intentar llamar a una herramienta así sin buscar primero, y la solicitud siguiente puede entonces fallar. Una búsqueda que no coincide con ninguna herramienta diferida también es silenciosa: produce una respuesta en texto en lugar de un error estructurado de recuperación, por lo que el código que espera un paso tool_search_result para detectar un fallo esperará en vano.
El soporte también necesita cuidado. El texto de lanzamiento dice que la función funciona con modelos Gemini 3.6 y posteriores, incluidos todos los modelos Gemini 4. La documentación lista cuatro códigos de modelos con soporte, gemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash y gemini-3.6-flash, y dice que otros modelos devuelven un error cuando se ajusta defer_loading. Si el texto o la documentación va por delante del otro, Google no lo dice. Fija un modelo listado si construyes sobre esto en vista previa, y espera que la superficie cambie antes de la disponibilidad general. El método anterior generateContent no admite la función en absoluto.
Tercero en llegar a la misma idea
Google no menciona a ningún rival en su texto, pero el diseño tiene una historia que vale la pena registrar, porque te dice que esta es ahora la forma estándar para bibliotecas grandes de herramientas en lugar de un experimento de un solo proveedor.
| Proveedor | Lanzamiento | Nombre | Resultado publicado |
|---|---|---|---|
| Anthropic | 24 de noviembre de 2025 | Tool Search Tool | Reducción del 85 por ciento de tokens en sus propias pruebas, de unos 77 000 a unos 8 700 tokens |
| OpenAI | 5 de marzo de 2026 | Tool search | Reducción del 47 por ciento en el uso total de tokens en 250 tareas en 36 servidores MCP, en sus propias pruebas |
| 19 de noviembre de 2026 | Tool Retrieval | Ninguna cifra publicada |
Los tres usan el mismo nombre de indicador, defer_loading: true. Las cifras de las dos primeras filas vienen de las pruebas de cada empresa sobre sus propios modelos y no son comparables entre sí, y menos aún con un resultado de Gemini que todavía no existe. Lo que la tabla sí sostiene es más estrecho y aun así útil: tres proveedores grandes miraron el mismo costo, buscaron la misma división entre una lista y un esquema, y la lanzaron. Si construyes agentes en más de una plataforma, tus descripciones de herramientas ahora deben servir como listas consultables en todas ellas.
Lo que funciona
- Ningún índice que construir ni alojar en el modo del lado del servidor; dos cambios activan la función
- Las herramientas frecuentes se quedan cargadas mientras la cola larga espera a unos 26 tokens por línea
- Servidores MCP remotos completos se difieren en un ajuste, sin lista herramienta por herramienta
- Cada búsqueda, cada carga y cada llamada es visible en interaction.steps para depurar
- Los esquemas cargados se sientan tarde en el mensaje, por lo que el prefijo en caché se mantiene estable
Lo que no funciona
- Solo vista previa, solo en la API Interactions, con una lista de modelos documentada más estrecha que el texto del lanzamiento
- Ninguna cifra de ahorro, latencia ni precisión de Google para planificar
- Los esquemas cargados no se pueden descargar y siguen facturando por el resto de una conversación
- Las herramientas nombradas en las instrucciones del sistema no deberían diferirse, lo que descarta un hábito común de mensajes
- Una búsqueda fallida devuelve texto plano, no un error estructurado que tu código pueda atrapar con limpieza
Cuál deberías elegir
Elige la recuperación del lado del servidor si tu biblioteca es grande y tu registro es simple. Si tu agente ya declara decenas de herramientas en código y la cola larga es el problema, este es el camino más corto: una herramienta nueva, un indicador en las herramientas que difieres, y ninguna infraestructura de búsqueda propia que ejecutar ni mantener.
Elige la recuperación del lado del cliente si los permisos o el descubrimiento son tuyos para gobernar. Los equipos con un filtro de permisos por usuario, su propio índice de incrustaciones o herramientas que aparecen cuando un usuario conecta una integración necesitan la búsqueda en sus propias manos. El viaje extra por búsqueda es el precio de ese control, y para esos equipos claramente vale la pena pagarlo.
Quédate con la carga completa si tu biblioteca es pequeña. Un agente con un puñado de herramientas no gana nada con un paso de búsqueda, una línea de lista por herramienta y un paso más del modelo por búsqueda. Los esquemas completos desde el inicio son más simples, y lo simple gana hasta que el conteo lo hace perder. La misma cautela se aplica a conversaciones muy largas donde las cargas tempranas nunca se descargan: cuenta tus cargas probables antes de diferir.
Mira el patrón más amplio si pruebas agentes de navegación y de herramientas. Google ha estado construyendo lugares donde los agentes pueden fallar con seguridad, como muestra nuestro perfil de su web espejo sellada para agentes de navegación, y las herramientas de puntuación estrechas como la de nuestro tutorial de la API Gemini Decisions muestran el mismo instinto desde otro lado: darle al modelo menos que cargar, y hacer cada paso más fácil de inspeccionar.
Reflexiones finales
Tool Retrieval no es un lanzamiento llamativo, y eso es parte de por qué importa. Toma un costo que cada constructor serio de agentes ya paga en silencio, los esquemas de las herramientas que la tarea actual nunca usará, y vuelve ese costo opcional para las herramientas que se quedan en espera. El mecanismo es pequeño, el registro de pasos es de verdad útil, y los detalles de MCP y de caché muestran que el diseño se pensó como un sistema en lugar de como una demostración.
Las cifras que faltan son la brecha honesta. Una función vendida por ahorrar tokens y proteger la precisión debería terminar por mostrar su trabajo, y Google todavía no lo ha hecho. Hasta que lo haga, trata Tool Retrieval como un diseño sólido en vista previa, verifica la lista de modelos contra la documentación en lugar del texto, y deja que tu propio tráfico te diga cuánto ahorra. Las bibliotecas de cientos de herramientas no van a desaparecer. Pagar el precio completo por describirlas todas en cada turno sí debería desaparecer.
Fuentes
- Lanzamiento, mecanismo, ejemplo de reembolso, afirmaciones sobre MCP y caché, declaración de precios y texto sobre modelos: Gemini API tool retrieval for efficient agent scaling, Google
- Detalle de la documentación, componentes de facturación, lista documentada de modelos, reglas de descarga y de nombres, y cifras de comparación de Anthropic y OpenAI: Google shrinks idle tools in Gemini agents to about 26 tokens each, PPC Land
- Resumen independiente del lanzamiento, los modos y el estado de vista previa: Gemini’s Tool Retrieval: Stop Paying for Tools Your Agent Never Calls, DEV Community
- Imágenes del héroe y del flujo: ilustraciones de Dirty Static, generadas en el estilo de la casa
FIN DE LA TRANSMISIÓN
Mantén la curiosidad. Cuestiónalo todo.


