Herramienta de búsqueda de herramientas

La herramienta de búsqueda de herramientas permite a Claude trabajar con cientos o miles de herramientas descubriendo y cargando dinámicamente solo las que necesita. En lugar de cargar todas las definiciones de herramientas en la ventana de contexto de antemano, 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.

Este enfoque resuelve dos desafíos críticos a medida que las bibliotecas de herramientas se escalan:

• Eficiencia de contexto: Las definiciones de herramientas pueden consumir porciones masivas de tu ventana de contexto (50 herramientas ≈ 10-20K tokens), dejando menos espacio para el trabajo real
• Precisión en la selección de herramientas: La capacidad de Claude para seleccionar correctamente herramientas se degrada significativamente con más de 30-50 herramientas disponibles convencionalmente

Aunque esto se proporciona como una herramienta del lado del servidor, también puedes implementar tu propia funcionalidad de búsqueda de herramientas del lado del cliente. Consulta Implementación personalizada de búsqueda de herramientas para más detalles.

También puedes implementar búsqueda de herramientas del lado del cliente devolviendo bloques tool_reference desde tu propia implementación de búsqueda.

Cómo funciona la búsqueda de herramientas

Hay 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 de herramientas
2. Proporcionas todas las definiciones de herramientas con defer_loading: true para herramientas que no deberían cargarse inmediatamente
3. Claude ve solo la herramienta de búsqueda de herramientas y cualquier herramienta no diferida inicialmente
4. Cuando Claude necesita herramientas adicionales, busca usando una herramienta de búsqueda de herramientas
5. La API devuelve 3-5 bloques tool_reference más relevantes
6. Estas referencias se expanden automáticamente en definiciones de herramientas completas
7. Claude selecciona de las herramientas descubiertas e las invoca

Esto mantiene tu ventana de contexto eficiente mientras se mantiene alta la precisión en la selección de herramientas.

Inicio rápido

Aquí hay un ejemplo simple con herramientas diferidas:

Definición de 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 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
}

Puntos clave:

• Las herramientas sin defer_loading se cargan en contexto inmediatamente
• Las herramientas con defer_loading: true se cargan solo cuando Claude las descubre a través de búsqueda
• La herramienta de búsqueda de herramientas en sí nunca debe tener defer_loading: true
• Mantén tus 3-5 herramientas más frecuentemente usadas como no diferidas para un rendimiento óptimo

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

Formato de respuesta

Cuando Claude usa la herramienta de búsqueda de herramientas, la respuesta incluye nuevos 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": {
        "query": "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"
}

Entendiendo la respuesta

• server_tool_use: Indica que Claude está invocando la herramienta de búsqueda de herramientas
• tool_search_tool_result: Contiene los resultados de búsqueda con un objeto tool_search_tool_search_result anidado
• tool_references: Array de objetos tool_reference que apuntan a herramientas descubiertas
• tool_use: Claude invocando la herramienta descubierta

Los bloques tool_reference se expanden automáticamente en definiciones de herramientas completas antes de ser mostrados a Claude. No necesitas manejar esta expansión tú mismo. Sucede automáticamente en la API siempre que proporciones todas las definiciones de herramientas coincidentes en el parámetro tools.

Integración MCP

La herramienta de búsqueda de herramientas funciona con servidores MCP. Agrega el encabezado beta "mcp-client-2025-11-20" a tu solicitud de API, y luego usa mcp_toolset con default_config para diferir la carga de herramientas MCP:

Opciones de configuración MCP:

• default_config.defer_loading: Establece el valor predeterminado para todas las herramientas del servidor MCP
• configs: Anula los valores predeterminados para herramientas específicas por nombre
• Combina múltiples servidores MCP con búsqueda de herramientas para bibliotecas de herramientas masivas

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:

{
  "type": "tool_search_tool_result",
  "tool_use_id": "toolu_custom_search",
  "content": {
    "type": "tool_search_tool_search_result",
    "tool_references": [{ "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 con defer_loading: true. Este enfoque te permite usar algoritmos de búsqueda más sofisticados mientras se mantiene la compatibilidad con el sistema de búsqueda de herramientas.

Para un ejemplo completo usando embeddings, consulta nuestro cookbook de búsqueda de herramientas con embeddings.

Manejo de errores

Errores HTTP (estado 400)

Estos errores previenen que la solicitud sea procesada:

Todas las herramientas diferidas:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "All tools have defer_loading set. At least one tool must be non-deferred."
  }
}

Definición de herramienta faltante:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Tool reference 'unknown_tool' has no corresponding tool definition"
  }
}

