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.
Encontre o sintoma ou erro que você vê e, em seguida, aplique a correção listada para ele.
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 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 | Schema ambíguo | Adicione strict: true (se o 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 | Defina-o 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 é uma falha de cache | 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 | Declare a ferramenta com defer_loading: true desde a primeira requisição e deixe a busca de ferramentas carregá-la inline, em vez de adicioná-la ao array posteriormente. |
Erros no momento da requisição
A coluna Erro mostra parte de cada mensagem, e ... representa um texto que varia.
| 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 ... block | A requisição de acompanhamento impede que uma ferramenta de servidor em espera seja executada | Consulte Uma chamada de ferramenta de servidor não tem bloco de resultado. |
Unsupported regex feature in pattern field: ... | O pattern de uma ferramenta estrita usa um recurso de regex que o modo estrito não consegue compilar, como uma backreference, um limite de palavra ou um intervalo {n,m} grande | Simplifique o padrão. Consulte Limitações do JSON Schema. |
Invalid regex in pattern field: ... | O pattern de uma ferramenta estrita tem um lookahead, um lookbehind ou um erro de sintaxe | Remova qualquer lookahead ou lookbehind e corrija quaisquer erros de sintaxe. 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. |
Uma chamada de ferramenta de servidor não tem bloco de resultado
Uma ferramenta de servidor ainda está aguardando para ser executada quando seu bloco server_tool_use ou mcp_tool_use não tem bloco de resultado. O erro was found without a corresponding ... block significa que a requisição de acompanhamento impede que a ferramenta em espera seja executada. A mensagem de erro e o stop_reason anterior mostram o motivo. Use o primeiro caso que corresponder:
- A mensagem termina com
but no `<name>` tool was providedouis not available after the last message: Aqui,<name>é o nome da ferramenta, comoweb_search. A requisição não define mais a ferramenta. Envie o mesmo arraytoolsde antes e, para uma ferramenta MCP, os mesmosmcp_servers. - O
stop_reasonanterior foitool_use: Sua mensagem do usuário tinha conteúdo após os blocostool_result. Envie apenas os blocostool_result, um para cada blocotool_usedo cliente. - O
stop_reasonanterior foipause_turn: Você adicionou uma mensagem do usuário. Remova-a para que a requisição termine com a resposta pausada como uma mensagemassistant.
Para ver as etapas completas, consulte Quando uma ferramenta de servidor ainda está aguardando e o motivo de parada pause_turn.
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 de JSON entre versões de modelos
| 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 | Analise 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.
Esta página foi útil?