Strumenti

Strumento di ricerca degli strumenti

Abilita Claude a lavorare con centinaia o migliaia di strumenti scoprendo e caricando dinamicamente quelli necessari su richiesta.

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 convenzionalmente

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.

Lo strumento di ricerca degli strumenti è attualmente in beta pubblica.

Per utilizzare questa funzione, aggiungi l'intestazione beta "advanced-tool-use-2025-11-20" alle tue richieste API.

Ti invitiamo a contattarci tramite il nostro modulo di feedback per condividere la tua esperienza con lo strumento di ricerca degli strumenti.

Supporto di piattaforme e modelli

Piattaforma	Modelli supportati
Claude API	Claude Opus 4.5, Claude Sonnet 4.5
Microsoft Foundry	Claude Opus 4.5, Claude Sonnet 4.5
Google Cloud Vertex AI	Claude Opus 4.5, Claude Sonnet 4.5
Amazon Bedrock	Claude Opus 4.5

Su Amazon Bedrock, la ricerca degli strumenti lato server è disponibile solo tramite l'API invoke, non l'API converse.

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:

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
Fornisci tutte le definizioni degli strumenti con defer_loading: true per gli strumenti che non dovrebbero essere caricati immediatamente
Claude vede solo lo strumento di ricerca degli strumenti e gli strumenti non differiti inizialmente
Quando Claude ha bisogno di strumenti aggiuntivi, cerca utilizzando uno strumento di ricerca degli strumenti
L'API restituisce 3-5 blocchi tool_reference più rilevanti
Questi riferimenti vengono automaticamente espansi in definizioni complete degli strumenti
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:

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: advanced-tool-use-2025-11-20" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-sonnet-4-5-20250929",
        "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

Lo strumento di ricerca degli strumenti ha due varianti:

JSON

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

JSON

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

Formato della query della variante Regex: regex Python, NON linguaggio naturale

Quando utilizzi tool_search_tool_regex_20251119, Claude costruisce pattern regex utilizzando la sintassi re.search() di Python, non query in linguaggio naturale. Pattern comuni:

"weather" - corrisponde ai nomi/descrizioni degli strumenti contenenti "weather"
"get_.*_data" - corrisponde a strumenti come get_user_data, get_weather_data
"database.*query|query.*database" - pattern OR per flessibilità
"(?i)slack" - ricerca case-insensitive

Lunghezza massima della query: 200 caratteri

Formato della query della variante BM25: Linguaggio naturale

Quando utilizzi tool_search_tool_bm25_20251119, Claude utilizza query in linguaggio naturale per cercare gli strumenti.

Caricamento differito degli strumenti

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

JSON

