¿Cómo decide Claude cuándo llamar a una herramienta?
Cuando le das a Claude un conjunto de herramientas, no estás escribiendo un programa que se envía a una función.
Le estás entregando a Claude un menú de opciones y una pequeña cantidad de texto que describe cada una, y le pides que lea la conversación y decida, en contexto, si usar una de esas opciones tiene sentido.
Esa decisión se infiere completamente de lo que escribiste en la description y el input_schema de cada herramienta, además de la configuración tool_choice en la solicitud.
Comprender lo que Claude realmente está sopesando cuando toma esa decisión es la diferencia entre una herramienta que se usa exactamente cuando debería y una que se ignora, se usa incorrectamente o se invoca en el momento equivocado.
Resumen
- Idea central: Claude decide si llamar a una herramienta y cuál, leyendo el
name, ladescriptiony elinput_schemade cada herramienta en relación con la conversación actual, no por ningún motor de reglas oculto. - Por qué es importante: Una herramienta con una descripción vaga o puramente funcional es invisible para este proceso de decisión exactamente en las situaciones en las que debería activarse, lo que lleva a llamadas perdidas o incorrectas.
- Conceptos clave: definición de herramienta, descripción, input_schema, bloque de contenido tool_use, tool_choice, llamadas de herramientas paralelas.
- Cuándo usarlo: Siempre que estés escribiendo o depurando una definición de herramienta, decidiendo cuántas herramientas exponer en una solicitud, o averiguando por qué Claude llamó a la herramienta incorrecta (o a ninguna).
- Limitaciones / Compensaciones: Esta es una decisión basada en texto en lenguaje natural, no una coincidencia determinista; descripciones ambiguas o un conjunto de herramientas sobrecargado aún pueden producir la decisión incorrecta incluso con un esquema bien formado.
- Temas relacionados: diseño de esquemas de herramientas, opciones de tool_choice, ejecución de herramientas paralelas, manejo de turnos de tool_result.
Fundamentos
Una definición de herramienta que envías a Claude tiene tres partes: un name, una description y un input_schema escrito como JSON Schema.
Claude nunca ejecuta tu herramienta; solo produce un bloque de contenido tool_use, una pieza de salida que nombra la herramienta y la entrada que cree que esa herramienta necesita, junto con un stop_reason de "tool_use".
Tu propio código es responsable de leer ese bloque, ejecutar la función correspondiente y enviar el resultado como un tool_result en el siguiente turno.
Debido a que Claude solo ve las definiciones que proporcionas, su decisión de llamar a una herramienta es realmente una tarea de comprensión de texto: lee la conversación, lee cada description y estima qué herramienta (si la hay) requiere la solicitud que tiene delante.
Una analogía útil es la de un nuevo empleado al que se le entrega un manual de instrucciones sobre "cuándo escalar" en lugar de un libro de reglas que se activa automáticamente; el empleado aún tiene que leer cada entrada y juzgar si la situación que tiene delante coincide.
Cuanto más clara y situacional sea cada entrada del manual, más fiable será que el empleado elija la correcta, y lo mismo ocurre con Claude al leer las descripciones de las herramientas.
Mecánica e interacciones
Claude sopesa tres cosas juntas al decidir si emitir un bloque tool_use: el texto de la description, la forma del input_schema y el valor de tool_choice en la solicitud.
La description tiene el mayor peso en la decisión de si debo llamar a esto en absoluto.
Una descripción que solo indica lo que hace una herramienta ("Obtiene el precio actual de las acciones de un ticker") le dice a Claude la función de la herramienta, pero no cuándo se aplica, por lo que Claude tiene que inferir la condición de activación por sí mismo, que es exactamente donde ocurren los errores.
Una descripción que establece explícitamente la condición de activación ("Llama a esto cuando el usuario pregunte sobre el precio actual o reciente de una acción") le da a Claude una coincidencia directa con la solicitud real del usuario, lo que mejora notablemente si Claude la llama en el momento adecuado.
tools = [{
"name": "get_stock_price",
"description": (
"Llama a esto cuando el usuario pregunte sobre el precio actual o reciente "
"de una acción que cotiza en bolsa. No lo uses para datos históricos de precios "
"anteriores a 30 días."
),
"input_schema": {
"type": "object",
"properties": {
"ticker": {"type": "string", "description": "Símbolo de cotización de acciones, por ejemplo, AAPL"}
},
"required": ["ticker"]
}
}]Una vez que Claude ha decidido que una herramienta es relevante, input_schema da forma a la segunda mitad de la decisión: qué argumentos generar.
Un esquema ambiguo, un parámetro sin description, un type demasiado laxo, una lista required faltante, obliga a Claude a adivinar la intención de la misma manera que una firma de función vaga obliga a un desarrollador humano a adivinar, y esa suposición puede producir una llamada con la herramienta correcta pero la entrada incorrecta o incompleta.
tool_choice se encuentra fuera de ambos y restringe la decisión a nivel de solicitud en lugar de a nivel de texto: auto deja la decisión de si debo llamar a una herramienta completamente a Claude, any fuerza a que se llame a alguna herramienta, tool fija la llamada a una herramienta nombrada específica, y none prohíbe las llamadas a herramientas por completo, independientemente de lo bien que coincida cualquier descripción.
Cualquiera de estos puede combinarse con "disable_parallel_tool_use": true, lo que desactiva la capacidad de Claude para solicitar más de una herramienta en el mismo turno, una capacidad que de otro modo está disponible en auto y any cuando la solicitud realmente requiere múltiples búsquedas independientes.
Consideraciones y aplicaciones avanzadas
El proceso de decisión se degrada de maneras específicas y predecibles a medida que un conjunto de herramientas crece o se vuelve descuidado, y cada modo de falla se remonta a una de las tres entradas anteriores.
Descripciones superpuestas, dos herramientas que se aplican plausiblemente al mismo tipo de solicitud, dividen la confianza de Claude y aumentan las probabilidades de elegir la menos apropiada, o de cubrirse no llamando a ninguna.
Los nombres de herramientas vagos agravan esto: un nombre como handle_request no le da a Claude ninguna señal independiente más allá de la descripción, por lo que la descripción tiene que hacer todo el trabajo sola.
Demasiadas herramientas en una solicitud tienen un efecto similar, incluso cuando cada descripción individual está bien escrita, porque Claude ahora está comparando un conjunto más grande de candidatos plausibles con la misma señal conversacional, razón por la cual mantener el conjunto de herramientas activo enfocado (y, para bibliotecas de herramientas muy grandes, cargar solo las herramientas relevantes bajo demanda) mejora la precisión independientemente de cómo se describa una sola herramienta.
| Enfoque | Fortaleza | Debilidad | Mejor ajuste |
|---|---|---|---|
| Descripción funcional ("Obtiene X") | Rápido de escribir | Deja la condición de activación a la inferencia | Conjuntos de herramientas pequeños e inequívocos |
| Descripción basada en el disparador ("Llama a esto cuando...") | Establece explícitamente la condición de "debe llamar" | Requiere más reflexión inicial por herramienta | Cualquier conjunto de herramientas de producción, especialmente dominios superpuestos |
tool_choice: "auto" | Permite a Claude razonar sobre la relevancia por turno | Depende completamente de la calidad de la descripción | Asistentes de propósito general |
tool_choice: "tool" | Elimina la ambigüedad para un siguiente paso conocido | No hay flexibilidad si la suposición es incorrecta | Flujos de trabajo guiados o de un solo camino |
La misma mecánica explica por qué las llamadas a herramientas paralelas funcionan en absoluto: cuando tool_choice lo permite y la conversación contiene genuinamente dos necesidades independientes, por ejemplo, una solicitud que pide tanto el clima como una conversión de moneda, Claude puede emitir dos bloques tool_use en un turno porque la descripción de cada herramienta coincidió independientemente con una parte distinta de la solicitud.
Esto no es Claude "agrupando" llamadas como una optimización; es el mismo juicio de relevancia por herramienta aplicado dos veces dentro de una sola respuesta.
Conceptos erróneos comunes
- "Claude ejecuta la herramienta." Claude solo produce un bloque
tool_useque describe lo que quiere que se llame; el código de tu propia aplicación realiza la ejecución real y devuelve untool_result. - "El nombre de una herramienta no importa mucho." Un nombre claro y específico le da a Claude una señal adicional más allá de la descripción, especialmente cuando varias herramientas conviven en la misma conversación.
- "Más herramientas siempre significa más capacidad." A partir de cierto punto, agregar herramientas con propósitos superpuestos reduce la precisión al darle a Claude más candidatos plausibles pero incorrectos para sopesar.
- "
tool_choice: autosignifica que Claude siempre encontrará una razón para usar una herramienta."autosignifica que Claude decide caso por caso; si la condición de activación de ninguna descripción coincide con la conversación, Claude responderá legítimamente sin llamar a nada. - "El esquema solo afecta cómo se ven los argumentos, no si Claude llama a la herramienta." Un
input_schemaconfuso puede, por sí mismo, disminuir la confianza de Claude en que entiende la herramienta lo suficientemente bien como para invocarla correctamente, incluso cuando ladescriptionpor sí sola se lee claramente.
Preguntas frecuentes
¿Qué información utiliza Claude realmente para decidir si llamar a una herramienta?
- El
name, ladescriptiony elinput_schemade cada herramienta incluida en la solicitud. - La conversación actual, incluidos los turnos anteriores.
- La configuración
tool_choice, que puede forzar, prohibir o dejar abierta la decisión.
¿Claude ejecuta la herramienta misma una vez que decide llamarla?
No. Claude solo emite un bloque de contenido tool_use que nombra la herramienta y su entrada generada, con stop_reason: "tool_use". El código de tu aplicación ejecuta la herramienta y devuelve el resultado como un tool_result.
¿Por qué una descripción que establece la funcionalidad a veces no logra activar una llamada?
Porque le dice a Claude lo que hace la herramienta, pero no cuándo se aplica, dejando que Claude infiera la condición de activación de la conversación por sí mismo, lo cual es una coincidencia menos confiable que una descripción que establece la condición directamente.
¿Qué hace que una descripción sea más confiable para activar la llamada correcta?
Indicar la condición específica bajo la cual se debe usar la herramienta, por ejemplo, "Llama a esto cuando el usuario pregunte sobre precios actuales o eventos recientes", en lugar de solo describir lo que devuelve la herramienta.
¿Puede una descripción bien escrita fallar si el input_schema no está claro?
Sí. Una descripción clara permite seleccionar la herramienta correcta, pero un input_schema ambiguo, descripciones de parámetros faltantes o una lista required laxa, aún pueden hacer que Claude genere una entrada incompleta o incorrecta para esa herramienta.
¿Qué controla realmente tool_choice: "auto"?
Deja la decisión de si debe llamar a una herramienta completamente al juicio de Claude basándose en las descripciones y la conversación, a diferencia de any (debe usar alguna herramienta), tool (debe usar una herramienta nombrada) o none (no debe usar ninguna herramienta).
¿Cuándo usaría tool_choice: "any" en lugar de "auto"?
Cuando quieres garantizar que se llame a alguna herramienta en este turno (estás seguro de que se necesita una respuesta de herramienta) pero aún estás dispuesto a dejar que Claude elija cuál, en lugar de fijarla a una sola herramienta nombrada.
¿Puede Claude llamar a más de una herramienta en un solo turno?
Sí, esto se conoce como llamadas a herramientas paralelas. Cuando tool_choice lo permite y la conversación contiene necesidades genuinamente independientes, Claude puede emitir múltiples bloques tool_use en una sola respuesta.
¿Cómo evito las llamadas a herramientas paralelas si solo quiero que se use una herramienta por turno?
Agrega "disable_parallel_tool_use": true a cualquier valor de tool_choice que estés usando; funciona con auto, any y tool.
¿Por qué agregar más herramientas a veces hace que Claude sea peor para elegir la correcta?
Cada herramienta adicional es otro candidato plausible que Claude tiene que sopesar contra la misma señal conversacional; descripciones superpuestas o vagamente diferenciadas aumentan las probabilidades de una elección incorrecta o una llamada perdida a medida que el conjunto crece.
¿Importa el nombre de la herramienta si la descripción ya es clara?
Aún ayuda. Un nombre específico es una señal adicional junto con la descripción, y se vuelve más importante a medida que aparecen más herramientas con propósitos similares en la misma solicitud.
Si Claude no llama a ninguna herramienta, ¿siempre significa que algo está roto?
No necesariamente. Bajo tool_choice: "auto", Claude legítimamente omite el uso de herramientas cuando la condición de activación de ninguna descripción coincide con la conversación; ese es el comportamiento previsto, no un fallo.
¿Es determinista la decisión de selección de herramientas de Claude dadas las mismas entradas?
Es un juicio basado en texto en lenguaje natural en lugar de una coincidencia de reglas fijas, por lo que es mejor tratarlo como una inferencia confiable pero no garantizada; las descripciones bien escritas y no superpuestas lo hacen confiable en la práctica.
Relacionado
- Conceptos básicos de uso de herramientas - define una herramienta y maneja su ida y vuelta de tool_use y tool_result.
- Definición de esquemas de herramientas con name, description e input_schema - una mirada más cercana a la escritura de la mitad del esquema de esta decisión.
- Referencia de opciones de Tool Choice - el comportamiento completo de
auto,any,toolynone. - Mejores prácticas - patrones para mantener los conjuntos de herramientas enfocados y las descripciones inequívocas.
Versiones de la pila: Escrito para 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 las especificaciones actuales en platform.claude.com/docs antes de confiar en ellas.