Herramienta de búsqueda de herramientas

La herramienta de búsqueda de herramientas permite a Claude trabajar con cientos o miles de herramientas descubriéndolas y cargándolas dinámicamente bajo demanda. En lugar de cargar todas las definiciones de herramientas en la ventana de contexto de antemano, Claude busca en su 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 problemas que se agravan rápidamente a medida que las bibliotecas de herramientas escalan:

• Saturación del contexto: Las definiciones de herramientas consumen rápidamente el presupuesto de contexto. Una configuración típica de múltiples servidores (GitHub, Slack, Sentry, Grafana, Splunk) puede consumir ~55k tokens en definiciones antes de que Claude realice cualquier trabajo real. La búsqueda de herramientas generalmente reduce esto en más del 85%, cargando solo las 3–5 herramientas que Claude realmente necesita para una solicitud dada.
• Precisión en la selección de herramientas: La capacidad de Claude para elegir correctamente la herramienta adecuada se degrada significativamente una vez que se superan las 30–50 herramientas disponibles. Al mostrar un conjunto enfocado de herramientas relevantes bajo demanda, la búsqueda de herramientas mantiene alta la precisión de selección incluso con miles de herramientas.

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 (p. ej., 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 las herramientas que no deben cargarse inmediatamente
3. Claude ve inicialmente 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 devuelve 3-5 bloques tool_reference más relevantes
6. Estas referencias se expanden automáticamente en definiciones completas de herramientas
7. Claude selecciona entre las herramientas descubiertas y las invoca

Esto mantiene tu ventana de contexto eficiente mientras 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 las herramientas para carga bajo demanda añadiendo 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 el contexto inmediatamente
• Las herramientas con defer_loading: true solo se cargan cuando Claude las descubre mediante 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 utilizadas como no diferidas para un rendimiento óptimo

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

Cómo funciona el diferimiento internamente: Las herramientas diferidas no se incluyen en el prefijo del prompt del sistema. Cuando el modelo descubre una herramienta diferida a través de la búsqueda de herramientas, la definición de la herramienta se añade en línea como un bloque tool_reference en la conversación. El prefijo no se modifica, por lo que se preserva el caché de prompts. La gramática para el modo estricto se construye a partir del conjunto completo de herramientas, por lo que defer_loading y el modo estricto se combinan sin recompilación de gramática.

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 las herramientas descubiertas
• tool_use: Claude invocando la herramienta descubierta

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

Integración con MCP

Para configurar mcp_toolset con defer_loading, consulta Conector MCP.

Implementación personalizada de búsqueda de herramientas

Puedes implementar tu propia lógica de búsqueda de herramientas (p. ej., 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 con defer_loading: true. Este enfoque te permite usar algoritmos de búsqueda más sofisticados mientras mantienes la compatibilidad con el sistema de búsqueda de herramientas.

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

Manejo de errores

Errores HTTP (estado 400)

Estos errores impiden 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 tasa 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

Caché de prompts

Para saber cómo defer_loading preserva el caché de prompts, consulta Uso de herramientas con caché de prompts.

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

Streaming

Con el 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 las 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 tienen el mismo precio que las de las solicitudes regulares de la API de mensajes.

Retención de datos

La búsqueda de herramientas del lado del servidor (herramienta tool_search) indexa y almacena datos del catálogo de herramientas (nombres de herramientas, descripciones y metadatos de argumentos) más allá de la respuesta inmediata de la API; estos datos del catálogo se retienen de acuerdo con la política de retención estándar de Anthropic. Las implementaciones personalizadas de búsqueda de herramientas del lado del cliente que usan la API de mensajes estándar son completamente elegibles para ZDR.

Para la elegibilidad ZDR en todas las funciones, consulta API y retención de datos.

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 del patrón: Máximo 200 caracteres para patrones regex
• Soporte de modelos: Solo Claude Mythos Preview, Sonnet 4.0+, Opus 4.0+ (sin Haiku)

Cuándo usar la búsqueda de herramientas

Buenos casos de uso:

• 10+ herramientas disponibles en tu sistema
• Definiciones de herramientas que consumen >10k tokens
• Experimentando problemas de precisión en la selección de herramientas con grandes conjuntos de herramientas
• Construyendo sistemas con MCP con múltiples servidores (200+ herramientas)
• Biblioteca de herramientas que crece con el tiempo

Cuándo la llamada tradicional de herramientas 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 utilizadas como no diferidas
• Escribe nombres y descripciones de herramientas claros y descriptivos
• Usa espacios de nombres consistentes en los nombres de herramientas: prefija por servicio o recurso (p. ej., github_, slack_) para que las consultas de búsqueda muestren naturalmente el grupo de herramientas correcto
• Usa palabras clave semánticas en las descripciones que coincidan con cómo los usuarios describen las tareas
• Añade una sección en el prompt del sistema describiendo las categorías de herramientas disponibles: "Puedes buscar herramientas para interactuar con Slack, GitHub y Jira"
• Monitorea qué herramientas descubre Claude para refinar las descripciones

Uso

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

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

Próximos pasos