{
  "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:

JSON

{
  "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_result",
      "tool_use_id": "srvtoolu_01ABC123",
      "content": [{ "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_result con tool_reference: I risultati della ricerca contenenti riferimenti 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 finché 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'intestazione beta "mcp-client-2025-11-20" alla tua richiesta API, quindi utilizza mcp_tool_set con default_configs per differire il caricamento degli strumenti MCP:

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: advanced-tool-use-2025-11-20,mcp-client-2025-11-20" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 2048,
    "mcp_servers": [
      {
        "type": "url",
        "name": "database-server",
        "url": "https://mcp-db.example.com"
      }
    ],
    "tools": [
      {
        "type": "tool_search_tool_regex_20251119",
        "name": "tool_search_tool_regex"
      },
      {
        "type": "mcp_tool_set",
        "mcp_server_name": "database-server",
        "default_configs": {
          "defer_loading": true
        },
        "configs": {
          "search_events": {
            "defer_loading": false
          }
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "What events are in my database?"
      }
    ]
  }'

Opzioni di configurazione MCP:

default_configs.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 embedding o ricerca semantica) restituendo blocchi tool_reference da uno strumento personalizzato:

JSON

{
  "type": "tool_result",
  "tool_use_id": "toolu_custom_search",
  "content": [{ "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 embedding, vedi il nostro cookbook di ricerca degli strumenti con embedding.

Gestione degli errori

Lo strumento di ricerca degli strumenti non è compatibile con gli esempi di utilizzo degli strumenti. Se hai bisogno di fornire esempi di utilizzo degli strumenti, utilizza la chiamata degli strumenti standard senza ricerca degli strumenti.

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 sull'errore nel corpo:

JSON

{
  "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

Memorizzazione nella cache dei prompt

La ricerca degli strumenti funziona con la memorizzazione nella cache dei prompt. Aggiungi punti di interruzione cache_control per ottimizzare le conversazioni multi-turno:

Python

import anthropic

client = anthropic.Anthropic()

# Prima richiesta con ricerca degli strumenti
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
        }
    ]
)

# Aggiungi la risposta di Claude alla conversazione
messages.append({
    "role": "assistant",
    "content": response1.content
})

# Seconda richiesta con punto di interruzione della cache
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 nell'intera 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"}}

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

// Pausa mentre la ricerca viene eseguita

// Risultati della ricerca trasmessi
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "tool_result", "tool_use_id": "srvtoolu_xyz789", "content": [{"type": "tool_reference", "tool_name": "get_weather"}]}}

// Claude continua con gli strumenti scoperti

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+ (nessun Haiku)

Quando utilizzare la ricerca degli strumenti

Buoni casi d'uso:

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
Sistemi alimentati da 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 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 perfezionare le descrizioni

Utilizzo e prezzi

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

JSON

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

Per informazioni sui prezzi attuali, vedi la pagina dei prezzi.

Strumenti

Strumento di ricerca degli strumenti

Abilita Claude a lavorare con centinaia o migliaia di strumenti scoprendo e caricando dinamicamente quelli necessari su richiesta.

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 convenzionalmente

Lo strumento di ricerca degli strumenti è attualmente in beta pubblica.

Per utilizzare questa funzione, aggiungi l'intestazione beta "advanced-tool-use-2025-11-20" alle tue richieste API.

Ti invitiamo a contattarci tramite il nostro modulo di feedback per condividere la tua esperienza con lo strumento di ricerca degli strumenti.

Supporto di piattaforme e modelli

Piattaforma	Modelli supportati
Claude API	Claude Opus 4.5, Claude Sonnet 4.5
Microsoft Foundry	Claude Opus 4.5, Claude Sonnet 4.5
Google Cloud Vertex AI	Claude Opus 4.5, Claude Sonnet 4.5
Amazon Bedrock	Claude Opus 4.5

Su Amazon Bedrock, la ricerca degli strumenti lato server è disponibile solo tramite l'API invoke, non l'API converse.

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:

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
Fornisci tutte le definizioni degli strumenti con defer_loading: true per gli strumenti che non dovrebbero essere caricati immediatamente
Claude vede solo lo strumento di ricerca degli strumenti e gli strumenti non differiti inizialmente
Quando Claude ha bisogno di strumenti aggiuntivi, cerca utilizzando uno strumento di ricerca degli strumenti
L'API restituisce 3-5 blocchi tool_reference più rilevanti
Questi riferimenti vengono automaticamente espansi in definizioni complete degli strumenti
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:

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: advanced-tool-use-2025-11-20" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-sonnet-4-5-20250929",
        "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

Lo strumento di ricerca degli strumenti ha due varianti:

JSON

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

JSON

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

Formato della query della variante Regex: regex Python, NON linguaggio naturale

Quando utilizzi tool_search_tool_regex_20251119, Claude costruisce pattern regex utilizzando la sintassi re.search() di Python, non query in linguaggio naturale. Pattern comuni:

"weather" - corrisponde ai nomi/descrizioni degli strumenti contenenti "weather"
"get_.*_data" - corrisponde a strumenti come get_user_data, get_weather_data
"database.*query|query.*database" - pattern OR per flessibilità
"(?i)slack" - ricerca case-insensitive

Lunghezza massima della query: 200 caratteri

Formato della query della variante BM25: Linguaggio naturale

Quando utilizzi tool_search_tool_bm25_20251119, Claude utilizza query in linguaggio naturale per cercare gli strumenti.

Caricamento differito degli strumenti

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

JSON

{
  "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:

JSON

{
  "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_result",
      "tool_use_id": "srvtoolu_01ABC123",
      "content": [{ "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_result con tool_reference: I risultati della ricerca contenenti riferimenti agli strumenti scoperti
tool_use: Claude che invoca lo strumento scoperto

Integrazione MCP

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: advanced-tool-use-2025-11-20,mcp-client-2025-11-20" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 2048,
    "mcp_servers": [
      {
        "type": "url",
        "name": "database-server",
        "url": "https://mcp-db.example.com"
      }
    ],
    "tools": [
      {
        "type": "tool_search_tool_regex_20251119",
        "name": "tool_search_tool_regex"
      },
      {
        "type": "mcp_tool_set",
        "mcp_server_name": "database-server",
        "default_configs": {
          "defer_loading": true
        },
        "configs": {
          "search_events": {
            "defer_loading": false
          }
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "What events are in my database?"
      }
    ]
  }'

Opzioni di configurazione MCP:

default_configs.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 embedding o ricerca semantica) restituendo blocchi tool_reference da uno strumento personalizzato:

JSON

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

Per un esempio completo utilizzando embedding, vedi il nostro cookbook di 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 dei risultati degli strumenti (stato 200)

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

JSON

{
  "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

Memorizzazione nella cache dei prompt

La ricerca degli strumenti funziona con la memorizzazione nella cache dei prompt. Aggiungi punti di interruzione cache_control per ottimizzare le conversazioni multi-turno:

Python

import anthropic

client = anthropic.Anthropic()

# Prima richiesta con ricerca degli strumenti
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
        }
    ]
)

# Aggiungi la risposta di Claude alla conversazione
messages.append({
    "role": "assistant",
    "content": response1.content
})

# Seconda richiesta con punto di interruzione della cache
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)}")

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"}}

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

// Pausa mentre la ricerca viene eseguita

// Risultati della ricerca trasmessi
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "tool_result", "tool_use_id": "srvtoolu_xyz789", "content": [{"type": "tool_reference", "tool_name": "get_weather"}]}}

