Referência de Opções de Tool Choice
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.
Como Usar Esta Referência
- Procure o modo com base no que você precisa que o Claude faça nesta vez - decida livremente, use algo, use uma coisa específica ou não use nada.
- Copie o snippet Python correspondente e substitua os nomes das suas ferramentas.
- Verifique a coluna "Use quando" antes de pegar
{"type": "tool", ...}por hábito -autoé o ideal para a maioria das vezes em conversas. - Adicione
disable_parallel_tool_useapenas quando seu código downstream não puder lidar com mais de uma chamada de ferramenta por vez. - Trocar
tool_choiceentre requisições é seguro para o cache - veja a nota sobre cache abaixo antes de evitá-lo pelo motivo errado.
Os Quatro Modos
| 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"}.
Formatos de Requisição
{"tool_choice": {"type": "auto"}}{"tool_choice": {"type": "any"}}{"tool_choice": {"type": "tool", "name": "get_weather"}}{"tool_choice": {"type": "none"}}Uso em Python
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"},
messages=[{"role": "user", "content": "Quanto é 12 vezes 5?"}],
)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": "user", "content": "Qual é a previsão do tempo em São Paulo?"}],
)disable_parallel_tool_use
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.
Escolhendo um Modo
- auto - o padrão para agentes e interfaces de chat. O Claude pondera a conversa contra a
descriptionde cada ferramenta e decide por si mesmo. - any - use quando o turno deve resultar em alguma ação, mas a escolha da ação é genuinamente do Claude - por exemplo, um turno de roteador onde várias ferramentas podem ser passos válidos.
- tool - força uma ferramenta nomeada. Este é um padrão mais antigo para extração de dados estruturados; para extração de dados pura,
output_config.formatcom saídas estruturadas é frequentemente uma opção melhor agora.tool_choiceforç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. - none - suprime o uso de ferramentas para um turno sem descartar
toolsda requisição. Removertoolsinteiramente para parar o uso de ferramentas invalidaria o tier de cache de ferramentas; definirtool_choiceparanonemantém as mesmas definições de ferramentas na requisição para que o cache permaneça intacto.
Nota sobre Cache
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.
FAQs
O que o Claude faz se eu omitir tool_choice inteiramente?
O mesmo que {"type": "auto"} - o Claude decide por si mesmo se chama uma ferramenta, desde que tools esteja presente na requisição.
O `{"type": "any"}` me permite controlar qual ferramenta o Claude escolhe?
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.
Posso usar tool_choice: none para impedir que o Claude use ferramentas pelo resto da conversa?
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.
Por que manter `tools` na requisição quando defino tool_choice como none?
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.
Forçar uma ferramenta com {"type": "tool", ...} ainda é a maneira correta de fazer extração de dados estruturados?
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.
O que acontece se a ferramenta nomeada em {"type": "tool", "name": "..."} não estiver na minha lista de ferramentas?
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.
Trocar tool_choice entre requisições prejudica minha taxa de acertos do cache de prompt?
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.
disable_parallel_tool_use muda qual ferramenta o Claude escolhe?
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.
Qual é o padrão para disable_parallel_tool_use se eu não o definir?
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 eu usaria `any` em vez de apenas deixar tool_choice em auto?
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.
O `none` é o mesmo que não passar `tools`?
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.
Posso forçar uma chamada de ferramenta e ainda deixar o Claude adicionar texto explicativo?
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.
Relacionados
- Noções Básicas de Uso de Ferramentas - o ciclo completo incluindo um exemplo de
tool_choiceem contexto - Executando Chamadas de Ferramentas Paralelas em um Único Turno - lidando com múltiplos blocos
tool_usequando chamadas paralelas não são desabilitadas - Definindo Esquemas de Ferramentas com name, description e input_schema - o que o Claude lê para decidir qual ferramenta se encaixa, sob
auto - Melhores Práticas - orientações mais amplas para uso de ferramentas e chamadas de função nesta stack
Versõ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.