Herramienta de búsqueda de herramientas

La herramienta de búsqueda de herramientas 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 inicio, Claude busca en tu catálogo de herramientas (incluyendo 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 inicio causa dos problemas a medida que crece una biblioteca de herramientas:

• Sobrecarga de 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 realice 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. Debido a 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.

La búsqueda de herramientas está disponible de forma general en la API de Claude. Para ver los modelos compatibles, 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 arreglo tools y estableces defer_loading: true en las herramientas que no deben cargarse desde el inicio. 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 por defecto).
6. La API expande automáticamente estas referencias en definiciones completas de herramientas.
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-4-8",
    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 se describe 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 qué entra en la ventana de contexto, no qué envías en la solicitud:

• Sigues enviando la definición completa de cada herramienta en el arreglo 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 a través de 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.

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 a través de 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 pasarla a Claude. El prefijo no se modifica, por lo que se preserva el almacenamiento en caché de prompts. La gramática para el modo estricto (las reglas que restringen la salida de 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 componen sin recompilación de 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"
      }
    },
    {
      "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"
}



Comprender 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_....
• tool_search_tool_result: los resultados de la búsqueda, en un objeto anidado tool_search_tool_search_result. Mantenlo en el historial de mensajes tal como está.
• tool_references: un arreglo 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 completas de herramientas antes de mostrárselas 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, pasa 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 arreglo 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 del 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 arreglo 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 individuales de herramientas. 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 arreglo 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 excedió el límite de velocidad para operaciones de búsqueda de herramientas
• execution_time_exceeded: la búsqueda excedió su límite de tiempo de ejecución



Errores comunes



Almacenamiento en caché de prompts

Para saber cómo defer_loading preserva 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 eventos de búsqueda de herramientas como parte del flujo:

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 Lotes de Mensajes.



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 por defecto
• Longitud de patrón y consulta: 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 aplique 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 de 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 estándar a herramientas, sin búsqueda de herramientas, es más adecuada cuando tienes menos de 10 herramientas, cada herramienta se usa 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 herramientas: agrega un prefijo por servicio o recurso (por ejemplo, github_, slack_) para que una búsqueda coincida con todo el grupo.
• Usa palabras clave en las descripciones que coincidan con cómo los usuarios describen las tareas.
• Agrega una sección en la indicación del sistema que describa las categorías de herramientas disponibles: "Puedes buscar herramientas para interactuar con Slack, GitHub y Jira."
• Monitorea qué herramientas descubre Claude para refinar tus descripciones.



Uso

La búsqueda de herramientas no se mide como una herramienta de servidor separada. 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 al igual que cualquier otra definición de herramienta.



Próximos pasos