// Claude continua con gli strumenti scoperti

Richieste batch

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+ (nessun Haiku)

Quando utilizzare la ricerca degli strumenti

Buoni casi d'uso:

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
Sistemi alimentati da 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 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 perfezionare le descrizioni

Utilizzo e prezzi

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

JSON

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

Per informazioni sui prezzi attuali, vedi la pagina dei prezzi.

Supporto di piattaforme e modelli

Come funziona la ricerca degli strumenti

Avvio rapido

Definizione dello strumento

Caricamento differito degli strumenti

Formato della risposta

Comprensione della risposta

Integrazione MCP

Implementazione personalizzata della ricerca degli strumenti

Gestione degli errori

Errori HTTP (stato 400)

Errori dei risultati degli strumenti (stato 200)

Errori comuni

Errore 400: Tutti gli strumenti sono differiti

Errore 400: Definizione dello strumento mancante

Claude non trova gli strumenti previsti

Memorizzazione nella cache dei prompt

Streaming

Richieste batch

Limiti e best practice

Limiti

Quando utilizzare la ricerca degli strumenti

Suggerimenti di ottimizzazione

Utilizzo e prezzi

Supporto di piattaforme e modelli

Come funziona la ricerca degli strumenti

Avvio rapido

Definizione dello strumento

Caricamento differito degli strumenti

Formato della risposta

Comprensione della risposta

Integrazione MCP

Implementazione personalizzata della ricerca degli strumenti

Gestione degli errori

Errori HTTP (stato 400)

Errori dei risultati degli strumenti (stato 200)

Errori comuni

Errore 400: Tutti gli strumenti sono differiti

Errore 400: Definizione dello strumento mancante

Claude non trova gli strumenti previsti

Memorizzazione nella cache dei prompt

Streaming

Richieste batch

Limiti e best practice

Limiti

Quando utilizzare la ricerca degli strumenti

Suggerimenti di ottimizzazione

Utilizzo e prezzi