//
Busque em todas as páginas da documentação
tool_choice é um parâmetro de nível superior em messages.create() que controla se o Claude usará uma ferramenta e, em caso afirmativo, qual. Esta página é uma referência rápida para os quatro modos e o modificador que se aplica a todos eles.
{"type": "tool", ...} por hábito - auto é o ideal para a maioria das vezes em conversas.disable_parallel_tool_use apenas quando seu código downstream não puder lidar com mais de uma chamada de ferramenta por vez.tool_choice entre requisições é seguro para o cache - veja a nota sobre cache abaixo antes de evitá-lo pelo motivo errado.| Modo | Valor | Comportamento do Claude | Use quando |
|---|---|---|---|
| Auto | {"type": "auto"} | O Claude decide se usará uma ferramenta e qual, com base na conversa. | Agentes conversacionais de propósito geral onde o uso de ferramentas é opcional na maioria das vezes. |
| Any | {"type": "any"} | O Claude deve chamar uma das ferramentas fornecidas, mas você não escolhe qual. | Você sabe que a vez deve terminar em alguma ação, mas qualquer uma das várias ferramentas satisfaria isso. |
| Tool | {"type": "tool", "name": "..."} | O Claude deve chamar a ferramenta exata que você nomear. | Forçar extração estruturada em um esquema, ou forçar uma ação específica, independentemente do que o Claude escolheria de outra forma. |
| None | {"type": "none"} | O Claude não deve chamar nenhuma ferramenta, mesmo que tools ainda esteja na requisição. | Suprimir temporariamente o uso de ferramentas (por exemplo, uma vez para fazer uma pergunta de esclarecimento) sem remover as definições de ferramentas da requisição. |
Nota: auto é o padrão. Omitir tool_choice inteiramente quando tools está presente se comporta da mesma forma que {"type": "auto"}.
{"tool_choice": {"type": "auto"}}{"tool_choice": {"type": "any"}}{"tool_choice": {"type": "tool", "name": "get_weather"}}{"tool_choice": {"type": "none"}}Passe tool_choice como um argumento nomeado para client.messages.create(...), com o mesmo formato do JSON acima:
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"},
Forçando uma ferramenta específica pelo nome:
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":
Todos os quatro modos aceitam um sinalizador opcional "disable_parallel_tool_use": true ao lado de type. Ele limita o Claude a, no máximo, uma chamada de ferramenta por resposta, mesmo em turnos onde ele chamaria várias ferramentas em paralelo. O padrão é false - chamadas de ferramentas paralelas são permitidas.
tool_choice={"type": "auto", "disable_parallel_tool_use": True}Use-o quando seu código de execução de ferramentas assume exatamente um bloco tool_use por turno e você não quer adicionar lógica de loop para lidar com vários.
description de cada ferramenta e decide por si mesmo.output_config.format com saídas estruturadas é frequentemente uma opção melhor agora. tool_choice forçado ainda é comum quando você precisa forçar uma ação, não apenas um formato - como exigir uma chamada de função específica em um ambiente de teste ou um passo de fluxo guiado.tools da requisição. Remover tools inteiramente para parar o uso de ferramentas invalidaria o tier de cache de ferramentas; definir tool_choice para none mantém as mesmas definições de ferramentas na requisição para que o cache permaneça intacto.Alterar tool_choice entre requisições não invalida os tiers de cache de ferramentas ou de prompt do sistema. Apenas uma troca de modelo ou uma alteração real nas próprias definições de ferramentas quebra esses tiers de cache. Isso significa que alternar tool_choice por requisição - digamos, auto na maioria das vezes e none em um turno de pergunta de esclarecimento - é seguro para o cache, e você não precisa manter tool_choice constante para preservar sua taxa de acertos de cache.
O mesmo que {"type": "auto"} - o Claude decide por si mesmo se chama uma ferramenta, desde que tools esteja presente na requisição.
Não. Ele apenas garante que o Claude chame uma das ferramentas que você forneceu. Se você precisar de uma ferramenta específica, use {"type": "tool", "name": "..."} em vez disso.
Apenas para a requisição em que está definido. tool_choice é avaliado por chamada a messages.create(), então você definiria {"type": "none"} em cada requisição subsequente onde deseja que o uso de ferramentas seja suprimido.
Remover tools inteiramente muda a requisição e invalida o tier de cache de ferramentas. Manter tools no lugar e definir tool_choice como {"type": "none"} suprime o uso de ferramentas para aquele turno, mantendo as definições de ferramentas em cache intactas.
Ainda é comum e funciona bem, mas para casos de uso de extração de dados pura, output_config.format com saídas estruturadas é frequentemente uma opção melhor agora. tool_choice forçado continua sendo a chamada correta quando você precisa forçar uma ação, não apenas moldar uma resposta.
A requisição é inválida - o nome deve corresponder a uma das ferramentas que você passou em tools. Mantenha a lista de ferramentas e o nome forçado em sincronia, especialmente se as listas de ferramentas forem construídas dinamicamente.
Não. Apenas trocas de modelo e alterações reais nas definições de ferramentas invalidam os tiers de cache de ferramentas e de prompt do sistema. tool_choice em si não faz parte do que é cacheado, então alterná-lo por requisição é seguro.
Não, ele apenas limita o Claude a, no máximo, uma chamada de ferramenta naquela resposta. Ele funciona em conjunto com qualquer um dos quatro valores de type - auto, any, tool ou none - ele apenas muda quantos chamados retornam, não a lógica de seleção.
false. O Claude pode retornar múltiplos blocos tool_use em um turno, a menos que você explicitamente defina disable_parallel_tool_use como true.
Quando você precisa de uma garantia de que o turno resulta em uma chamada de ferramenta - auto permite que o Claude decida não chamar nada, o que é um problema se seu fluxo assume que uma ação sempre acontece.
Funcionalmente semelhante para aquele turno - nenhuma ferramenta é chamada em nenhum dos casos - mas eles diferem para o cache. Omitir tools descarta as definições de ferramentas em cache; {"type": "none"} mantém tools na requisição para que o tier de cache sobreviva.
Sim - forçar uma ferramenta controla se/qual ferramenta é chamada, não se o Claude também pode produzir conteúdo de texto ao lado do bloco tool_use, dependendo do comportamento do modelo para aquele turno.
tool_choice em contextotool_use quando chamadas paralelas não são desabilitadasautoVersões da Stack: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão), e Claude Haiku 4.5 - e o SDK oficial
anthropicpara Python (última versão 0.x). Nomes de modelos, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.