Prezzo early bird (fino al 25 dic.), bloccato finché resti abbonato: Go a $10/mese (invece di $20), Plus con Opus 5.5 a soli $30/mese (invece di $50)Abbonati ora →

Gemini API Tool Retrieval: quando fa davvero risparmiare token (2026)

Un agente può conoscere centinaia di strumenti senza portarsi dietro, a ogni richiesta, tutti i relativi schemi dei parametri. È la promessa di Tool Retrieval nella Gemini API: nomi e descrizioni restano disponibili, mentre gli schemi completi vengono caricati soltanto per i tool necessari al compito. C'è però un rovescio della medaglia: ogni ricerca richiede un ulteriore passaggio del modello. Se l'agente cerca tool a ogni turno, il conto può salire anziché scendere.

Google ha lanciato la funzionalità in preview il 19 novembre 2026, esclusivamente nella Interactions API. Introduce il tool tool_search e il flag defer_loading: true. I tool differiti mostrano nome e descrizione, ma tengono il JSON dei parametri fuori dal contesto. Non è previsto un costo dedicato: si applicano le normali tariffe per input, input in cache e output.

Perché 200 tool potevano pesare 164.000 token prima ancora della prima chiamata

A incidere sul costo del prompt non è solo il numero di tool, ma soprattutto la dimensione dei loro schemi. Con cataloghi estesi, gli schemi possono finire per dominare l'intero contesto.

Un'analisi tecnica indipendente della documentazione Google riporta un confronto indicativo: circa 164.000 token di input senza differimento contro circa 23.650 con Tool Retrieval per una libreria da 200 tool, quando per ogni richiesta ne vengono usati solo pochi. Sono valori arrotondati tratti da quell'analisi, non un benchmark: il punto è smettere di pagare per gli schemi che non verranno mai usati.

C'è poi la precisione nella scelta. Decine di schemi simili che competono nello stesso contesto moltiplicano le occasioni di selezionare il tool sbagliato. Google presenta Tool Retrieval come un aiuto sia per il carico di token sia per l'accuratezza della selezione. Non sono però stati pubblicati dati sull'accuratezza: va quindi considerata un'ipotesi da verificare sui propri task.

Come funziona Gemini Tool Retrieval: tool_search e defer_loading

La configurazione richiede due frammenti dichiarativi sintetici: un elemento tool_search pari a {"type": "tool_search"} e "defer_loading": true su ogni tool da differire. La struttura completa della richiesta è mostrata nell'analisi della documentazione. Il modello continua a vedere nome e descrizione di ogni tool differito. Secondo la guida a defer_loading, se è impostato short_description il modello vede quel testo; in caso contrario, vede la prima frase della descrizione completa.