Errores de resultado de herramienta (estado 200)

Los errores durante la ejecución de herramientas devuelven una respuesta 200 con información de error en el cuerpo:

{
  "type": "tool_result",
  "tool_use_id": "srvtoolu_01ABC123",
  "content": {
    "type": "tool_search_tool_result_error",
    "error_code": "invalid_pattern"
  }
}

Códigos de error:

• too_many_requests: Límite de velocidad excedido para operaciones de búsqueda de herramientas
• invalid_pattern: Patrón regex malformado
• pattern_too_long: El patrón excede el límite de 200 caracteres
• unavailable: Servicio de búsqueda de herramientas temporalmente no disponible

Errores comunes

Almacenamiento en caché de prompts

La búsqueda de herramientas funciona con almacenamiento en caché de prompts. Agrega puntos de ruptura cache_control para optimizar conversaciones de múltiples turnos:

import anthropic

client = anthropic.Anthropic()

# Primera solicitud con búsqueda de herramientas
messages = [
    {
        "role": "user",
        "content": "What's the weather in Seattle?"
    }
]

response1 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    betas=["advanced-tool-use-2025-11-20"],
    max_tokens=2048,
    messages=messages,
    tools=[
        {
            "type": "tool_search_tool_regex_20251119",
            "name": "tool_search_tool_regex"
        },
        {
            "name": "get_weather",
            "description": "Get weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"]
            },
            "defer_loading": True
        }
    ]
)

# Agrega la respuesta de Claude a la conversación
messages.append({
    "role": "assistant",
    "content": response1.content
})

# Segunda solicitud con punto de ruptura de caché
messages.append({
    "role": "user",
    "content": "What about New York?",
    "cache_control": {"type": "ephemeral"}
})

response2 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    betas=["advanced-tool-use-2025-11-20"],
    max_tokens=2048,
    messages=messages,
    tools=[
        {
            "type": "tool_search_tool_regex_20251119",
            "name": "tool_search_tool_regex"
        },
        {
            "name": "get_weather",
            "description": "Get weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"]
            },
            "defer_loading": True
        }
    ]
)

print(f"Cache read tokens: {response2.usage.get('cache_read_input_tokens', 0)}")

El sistema expande automáticamente bloques tool_reference en todo el historial de conversación completo, por lo que Claude puede reutilizar herramientas descubiertas en turnos posteriores sin volver a buscar.

Streaming

Con streaming habilitado, recibirás 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"}}

// Consulta de búsqueda transmitida
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"weather\"}"}}

// Pausa mientras se ejecuta la búsqueda

// Resultados de búsqueda transmitidos
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 continúa con herramientas descubiertas

Solicitudes por lotes

Puedes incluir la herramienta de búsqueda de herramientas en la API de Lotes de Mensajes. Las operaciones de búsqueda de herramientas a través de la API de Lotes de Mensajes se cotizan igual que las solicitudes de la API de Mensajes regular.

Límites y mejores prácticas

Límites

• Máximo de herramientas: 10,000 herramientas en tu catálogo
• Resultados de búsqueda: Devuelve 3-5 herramientas más relevantes por búsqueda
• Longitud de patrón: Máximo 200 caracteres para patrones regex
• Soporte de modelo: Solo Sonnet 4.0+, Opus 4.0+ (sin Haiku)

Cuándo usar búsqueda de herramientas

Casos de uso buenos:

• 10+ herramientas disponibles en tu sistema
• Definiciones de herramientas consumiendo >10K tokens
• Experimentando problemas de precisión en la selección de herramientas con grandes conjuntos de herramientas
• Construyendo sistemas impulsados por MCP con múltiples servidores (200+ herramientas)
• Biblioteca de herramientas creciendo con el tiempo

Cuándo el llamado de herramientas tradicional podría ser mejor:

• Menos de 10 herramientas en total
• Todas las herramientas se usan frecuentemente en cada solicitud
• Definiciones de herramientas muy pequeñas (<100 tokens en total)

Consejos de optimización

• Mantén 3-5 herramientas más frecuentemente usadas como no diferidas
• Escribe nombres y descripciones de herramientas claros y descriptivos
• Usa palabras clave semánticas en descripciones que coincidan con cómo los usuarios describen tareas
• Agrega una sección de prompt del sistema describiendo categorías de herramientas disponibles: "Puedes buscar herramientas para interactuar con Slack, GitHub y Jira"
• Monitorea qué herramientas descubre Claude para refinar descripciones

Uso

El uso de la herramienta de búsqueda de herramientas se rastrea en el objeto de uso de respuesta:

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