Hoja de referencia de parámetros defer_loading para la Herramienta de Búsqueda de Herramientas
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.
Cómo usar esta hoja de referencia
- Busca la cadena
typeexacta para la variante de búsqueda que deseas antes de escribir el arraytools; un error tipográfico en el sufijo de fecha es una fuente común de errores de "tipo de herramienta desconocido". - Revisa la tabla de restricciones antes de desplegar; los dos modos de fallo críticos (posponer la propia herramienta de búsqueda, posponer todas las herramientas) son silenciosos hasta el momento de la solicitud.
- Utiliza la tabla de decisión para elegir entre regex y BM25 en función de cómo esté organizada tu biblioteca de herramientas.
- Vuelve a consultar la nota sobre el ahorro de tokens cuando el número de tus herramientas supere la docena;
defer_loadingsolo compensa una vez que el volumen del esquema se convierte en el cuello de botella.
Variantes de la Herramienta de Búsqueda de Herramientas
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...
]Referencia de 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.
Restricciones y Puntos a tener en cuenta
| 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. |
Forma Mínima de la Solicitud
{
"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?"}],
)Elegir entre Regex y BM25
| 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 |
Preguntas Frecuentes
¿Qué ahorra realmente defer_loading?
- Mantiene el esquema JSON completo de una herramienta fuera de la carga útil de la solicitud inicial.
- Claude solo ve el nombre y la descripción de la herramienta (a través de la herramienta de búsqueda) hasta que decide que la herramienta es relevante.
- En bibliotecas de herramientas grandes, aquí es donde provienen los ahorros de ~85% de tokens: dejas de pagar por reenviar cientos de esquemas no utilizados en cada turno.
¿Puedo establecer defer_loading: true en todas las herramientas de mi array tools?
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.
¿Se puede posponer la propia herramienta de búsqueda?
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.
¿Cómo sé cuándo Claude ha utilizado la herramienta de búsqueda?
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.
¿Rompe la llamada a la herramienta de búsqueda el almacenamiento en caché del prompt?
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.
¿Debo posponer todas las herramientas que no estén en la ruta obvia de la solicitud actual?
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.
¿Necesito una cabecera beta para usar la Herramienta de Búsqueda de Herramientas?
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.
¿Cómo paso defer_loading en el SDK de Python?
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.
¿Cuál es la diferencia entre el descubrimiento por Regex y BM25?
- Regex (
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. - BM25 (
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.
¿Puedo mezclar herramientas pospuestas y siempre cargadas en la misma solicitud?
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.
¿Qué modelo debo usar en las solicitudes de ejemplo?
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.
¿Vale la pena usar defer_loading en una biblioteca de herramientas pequeña?
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.
Relacionado
- Escalar a Cientos de Herramientas con la Herramienta de Búsqueda de Herramientas - el tutorial completo que resume esta hoja de referencia.
- Conexión a Herramientas Remotas a través del Conector MCP - otra forma de escalar una gran superficie de herramientas.
- Referencia de Opciones de Elección de Herramientas - controlando cuándo y qué herramientas llama Claude.
- Mejores Prácticas - guía más amplia sobre el uso de herramientas en la que encaja esta hoja de referencia.
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.