Strumento di ricerca degli strumenti

Lo strumento di ricerca degli strumenti consente a Claude di lavorare con centinaia o migliaia di strumenti scoprendo e caricando dinamicamente quelli necessari su richiesta. Invece di caricare tutte le definizioni degli strumenti nella finestra di contesto in anticipo, Claude cerca il 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.

Questo approccio risolve due sfide critiche man mano che le librerie di strumenti si espandono:

• Efficienza del contesto: Le definizioni degli strumenti possono consumare porzioni massicce della tua finestra di contesto (50 strumenti ≈ 10-20K token), lasciando meno spazio per il lavoro effettivo
• Accuratezza della selezione degli strumenti: La capacità di Claude di selezionare correttamente gli strumenti si degrada significativamente con più di 30-50 strumenti disponibili convencionalmente

Sebbene questo sia fornito come uno strumento lato server, puoi anche implementare la tua funzionalità di ricerca degli strumenti lato client. Vedi Implementazione personalizzata della ricerca degli strumenti per i dettagli.

Puoi anche implementare ricerca degli strumenti lato client restituendo blocchi tool_reference dalla tua implementazione di ricerca personalizzata.

Come funziona la ricerca degli strumenti

Ci sono 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 es. tool_search_tool_regex_20251119 o tool_search_tool_bm25_20251119) nella tua lista di strumenti
2. Fornisci tutte le definizioni degli strumenti con defer_loading: true per gli strumenti che non dovrebbero essere caricati immediatamente
3. Claude vede solo lo strumento di ricerca degli strumenti e gli strumenti non differiti inizialmente
4. Quando Claude ha bisogno di strumenti aggiuntivi, cerca utilizzando uno strumento di ricerca degli strumenti
5. L'API restituisce 3-5 blocchi tool_reference più rilevanti
6. Questi riferimenti vengono automaticamente espansi in definizioni complete degli strumenti
7. Claude seleziona dagli strumenti scoperti e li invoca

Questo mantiene la tua finestra di contesto efficiente mantenendo un'elevata accuratezza nella selezione degli strumenti.

Avvio rapido

Ecco un semplice esempio con strumenti differiti:

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
}

Punti chiave:

• Gli strumenti senza defer_loading vengono caricati nel contesto immediatamente
• Gli strumenti con defer_loading: true vengono caricati solo quando Claude li scopre tramite ricerca
• Lo strumento di ricerca degli strumenti stesso non dovrebbe mai avere defer_loading: true
• Mantieni i tuoi 3-5 strumenti più utilizzati frequentemente come non differiti per prestazioni ottimali

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

Formato della risposta

Quando Claude utilizza lo strumento di ricerca degli strumenti, la risposta include nuovi 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": {
        "query": "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"
}

Comprensione della risposta

• server_tool_use: Indica che Claude sta invocando lo strumento di ricerca degli strumenti
• tool_search_tool_result: Contiene i risultati della ricerca con un oggetto tool_search_tool_search_result annidato
• tool_references: Array di oggetti tool_reference che puntano agli strumenti scoperti
• tool_use: Claude che invoca lo strumento scoperto

I blocchi tool_reference vengono automaticamente espansi in definizioni complete degli strumenti prima di essere mostrati a Claude. Non è necessario gestire questa espansione da solo. Accade automaticamente nell'API purché fornisci tutte le definizioni degli strumenti corrispondenti nel parametro tools.

Integrazione MCP

Lo strumento di ricerca degli strumenti funziona con i server MCP. Aggiungi l'header beta "mcp-client-2025-11-20" alla tua richiesta API, e quindi utilizza mcp_toolset con default_config per differire il caricamento degli strumenti MCP:

Opzioni di configurazione MCP:

• default_config.defer_loading: Imposta il valore predefinito per tutti gli strumenti dal server MCP
• configs: Sostituisci i valori predefiniti per strumenti specifici per nome
• Combina più server MCP con la ricerca degli strumenti per librerie di strumenti massicce

Implementazione personalizzata della ricerca degli strumenti

Puoi implementare la tua logica di ricerca degli strumenti (ad es. utilizzando embeddings o ricerca semantica) restituendo blocchi tool_reference da uno strumento personalizzato:

{
  "type": "tool_search_tool_result",
  "tool_use_id": "toolu_custom_search",
  "content": {
    "type": "tool_search_tool_search_result",
    "tool_references": [{ "type": "tool_reference", "tool_name": "discovered_tool_name" }]
  }
}

Ogni strumento referenziato deve avere una definizione dello strumento corrispondente nel parametro tools di livello superiore con defer_loading: true. Questo approccio ti consente di utilizzare algoritmi di ricerca più sofisticati mantenendo la compatibilità con il sistema di ricerca degli strumenti.

Per un esempio completo utilizzando embeddings, vedi il nostro cookbook di ricerca degli strumenti con embeddings.

