Como Claude Decide Quando Chamar uma Ferramenta
Quando você fornece ao Claude um conjunto de ferramentas, você não está escrevendo um programa que chama uma função.
Você está entregando ao Claude um menu de opções e uma pequena quantidade de texto descrevendo cada uma, e pedindo para ele ler a conversa e decidir, em contexto, se usar uma dessas opções faz sentido.
Essa decisão é inteiramente inferida do que você escreveu na description e no input_schema de cada ferramenta, mais a configuração tool_choice na requisição.
Entender o que o Claude está realmente ponderando quando toma essa decisão é a diferença entre uma ferramenta que é usada exatamente quando deveria e uma que é ignorada, mal utilizada ou invocada no momento errado.
Resumo
- Ideia Central: Claude decide se e qual ferramenta chamar lendo o
name,descriptioneinput_schemade cada ferramenta em relação à conversa atual, não por algum mecanismo de regras oculto. - Por Que Importa: Uma ferramenta com uma descrição vaga ou puramente funcional é invisível para este processo de decisão exatamente nas situações em que deveria ser acionada, levando a chamadas perdidas ou incorretas.
- Conceitos Chave: definição de ferramenta, description, input_schema, bloco de conteúdo tool_use, tool_choice, chamadas paralelas de ferramentas.
- Quando Usar: Sempre que estiver escrevendo ou depurando uma definição de ferramenta, decidindo quantas ferramentas expor em uma única requisição, ou descobrindo por que o Claude chamou a ferramenta errada (ou nenhuma).
- Limitações / Trade-offs: Esta é uma decisão baseada em texto em linguagem natural, não uma correspondência determinística; descrições ambíguas ou um conjunto de ferramentas sobrecarregado ainda podem produzir a decisão errada, mesmo com um schema bem formado.
- Tópicos Relacionados: design de schema de ferramentas, opções de
tool_choice, execução paralela de ferramentas, tratamento de turnos detool_result.
Fundamentos
Uma definição de ferramenta que você envia ao Claude tem três partes: um name, uma description e um input_schema escrito como JSON Schema.
O Claude nunca executa sua ferramenta; ele apenas produz um bloco de conteúdo tool_use, uma parte da saída nomeando a ferramenta e a entrada que ele acha que a ferramenta precisa, juntamente com um stop_reason de "tool_use".
Seu próprio código é responsável por ler esse bloco, executar a função correspondente e enviar o resultado como um tool_result no próximo turno.
Como o Claude só vê as definições que você fornece, sua decisão de chamar uma ferramenta é realmente uma tarefa de compreensão de texto: ele lê a conversa, lê cada description e estima qual ferramenta (se alguma) a requisição à sua frente solicita.
Uma analogia útil é um novo funcionário recebendo um fichário de instruções "quando escalar" em vez de um livro de regras que dispara automaticamente; o funcionário ainda precisa ler cada entrada e julgar se a situação à sua frente corresponde.
Quanto mais claras e situacionais forem cada entrada do fichário, mais confiavelmente o funcionário escolherá a correta, e o mesmo vale para o Claude lendo as descrições das ferramentas.
Mecânicas e Interações
O Claude pondera três coisas juntas ao decidir se emite um bloco tool_use: o texto da description, a forma do input_schema e o valor tool_choice na requisição.
A description carrega o maior peso na decisão de "devo chamar isso?".
Uma descrição que apenas afirma o que uma ferramenta faz ("Obtém o preço atual da ação para um ticker") informa ao Claude a função da ferramenta, mas não quando ela se aplica, então o Claude tem que inferir a condição de gatilho por conta própria, que é exatamente onde ocorrem falhas.
Uma descrição que afirma explicitamente a condição de gatilho ("Chame isso quando o usuário perguntar sobre o preço atual ou recente de uma ação. Não use para dados de preço históricos mais antigos que 30 dias.") dá ao Claude uma correspondência direta com a solicitação real do usuário, o que melhora mensuravelmente se o Claude a chama no momento certo.
tools = [{
"name": "get_stock_price",
"description": (
"Chame isso quando o usuário perguntar sobre o preço atual ou recente "
"de uma ação negociada publicamente. Não use para dados de preço históricos "
"mais antigos que 30 dias."
),
"input_schema": {
"type": "object",
"properties": {
"ticker": {"type": "string", "description": "Símbolo do ticker da ação, ex: AAPL"}
},
"required": ["ticker"]
}
}]Uma vez que o Claude decidiu que uma ferramenta é relevante, o input_schema molda a segunda metade da decisão: quais argumentos gerar.
Um schema ambíguo, um parâmetro sem description, um type excessivamente flexível, uma lista required ausente, força o Claude a adivinhar a intenção da mesma forma que uma assinatura de função vaga força um desenvolvedor humano a adivinhar, e essa suposição pode produzir uma chamada com a ferramenta certa, mas com entrada incorreta ou incompleta.
O tool_choice fica fora de ambos e restringe a decisão no nível da requisição em vez do nível do texto: auto deixa o julgamento de "devo chamar uma ferramenta?" inteiramente para o Claude, any força alguma ferramenta a ser chamada, tool fixa a chamada em uma ferramenta nomeada específica, e none proíbe chamadas de ferramentas, independentemente de quão bem qualquer descrição corresponda.
Qualquer um desses pode ser emparelhado com "disable_parallel_tool_use": true, que desativa a capacidade do Claude de solicitar mais de uma ferramenta no mesmo turno, uma capacidade que está disponível de outra forma sob auto e any quando a requisição realmente exige várias consultas independentes.
Considerações Avançadas e Aplicações
O processo de decisão degrada de maneiras específicas e previsíveis à medida que um conjunto de ferramentas cresce ou se torna desleixado, e cada modo de falha remonta a uma das três entradas acima.
Descrições sobrepostas, duas ferramentas que ambas se aplicam plausivelmente ao mesmo tipo de solicitação, dividem a confiança do Claude e aumentam a probabilidade de escolher a menos apropriada, ou de se proteger chamando nenhuma.
Nomes de ferramentas vagos complicam isso: um nome como handle_request não dá ao Claude nenhum sinal independente além da descrição, então a descrição tem que fazer todo o trabalho sozinha.
Muitas ferramentas em uma única requisição têm um efeito semelhante, mesmo quando cada descrição individual é bem escrita, porque o Claude agora está comparando um conjunto maior de candidatos plausíveis com o mesmo sinal conversacional, razão pela qual manter o conjunto de ferramentas ativo focado (e, para bibliotecas de ferramentas muito grandes, carregar apenas ferramentas relevantes sob demanda) melhora a precisão independentemente de como qualquer ferramenta única é descrita.
| Abordagem | Força | Fraqueza | Melhor Ajuste |
|---|---|---|---|
| Descrição funcional ("Obtém X") | Rápida de escrever | Deixa a condição de gatilho para inferência | Conjuntos de ferramentas pequenos e sem ambiguidades |
| Descrição baseada em gatilho ("Chame isso quando...") | Afirma explicitamente a condição de chamada | Requer mais reflexão inicial por ferramenta | Qualquer conjunto de ferramentas de produção, especialmente domínios sobrepostos |
tool_choice: "auto" | Permite que o Claude raciocine sobre relevância por turno | Depende inteiramente da qualidade da descrição | Assistentes de propósito geral |
tool_choice: "tool" | Remove a ambiguidade para um próximo passo conhecido | Nenhuma flexibilidade se a suposição estiver errada | Fluxos de trabalho guiados ou de caminho único |
As mesmas mecânicas explicam por que as chamadas paralelas de ferramentas funcionam: quando tool_choice permite e a conversa genuinamente contém duas necessidades independentes, por exemplo, uma solicitação que pede tanto o clima quanto uma conversão de moeda, o Claude pode emitir dois blocos tool_use em um turno porque a descrição de cada ferramenta correspondeu independentemente a uma parte distinta da solicitação.
Isso não é o Claude "agrupando" chamadas como uma otimização; é o mesmo julgamento de relevância por ferramenta aplicado duas vezes dentro de uma única resposta.
Equívocos Comuns
- "Claude executa a ferramenta." Claude apenas produz um bloco
tool_usedescrevendo o que ele quer chamar; seu próprio código de aplicação realiza a execução real e retorna umtool_result. - "O nome de uma ferramenta não importa muito." Um nome claro e específico dá ao Claude um sinal extra além da descrição, especialmente quando várias ferramentas vivem na mesma conversa.
- "Mais ferramentas sempre significam mais capacidade." Além de um certo ponto, adicionar ferramentas com propósitos sobrepostos reduz a precisão ao dar ao Claude mais candidatos plausíveis, mas errados, para ponderar.
- "
tool_choice: autosignifica que Claude sempre encontrará um motivo para usar uma ferramenta."autosignifica que Claude decide caso a caso; se nenhuma condição de gatilho de descrição corresponder, o Claude responderá legitimamente sem chamar nada. - "O schema afeta apenas a aparência dos argumentos, não se o Claude chama a ferramenta." Um
input_schemaconfuso pode, por si só, diminuir a confiança do Claude de que ele entende bem a ferramenta para invocá-la corretamente, mesmo quando adescriptionsozinha é clara.
FAQs
Que informações o Claude realmente usa para decidir se chama uma ferramenta?
- O
name,descriptioneinput_schemade todas as ferramentas incluídas na requisição. - A conversa atual, incluindo turnos anteriores.
- A configuração
tool_choice, que pode forçar, proibir ou deixar a decisão em aberto.
O Claude executa a ferramenta ele mesmo depois de decidir chamá-la?
Não. O Claude apenas emite um bloco de conteúdo tool_use nomeando a ferramenta e sua entrada gerada, com stop_reason: "tool_use". Seu código de aplicação executa a ferramenta e retorna o resultado como um tool_result.
Por que uma descrição que afirma a funcionalidade às vezes falha em acionar uma chamada?
Porque ela diz ao Claude o que a ferramenta faz, mas não quando ela se aplica, deixando o Claude inferir a condição de gatilho da conversa por conta própria, o que é uma correspondência menos confiável do que uma descrição que afirma a condição diretamente.
O que torna uma descrição mais confiável para acionar a chamada correta?
Afirmar a condição específica sob a qual a ferramenta deve ser usada, por exemplo, "Chame isso quando o usuário perguntar sobre preços atuais ou eventos recentes", em vez de apenas descrever o que a ferramenta retorna.
Uma descrição bem escrita ainda pode falhar se o input_schema for pouco claro?
Sim. Uma descrição clara seleciona a ferramenta certa, mas um input_schema ambíguo, descrições de parâmetros ausentes ou uma lista required flexível, ainda podem fazer com que o Claude gere uma entrada incompleta ou incorreta para essa ferramenta.
O que `tool_choice: "auto"` realmente controla?
Deixa a decisão de "devo chamar uma ferramenta?" inteiramente ao julgamento do Claude com base nas descrições e na conversa, em oposição a any (deve usar alguma ferramenta), tool (deve usar uma ferramenta nomeada) ou none (não deve usar nenhuma ferramenta).
Quando eu usaria `tool_choice: "any"` em vez de `"auto"`?
Quando você quer garantir que alguma ferramenta seja chamada neste turno (você tem certeza de que uma resposta de ferramenta é necessária), mas ainda está disposto a deixar o Claude escolher qual, em vez de fixá-la em uma única ferramenta nomeada.
O Claude pode chamar mais de uma ferramenta em um único turno?
Sim, isso é chamada paralela de ferramentas. Quando tool_choice permite e a conversa contém necessidades genuinamente independentes, o Claude pode emitir múltiplos blocos tool_use em uma única resposta.
Como evito chamadas paralelas de ferramentas se quero que apenas uma ferramenta seja usada por turno?
Adicione "disable_parallel_tool_use": true a qualquer valor tool_choice que você esteja usando; funciona com auto, any e tool.
Por que adicionar mais ferramentas às vezes piora a capacidade do Claude de escolher a correta?
Cada ferramenta adicional é outro candidato plausível que o Claude tem que ponderar contra o mesmo sinal conversacional; descrições sobrepostas ou vagamente diferenciadas aumentam a probabilidade de uma escolha errada ou de uma chamada perdida à medida que o conjunto cresce.
O nome da ferramenta importa se a descrição já está clara?
Ainda ajuda. Um nome específico é um sinal extra ao lado da descrição, e se torna mais importante à medida que mais ferramentas com propósitos semelhantes aparecem na mesma requisição.
Se o Claude não chama nenhuma ferramenta, isso sempre significa que algo está quebrado?
Não necessariamente. Sob tool_choice: "auto", o Claude legitimamente pula o uso de ferramentas quando nenhuma condição de gatilho de descrição corresponde à conversa; esse é o comportamento pretendido, não uma falha.
A decisão de seleção de ferramentas do Claude é determinística dados os mesmos inputs?
É um julgamento baseado em texto em linguagem natural em vez de uma correspondência de regras fixa, então é melhor tratá-lo como uma inferência confiável, mas não garantida; descrições bem escritas e sem sobreposição a tornam confiável na prática.
Relacionados
- Noções Básicas de Uso de Ferramentas - defina uma ferramenta e lide com seu ciclo de
tool_useetool_result. - Definindo Schemas de Ferramentas com name, description e input_schema - um olhar mais atento sobre a escrita da metade do schema desta decisão.
- Referência de Opções de Escolha de Ferramentas - o comportamento completo de
auto,any,toolenone. - Melhores Práticas - padrões para manter conjuntos de ferramentas focados e descrições sem ambiguidades.
Versões da Stack: Escrito contra a linha de modelos Claude atual a partir de ~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.