---
title: Strumento di ricerca strumenti
url: https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-search-tool
description: Scala fino a centinaia o migliaia di strumenti lasciando che Claude cerchi nel tuo catalogo di strumenti e carichi solo quelli di cui ha bisogno.
---

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](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-search-tool#model-compatibility).

<Tip>
  Per approfondire le sfide di scalabilità che la ricerca strumenti risolve, consulta [Advanced tool use](https://www.anthropic.com/engineering/advanced-tool-use). Il caricamento su richiesta della ricerca strumenti è anche un esempio del più ampio principio di recupero just-in-time descritto in [Effective context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents).
</Tip>

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](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-search-tool#custom-tool-search-implementation) per i dettagli.

<Note>
  Condividi il tuo feedback su questa funzionalità tramite il [modulo di feedback](https://forms.gle/MhcGFFwLxuwnWTkYA).
</Note>

<Note>
  Per scoprire come la "zero data retention" (conservazione zero dei dati), o ZDR, si applica a questa funzionalità, consulta [API e conservazione dei dati](https://platform.claude.com/docs/it/manage-claude/api-and-data-retention).
</Note>

<Warning>
  Su Amazon Bedrock, la ricerca strumenti lato server è disponibile solo tramite la [InvokeModel API](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-runtime_example_bedrock-runtime_InvokeModel_AnthropicClaude_section.html), non tramite la Converse API.
</Warning>

<Note>
  Su [Claude Platform on AWS](https://platform.claude.com/docs/it/build-with-claude/claude-platform-on-aws), la ricerca strumenti lato server funziona in modo identico alla Claude API. Claude Platform on AWS utilizza direttamente la Messages API di Anthropic, quindi non esiste alcuna distinzione tra InvokeModel e Converse.
</Note>

## Compatibilità dei modelli

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

| Modello                                                                                                                           | Versioni dello strumento                                            |
| --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| Claude Fable 5.1 (claude-fable-5-1)                                                                                               | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Mythos 5.1 (claude-mythos-5-1)                                                                                             | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Fable 5 (claude-fable-5)                                                                                                   | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Mythos 5 (claude-mythos-5)                                                                                                 | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Opus 5.5 (claude-opus-5-5)                                                                                                 | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Opus 5 (claude-opus-5)                                                                                                     | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Sonnet 5.5 (claude-sonnet-5-5)                                                                                             | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Sonnet 5 (claude-sonnet-5)                                                                                                 | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Haiku 5.5 (claude-haiku-5-5)                                                                                               | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Opus 4.8 (claude-opus-4-8)                                                                                                 | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Opus 4.7 (claude-opus-4-7)                                                                                                 | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Opus 4.6 (claude-opus-4-6)                                                                                                 | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Sonnet 4.6 (claude-sonnet-4-6)                                                                                             | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Opus 4.5 (claude-opus-4-5-20251101)                                                                                        | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Sonnet 4.5 (claude-sonnet-4-5-20250929) ([deprecato](https://platform.claude.com/docs/it/about-claude/model-deprecations)) | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Haiku 4.5 (claude-haiku-4-5-20251001)                                                                                      | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |

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:

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
      -H "x-api-key: $ANTHROPIC_API_KEY" \
      -H "anthropic-version: 2023-06-01" \
      -H "content-type: application/json" \
      -d '{
          "model": "claude-opus-5-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
              }
          ]
      }'
  ```

  ```bash CLI
  ant messages create <<'YAML'
  model: claude-opus-5-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
  YAML
  ```

  ```python Python
  client = anthropic.Anthropic()

  response = client.messages.create(
      model="claude-opus-5-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)
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const response = await client.messages.create({
    model: "claude-opus-5-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" as const,
          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" as const,
          properties: {
            query: { type: "string" },
            file_types: {
              type: "array",
              items: { type: "string" }
            }
          },
          required: ["query"]
        },
        defer_loading: true
      }
    ]
  });

  console.log(response);
  ```

  ```csharp C#
  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 2048,
      Messages = [
          new() {
              Role = Role.User,
              Content = "What is the weather in San Francisco?"
          }
      ],
      Tools = [
          new ToolUnion(new ToolSearchToolRegex20251119
          {
              Type = ToolSearchToolRegex20251119Type.ToolSearchToolRegex20251119
          }),
          new ToolUnion(new Tool()
          {
              Name = "get_weather",
              Description = "Get the weather at a specific location",
              InputSchema = new InputSchema()
              {
                  Properties = new Dictionary<string, JsonElement>
                  {
                      ["location"] = JsonSerializer.SerializeToElement(new { type = "string" }),
                      ["unit"] = JsonSerializer.SerializeToElement(new { type = "string", @enum = new[] { "celsius", "fahrenheit" } }),
                  },
                  Required = ["location"],
              },
              DeferLoading = true,
          }),
          new ToolUnion(new Tool()
          {
              Name = "search_files",
              Description = "Search through files in the workspace",
              InputSchema = new InputSchema()
              {
                  Properties = new Dictionary<string, JsonElement>
                  {
                      ["query"] = JsonSerializer.SerializeToElement(new { type = "string" }),
                      ["file_types"] = JsonSerializer.SerializeToElement(new { type = "array", items = new { type = "string" } }),
                  },
                  Required = ["query"],
              },
              DeferLoading = true,
          }),
      ]
  };

  var message = await client.Messages.Create(parameters);
  Console.WriteLine(message);
  ```

  ```go Go
  client := anthropic.NewClient()

  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 2048,
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("What is the weather in San Francisco?")),
  	},
  	Tools: []anthropic.ToolUnionParam{
  		{OfToolSearchToolRegex20251119: &anthropic.ToolSearchToolRegex20251119Param{
  			Type: anthropic.ToolSearchToolRegex20251119TypeToolSearchToolRegex20251119,
  		}},
  		{OfTool: &anthropic.ToolParam{
  			Name:        "get_weather",
  			Description: anthropic.String("Get the weather at a specific location"),
  			InputSchema: anthropic.ToolInputSchemaParam{
  				Properties: map[string]any{
  					"location": map[string]any{"type": "string"},
  					"unit": map[string]any{
  						"type": "string",
  						"enum": []string{"celsius", "fahrenheit"},
  					},
  				},
  				Required: []string{"location"},
  			},
  			DeferLoading: anthropic.Bool(true),
  		}},
  		{OfTool: &anthropic.ToolParam{
  			Name:        "search_files",
  			Description: anthropic.String("Search through files in the workspace"),
  			InputSchema: anthropic.ToolInputSchemaParam{
  				Properties: map[string]any{
  					"query":      map[string]any{"type": "string"},
  					"file_types": map[string]any{"type": "array", "items": map[string]any{"type": "string"}},
  				},
  				Required: []string{"query"},
  			},
  			DeferLoading: anthropic.Bool(true),
  		}},
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(response.RawJSON())
  ```

  ```java Java
  import com.anthropic.models.messages.ToolSearchToolRegex20251119;

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      InputSchema weatherSchema = InputSchema.builder()
          .properties(JsonValue.from(Map.of(
              "location", Map.of("type", "string"),
              "unit", Map.of(
                  "type", "string",
                  "enum", List.of("celsius", "fahrenheit")
              )
          )))
          .putAdditionalProperty("required", JsonValue.from(List.of("location")))
          .build();

      InputSchema searchSchema = InputSchema.builder()
          .properties(JsonValue.from(Map.of(
              "query", Map.of("type", "string"),
              "file_types", Map.of(
                  "type", "array",
                  "items", Map.of("type", "string")
              )
          )))
          .putAdditionalProperty("required", JsonValue.from(List.of("query")))
          .build();

      MessageCreateParams params = MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(2048L)
          .addUserMessage("What is the weather in San Francisco?")
          .addTool(ToolSearchToolRegex20251119.builder()
              .type(ToolSearchToolRegex20251119.Type.TOOL_SEARCH_TOOL_REGEX_20251119)
              .build())
          .addTool(Tool.builder()
              .name("get_weather")
              .description("Get the weather at a specific location")
              .inputSchema(weatherSchema)
              .deferLoading(true)
              .build())
          .addTool(Tool.builder()
              .name("search_files")
              .description("Search through files in the workspace")
              .inputSchema(searchSchema)
              .deferLoading(true)
              .build())
          .build();

      Message response = client.messages().create(params);
      IO.println(response);
  }
  ```

  ```php PHP
  $client = new Client();

  $message = $client->messages->create(
      maxTokens: 2048,
      messages: [
          ['role' => 'user', 'content' => 'What is the weather in San Francisco?'],
      ],
      model: 'claude-opus-5-5',
      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,
          ],
      ],
  );

  echo $message;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  message = client.messages.create(
    model: "claude-opus-5-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
      }
    ]
  )

  puts message
  ```
</CodeGroup>

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](https://platform.claude.com/docs/it/agents-and-tools/tool-use/handle-tool-calls). [Formato della risposta](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-search-tool#response-format) mostra i blocchi che ricevi e cosa inviare successivamente.

## Definizione dello strumento

Lo strumento di ricerca strumenti ha due varianti:

```json JSON
{
  "type": "tool_search_tool_regex_20251119",
  "name": "tool_search_tool_regex"
}
```

```json JSON
{
  "type": "tool_search_tool_bm25_20251119",
  "name": "tool_search_tool_bm25"
}
```

<Warning>
  **Formato delle query della variante regex: regex Python, non linguaggio naturale**

  Con `tool_search_tool_regex_20251119`, Claude scrive pattern Python `re.search()`, non query in linguaggio naturale. La corrispondenza non distingue tra maiuscole e minuscole. I pattern comuni includono i seguenti:

  * `"weather"`: corrisponde a nomi e descrizioni di strumenti contenenti "weather"
  * `"get_.*_data"`: corrisponde a strumenti come `get_user_data` e `get_weather_data`
  * `"database.*query|query.*database"`: corrisponde a entrambi gli ordini delle parole

  Lunghezza massima del pattern: 200 caratteri
</Warning>

<Note>
  **Formato delle query della variante BM25: linguaggio naturale**

  Con `tool_search_tool_bm25_20251119`, Claude cerca con query in linguaggio naturale. Lunghezza massima della query: 500 caratteri.
</Note>

### Caricamento differito degli strumenti

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

```json 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
}
```

`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](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-reference#client-toolsets) 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](https://platform.claude.com/docs/it/agents-and-tools/tool-use/strict-tool-use) (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:

```json 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": {
        "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](https://platform.claude.com/docs/it/agents-and-tools/mcp-connector), 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](https://platform.claude.com/docs/it/agents-and-tools/mcp-connector#mcp-toolset-configuration).

## 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:

```json JSON
{
  "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.

<Note>
  Il formato `tool_search_tool_result` mostrato nella sezione [Formato della risposta](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-search-tool#response-format) è il formato lato server usato internamente dalla ricerca strumenti integrata di Anthropic. Per le implementazioni personalizzate lato client, usa sempre il formato `tool_result` standard con blocchi di contenuto `tool_reference` come mostrato nell'esempio precedente.
</Note>

Per un esempio completo che usa gli embedding, consulta la ricetta [ricerca strumenti con embedding](https://platform.claude.com/cookbook/tool-use-tool-search-with-embeddings).

## Gestione degli errori

<Note>
  Gli [esempi di uso degli strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/define-tools#providing-tool-use-examples) funzionano con la ricerca strumenti: quando Claude scopre uno strumento differito, l'API espande i suoi `input_examples` insieme alla sua definizione.
</Note>

### Errori HTTP (stato 400)

Questi errori impediscono all'API di elaborare la richiesta:

**Tutti gli strumenti differiti:**

```json
{
  "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:**

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

```json JSON
{
  "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

<Accordion title="Errore 400: tutti gli strumenti sono differiti">
  **Causa:** Hai impostato `defer_loading: true` su ogni strumento, incluso lo strumento di ricerca strumenti.

  **Soluzione:** Rimuovi `defer_loading` dallo strumento di ricerca strumenti:

  ```json
  {
    "type": "tool_search_tool_regex_20251119",
    "name": "tool_search_tool_regex"
  }
  ```
</Accordion>

<Accordion title="Errore 400: definizione dello strumento mancante">
  **Causa:** Un `tool_reference` punta a uno strumento non presente nel tuo array `tools`.

  **Soluzione:** Assicurati che ogni strumento che potrebbe essere scoperto abbia una definizione completa:

  ```json
  {
    "name": "my_tool",
    "description": "Full description here",
    "input_schema": {
      "type": "object"
    },
    "defer_loading": true
  }
  ```
</Accordion>

<Accordion title="Claude non trova gli strumenti previsti">
  **Causa:** Il pattern regex non corrisponde al nome, alla descrizione, ai nomi degli argomenti o alle descrizioni degli argomenti dello strumento.

  **Passaggi di debug:**

  1. Controlla il nome dello strumento, la descrizione, i nomi degli argomenti e le descrizioni degli argomenti. Claude cerca in tutti questi campi.
  2. Testa il tuo pattern: `import re; re.search(r"your_pattern", "tool_name", re.IGNORECASE)`.
  3. La corrispondenza non distingue tra maiuscole e minuscole, quindi le differenze di maiuscole non sono il problema.
  4. Claude usa pattern ampi come `".*weather.*"`, non corrispondenze esatte.

  **Suggerimento:** Aggiungi parole chiave comuni alle descrizioni degli strumenti per migliorarne la reperibilità.
</Accordion>

## Cache dei prompt

Per scoprire come `defer_loading` preserva la cache dei prompt, consulta [Uso degli strumenti con la cache dei prompt](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-use-with-prompt-caching).

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:

```sse
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](https://platform.claude.com/docs/it/build-with-claude/batch-processing).

## 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](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-search-tool#model-compatibility)

### 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

<CardGroup cols={2}>
  <Card title="Strumento memoria" icon="brain" href="https://platform.claude.com/docs/it/agents-and-tools/tool-use/memory-tool">
    Consenti a Claude di archiviare e recuperare informazioni tra le conversazioni implementando le operazioni sui file dello strumento memoria nella tua applicazione.
  </Card>

  <Card title="Riferimento degli strumenti" icon="book" href="https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-reference">
    Elenco degli strumenti forniti da Anthropic e riferimento per le proprietà opzionali delle definizioni degli strumenti.
  </Card>

  <Card title="Connettore MCP" icon="link" href="https://platform.claude.com/docs/it/agents-and-tools/mcp-connector">
    Configura i toolset MCP con caricamento differito.
  </Card>

  <Card title="Uso degli strumenti con la cache dei prompt" icon="bolt" href="https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-use-with-prompt-caching">
    Memorizza nella cache le definizioni degli strumenti tra i turni e comprendi cosa invalida la tua cache.
  </Card>

  <Card title="Definire gli strumenti" icon="hammer" href="https://platform.claude.com/docs/it/agents-and-tools/tool-use/define-tools">
    Specifica gli schemi degli strumenti, scrivi descrizioni efficaci e controlla quando Claude chiama i tuoi strumenti.
  </Card>
</CardGroup>