Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Tabelas de sintoma para solução dos erros mais comuns de uso de ferramentas. Cada correção faz referência cruzada à página responsável pelo recurso.
| 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 esquema genérico demais | 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âmetros errados | O modelo está adivinhando com base em um esquema ambíguo | Adicione strict: true (se seu esquema estiver no subconjunto suportado) ou adicione input_examples. |
| Sintoma | Causa provável | Correção |
|---|---|---|
| Parâmetro que não existe no seu esquema | Geração excessiva do modelo sem modo estrito | Adicione strict: true se seu esquema estiver no subconjunto suportado. |
| Valores de parâmetros fora do seu enum | Modo estrito ausente ou enum grande demais | Reduza o enum ou adicione input_examples mostrando escolhas válidas. |
| Sintoma | Causa provável | Correção |
|---|---|---|
| Claude chama ferramentas sequencialmente quando paralelo seria melhor | Formatação do histórico de mensagens | Envie múltiplos blocos tool_result em UMA mensagem de usuário, não um por turno. Consulte Uso de ferramentas paralelas. |
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. |
| Sintoma | Causa provável | Correção |
|---|---|---|
| Toda requisição é um cache miss | tool_choice variando entre requisições | Mantenha tool_choice estável ou coloque o breakpoint de cache_control antes do ponto de variação. Consulte Uso de ferramentas com cache de prompt. |
| Adicionar uma ferramenta no meio da conversa quebra o cache | Ferramenta adicionada no início do array de ferramentas | Use defer_loading: true com busca de ferramentas para anexar a ferramenta inline em vez de modificar o início do array. |
| 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 paralelas. |
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 sua próxima mensagem de 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 de 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. |
Input schema is not compatible with strict mode: string patterns are not supported | Uso de pattern com strict: true | Remova o pattern ou remova strict: true. A palavra-chave pattern ainda não está no subconjunto suportado de 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. |
Se uma requisição falhar com um invalid_request_error 400 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 completa 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 os passos de correção.
| Sintoma | Causa provável | Correção |
|---|---|---|
| Claude se recusa a agir com base em um resultado de ferramenta, ou pede ao usuário para confirmar instruções que vieram dele | Suas próprias instruções estão sendo entregues dentro do conteúdo de 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 de user após o bloco tool_result, ou (no Claude Opus 4.8 e posteriores) em uma mensagem de sistema no meio da conversa. Mantenha o resultado da ferramenta apenas com os dados. Consulte Mitigar jailbreaks e injeções de prompt. |
| Sintoma | Causa | Correção |
|---|---|---|
| Comparação de strings em entradas de ferramentas falha com modelos mais recentes | O escape de Unicode e de barras difere entre versões de modelos | Faça o parse com json.loads() ou JSON.parse(). Nunca faça correspondência de string bruta em entrada serializada. |
Escreva esquemas 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 com esquema da Anthropic e suas strings de versão.
Was this page helpful?