MessagesFerramentas
Solução de problemas de uso de ferramentas
Corrija os erros mais comuns de uso de ferramentas com tabelas de diagnóstico de sintoma para correção.
Tabelas de sintoma para correção para os erros mais comuns de "tool use" (uso de ferramentas). Cada correção faz referência cruzada à página responsável pelo recurso.
Claude chama a ferramenta errada
| Sintoma | Causa provável | Correção |
|---|---|---|
| Claude chama a ferramenta A quando você queria a ferramenta B | Ambiguidade na descrição | Refine as descrições. Diferencie as ferramentas por QUANDO usá-las, não apenas pelo QUE elas fazem. Consulte Definir ferramentas. |
| Claude nunca chama sua ferramenta | Colisão de nomes de ferramentas ou schema excessivamente genérico | Verifique se há nomes duplicados na sua lista de ferramentas. Adicione input_examples para tornar o uso pretendido concreto. |
| Claude chama com tipos de parâmetro errados | Modelo adivinhando diante de um schema ambíguo | Adicione strict: true (se seu schema estiver no subconjunto suportado) ou adicione input_examples. |
Claude inventa parâmetros de ferramentas
| Sintoma | Causa provável | Correção |
|---|---|---|
| Parâmetro que não existe no seu schema | Geração excessiva do modelo sem o modo estrito | Adicione strict: true se seu schema estiver no subconjunto suportado. |
| Valores de parâmetro fora do seu enum | Modo estrito ausente ou enum grande demais | Reduza o enum ou adicione input_examples mostrando escolhas válidas. |
Chamadas de ferramentas paralelas não funcionam
| Sintoma | Causa provável | Correção |
|---|---|---|
| Claude chama ferramentas sequencialmente quando o paralelo seria melhor | Formatação do histórico de mensagens | Envie vários blocos tool_result em UMA mensagem do usuário, não um por turno. Consulte Uso de ferramentas em paralelo. |
disable_parallel_tool_use parece ser ignorado | Definido tarde demais na conversa | Deve ser definido na requisição que retorna tool_use. Defini-lo em uma requisição posterior não tem efeito sobre chamadas de ferramentas anteriores. |
O cache continua sendo invalidado
| Sintoma | Causa provável | Correção |
|---|---|---|
| Toda requisição é um cache miss | tool_choice, a configuração de pensamento ou output_config.effort variando entre requisições | Mantenha tool_choice estável ou coloque o ponto de interrupção cache_control antes do ponto de variação; mantenha a configuração de pensamento e o nível de esforço constantes durante toda a vida de uma conversa em cache. Consulte Uso de ferramentas com cache de prompt e Pensamento e cache de prompt. |
| Adicionar uma ferramenta no meio da conversa quebra o cache | Ferramenta inserida no início do array de ferramentas | Use defer_loading: true com a busca de ferramentas para anexar a ferramenta inline em vez de modificar o início do array. |
Erros no momento da requisição
| Erro | Causa | Correção |
|---|---|---|
tool_use ids were found without tool_result blocks immediately after | tool_result ausente para alguns ids de tool_use, ou tool_result não é o primeiro bloco de conteúdo na mensagem do usuário | Retorne um tool_result para cada bloco tool_use na resposta do assistente. Coloque os blocos tool_result antes de qualquer texto. Consulte Lidar com chamadas de ferramentas e Uso de ferramentas em paralelo. |
was found without a corresponding <name>_tool_result block | O turno anterior do assistente tem um bloco server_tool_use sem bloco de resultado (na maioria das vezes, Claude o chamou junto com uma ferramenta do cliente), e ou sua próxima mensagem do usuário encerrou esse turno (por exemplo, com texto após os blocos tool_result) ou a requisição de retomada não define mais essa ferramenta de servidor (a mensagem então termina com but no <name> tool was provided) | Envie uma mensagem do usuário contendo apenas os blocos tool_result para os ids de tool_use do cliente e mantenha o mesmo array tools. Consulte Motivos de parada e fallback. |
Unsupported regex feature in pattern field: ... | Um pattern no input_schema de uma ferramenta estrita usa um recurso de regex que o modo estrito não consegue compilar, como uma backreference, um lookaround, um limite de palavra ou um intervalo {n,m} grande | Simplifique o padrão. Padrões ancorados com quantificadores básicos, classes de caracteres e grupos são suportados; consulte Limitações do JSON Schema. |
All tools have defer_loading: true | Nenhuma ferramenta visível para o modelo | Pelo menos uma ferramenta deve ser carregada imediatamente. A própria ferramenta de busca de ferramentas nunca deve ter defer_loading: true. |
Erro: blocos de pensamento não podem ser modificados
Se uma requisição falhar com um 400 invalid_request_error cuja mensagem contém `thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified ao continuar uma conversa após uma chamada de ferramenta, sua aplicação está alterando os blocos de pensamento do assistente antes de enviá-los de volta. Envie a mensagem inteira do assistente de volta sem alterações e, em seguida, anexe seu tool_result.
Consulte Blocos de pensamento não podem ser modificados para ver o erro completo e as etapas de correção.
Claude sinaliza resultados de ferramentas como injeção de prompt
| Sintoma | Causa provável | Correção |
|---|---|---|
| Claude se recusa a agir com base em um resultado de ferramenta, ou pede ao usuário que confirme instruções que vieram dele | Suas próprias instruções estão sendo entregues dentro do conteúdo do tool_result | Claude é treinado para tratar instruções dentro de resultados de ferramentas como conteúdo de terceiros potencialmente não confiável. Mova suas instruções para fora do resultado da ferramenta: envie-as em um turno user após o bloco tool_result ou, em modelos suportados, em uma mensagem do sistema no meio da conversa. Mantenha no resultado da ferramenta apenas os dados. Consulte Mitigar jailbreaks e injeções de prompt. |
Diferenças de escape em JSON (Opus 4.6+)
| Sintoma | Causa | Correção |
|---|---|---|
| A comparação de strings nas entradas de ferramentas falha com modelos mais novos | O escape de Unicode e de barras difere entre versões de modelo | Faça o parse com json.loads() ou JSON.parse(). Nunca faça correspondência de strings brutas na entrada serializada. |
Próximos passos
Escreva schemas e descrições que direcionem Claude para a ferramenta certa.
Execute ferramentas e retorne resultados no formato de mensagem exigido.
Diretório completo de ferramentas fornecidas pela Anthropic e suas strings de versão.
Was this page helpful?