- 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
La ricerca di strumenti è attiva per impostazione predefinita, con le eccezioni elencate in Configurare la ricerca di strumenti. Quando è 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 fino a quando l’SDK compatta i messaggi in cui l’agente li ha scoperti. Dopo tale compattazione, l’agente ricerca di nuovo quegli strumenti quando ne ha nuovamente bisogno. La ricerca di strumenti aggiunge un extra round-trip ogni volta che Claude cerca strumenti, ma per grandi set di strumenti questo è compensato da un contesto più piccolo ad ogni turno. Con meno di ~10 strumenti le cui definizioni si adattano comodamente alla finestra di contesto, 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 non è supportata su Microsoft Foundry distribuzioni ospitate su Azure, che la rifiutano lato server: l’SDK rileva il rifiuto e carica le definizioni degli strumenti in anticipo per quella distribuzione.
ENABLE_TOOL_SEARCH non può ignorare questo, poiché il rifiuto proviene dalla distribuzione stessa.Configurare la ricerca di strumenti
La ricerca di strumenti è attiva per impostazione predefinita. Per i modelli nell’elenco dei modelli non supportati dell’SDK, l’SDK carica invece le definizioni degli strumenti in anticipo, e nessun valore diENABLE_TOOL_SEARCH può sovrascrivere questo comportamento. Su Google Cloud’s Agent Platform, l’SDK decide in base alla generazione del modello:
- Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 e successivi: la ricerca di strumenti è attiva per impostazione predefinita.
- Modelli precedenti di Agent Platform: l’SDK carica le definizioni degli strumenti in anticipo, perché i loro stack di servizio rifiutano l’intestazione beta richiesta.
ENABLE_TOOL_SEARCHnon può sovrascrivere questo comportamento.
ENABLE_TOOL_SEARCH.
L’SDK disabilita anche la ricerca di strumenti quando ANTHROPIC_BASE_URL punta a un host non di prima parte, poiché la maggior parte dei proxy non inoltra i blocchi tool_reference. Puoi sovrascrivere questo valore predefinito con la variabile d’ambiente ENABLE_TOOL_SEARCH:
L’impostazione
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS mantiene la ricerca di strumenti disattivata. Non puoi sovrascriverla impostando tu stesso ENABLE_TOOL_SEARCH. Su Claude Code v2.1.227 o successivo, la tua organizzazione può mantenere attiva la ricerca di strumenti nonostante questa variabile tramite le impostazioni gestite. In una sessione che riceve la configurazione HIPAA, la ricerca di strumenti è disattivata, e né ENABLE_TOOL_SEARCH né le impostazioni gestite la riattivano. Disabilitare le capacità pre-release spiega dove si applica l’override e cosa rimuove la variabile.
La ricerca di strumenti si applica a tutti gli strumenti registrati, che provengano da server MCP remoti o da server MCP SDK personalizzati. Quando usi auto, l’SDK conta ogni definizione che la ricerca di strumenti può differire verso un’unica soglia combinata: ogni strumento MCP che non è contrassegnato come alwaysLoad, da qualsiasi server, più gli strumenti integrati che si caricano su richiesta. L’SDK carica in anticipo gli strumenti integrati principali come Bash, Read ed Edit e non li conta verso la soglia. Un mod in uno dei tuoi plugin può anche differire uno strumento o caricarlo in anticipo, il che modifica questo conteggio.
Imposta il valore nell’opzione env di query(). In TypeScript, env sostituisce l’ambiente del sottoprocesso, quindi espandi ...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, li pre-approva tutti con un carattere jolly e usa auto:5 in modo che la ricerca di strumenti si attivi quando le definizioni che può differire raggiungono il 5% della finestra di contesto:
https://tools.example.com/mcp con l’URL del tuo 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 capire perché un’esecuzione non è riuscita, controlla il subtype del messaggio di risultato, come error_during_execution, all’interno del ciclo. Per ulteriori informazioni sui messaggi di risultato, consulta Gestire il risultato.
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: Opus 4, Sonnet 4, Haiku 4.5 e modelli successivi, oppure Opus 4.5, Sonnet 4.5, Haiku 4.5 e modelli successivi su Google Cloud’s Agent Platform. Sui modelli precedenti l’SDK carica le definizioni degli strumenti in anticipo, come descritto in Configurare la ricerca degli strumenti.
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