Referencia de Opciones de Tool Choice
tool_choice es un parámetro de nivel superior en messages.create() que controla si Claude utiliza una herramienta y, en caso afirmativo, cuál. Esta página es una referencia rápida para los cuatro modos y el modificador que se aplica a todos ellos.
Cómo Usar Esta Referencia
- Busca el modo según lo que necesitas que Claude haga en este turno: decide libremente, usa algo, usa una cosa específica o no uses nada.
- Copia el fragmento de Python correspondiente y reemplaza los nombres de tus herramientas.
- Consulta la columna "Úsalo cuando" antes de recurrir a
{"type": "tool", ...}por costumbre:autoes adecuado para la mayoría de los turnos conversacionales. - Añade
disable_parallel_tool_usesolo cuando tu código posterior no pueda manejar más de una llamada a herramienta por turno. - Cambiar
tool_choiceentre solicitudes es seguro para el caché; consulta la nota sobre el caché a continuación antes de evitarlo por una razón incorrecta.
Los Cuatro Modos
| Modo | Valor | Comportamiento de Claude | Úsalo cuando |
|---|---|---|---|
| Auto | {"type": "auto"} | Claude decide si usar una herramienta y cuál, basándose en la conversación. | Agentes conversacionales de propósito general donde el uso de herramientas es opcional la mayoría de los turnos. |
| Any | {"type": "any"} | Claude debe llamar a una de las herramientas proporcionadas, pero tú no eliges cuál. | Sabes que el turno debe terminar con alguna acción, pero cualquiera de varias herramientas la satisfaría. |
| Tool | {"type": "tool", "name": "..."} | Claude debe llamar a la herramienta exacta que nombres. | Forzar la extracción estructurada en un esquema, o forzar una acción específica independientemente de lo que Claude elegiría de otro modo. |
| None | {"type": "none"} | Claude no debe llamar a ninguna herramienta, aunque tools todavía esté en la solicitud. | Suprimir temporalmente el uso de herramientas (por ejemplo, un turno de pregunta aclaratoria) sin eliminar las definiciones de herramientas de la solicitud. |
Nota: auto es el valor predeterminado. Omitir tool_choice por completo cuando tools está presente se comporta igual que {"type": "auto"}.
Formatos de Solicitud
{"tool_choice": {"type": "auto"}}{"tool_choice": {"type": "any"}}{"tool_choice": {"type": "tool", "name": "get_weather"}}{"tool_choice": {"type": "none"}}Uso en Python
Pasa tool_choice como un argumento de palabra clave a client.messages.create(...), con la misma forma que el JSON anterior:
from anthropic import Anthropic
client = Anthropic()
response = client.messages.create(
model="claude-sonnet-5",
max_tokens=1024,
tools=[weather_tool, calculate_tool],
tool_choice={"type": "any"},
messages=[{"role": "user", "content": "¿Cuánto es 12 por 5?"}],
)Forzar una herramienta específica por nombre:
response = client.messages.create(
model="claude-sonnet-5",
max_tokens=1024,
tools=[weather_tool, calculate_tool],
tool_choice={"type": "tool", "name": "get_weather"},
messages=[{"role": "user", "content": "¿Qué tiempo hace en Austin, TX?"}],
)disable_parallel_tool_use
Los cuatro modos aceptan un indicador opcional "disable_parallel_tool_use": true junto con type. Limita a Claude a como máximo una llamada a herramienta por respuesta, incluso en turnos donde de otro modo llamaría a varias herramientas en paralelo. El valor predeterminado es false: se permiten llamadas a herramientas en paralelo.
tool_choice={"type": "auto", "disable_parallel_tool_use": True}Úsalo cuando tu código de ejecución de herramientas asuma exactamente un bloque tool_use por turno y no quieras añadir lógica de bucle para manejar varios.
Elección de un Modo
- auto - el predeterminado para agentes e interfaces de chat. Claude sopesa la conversación frente a la
descriptionde cada herramienta y decide por sí mismo. - any - úsalo cuando el turno deba resultar en alguna acción, pero la elección de la acción depende genuinamente de Claude; por ejemplo, un turno de enrutamiento donde varias herramientas podrían ser pasos siguientes válidos.
- tool - fuerza una herramienta con nombre específico. Este es un patrón más antiguo para la extracción de datos estructurados; para la extracción de datos pura,
output_config.formatcon salidas estructuradas es a menudo una mejor opción ahora. Forzartool_choicesigue siendo común cuando necesitas forzar una acción, no solo una forma, como requerir una llamada a función específica en un entorno de prueba o un paso de flujo guiado. - none - suprime el uso de herramientas para un turno sin eliminar
toolsde la solicitud. Eliminartoolspor completo para detener el uso de herramientas invalidaría el nivel de caché de herramientas; establecertool_choiceennonemantiene las mismas definiciones de herramientas en la solicitud para que el caché permanezca intacto.
Nota sobre el Caché
Cambiar tool_choice entre solicitudes no invalida los niveles de caché de herramientas o de prompt del sistema. Solo un cambio de modelo o un cambio real en las definiciones de herramientas rompe esos niveles de caché. Eso significa que alternar tool_choice por solicitud, por ejemplo, auto en la mayoría de los turnos y none en un turno de pregunta aclaratoria, es seguro para el caché, y no necesitas mantener tool_choice constante para preservar tu tasa de aciertos de caché.
Preguntas Frecuentes
¿Qué hace Claude si omito tool_choice por completo?
Igual que {"type": "auto"}: Claude decide por sí mismo si llama a una herramienta, siempre que tools esté presente en la solicitud.
¿`{"type": "any"}` me permite controlar qué herramienta elige Claude?
No. Solo garantiza que Claude llame a una de las herramientas que proporcionaste. Si necesitas una herramienta específica, usa {"type": "tool", "name": "..."} en su lugar.
¿Puedo usar tool_choice: none para evitar que Claude use herramientas durante el resto de la conversación?
Solo para la solicitud en la que está configurado. tool_choice se evalúa por cada llamada a messages.create(), por lo que deberías establecer {"type": "none"} en cada solicitud posterior donde quieras suprimir el uso de herramientas.
¿Por qué mantener `tools` en la solicitud cuando configuro tool_choice a none?
Eliminar tools por completo cambia la solicitud e invalida el nivel de caché de herramientas. Mantener tools en su lugar y establecer tool_choice en {"type": "none"} suprime el uso de herramientas para ese turno mientras mantiene intactas las definiciones de herramientas cacheadas.
¿Forzar una herramienta con {"type": "tool", ...} sigue siendo la forma correcta de hacer extracción de datos estructurados?
Sigue siendo común y funciona bien, pero para casos de uso de extracción de datos pura, output_config.format con salidas estructuradas es a menudo una mejor opción ahora. Forzar tool_choice sigue siendo la llamada correcta cuando necesitas forzar una acción, no solo dar forma a una respuesta.
¿Qué sucede si la herramienta nombrada en {"type": "tool", "name": "..."} no está en mi lista de herramientas?
La solicitud es inválida: el nombre debe coincidir con una de las herramientas que pasaste en tools. Mantén la lista de herramientas y el nombre forzado sincronizados, especialmente si las listas de herramientas se construyen dinámicamente.
¿Cambiar tool_choice entre solicitudes perjudica mi tasa de aciertos de caché del prompt?
No. Solo los cambios de modelo y los cambios reales en las definiciones de herramientas invalidan los niveles de caché de herramientas y del prompt del sistema. tool_choice en sí mismo no forma parte de lo que se cachea, por lo que alternarlo por solicitud es seguro.
¿`disable_parallel_tool_use` cambia qué herramienta elige Claude?
No, solo limita a Claude a como máximo una llamada a herramienta en esa respuesta. Funciona junto con cualquiera de los cuatro valores de type ( auto, any, tool, o none), solo cambia cuántas llamadas regresan, no la lógica de selección.
¿Cuál es el valor predeterminado para disable_parallel_tool_use si no lo configuro?
false. Claude puede devolver múltiples bloques tool_use en un turno a menos que establezcas explícitamente disable_parallel_tool_use en true.
¿Cuándo debería usar `any` en lugar de simplemente dejar tool_choice en auto?
Cuando necesites una garantía de que el turno resulta en una llamada a herramienta; auto permite a Claude decidir no llamar a nada, lo cual es un problema si tu flujo asume que siempre ocurre una acción.
¿Es `none` lo mismo que no pasar `tools` en absoluto?
Funcionalmente similar para ese turno (no se llama a ninguna herramienta en ambos casos), pero difieren en el caché. Omitir tools descarta las definiciones de herramientas cacheadas; {"type": "none"} mantiene tools en la solicitud para que el nivel de caché sobreviva.
¿Puedo forzar una llamada a herramienta y aún así permitir que Claude añada texto explicativo?
Sí, forzar una herramienta controla si/qué herramienta se llama, no si Claude también puede producir contenido de texto junto con el bloque tool_use, dependiendo del comportamiento del modelo para ese turno.
Relacionado
- Conceptos Básicos de Uso de Herramientas - el ciclo completo incluyendo un ejemplo de
tool_choiceen contexto - Ejecución de Llamadas Paralelas a Herramientas en un Solo Turno - manejo de múltiples bloques
tool_usecuando las llamadas paralelas no están deshabilitadas - Definición de Esquemas de Herramientas con name, description e input_schema - lo que Claude lee para decidir qué herramienta encaja, bajo
auto - Mejores Prácticas - guía más amplia para el uso de herramientas y llamadas a funciones en esta pila
Versiones de la Pila: Escrito contra la línea de modelos 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
anthropic(última versión 0.x). Los nombres de modelos, versiones de SDK y precios cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.