---
title: Herramienta de búsqueda de herramientas
url: https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-search-tool
description: Escala a cientos o miles de herramientas permitiendo que Claude busque en tu catálogo de herramientas y cargue solo las herramientas que necesita.
---

La herramienta de búsqueda de herramientas ("tool search tool") permite que Claude trabaje con cientos o miles de herramientas descubriéndolas y cargándolas bajo demanda. En lugar de cargar todas las definiciones de herramientas en la "context window" (ventana de contexto) desde el principio, Claude busca en tu catálogo de herramientas (incluidos los nombres de herramientas, descripciones, nombres de argumentos y descripciones de argumentos) y carga solo las herramientas que necesita.

Cargar todas las definiciones de herramientas desde el principio causa dos problemas a medida que crece una biblioteca de herramientas:

* **Inflación del contexto:** Una configuración típica de múltiples servidores (GitHub, Slack, Sentry, Grafana y Splunk) puede consumir \~55k tokens en definiciones antes de que Claude haga cualquier trabajo. La búsqueda de herramientas normalmente reduce esto en más del 85 por ciento, cargando solo las 3–5 herramientas que Claude necesita para una solicitud determinada.
* **Precisión en la selección de herramientas:** La capacidad de Claude para elegir la herramienta correcta se degrada una vez que superas las 30–50 herramientas disponibles. Dado que la búsqueda de herramientas carga solo un conjunto enfocado de herramientas relevantes bajo demanda, la precisión de selección se mantiene alta incluso con miles de herramientas.

