Busca en todas las páginas de la documentación
Referencia rápida para configurar la Herramienta de Búsqueda de Herramientas: qué cadena type declarar, qué hace defer_loading en una herramienta individual y las restricciones que provocarán un error 400 en tu solicitud si las configuras incorrectamente.
type exacta para la variante de búsqueda que deseas antes de escribir el array tools; un error tipográfico en el sufijo de fecha es una fuente común de errores de "tipo de herramienta desconocido".defer_loading solo compensa una vez que el volumen del esquema se convierte en el cuello de botella.type | name | Método de descubrimiento | Mejor para |
|---|---|---|---|
tool_search_tool_regex_20251119 | tool_search_tool_regex | Coincidencia de patrones Regex sobre nombres y descripciones de herramientas | Bibliotecas de herramientas con convenciones de nomenclatura predecibles (por ejemplo, crm_get_*, crm_update_*) |
tool_search_tool_bm25_20251119 | tool_search_tool_bm25 | Clasificación de relevancia de palabras clave BM25 | Catálogos de herramientas grandes y poco relacionados donde Claude necesita hacer coincidir la intención del lenguaje natural con las descripciones de las herramientas |
Ambas son herramientas del lado del servidor; las declaras en el array tools como cualquier otra herramienta, pero Anthropic realiza la búsqueda. Ninguna de ellas toma un input_schema; Claude las llama de la misma manera que llama a cualquier herramienta, y tú nunca implementas un manejador para ellas.
tools = [
{"type": "tool_search_tool_bm25_20251119", "name": "tool_search_tool_bm25"},
# ...tus otras definiciones de herramientas...
]defer_loading| Campo | Tipo | Por defecto | Efecto |
|---|---|---|---|
defer_loading | booleano | false | Cuando es true en la definición de una herramienta, su esquema completo se deja fuera del contexto de la solicitud inicial. Claude descubre la herramienta llamando a la herramienta de búsqueda, y el esquema coincidente se carga en el contexto bajo demanda. |
{
"name": "get_weather",
"description": "Obtener el tiempo actual para una ubicación.",
"input_schema": {
"type": "object",
"properties": {"location": {"type": "string"}},
"required": ["location"],
},
"defer_loading": True,
}defer_loading es el mecanismo detrás del ahorro de tokens: en una biblioteca de cientos de herramientas, posponer la mayoría de las que se usan con poca frecuencia y mantener solo un puñado siempre cargadas puede reducir aproximadamente el 85% de los tokens que de otro modo se gastarían reenviando cada esquema de herramienta en cada solicitud.
| Restricción | Qué sucede si la violas |
|---|---|
La propia herramienta de búsqueda (tool_search_tool_regex / tool_search_tool_bm25) nunca debe tener defer_loading: true. | La herramienta de búsqueda debe ser visible para Claude desde el primer turno; posponerla significaría que nada podría descubrirla jamás. |
| Al menos una herramienta en la solicitud debe permanecer sin posponer. | Un array tools completamente pospuesto devuelve 400: Todas las herramientas tienen defer_loading establecido. |
| Los esquemas descubiertos se añaden a la solicitud, no se reemplazan. | Esto es una característica, no un problema; significa que el prefijo de caché del prompt para tools y system se mantiene intacto durante una llamada de búsqueda, por lo que no pagas un coste completo de caché perdida cada vez que Claude busca. |
Los resultados de la búsqueda llegan como un bloque de contenido tool_search_tool_result. | El código que solo comprueba los tipos de bloque tool_use / text ignorará silenciosamente los resultados de la búsqueda; bifurca explícitamente en tool_search_tool_result si estás inspeccionando el contenido de la respuesta. |
| Se admite y se espera la mezcla de herramientas siempre cargadas y pospuestas en una sola solicitud. | Mantén las herramientas de uso frecuente y con esquemas pequeños siempre cargadas; pospón las herramientas de uso poco frecuente o las que forman parte de un catálogo grande. |
{
"model": "claude-sonnet-5",
"max_tokens": 1024,
"tools": [
{"type": "tool_search_tool_bm25_20251119", "name": "tool_search_tool_bm25"},
{"name": "get_weather", "description": "...", "input_schema": {"type": "object", "properties": {}}, "defer_loading": true}
],
"messages": [{"role": "user", "content": "..."}]
}Python equivalente, usando el SDK oficial de anthropic:
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-sonnet-5",
max_tokens=1024,
tools=[
{"type": "tool_search_tool_bm25_20251119", "name": "tool_search_tool_bm25"},
{
"name": "get_weather",
"description": "Obtener el tiempo actual para una ubicación.",
"input_schema": {
"type": "object",
"properties": {"location": {"type": "string"}},
"required": ["location"],
},
"defer_loading": True,
},
],
messages=[{"role": "user", "content": "¿Qué tiempo hace en Boston?"}],
)| Si tu biblioteca de herramientas... | Usa |
|---|---|
| Sigue una convención de nomenclatura/prefijo consistente que puedes expresar como un patrón | tool_search_tool_regex_20251119 |
| Es grande, está organizada de forma laxa o se corresponde mejor con la intención del lenguaje natural que con la estructura de nombres | tool_search_tool_bm25_20251119 |
| Es lo suficientemente pequeña como para que todos los esquemas quepan cómodamente en el contexto | Ninguna - omite la Herramienta de Búsqueda de Herramientas por completo y carga todas las herramientas normalmente |
No. Al menos una herramienta debe permanecer sin posponer, o la solicitud devuelve 400: Todas las herramientas tienen defer_loading establecido. En la práctica, esto significa la propia herramienta de búsqueda más al menos otra herramienta.
No. tool_search_tool_regex y tool_search_tool_bm25 nunca deben tener defer_loading: true; Claude necesita la herramienta de búsqueda visible desde el principio para poder descubrir cualquier otra cosa.
Busca un bloque de contenido tool_search_tool_result en la respuesta. Este es un tipo de bloque distinto de tool_use y text; el código que solo comprueba estos dos lo pasará por alto.
No. Los esquemas de herramientas descubiertos se añaden a la solicitud en lugar de reemplazar el array tools existente, por lo que el prefijo almacenado en caché para tools y system se conserva durante la llamada de búsqueda.
No necesariamente. Mantén siempre cargadas las herramientas de uso frecuente con esquemas pequeños, de modo que las solicitudes comunes no necesiten un viaje de ida y vuelta de búsqueda. Reserva defer_loading para herramientas que se usan raramente o que forman parte de un catálogo grande donde el volumen del esquema es el problema real.
Declara la herramienta por su cadena type versionada (tool_search_tool_regex_20251119 o tool_search_tool_bm25_20251119) en el array tools como cualquier otra herramienta del lado del servidor. Consulta la documentación actual de la plataforma para conocer los requisitos de cabecera, ya que el estado beta puede cambiar entre las versiones del SDK.
Añade "defer_loading": True como una clave dentro del diccionario de la herramienta en la lista tools que pasas a client.messages.create(...). Se sitúa junto a name, description y input_schema en la misma definición de herramienta.
tool_search_tool_regex_20251119) compara los nombres y descripciones de las herramientas con un patrón; bueno cuando tus herramientas siguen una convención de nomenclatura predecible.tool_search_tool_bm25_20251119) clasifica las herramientas por relevancia de palabras clave; mejor cuando los nombres de las herramientas no codifican claramente la intención y Claude necesita hacer coincidir el lenguaje natural con las descripciones.Sí, y este es el patrón de uso esperado. Mantén un pequeño conjunto de herramientas de uso frecuente siempre cargadas y pospón el resto de un catálogo grande.
claude-sonnet-5 es el modelo Claude predeterminado actual y funciona bien para cargas de trabajo con mucho uso de herramientas. Cualquier modelo actual que admita el uso de herramientas puede utilizar la Herramienta de Búsqueda de Herramientas.
Generalmente no. Si todos tus esquemas de herramientas ya caben cómodamente en el contexto sin una sobrecarga de tokens notable, omite la Herramienta de Búsqueda de Herramientas por completo; el viaje de ida y vuelta de búsqueda añade una latencia que no necesitas pagar.
Versiones de Stack: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5 - y el SDK oficial de Python de
anthropic(última versión 0.x). Los nombres de los modelos, las versiones del SDK y los precios cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.
Revisado por Chris St. John·Última actualización: 16 jul 2026