Tool di ricerca strumenti

Il tool di ricerca strumenti consente a Claude di lavorare con centinaia o migliaia di strumenti scoprendoli e caricandoli dinamicamente su richiesta. Invece di caricare tutte le definizioni degli strumenti nella finestra di contesto in anticipo, Claude cerca nel catalogo degli 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 problemi che si amplificano rapidamente man mano che le librerie di strumenti crescono:

• Gonfiamento del contesto: Le definizioni degli strumenti consumano rapidamente il budget del contesto. Una tipica configurazione multi-server (GitHub, Slack, Sentry, Grafana, Splunk) può consumare ~55k token in definizioni prima che Claude faccia qualsiasi lavoro effettivo. La ricerca degli strumenti riduce tipicamente questo di oltre l'85%, caricando solo i 3-5 strumenti di cui Claude ha effettivamente bisogno per una determinata richiesta.
• Accuratezza nella selezione degli strumenti: La capacità di Claude di scegliere correttamente lo strumento giusto si degrada significativamente una volta superati i 30-50 strumenti disponibili. Portando in superficie un insieme focalizzato di strumenti rilevanti su richiesta, la ricerca degli strumenti mantiene alta l'accuratezza della selezione anche tra migliaia di strumenti.

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

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

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 strumenti
• BM25 (tool_search_tool_bm25_20251119): Claude utilizza query in linguaggio naturale per cercare strumenti

Quando abiliti il tool di ricerca strumenti:

1. Includi un tool di ricerca 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 devono essere caricati immediatamente
3. Claude vede inizialmente solo il tool di ricerca strumenti e gli strumenti non differiti
4. Quando Claude ha bisogno di strumenti aggiuntivi, esegue la ricerca usando un tool di ricerca 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 efficiente la finestra di contesto mantenendo alta l'accuratezza nella selezione degli strumenti.

Avvio rapido

Ecco un semplice esempio con strumenti differiti:

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "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
            }
        ]
    }'

Definizione dello strumento

Il tool 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
}

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
• Il tool di ricerca strumenti stesso non dovrebbe mai avere defer_loading: true
• Mantieni i tuoi 3-5 strumenti più frequentemente usati 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.

Come funziona il differimento internamente: Gli strumenti differiti non sono inclusi nel prefisso del prompt di sistema. Quando il modello scopre uno strumento differito tramite la ricerca degli strumenti, la definizione dello strumento viene aggiunta inline come blocco tool_reference nella conversazione. Il prefisso rimane invariato, quindi la cache del prompt viene preservata. La grammatica per la modalità strict viene costruita dall'intero set di strumenti, quindi defer_loading e la modalità strict si compongono senza ricompilazione della grammatica.

Formato della risposta

Quando Claude utilizza il tool di ricerca strumenti, la risposta include nuovi 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": {
        "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 il tool di ricerca 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 manualmente. Avviene automaticamente nell'API purché tu fornisca tutte le definizioni degli strumenti corrispondenti nel parametro tools.

Integrazione MCP

Per la configurazione di mcp_toolset con defer_loading, consulta MCP connector.

Implementazione personalizzata della ricerca degli strumenti

Puoi implementare la tua logica di ricerca degli strumenti personalizzata (ad es., 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 di contenuto:

{
  "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 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 che utilizza gli embedding, consulta il cookbook sulla ricerca degli strumenti con embedding.

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 del risultato dello strumento (stato 200)

Gli errori durante l'esecuzione dello strumento restituiscono una risposta 200 con informazioni sull'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 frequenza 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

Cache del prompt

Per come defer_loading preserva la cache del prompt, consulta Utilizzo degli strumenti con la cache del prompt.

Il sistema espande automaticamente i blocchi tool_reference nell'intera cronologia della conversazione, in modo che Claude possa riutilizzare gli strumenti scoperti nei turni successivi senza effettuare nuove ricerche.

Streaming

Con lo streaming abilitato, riceverai 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"}}

// Query di ricerca in streaming
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"weather\"}"}}

// Pausa durante l'esecuzione della ricerca

// Risultati della ricerca in streaming
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 continua con gli strumenti scoperti

Richieste batch

Puoi includere il tool di ricerca strumenti nell'API Messages Batches. Le operazioni di ricerca degli strumenti tramite l'API Messages Batches hanno lo stesso prezzo delle richieste API Messages regolari.

Conservazione dei dati

La ricerca degli strumenti lato server (strumento tool_search) indicizza e memorizza i dati del catalogo degli strumenti (nomi degli strumenti, descrizioni e metadati degli argomenti) oltre la risposta API immediata; questi dati del catalogo vengono conservati in base alla politica di conservazione standard di Anthropic. Le implementazioni personalizzate di ricerca degli strumenti lato client che utilizzano l'API Messages standard sono completamente idonee per ZDR.

Per l'idoneità ZDR in tutte le funzionalità, consulta API e conservazione dei dati.

Limiti e best practice

Limiti

• Numero massimo di strumenti: 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 Claude Mythos Preview, Sonnet 4.0+, Opus 4.0+ (nessun Haiku)

Quando utilizzare la ricerca degli strumenti

Casi d'uso ottimali:

• 10+ strumenti disponibili nel tuo sistema
• Definizioni degli strumenti che 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 tradizionale agli strumenti potrebbe essere migliore:

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

Suggerimenti per l'ottimizzazione

• Mantieni i 3-5 strumenti più frequentemente usati come non differiti
• Scrivi nomi e descrizioni degli strumenti chiari e descrittivi
• Usa una denominazione coerente nei nomi degli strumenti: prefissa per servizio o risorsa (ad es., github_, slack_) in modo che le query di ricerca portino naturalmente in superficie il gruppo di strumenti corretto
• Usa parole chiave semantiche nelle descrizioni che corrispondano a come gli utenti descrivono i compiti
• 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 descrizioni

Utilizzo

L'utilizzo del tool di ricerca strumenti viene tracciato nell'oggetto di utilizzo della risposta:

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

Prossimi passi