Herramienta de búsqueda de herramientas

La herramienta de búsqueda de herramientas permite que Claude trabaje con cientos o miles de herramientas descubriendo 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 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 problemas que se agravan rápidamente a medida que las bibliotecas de herramientas se escalan:

• Inflación de contexto: Las definiciones de herramientas consumen tu presupuesto de contexto rápidamente. Una configuración típica de múltiples servidores (GitHub, Slack, Sentry, Grafana, Splunk) puede consumir ~55k tokens en definiciones antes de que Claude haga ningún trabajo real. La búsqueda de herramientas típicamente 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 excedes 30-50 herramientas disponibles. Al mostrar un conjunto enfocado de herramientas relevantes bajo demanda, la búsqueda de herramientas mantiene la precisión de selección alta incluso en 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 obtener 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 de 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 utilizadas 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.

Cómo funciona el diferimiento internamente: Las herramientas diferidas no se incluyen en el prefijo del mensaje del sistema. Cuando el modelo descubre una herramienta diferida a través de búsqueda de herramientas, la definición de la herramienta se agrega en línea como un bloque tool_reference en la conversación. El prefijo no se toca, por lo que el almacenamiento en caché de mensajes se preserva. La gramática para modo estricto se construye a partir del conjunto completo de herramientas, por lo que defer_loading y 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 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

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 (por ejemplo, usando incrustaciones 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 se mantiene la compatibilidad con el sistema de búsqueda de herramientas.

Para un ejemplo completo usando incrustaciones, consulta el libro de recetas de búsqueda de herramientas con incrustaciones.

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 mensajes

Para cómo defer_loading preserva el almacenamiento en caché de mensajes, consulta Uso de herramientas con almacenamiento en caché de mensajes.

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

// Search query streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"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. 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.

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 elegibilidad de ZDR en todas las características, consulta Retención de API y 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 de patrón: Máximo 200 caracteres para patrones regex
• Soporte de modelo: Claude Mythos Preview, Sonnet 4.0+, Opus 4.0+ solo (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 selección de herramientas con conjuntos de herramientas grandes
• Construyendo sistemas impulsados por MCP con múltiples servidores (200+ herramientas)
• Biblioteca de herramientas creciendo con el tiempo

Cuándo la llamada 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 utilizadas como no diferidas
• Escribe nombres y descripciones de herramientas claros y descriptivos
• Usa espacios de nombres consistentes en nombres de herramientas: prefijo por servicio o recurso (por ejemplo, github_, slack_) para que las consultas de búsqueda naturalmente muestren el grupo de herramientas correcto
• Usa palabras clave semánticas en descripciones que coincidan con cómo los usuarios describen tareas
• Agrega una sección de mensaje 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
    }
  }
}

Próximos pasos