- Efficienza del contesto: Le definizioni degli strumenti possono consumare grandi porzioni della finestra di contesto (50 strumenti possono utilizzare 10-20K token), lasciando meno spazio per il lavoro effettivo.
- Accuratezza della selezione degli strumenti: L’accuratezza della selezione degli strumenti si degrada con più di 30-50 strumenti caricati contemporaneamente.
Come funziona la ricerca di strumenti
Quando la ricerca di strumenti è attiva, le definizioni degli strumenti vengono trattenute dalla finestra di contesto. L’agente riceve un riepilogo degli strumenti disponibili e cerca quelli rilevanti quando l’attività richiede una capacità non già caricata. Fino a cinque dei più rilevanti strumenti vengono caricati nel contesto per impostazione predefinita, dove rimangono disponibili per i turni successivi. Se la conversazione è abbastanza lunga da far sì che l’SDK compatti i messaggi precedenti per liberare spazio, gli strumenti precedentemente scoperti possono essere rimossi e l’agente ricerca di nuovo secondo le necessità. La ricerca di strumenti aggiunge un extra round-trip la prima volta che Claude scopre uno strumento (il passaggio di ricerca), ma per grandi set di strumenti questo è compensato da un contesto più piccolo ad ogni turno. Con meno di ~10 strumenti, il caricamento di tutto in anticipo è generalmente più veloce. Per i dettagli sul meccanismo API sottostante, vedere Ricerca di strumenti nell’API.La ricerca di strumenti è supportata su Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.5 e modelli successivi; vedere compatibilità dei modelli nella documentazione API per l’elenco attuale. Su Google Cloud’s Agent Platform, i modelli supportati minimi sono Claude Sonnet 4.5 e Claude Opus 4.5.
Configurare la ricerca di strumenti
La ricerca di strumenti è attiva per impostazione predefinita. È disabilitata per impostazione predefinita su Google Cloud’s Agent Platform, dove è supportata per Claude Sonnet 4.5 e successivo e Claude Opus 4.5 e successivo. È anche disabilitata quandoANTHROPIC_BASE_URL punta a un host non di prima parte, poiché la maggior parte dei proxy non inoltrano i blocchi tool_reference. Potete ignorare uno qualsiasi dei valori predefiniti con la variabile di ambiente ENABLE_TOOL_SEARCH:
L’impostazione
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS mantiene la ricerca di strumenti disattivata, e ENABLE_TOOL_SEARCH non può ignorarla. La variabile rimuove l’intestazione beta che le definizioni degli strumenti defer_loading e i blocchi di contenuto tool_reference richiedono.
La ricerca di strumenti si applica a tutti gli strumenti registrati, che provengano da server MCP remoti o da server MCP SDK personalizzati. Quando si utilizza auto, la soglia si basa sulla dimensione combinata di tutte le definizioni degli strumenti su tutti i server.
Impostare il valore nell’opzione env su query(). In TypeScript, env sostituisce l’ambiente del sottoprocesso, quindi diffondere ...process.env per mantenere le variabili ereditate. In Python, env viene unito sopra l’ambiente ereditato. Questo esempio si connette a un server MCP remoto che espone molti strumenti, pre-approva tutti loro con un carattere jolly e utilizza auto:5 in modo che la ricerca di strumenti si attivi quando le loro definizioni superano il 5% della finestra di contesto:
https://tools.example.com/mcp con l’URL del vostro server MCP. In caso di successo, il testo del risultato viene stampato sulla console.
Poiché si tratta di una chiamata query() a singolo scatto, l’SDK genera un’eccezione dopo aver restituito un risultato di errore, quindi l’esempio racchiude il ciclo in un blocco try. Per vedere perché un’esecuzione non è riuscita, controllare il subtype del messaggio di risultato, come error_during_execution, all’interno del ciclo. Per ulteriori informazioni sui messaggi di risultato, vedere Gestire il risultato.
Impostare ENABLE_TOOL_SEARCH su "false" disabilita la ricerca di strumenti e carica tutte le definizioni degli strumenti nel contesto ad ogni turno. Questo rimuove il round-trip di ricerca, che può essere più veloce quando il set di strumenti è piccolo (meno di ~10 strumenti) e le definizioni si adattano comodamente nella finestra di contesto.
Ottimizzare la scoperta degli strumenti
Il meccanismo di ricerca abbina le query ai nomi e alle descrizioni degli strumenti. Nomi comesearch_slack_messages emergono per una gamma più ampia di richieste rispetto a query_slack. Le descrizioni con parole chiave specifiche (“Cerca messaggi Slack per parola chiave, canale o intervallo di date”) corrispondono a più query rispetto a quelle generiche (“Query Slack”).
Potete anche aggiungere una sezione di prompt di sistema che elenca le categorie di strumenti disponibili. Questo dà all’agente il contesto su quali tipi di strumenti sono disponibili per la ricerca. Passate il testo attraverso l’opzione systemPrompt in TypeScript o system_prompt in Python, utilizzando il preset claude_code con append, che aggiunge il vostro testo al prompt del preset invece di sostituirlo:
Limiti
- Strumenti massimi: 10.000 strumenti nel vostro catalogo
- Risultati di ricerca: restituisce fino a cinque strumenti più rilevanti per ricerca per impostazione predefinita
- Supporto del modello: Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.5 e modelli successivi; consultare la compatibilità del modello nella documentazione API per l’elenco attuale. Su Google Cloud’s Agent Platform, Claude Sonnet 4.5 e successivi e Claude Opus 4.5 e successivi.
Documentazione correlata
- Ricerca di strumenti nell’API: Documentazione API completa per la ricerca di strumenti, incluse implementazioni personalizzate
- Connettere server MCP: Connettere a strumenti esterni tramite server MCP
- Strumenti personalizzati: Creare i vostri strumenti con server MCP SDK
- Riferimento SDK TypeScript: Riferimento API completo
- Riferimento SDK Python: Riferimento API completo