Gestione degli errori

Errori HTTP (stato 400)

Questi errori impediscono l'elaborazione della richiesta:

Tutti gli strumenti differiti:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "All tools have defer_loading set. At least one tool must be non-deferred."
  }
}

Definizione dello strumento mancante:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Tool reference 'unknown_tool' has no corresponding tool definition"
  }
}

Errori dei risultati degli strumenti (stato 200)

Gli errori durante l'esecuzione dello strumento restituiscono una risposta 200 con informazioni di errore nel corpo:

{
  "type": "tool_result",
  "tool_use_id": "srvtoolu_01ABC123",
  "content": {
    "type": "tool_search_tool_result_error",
    "error_code": "invalid_pattern"
  }
}

Codici di errore:

• too_many_requests: Limite di velocità superato per le operazioni di ricerca degli strumenti
• invalid_pattern: Pattern regex malformato
• pattern_too_long: Il pattern supera il limite di 200 caratteri
• unavailable: Servizio di ricerca degli strumenti temporaneamente non disponibile

Errori comuni

Caching dei prompt

La ricerca degli strumenti funziona con il caching dei prompt. Aggiungi punti di interruzione cache_control per ottimizzare le conversazioni multi-turno:

import anthropic

client = anthropic.Anthropic()

# First request with tool search
messages = [
    {
        "role": "user",
        "content": "What's the weather in Seattle?"
    }
]

response1 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    betas=["advanced-tool-use-2025-11-20"],
    max_tokens=2048,
    messages=messages,
    tools=[
        {
            "type": "tool_search_tool_regex_20251119",
            "name": "tool_search_tool_regex"
        },
        {
            "name": "get_weather",
            "description": "Get weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"]
            },
            "defer_loading": True
        }
    ]
)

# Add Claude's response to conversation
messages.append({
    "role": "assistant",
    "content": response1.content
})

# Second request with cache breakpoint
messages.append({
    "role": "user",
    "content": "What about New York?",
    "cache_control": {"type": "ephemeral"}
})

response2 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    betas=["advanced-tool-use-2025-11-20"],
    max_tokens=2048,
    messages=messages,
    tools=[
        {
            "type": "tool_search_tool_regex_20251119",
            "name": "tool_search_tool_regex"
        },
        {
            "name": "get_weather",
            "description": "Get weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"]
            },
            "defer_loading": True
        }
    ]
)

print(f"Cache read tokens: {response2.usage.get('cache_read_input_tokens', 0)}")

Il sistema espande automaticamente i blocchi tool_reference in tutta la cronologia della conversazione, quindi Claude può riutilizzare gli strumenti scoperti nei turni successivi senza ricercare di nuovo.

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 query streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"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. Le operazioni di ricerca degli strumenti tramite l'API Messages Batches hanno lo stesso prezzo di quelle nelle richieste dell'API Messages regolari.

Limiti e best practice

Limiti

• Strumenti massimi: 10.000 strumenti nel tuo catalogo
• Risultati della ricerca: Restituisce 3-5 strumenti più rilevanti per ricerca
• Lunghezza del pattern: Massimo 200 caratteri per i pattern regex
• Supporto del modello: Solo Sonnet 4.0+, Opus 4.0+ (no Haiku)

Quando utilizzare la ricerca degli strumenti

Buoni casi d'uso:

• 10+ strumenti disponibili nel tuo sistema
• Le definizioni degli strumenti consumano >10K token
• Problemi di accuratezza nella selezione degli strumenti con grandi set di strumenti
• Costruzione di sistemi basati su MCP con più server (200+ strumenti)
• Libreria di strumenti in crescita nel tempo

Quando la chiamata degli strumenti tradizionale potrebbe essere migliore:

• Meno di 10 strumenti totali
• Tutti gli strumenti sono utilizzati frequentemente in ogni richiesta
• Definizioni degli strumenti molto piccole (<100 token totali)

Suggerimenti di ottimizzazione

• Mantieni i tuoi 3-5 strumenti più utilizzati frequentemente come non differiti
• Scrivi nomi e descrizioni degli strumenti chiari e descrittivi
• Utilizza parole chiave semantiche nelle descrizioni che corrispondono a come gli utenti descrivono i compiti
• Aggiungi una sezione di prompt di sistema che descrive le categorie di strumenti disponibili: "Puoi cercare strumenti per interagire con Slack, GitHub e Jira"
• Monitora quali strumenti Claude scopre per affinare le descrizioni

Utilizzo

L'utilizzo dello strumento di ricerca degli strumenti viene tracciato nell'oggetto di utilizzo della risposta:

{
  "usage": {
    "input_tokens": 1024,
    "output_tokens": 256,
    "server_tool_use": {
      "tool_search_requests": 2
    }
  }
}