Il flusso lato server avviene tutto in una sola richiesta:

  1. Il modello emette tool_search_call, per esempio richiedendo issue_refund.
  2. L'API restituisce tool_search_result con lo schema completo.
  3. Il modello emette la vera function_call (nell'esempio di rimborso di Google compaiono order_id: "A-1042" e amount: 40 con il modello gemini-4-hydrogen).
  4. Il codice dell'app esegue l'operazione e restituisce function_result.

Registra tutto in interaction.steps. Se viene caricato il tool sbagliato, la prima cosa da controllare nella traccia sono nomi o descrizioni troppo vaghi.

Server o client: una richiesta oppure un round trip in più

ModalitàChi esegue la ricercaIndice da creareRound trip aggiuntiviQuando usarla
Lato server (predefinita)GeminiNessuno — "There's no index to build or host."Nessuno, nella stessa richiestaLibrerie grandi e perlopiù statiche; interi server MCP
Lato client ("execution": "client")La tua appIl tuo registro o indice di embeddingUno per ogni ricercaPermessi per utente, registri privati, tool aggiunti durante la conversazione

Il recupero lato server non richiede un indice ospitato e si completa nella stessa risposta. Secondo l'analisi della documentazione, impostare defer_loading: true su un tool mcp_server differisce tutti i tool esposti da quel server.

La modalità client usa tool_search con "execution": "client" (nell'esempio il nome è search_tools, con una stringa query obbligatoria). L'app restituisce le corrispondenze in un function_result, quindi prosegue con client.interactions.create includendo previous_interaction_id. Sempre secondo l'analisi citata, è consentito un solo tool_search per richiesta e le due modalità non sono combinabili.

Scegli la modalità client quando l'autorizzazione dipende dall'utente o le integrazioni possono comparire nel corso della conversazione: una ricerca lato server su un catalogo condiviso non applica da sola il filtro dei permessi per utente, secondo l'analisi citata. La stessa analisi indica inoltre che la modalità client consente di far comparire tool a conversazione avviata senza dichiararli tutti in anticipo.

I conti di Gemini Tool Retrieval: 26 token subito, poi un altro passaggio completo

Come chiarisce l'annuncio di Google, Tool Retrieval non comporta un addebito separato: "Tool Retrieval has no separate charge." Restano quattro voci a consumo, secondo l'analisi sull'economia dei token:

  • tool_search aggiunge un piccolo blocco fisso di token di input a ogni richiesta.
  • L'analisi citata stima circa 26 token per ogni riga con nome e descrizione di un tool differito.
  • Ogni ricerca lato server avvia un altro passaggio del modello sul contesto corrente, fatturato tramite total_tool_use_tokens per un volume vicino ai token di input del prompt, al netto dei cache hit, secondo l'analisi.
  • Ogni schema caricato continua a essere fatturato come input per il resto della conversazione e non può essere rimosso.
Carico di lavoro (stime illustrative dall'analisi citata)Senza retrievalCon retrievalEsito
200 tool, pochi usati per task~164.000 token~23.650 tokenRisparmio
10 tool, contesto da 30k, ricerca quasi a ogni turno~68.000 token~92.830 tokenCosta di più
Confronto illustrativo dei token di input per carichi di lavoro con Gemini Tool Retrieval

Il consiglio di Google, nello stesso annuncio, è netto: "Measure it against your own traffic."

"In modalità server... ogni ricerca lato server aggiunge un altro passaggio del modello sul contesto corrente... Perciò una grande libreria in cui ogni task usa pochi tool può trarne vantaggio. Una piccola libreria con una conversazione lunga e ricerche frequenti può invece costare di più." — @tekroch

Il differimento può rendere più stabile il prefisso in cache, ma può anche far scendere il prompt sotto la soglia minima per la cache. Secondo l'analisi citata, conviene quindi monitorare il tasso di cache hit insieme ai token di input.

Quando differire i tool e quando lasciarli già caricati

Con librerie piccole, conviene prima confrontare il caricamento statico: frequenza delle ricerche e dimensione degli schemi contano più di qualsiasi soglia basata sul numero di tool. Per cataloghi ampi in cui ogni task usa 1–3 tool, differisci lato server la coda lunga e mantieni non differiti i tool usati più spesso, cioè quelli presenti nella maggior parte delle richieste. Se i tool sono specifici per utente o compaiono a chat iniziata, usa la modalità client e considera un round trip per ogni ricerca.

Le note di implementazione citate elencano tre casi critici da gestire:

  1. Non differire un tool menzionato nelle istruzioni di sistema o nell'output di un altro tool: il modello potrebbe chiamarlo senza effettuare una ricerca e il turno successivo può fallire.
  2. Le funzioni differite devono comunque includere parameters completi nella richiesta; limitarsi a nome e descrizione può restituire uno schema vuoto e non invocabile.
  3. Nelle app stateless, ripeti a ogni turno senza modifiche tool_search_call, tool_search_result, firme e l'intero array tools.

La qualità della descrizione determina il recupero: prima di vedere lo schema, il modello sceglie tra nomi e descrizioni. "Search customer invoices by date range" è facilmente recuperabile; "Invoice helper" entra in collisione con altri tool. Il differimento non è un confine di sicurezza: nomi e descrizioni dei MCP differiti restano visibili come input del prompt, mentre i tool caricati operano con i permessi concessi, secondo l'analisi di sicurezza.

Cosa manca ancora nella preview

È una preview disponibile solo nella Interactions API, sulla superficie v1beta. Non supporta generateContent; secondo l'analisi della documentazione, usare defer_loading con un modello non supportato restituisce HTTP 400.

La copertura dei modelli è oggi più ristretta di quanto suggerisca l'annuncio: Google parla di Gemini 3.6 e versioni successive, inclusi tutti i modelli Gemini 4, mentre l'analisi citata riferisce che la documentazione live elenca attualmente gemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash e gemini-3.6-flash. Prima di dare per scontato il supporto dei modelli affini, verifica la documentazione per quello che usi. Non è stata annunciata una data per la disponibilità generale. Anthropic ha introdotto la stessa idea di defer_loading in beta nel novembre 2025; le differenze di Google sono il differimento MCP lato server e la modalità client, secondo la copertura del lancio.

Forma della libreriaModalità da sceglierePrima azione
Piccola e stabileCaricamento staticoMisura i token degli schemi prima di aggiungere complessità
50–200 tool, pochi usati per taskDifferimento lato serverDifferisci la coda lunga, mantieni caricati i tool più usati
Tool per utente o aggiunti a chat in corsoRetrieval lato clientCrea una ricerca che tenga conto dei permessi
Tutti i tool usati a ogni turnoCaricamento staticoL'overhead della ricerca probabilmente supera il risparmio

Rilascia inizialmente una sola porzione della coda lunga, poi confronta token di input, total_tool_use_tokens, latenza e successo del task con e senza differimento, usando task identici.

FAQ

Tool Retrieval funziona con generateContent?

No. Solo Interactions API su v1beta.

Quali modelli lo supportano?

È stato annunciato per Gemini 3.6 e versioni successive, incluso Gemini 4; l'analisi citata riferisce però che la documentazione live lo restringe attualmente a modelli che includono gemini-4-hydrogen e gemini-3.6-flash. Verifica la documentazione per il modello esatto.

Può aumentare la mia spesa?

Sì. Nel carico di lavoro illustrativo citato con 10 tool, il consumo sale da ~68.000 a ~92.830 token quando le ricerche avvengono quasi a ogni turno.