Strumento di ricerca degli strumenti

Lo strumento di ricerca degli strumenti consente a Claude di lavorare con centinaia o migliaia di strumenti scoprendoli e caricandoli su richiesta. Invece di caricare tutte le definizioni degli strumenti nella "context window" (finestra di contesto) in anticipo, Claude cerca nel tuo catalogo di strumenti (inclusi nomi degli strumenti, descrizioni, nomi degli argomenti e descrizioni degli argomenti) e carica solo gli strumenti di cui ha bisogno.

Caricare ogni definizione di strumento in anticipo causa due problemi man mano che una libreria di strumenti cresce:

• Sovraccarico del contesto: una tipica configurazione multi-server (GitHub, Slack, Sentry, Grafana e Splunk) può consumare circa 55k token in definizioni prima che Claude svolga qualsiasi lavoro. La ricerca degli strumenti riduce tipicamente questo valore di oltre l'85 percento, caricando solo i 3–5 strumenti di cui Claude ha bisogno per una determinata richiesta.
• Accuratezza nella selezione degli strumenti: la capacità di Claude di scegliere lo strumento giusto si degrada una volta superati i 30–50 strumenti disponibili. Poiché la ricerca degli strumenti carica su richiesta solo un insieme mirato di strumenti rilevanti, l'accuratezza della selezione rimane elevata anche con migliaia di strumenti.

La ricerca degli strumenti è generalmente disponibile sull'API di Claude. Per i modelli supportati, consulta Compatibilità dei modelli.

La ricerca degli strumenti viene eseguita come strumento lato server, ma puoi anche implementare la tua ricerca degli strumenti lato client. Consulta Implementazione personalizzata della ricerca degli strumenti per i dettagli.



Compatibilità dei modelli

Entrambe le varianti di ricerca degli strumenti sono disponibili sui seguenti modelli:

Claude Opus 4.1 e i modelli precedenti non supportano lo strumento di ricerca degli strumenti.



Come funziona la ricerca degli strumenti

Esistono due varianti di ricerca degli strumenti:

• Regex (tool_search_tool_regex_20251119): Claude costruisce pattern regex per cercare gli strumenti.
• BM25 (tool_search_tool_bm25_20251119): Claude utilizza query in linguaggio naturale per cercare gli strumenti.

Quando abiliti lo strumento di ricerca degli strumenti:

1. Includi uno strumento di ricerca degli strumenti (ad esempio, tool_search_tool_regex_20251119 o tool_search_tool_bm25_20251119) nella tua lista tools.
2. Fornisci ogni definizione di strumento nell'array tools e imposti defer_loading: true sugli strumenti che non devono essere caricati in anticipo. Almeno uno strumento, normalmente lo strumento di ricerca degli strumenti stesso, deve rimanere non differito.
3. Inizialmente, il contesto di Claude contiene solo lo strumento di ricerca degli strumenti e gli eventuali strumenti non differiti.
4. Quando Claude ha bisogno di strumenti aggiuntivi, li cerca utilizzando uno strumento di ricerca degli strumenti.
5. L'API esegue la ricerca e restituisce gli strumenti corrispondenti come blocchi tool_reference (fino a 5 per impostazione predefinita).
6. L'API espande automaticamente questi riferimenti in definizioni complete degli strumenti.
7. Claude seleziona tra gli strumenti scoperti e li chiama.



Avvio rapido

L'esempio seguente include lo strumento di ricerca degli strumenti e due strumenti differiti:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=2048,
    messages=[{"role": "user", "content": "What is the weather in San Francisco?"}],
    tools=[
        {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},
        {
            "name": "get_weather",
            "description": "Get the weather at a specific location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"},
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
                },
                "required": ["location"],
            },
            "defer_loading": True,
        },
        {
            "name": "search_files",
            "description": "Search through files in the workspace",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {"type": "string"},
                    "file_types": {"type": "array", "items": {"type": "string"}},
                },
                "required": ["query"],
            },
            "defer_loading": True,
        },
    ],
)

print(response)

Claude cerca nel catalogo, scopre get_weather e lo chiama. La risposta termina con stop_reason: "tool_use". Esegui lo strumento scoperto e restituisci un tool_result come descritto in Gestire le chiamate agli strumenti. Formato della risposta mostra i blocchi che ricevi e cosa inviare successivamente.



Definizione dello strumento

Lo strumento di ricerca degli strumenti ha due varianti:

{
  "type": "tool_search_tool_regex_20251119",
  "name": "tool_search_tool_regex"
}

{
  "type": "tool_search_tool_bm25_20251119",
  "name": "tool_search_tool_bm25"
}



Caricamento differito degli strumenti

Contrassegna gli strumenti per il caricamento su richiesta aggiungendo defer_loading: true:

{
  "name": "get_weather",
  "description": "Get current weather for a location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": { "type": "string" },
      "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
    },
    "required": ["location"]
  },
  "defer_loading": true
}

