Strumento di ricerca degli strumenti

Lo strumento di ricerca degli strumenti (tool search tool) permette a Claude di lavorare con centinaia o migliaia di strumenti scoprendoli e caricandoli su richiesta. Invece di caricare tutte le definizioni degli strumenti nella finestra di contesto fin dall'inizio, 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 fin dall'inizio causa due problemi man mano che una libreria di strumenti cresce:

• Gonfiamento del contesto: una tipica configurazione multiserver (GitHub, Slack, Sentry, Grafana e Splunk) può consumare ~55k token in definizioni prima che Claude faccia qualsiasi lavoro. La ricerca degli strumenti tipicamente riduce 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 solo un insieme mirato di strumenti rilevanti su richiesta, l'accuratezza della selezione rimane alta anche su migliaia di strumenti.

La ricerca degli strumenti è generalmente disponibile sulla Claude API. 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 della 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 della ricerca degli strumenti:

• Regex (tool_search_tool_regex_20251119): Claude costruisce pattern regex per cercare gli strumenti.
• BM25 (tool_search_tool_bm25_20251119): Claude usa 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 imposta defer_loading: true sugli strumenti che non devono essere caricati fin dall'inizio. 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, effettua una ricerca usando 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-5",
    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 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 usati più frequentemente come non differiti in modo che Claude possa chiamarli senza prima effettuare una ricerca.

Entrambe le varianti della 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 usa 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 annidato tool_search_tool_search_result. 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, ripassa il contenuto dell'assistente senza modifiche, 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, quindi Claude può riutilizzare gli strumenti scoperti nei turni successivi senza effettuare nuovamente la ricerca. 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, oppure 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, usando 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 permette di usare 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 usa gli embedding, consulta la ricetta ricerca degli strumenti con embedding.



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 della 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é è scaduto il timeout 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 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 nella Messages Batches API.



Limiti e best practice



Limiti

• Numero massimo di strumenti differiti: 10.000 strumenti con defer_loading: true per richiesta
• Risultati della 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 verifica una delle seguenti condizioni:

• Hai 10 o più strumenti disponibili.
• Le definizioni dei tuoi strumenti consumano più di 10k token.
• L'accuratezza nella selezione degli strumenti diminuisce man mano che il tuo insieme 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 usato in ogni richiesta, oppure le definizioni dei tuoi strumenti sono piccole (meno di 100 token in totale).



Suggerimenti per l'ottimizzazione

• Mantieni i tuoi 3–5 strumenti usati più frequentemente come non differiti.
• Scrivi nomi e descrizioni degli strumenti chiari e descrittivi.
• Usa un namespacing coerente nei nomi degli strumenti: usa un prefisso per servizio o risorsa (ad esempio, github_, slack_) in modo che una singola ricerca corrisponda all'intero gruppo.
• Usa nelle descrizioni parole chiave che corrispondono a come gli utenti descrivono le attività.
• Aggiungi una sezione del 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 conteggiata come strumento server separato. L'oggetto usage.server_tool_use della risposta non ha un campo per la ricerca degli strumenti, e le definizioni degli strumenti che la ricerca carica nel contesto vengono conteggiate come token di input come qualsiasi altra definizione di strumento.



Prossimi passi