Herramienta de búsqueda de herramientas

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.

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 para obtener más detalles.

Compatibilidad de modelos

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

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:

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)

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. Formato de respuesta 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:

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

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

Carga diferida de herramientas

Marca las herramientas para carga bajo demanda agregando defer_loading: true:

{
  "name": "get_weather",
  "description": "Get current weather for a location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": { "type": "string" },
      "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
    },
    "required": ["location"]
  },
  "defer_loading": true
}

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

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

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:

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

Para ver un ejemplo completo usando embeddings, consulta la receta de búsqueda de herramientas con embeddings.

Manejo de errores

Errores HTTP (estado 400)

Estos errores impiden que la API procese la solicitud:

Todas las herramientas diferidas:

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

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

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

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

{
  "name": "my_tool",
  "description": "Full description here",
  "input_schema": {
    "type": "object"
  },
  "defer_loading": true
}

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.

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:

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.

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

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