defer_loading controlla cosa entra nella finestra di contesto, non cosa invii nella richiesta:

• Invii comunque la definizione completa di ogni strumento nell'array tools a ogni richiesta, inclusi quelli differiti. L'API ne ha bisogno lato server per eseguire la ricerca ed espandere i blocchi tool_reference.
• Gli strumenti senza defer_loading vengono caricati immediatamente nel contesto.
• Gli strumenti con defer_loading: true vengono caricati solo quando Claude li scopre tramite la ricerca.
• Non impostare mai defer_loading: true sullo strumento di ricerca degli strumenti stesso.
• Mantieni i tuoi 3–5 strumenti più utilizzati come non differiti, così Claude può chiamarli senza prima cercarli.

Entrambe le varianti di ricerca degli strumenti (regex e bm25) cercano nei nomi degli strumenti, nelle descrizioni, nei nomi degli argomenti e nelle descrizioni degli argomenti.

Internamente, l'API esclude gli strumenti differiti dal prefisso del prompt di sistema. Quando Claude scopre uno strumento differito tramite la ricerca degli strumenti, l'API aggiunge un blocco tool_reference inline nella conversazione, quindi lo espande nella definizione completa dello strumento prima di passarlo a Claude. Il prefisso rimane intatto, quindi la cache dei prompt viene preservata. La grammatica per la modalità strict (le regole che vincolano l'output delle chiamate agli strumenti a corrispondere ai tuoi schemi) viene costruita dall'insieme completo degli strumenti, quindi defer_loading e la modalità strict si compongono senza ricompilazione della grammatica.



Formato della risposta

Quando Claude utilizza lo strumento di ricerca degli strumenti, la risposta include i seguenti tipi di blocchi:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll search for tools to help with the weather information."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01ABC123",
      "name": "tool_search_tool_regex",
      "input": {
        "pattern": "weather"
      }
    },
    {
      "type": "tool_search_tool_result",
      "tool_use_id": "srvtoolu_01ABC123",
      "content": {
        "type": "tool_search_tool_search_result",
        "tool_references": [{ "type": "tool_reference", "tool_name": "get_weather" }]
      }
    },
    {
      "type": "text",
      "text": "I found a weather tool. Let me get the weather for San Francisco."
    },
    {
      "type": "tool_use",
      "id": "toolu_01XYZ789",
      "name": "get_weather",
      "input": { "location": "San Francisco", "unit": "fahrenheit" }
    }
  ],
  "stop_reason": "tool_use"
}



Comprendere la risposta

• server_tool_use: la chiamata di Claude allo strumento di ricerca degli strumenti. La ricerca viene eseguita sui server di Anthropic. Non restituire mai un tool_result per il suo ID srvtoolu_....
• tool_search_tool_result: i risultati della ricerca, in un oggetto tool_search_tool_search_result annidato. Mantienilo nella cronologia dei messaggi così com'è.
• tool_references: un array di oggetti tool_reference che puntano agli strumenti scoperti. L'API li espande per Claude. Non devi mai espanderli tu stesso.
• tool_use: la chiamata di Claude a uno strumento scoperto. Eseguilo e restituisci un tool_result esattamente come nell'uso degli strumenti standard.

L'API espande automaticamente i blocchi tool_reference in definizioni complete degli strumenti prima di mostrarli a Claude. Non devi gestire questa espansione tu stesso, purché fornisca tutte le definizioni degli strumenti corrispondenti nel parametro tools.



Continuare la conversazione

Nella richiesta successiva, passa il contenuto dell'assistente invariato, inclusi i blocchi server_tool_use e tool_search_tool_result. Aggiungi il tuo tool_result per lo strumento scoperto in un messaggio utente e invia lo stesso array tools: lo strumento di ricerca più ogni definizione differita. Non restituire un tool_result per l'ID srvtoolu_...: l'API rifiuta la richiesta. L'API espande i blocchi tool_reference in tutta la cronologia della conversazione, così Claude può riutilizzare gli strumenti scoperti nei turni successivi senza cercarli di nuovo. Una ricerca che non trova corrispondenze restituisce un tool_search_tool_search_result con un array tool_references vuoto, non un errore.



Integrazione MCP

Se i tuoi strumenti provengono da server MCP tramite il connettore MCP, non imposti defer_loading sulle singole definizioni degli strumenti. Invece, impostalo una volta sul default_config della voce mcp_toolset per l'intero server, o per singolo strumento nei suoi configs. Consulta Configurazione del toolset MCP.



Implementazione personalizzata della ricerca degli strumenti

Puoi implementare la tua logica di ricerca degli strumenti (ad esempio, utilizzando embedding o ricerca semantica) restituendo blocchi tool_reference da uno strumento personalizzato. Quando Claude chiama il tuo strumento di ricerca personalizzato, restituisci un tool_result standard con blocchi tool_reference nell'array content:

