Strumento di ricerca strumenti

Lo strumento di ricerca strumenti ("tool search tool") 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) 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 svolga qualsiasi lavoro. La ricerca strumenti in genere 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 peggiora una volta superati i 30–50 strumenti disponibili. Poiché la ricerca strumenti carica su richiesta solo un insieme mirato di strumenti pertinenti, l'accuratezza della selezione rimane elevata anche con migliaia di strumenti.

Per i modelli che supportano la ricerca strumenti, consulta Compatibilità dei modelli.

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

Compatibilità dei modelli

Entrambe le varianti della ricerca strumenti sono disponibili sui seguenti modelli:

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

Come funziona la ricerca strumenti

Esistono due varianti della ricerca 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 strumenti:

1. Includi uno strumento di ricerca 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 fin dall'inizio. Almeno uno strumento, normalmente lo strumento di ricerca strumenti stesso, deve rimanere non differito.
3. Inizialmente, il contesto di Claude contiene solo lo strumento di ricerca strumenti e gli eventuali strumenti non differiti.
4. Quando Claude ha bisogno di strumenti aggiuntivi, esegue una ricerca usando uno strumento di ricerca strumenti.
5. L'API esegue la ricerca e restituisce gli strumenti corrispondenti come blocchi tool_reference (fino a 5 per impostazione predefinita; Claude può impostare un limit nel suo input di ricerca).
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 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 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 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 nel contesto immediatamente.
• 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 strumenti stesso.
• Mantieni non differiti i tuoi 3–5 strumenti usati più frequentemente, così Claude può chiamarli senza dover prima cercare.

I toolset per computer use e browser use (computer_toolset_20260801 e browser_toolset_20260801) accettano defer_loading per singolo strumento membro all'interno dell'oggetto configs della voce, non sulla voce stessa; una richiesta che lo imposta a livello di voce viene rifiutata. Poiché un toolset viene differito ed espanso come unità, defer_loading deve risolversi nello stesso valore su ogni membro abilitato e, quando Claude scopre il toolset tramite la ricerca, tutti i membri abilitati vengono caricati contemporaneamente. Consulta Toolset client per il formato di configs.

Entrambe le varianti della ricerca 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 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 "prompt caching" (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 a partire dal toolset completo, quindi defer_loading e la modalità strict si combinano senza ricompilazione della grammatica.

Formato della risposta

Quando Claude usa lo strumento di ricerca strumenti, la risposta include i seguenti tipi di blocco:

{
  "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",
        "limit": 10
      }
    },
    {
      "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 strumenti. La ricerca viene eseguita sui server di Anthropic. Non restituire mai un tool_result per il suo ID srvtoolu_.... L'input contiene la ricerca (pattern per la variante regex, query per BM25) e può includere un limit opzionale, un intero da 1 a 10.000 che limita il numero di strumenti corrispondenti restituiti dalla ricerca (predefinito: 5).
• 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 li espandi mai 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 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, quindi Claude può riutilizzare gli strumenti scoperti nei turni successivi senza cercare 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 nel 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 strumenti

Puoi implementare la tua logica di ricerca 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 consente 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 nello stesso modo.

Per un esempio completo che usa gli embedding, consulta la ricetta ricerca 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 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 ha potuto essere eseguita, ad esempio per timeout o perché il servizio non era disponibile
• too_many_requests: limite di velocità superato per le operazioni di ricerca strumenti
• execution_time_exceeded: la ricerca ha superato il suo limite di tempo di esecuzione

Errori comuni

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

{
  "name": "my_tool",
  "description": "Full description here",
  "input_schema": {
    "type": "object"
  },
  "defer_loading": true
}

Cache dei prompt

Per scoprire 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 breakpoint della cache su uno strumento non differito.

Streaming

Con lo streaming abilitato, riceverai gli eventi della ricerca 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 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; Claude può impostare limit nel suo input di ricerca su qualsiasi intero da 1 a 10.000
• 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 strumenti

Usa la ricerca strumenti quando si verifica 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 toolset cresce.
• Aggreghi più server MCP (oltre 200 strumenti).
• La tua libreria di strumenti cresce nel tempo.

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

Suggerimenti per l'ottimizzazione

• Mantieni non differiti i tuoi 3–5 strumenti usati più frequentemente.
• 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_) in modo che una singola ricerca corrisponda all'intero gruppo.
• Usa nelle descrizioni parole chiave che corrispondano al modo in cui gli utenti descrivono le attività.
• Aggiungi una sezione del prompt di sistema che descriva le categorie di strumenti disponibili: "You can search for tools to interact with Slack, GitHub, and Jira."
• Monitora quali strumenti Claude scopre per perfezionare le tue descrizioni.

Utilizzo

La ricerca strumenti non viene misurata come strumento server separato. L'oggetto usage.server_tool_use della risposta non ha un campo per la ricerca 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