Para conocer los modelos que admiten la búsqueda de herramientas, consulta [Compatibilidad de modelos](https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-search-tool#model-compatibility).

<Tip>
  Para obtener contexto sobre los desafíos de escalado que resuelve la búsqueda de herramientas, consulta [Advanced tool use](https://www.anthropic.com/engineering/advanced-tool-use). La carga bajo demanda de la búsqueda de herramientas también es un ejemplo del principio más amplio de recuperación justo a tiempo descrito en [Effective context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents).
</Tip>

La búsqueda de herramientas se ejecuta como una herramienta del lado del servidor, pero también puedes implementar tu propia búsqueda de herramientas del lado del cliente. Consulta [Implementación personalizada de búsqueda de herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-search-tool#custom-tool-search-implementation) para obtener más detalles.

<Note>
  Comparte tus comentarios sobre esta función a través del [formulario de comentarios](https://forms.gle/MhcGFFwLxuwnWTkYA).
</Note>

<Note>
  Para saber cómo se aplica la "zero data retention" (retención cero de datos), o ZDR, a esta función, consulta [API y retención de datos](https://platform.claude.com/docs/es/manage-claude/api-and-data-retention).
</Note>

<Warning>
  En Amazon Bedrock, la búsqueda de herramientas del lado del servidor está disponible solo a través de la [API InvokeModel](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-runtime_example_bedrock-runtime_InvokeModel_AnthropicClaude_section.html), no de la API Converse.
</Warning>

<Note>
  En [Claude Platform en AWS](https://platform.claude.com/docs/es/build-with-claude/claude-platform-on-aws), la búsqueda de herramientas del lado del servidor funciona de manera idéntica a la API de Claude. Claude Platform en AWS usa la API de Messages de Anthropic directamente, por lo que no existe la distinción entre InvokeModel y Converse.
</Note>

## Compatibilidad de modelos

Ambas variantes de búsqueda de herramientas están disponibles en los siguientes modelos:

| Modelo                                                                                                                           | Versiones de la herramienta                                         |
| -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| 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) ([obsoleto](https://platform.claude.com/docs/es/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 y los modelos anteriores no admiten la herramienta de búsqueda de herramientas.

## Cómo funciona la búsqueda de herramientas

Existen dos variantes de búsqueda de herramientas:

* **Regex** (`tool_search_tool_regex_20251119`): Claude construye patrones regex para buscar herramientas.
* **BM25** (`tool_search_tool_bm25_20251119`): Claude usa consultas en lenguaje natural para buscar herramientas.

Cuando habilitas la herramienta de búsqueda de herramientas:

1. Incluyes una herramienta de búsqueda de herramientas (por ejemplo, `tool_search_tool_regex_20251119` o `tool_search_tool_bm25_20251119`) en tu lista `tools`.
2. Proporcionas todas las definiciones de herramientas en el array `tools` y estableces `defer_loading: true` en las herramientas que no deben cargarse desde el principio. Al menos una herramienta, normalmente la propia herramienta de búsqueda de herramientas, debe permanecer sin diferir.
3. Inicialmente, el contexto de Claude contiene solo la herramienta de búsqueda de herramientas y cualquier herramienta no diferida.
4. Cuando Claude necesita herramientas adicionales, busca usando una herramienta de búsqueda de herramientas.
5. La API ejecuta la búsqueda y devuelve las herramientas coincidentes como bloques `tool_reference` (hasta 5 de forma predeterminada; Claude puede establecer un `limit` en su entrada de búsqueda).
6. La API expande automáticamente estas referencias en definiciones de herramientas completas.
7. Claude selecciona entre las herramientas descubiertas y las llama.

## Inicio rápido

El siguiente ejemplo incluye la herramienta de búsqueda de herramientas y dos herramientas diferidas:

<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 busca en el catálogo, descubre `get_weather` y la llama. La respuesta termina con `stop_reason: "tool_use"`. Ejecuta la herramienta descubierta y devuelve un `tool_result` como en [Manejar llamadas a herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/handle-tool-calls). [Formato de respuesta](https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-search-tool#response-format) muestra los bloques que recibes y qué enviar a continuación.

## Definición de la herramienta

La herramienta de búsqueda de herramientas tiene dos variantes:

```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 de consulta de la variante regex: regex de Python, no lenguaje natural**

  Con `tool_search_tool_regex_20251119`, Claude escribe patrones `re.search()` de Python, no consultas en lenguaje natural. La coincidencia no distingue entre mayúsculas y minúsculas. Los patrones comunes incluyen los siguientes:

  * `"weather"`: coincide con nombres y descripciones de herramientas que contienen "weather"
  * `"get_.*_data"`: coincide con herramientas como `get_user_data` y `get_weather_data`
  * `"database.*query|query.*database"`: coincide con cualquier orden de las palabras

  Longitud máxima del patrón: 200 caracteres
</Warning>

<Note>
  **Formato de consulta de la variante BM25: lenguaje natural**

  Con `tool_search_tool_bm25_20251119`, Claude busca con consultas en lenguaje natural. Longitud máxima de la consulta: 500 caracteres.
</Note>

### Carga diferida de herramientas

Marca las herramientas para carga bajo demanda agregando `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` controla lo que entra en la ventana de contexto, no lo que envías en la solicitud:

* Sigues enviando la definición completa de cada herramienta en el array `tools` en cada solicitud, incluidas las diferidas. La API las necesita del lado del servidor para ejecutar la búsqueda y expandir los bloques `tool_reference`.
* Las herramientas sin `defer_loading` se cargan en el contexto inmediatamente.
* Las herramientas con `defer_loading: true` se cargan solo cuando Claude las descubre mediante la búsqueda.
* Nunca establezcas `defer_loading: true` en la propia herramienta de búsqueda de herramientas.
* Mantén tus 3–5 herramientas más utilizadas sin diferir para que Claude pueda llamarlas sin buscar primero.

Los conjuntos de herramientas de uso de computadora y uso de navegador (`computer_toolset_20260801` y `browser_toolset_20260801`) reciben `defer_loading` por herramienta miembro dentro del objeto `configs` de la entrada, no en la entrada misma; una solicitud que lo establezca a nivel de entrada es rechazada. Dado que un conjunto de herramientas se difiere y se expande como una unidad, `defer_loading` debe resolverse al mismo valor en cada miembro habilitado, y cuando Claude descubre el conjunto de herramientas mediante la búsqueda, todos los miembros habilitados se cargan a la vez. Consulta [Conjuntos de herramientas del cliente](https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-reference#client-toolsets) para conocer el formato de `configs`.

Ambas variantes de búsqueda de herramientas (`regex` y `bm25`) buscan en nombres de herramientas, descripciones, nombres de argumentos y descripciones de argumentos.

Internamente, la API excluye las herramientas diferidas del prefijo de la indicación del sistema. Cuando Claude descubre una herramienta diferida mediante la búsqueda de herramientas, la API agrega un bloque `tool_reference` en línea en la conversación y luego lo expande en la definición completa de la herramienta antes de pasárselo a Claude. El prefijo permanece intacto, por lo que el "prompt caching" (almacenamiento en caché de prompts) se conserva. La gramática del [modo estricto](https://platform.claude.com/docs/es/agents-and-tools/tool-use/strict-tool-use) (las reglas que restringen la salida de las llamadas a herramientas para que coincida con tus esquemas) se construye a partir del conjunto completo de herramientas, por lo que `defer_loading` y el modo estricto se combinan sin recompilación de la gramática.

## Formato de respuesta

Cuando Claude usa la herramienta de búsqueda de herramientas, la respuesta incluye los siguientes tipos de bloques:

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

### Entender la respuesta

* **`server_tool_use`:** la llamada de Claude a la herramienta de búsqueda de herramientas. La búsqueda se ejecuta en los servidores de Anthropic. Nunca devuelvas un `tool_result` para su ID `srvtoolu_...`. El `input` contiene la búsqueda (`pattern` para la variante regex, `query` para BM25) y puede incluir un `limit` opcional, un entero de 1 a 10,000 que limita cuántas herramientas coincidentes devuelve la búsqueda (predeterminado: 5).
* **`tool_search_tool_result`:** los resultados de la búsqueda, en un objeto `tool_search_tool_search_result` anidado. Mantenlo en el historial de mensajes tal como está.
* **`tool_references`:** un array de objetos `tool_reference` que apuntan a las herramientas descubiertas. La API los expande para Claude. Nunca los expandes tú mismo.
* **`tool_use`:** la llamada de Claude a una herramienta descubierta. Ejecútala y devuelve un `tool_result` exactamente como en el uso de herramientas estándar.

La API expande automáticamente los bloques `tool_reference` en definiciones de herramientas completas antes de mostrárselos a Claude. No necesitas manejar esta expansión tú mismo, siempre que proporciones todas las definiciones de herramientas coincidentes en el parámetro `tools`.

### Continuar la conversación

En la siguiente solicitud, devuelve el contenido del asistente sin cambios, incluidos los bloques `server_tool_use` y `tool_search_tool_result`. Agrega tu `tool_result` para la herramienta descubierta en un mensaje de usuario y envía el mismo array `tools`: la herramienta de búsqueda más todas las definiciones diferidas. No devuelvas un `tool_result` para el ID `srvtoolu_...`: la API rechaza la solicitud. La API expande los bloques `tool_reference` a lo largo de todo el historial de la conversación, por lo que Claude puede reutilizar las herramientas descubiertas en turnos posteriores sin volver a buscar. Una búsqueda que no coincide con nada devuelve un `tool_search_tool_search_result` con un array `tool_references` vacío, no un error.

## Integración con MCP

Si tus herramientas provienen de servidores MCP a través del [conector MCP](https://platform.claude.com/docs/es/agents-and-tools/mcp-connector), no estableces `defer_loading` en las definiciones de herramientas individuales. En su lugar, establécelo una vez en el `default_config` de la entrada `mcp_toolset` para todo el servidor, o por herramienta en sus `configs`. Consulta [Configuración del conjunto de herramientas MCP](https://platform.claude.com/docs/es/agents-and-tools/mcp-connector#mcp-toolset-configuration).

## Implementación personalizada de búsqueda de herramientas

Puedes implementar tu propia lógica de búsqueda de herramientas (por ejemplo, usando embeddings o búsqueda semántica) devolviendo bloques `tool_reference` desde una herramienta personalizada. Cuando Claude llama a tu herramienta de búsqueda personalizada, devuelve un `tool_result` estándar con bloques `tool_reference` en el array de contenido:

```json JSON
{
  "type": "tool_result",
  "tool_use_id": "toolu_your_tool_id",
  "content": [{ "type": "tool_reference", "tool_name": "discovered_tool_name" }]
}
```

Cada herramienta referenciada debe tener una definición de herramienta correspondiente en el parámetro `tools` de nivel superior, normalmente con `defer_loading: true`. Esto te permite usar métodos de búsqueda que las variantes integradas no proporcionan, como la recuperación basada en embeddings, y la API expande los bloques `tool_reference` devueltos de la misma manera.

<Note>
  El formato `tool_search_tool_result` que se muestra en la sección [Formato de respuesta](https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-search-tool#response-format) es el formato del lado del servidor que usa internamente la búsqueda de herramientas integrada de Anthropic. Para implementaciones personalizadas del lado del cliente, usa siempre el formato `tool_result` estándar con bloques de contenido `tool_reference` como se muestra en el ejemplo anterior.
</Note>

Para ver un ejemplo completo usando embeddings, consulta la receta de [búsqueda de herramientas con embeddings](https://platform.claude.com/cookbook/tool-use-tool-search-with-embeddings).

## Manejo de errores

<Note>
  Los [ejemplos de uso de herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/define-tools#providing-tool-use-examples) funcionan con la búsqueda de herramientas: cuando Claude descubre una herramienta diferida, la API expande sus `input_examples` junto con su definición.
</Note>

### Errores HTTP (estado 400)

Estos errores impiden que la API procese la solicitud:

**Todas las herramientas diferidas:**

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "At least one tool must have defer_loading=false. All tools cannot be deferred."
  }
}
```

**Definición de herramienta faltante:**

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Tool reference 'unknown_tool' not found in available tools"
  }
}
```

### Errores de resultado de herramienta (estado 200)

Cuando una operación de búsqueda de herramientas falla durante la ejecución, la API devuelve una respuesta 200 con el error en el cuerpo:

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

El campo `error_code` tiene cuatro valores posibles:

* `invalid_tool_input`: la entrada de búsqueda no era válida, por ejemplo un patrón regex mal formado o un patrón que supera el límite de 200 caracteres
* `unavailable`: la búsqueda no pudo ejecutarse, por ejemplo porque se agotó el tiempo de espera o el servicio no estaba disponible
* `too_many_requests`: se superó el límite de velocidad para las operaciones de búsqueda de herramientas
* `execution_time_exceeded`: la búsqueda superó su límite de tiempo de ejecución

### Errores comunes

<Accordion title="Error 400: todas las herramientas están diferidas">
  **Causa:** Estableciste `defer_loading: true` en todas las herramientas, incluida la herramienta de búsqueda de herramientas.

  **Solución:** Elimina `defer_loading` de la herramienta de búsqueda de herramientas:

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

<Accordion title="Error 400: definición de herramienta faltante">
  **Causa:** Un `tool_reference` apunta a una herramienta que no está en tu array `tools`.

  **Solución:** Asegúrate de que cada herramienta que pueda descubrirse tenga una definición completa:

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

<Accordion title="Claude no encuentra las herramientas esperadas">
  **Causa:** El patrón regex no coincide con el nombre, la descripción, los nombres de argumentos ni las descripciones de argumentos de la herramienta.

  **Pasos de depuración:**

  1. Revisa el nombre de la herramienta, la descripción, los nombres de argumentos y las descripciones de argumentos. Claude busca en todos estos campos.
  2. Prueba tu patrón: `import re; re.search(r"your_pattern", "tool_name", re.IGNORECASE)`.
  3. La coincidencia no distingue entre mayúsculas y minúsculas, por lo que las diferencias de mayúsculas no son el problema.
  4. Claude usa patrones amplios como `".*weather.*"`, no coincidencias exactas.

  **Consejo:** Agrega palabras clave comunes a las descripciones de las herramientas para mejorar su capacidad de descubrimiento.
</Accordion>

## Almacenamiento en caché de prompts

Para saber cómo `defer_loading` conserva el almacenamiento en caché de prompts, consulta [Uso de herramientas con almacenamiento en caché de prompts](https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-use-with-prompt-caching).

Una herramienta con `defer_loading: true` no puede llevar también `cache_control`: la API devuelve un 400. Coloca el punto de interrupción de caché en una herramienta no diferida.

## Streaming

Con el streaming habilitado, recibirás los eventos de búsqueda de herramientas como parte del 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
```

## Solicitudes por lotes

Puedes incluir la herramienta de búsqueda de herramientas en la [API de Messages Batches](https://platform.claude.com/docs/es/build-with-claude/batch-processing).

## Límites y mejores prácticas

### Límites

* **Máximo de herramientas diferidas:** 10,000 herramientas con `defer_loading: true` por solicitud
* **Resultados de búsqueda:** cada búsqueda devuelve hasta 5 herramientas coincidentes de forma predeterminada; Claude puede establecer `limit` en su entrada de búsqueda en cualquier entero de 1 a 10,000
* **Longitud de patrones y consultas:** máximo 200 caracteres para patrones regex y 500 caracteres para consultas BM25
* **Compatibilidad de modelos:** consulta [Compatibilidad de modelos](https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-search-tool#model-compatibility)

### Cuándo usar la búsqueda de herramientas

Usa la búsqueda de herramientas cuando se cumpla cualquiera de las siguientes condiciones:

* Tienes 10 o más herramientas disponibles.
* Tus definiciones de herramientas consumen más de 10k tokens.
* La precisión en la selección de herramientas disminuye a medida que crece tu conjunto de herramientas.
* Agregas múltiples servidores MCP (más de 200 herramientas).
* Tu biblioteca de herramientas crece con el tiempo.

La llamada a herramientas estándar, sin búsqueda de herramientas, es más adecuada cuando tienes menos de 10 herramientas, todas las herramientas se usan en cada solicitud o tus definiciones de herramientas son pequeñas (menos de 100 tokens en total).

### Consejos de optimización

* Mantén tus 3–5 herramientas más utilizadas sin diferir.
* Escribe nombres y descripciones de herramientas claros y descriptivos.
* Usa espacios de nombres consistentes en los nombres de las herramientas: usa prefijos por servicio o recurso (por ejemplo, `github_`, `slack_`) para que una sola búsqueda coincida con todo el grupo.
* Usa palabras clave en las descripciones que coincidan con la forma en que los usuarios describen las tareas.
* Agrega una sección en la indicación del sistema que describa las categorías de herramientas disponibles: "You can search for tools to interact with Slack, GitHub, and Jira."
* Monitorea qué herramientas descubre Claude para refinar tus descripciones.

## Uso

La búsqueda de herramientas no se mide como una herramienta de servidor independiente. El objeto `usage.server_tool_use` de la respuesta no tiene un campo de búsqueda de herramientas, y las definiciones de herramientas que la búsqueda carga en el contexto cuentan como tokens de entrada como cualquier otra definición de herramienta.

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Herramienta de memoria" icon="brain" href="https://platform.claude.com/docs/es/agents-and-tools/tool-use/memory-tool">
    Permite que Claude almacene y recupere información entre conversaciones implementando las operaciones de archivos de la herramienta de memoria en tu aplicación.
  </Card>

  <Card title="Referencia de herramientas" icon="book" href="https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-reference">
    Directorio de herramientas proporcionadas por Anthropic y referencia de las propiedades opcionales de definición de herramientas.
  </Card>

  <Card title="Conector MCP" icon="link" href="https://platform.claude.com/docs/es/agents-and-tools/mcp-connector">
    Configura conjuntos de herramientas MCP con carga diferida.
  </Card>

  <Card title="Uso de herramientas con almacenamiento en caché de prompts" icon="bolt" href="https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-use-with-prompt-caching">
    Almacena en caché las definiciones de herramientas entre turnos y comprende qué invalida tu caché.
  </Card>

  <Card title="Definir herramientas" icon="hammer" href="https://platform.claude.com/docs/es/agents-and-tools/tool-use/define-tools">
    Especifica esquemas de herramientas, escribe descripciones efectivas y controla cuándo Claude llama a tus herramientas.
  </Card>
</CardGroup>