{
  "type": "tool_result",
  "tool_use_id": "toolu_your_tool_id",
  "content": [{ "type": "tool_reference", "tool_name": "discovered_tool_name" }]
}

Ogni strumento referenziato deve avere una definizione corrispondente nel parametro tools di primo livello, normalmente con defer_loading: true. Questo ti consente di utilizzare metodi di ricerca che le varianti integrate non forniscono, come il recupero basato su embedding, e l'API espande i blocchi tool_reference restituiti allo stesso modo.

Per un esempio completo che utilizza gli embedding, consulta la ricetta tool search with embeddings.



Gestione degli errori



Errori HTTP (stato 400)

Questi errori impediscono all'API di elaborare la richiesta:

Tutti gli strumenti differiti:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "At least one tool must have defer_loading=false. All tools cannot be deferred."
  }
}

Definizione dello strumento mancante:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Tool reference 'unknown_tool' not found in available tools"
  }
}



Errori nei risultati degli strumenti (stato 200)

Quando un'operazione di ricerca degli strumenti fallisce durante l'esecuzione, l'API restituisce una risposta 200 con l'errore nel corpo:

{
  "type": "tool_search_tool_result",
  "tool_use_id": "srvtoolu_01ABC123",
  "content": {
    "type": "tool_search_tool_result_error",
    "error_code": "invalid_tool_input",
    "error_message": "Invalid regular expression pattern: missing ) at position 1"
  }
}

Il campo error_code ha quattro valori possibili:

• invalid_tool_input: l'input di ricerca non era valido, ad esempio un pattern regex malformato o un pattern oltre il limite di 200 caratteri
• unavailable: la ricerca non è stata eseguita, ad esempio perché è scaduta o il servizio non era disponibile
• too_many_requests: limite di velocità superato per le operazioni di ricerca degli strumenti
• execution_time_exceeded: la ricerca ha superato il suo limite di tempo di esecuzione



Errori comuni



Cache dei prompt

Per come defer_loading preserva la cache dei prompt, consulta Uso degli strumenti con la cache dei prompt.

Uno strumento con defer_loading: true non può avere anche cache_control: l'API restituisce un errore 400. Posiziona il punto di interruzione della cache su uno strumento non differito.



Streaming

Con lo streaming abilitato, riceverai gli eventi di ricerca degli strumenti come parte dello stream:

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "tool_search_tool_regex"}}

// Search pattern streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"pattern\":\"weather\"}"}}

// Pause while search executes

// Search results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "tool_search_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "tool_search_tool_search_result", "tool_references": [{"type": "tool_reference", "tool_name": "get_weather"}]}}}

// Claude continues with discovered tools



Richieste batch

Puoi includere lo strumento di ricerca degli strumenti nell'API Messages Batches.



Limiti e best practice



Limiti

• Numero massimo di strumenti differiti: 10.000 strumenti con defer_loading: true per richiesta
• Risultati di ricerca: ogni ricerca restituisce fino a 5 strumenti corrispondenti per impostazione predefinita
• Lunghezza di pattern e query: massimo 200 caratteri per i pattern regex e 500 caratteri per le query BM25
• Supporto dei modelli: consulta Compatibilità dei modelli



Quando usare la ricerca degli strumenti

Usa la ricerca degli strumenti quando si applica una delle seguenti condizioni:

• Hai 10 o più strumenti disponibili.
• Le tue definizioni degli strumenti consumano più di 10k token.
• L'accuratezza nella selezione degli strumenti diminuisce man mano che il tuo set di strumenti cresce.
• Aggreghi più server MCP (200+ strumenti).
• La tua libreria di strumenti cresce nel tempo.

La chiamata standard agli strumenti, senza ricerca degli strumenti, è più adatta quando hai meno di 10 strumenti, ogni strumento viene utilizzato in ogni richiesta, o le tue definizioni degli strumenti sono piccole (meno di 100 token in totale).



Suggerimenti di ottimizzazione

• Mantieni i tuoi 3–5 strumenti più utilizzati come non differiti.
• Scrivi nomi e descrizioni degli strumenti chiari e descrittivi.
• Usa un namespacing coerente nei nomi degli strumenti: aggiungi un prefisso per servizio o risorsa (ad esempio, github_, slack_) così una singola ricerca corrisponde all'intero gruppo.
• Usa parole chiave nelle descrizioni che corrispondano a come gli utenti descrivono le attività.
• Aggiungi una sezione nel prompt di sistema che descriva le categorie di strumenti disponibili: "Puoi cercare strumenti per interagire con Slack, GitHub e Jira."
• Monitora quali strumenti Claude scopre per perfezionare le tue descrizioni.



Utilizzo

La ricerca degli strumenti non viene misurata come strumento server separato. L'oggetto usage.server_tool_use della risposta non ha alcun campo per la ricerca degli strumenti, e le definizioni degli strumenti che la ricerca carica nel contesto contano come token di input come qualsiasi altra definizione di strumento.



Passaggi successivi