Claude Platform Docs
MensagensFerramentas

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

SintomaCausa provávelCorreção
Claude chama a ferramenta A quando você queria a ferramenta BAmbiguidade na descriçãoRefine as descrições. Diferencie as ferramentas por QUANDO usá-las, não apenas pelo QUE elas fazem. Consulte Definir ferramentas.
Claude nunca chama sua ferramentaColisão de nomes de ferramentas ou schema genérico demaisVerifique 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 erradosSchema ambíguoAdicione strict: true (se o seu schema estiver no subconjunto suportado) ou adicione input_examples.

Claude inventa parâmetros de ferramentas

SintomaCausa provávelCorreção
Parâmetro que não existe no seu schemaGeração excessiva do modelo sem o modo estritoAdicione strict: true se seu schema estiver no subconjunto suportado.
Valores de parâmetro fora do seu enumModo estrito ausente ou enum grande demaisReduza o enum ou adicione input_examples mostrando escolhas válidas.

Chamadas de ferramentas paralelas não funcionam

SintomaCausa provávelCorreção
Claude chama ferramentas sequencialmente quando o paralelo seria melhorFormatação do histórico de mensagensEnvie 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 ignoradoDefinido tarde demais na conversaDefina-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

SintomaCausa provávelCorreção
Toda requisição é uma falha de cachetool_choice, a configuração de pensamento ou output_config.effort variando entre requisiçõesMantenha 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 cacheFerramenta inserida no início do array de ferramentasDeclare 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.

ErroCausaCorreção
tool_use ids were found without tool_result blocks immediately aftertool_result ausente para alguns IDs de tool_use, ou tool_result não é o primeiro bloco de conteúdo na mensagem do usuárioRetorne 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 ... blockA requisição de acompanhamento impede que uma ferramenta de servidor em espera seja executadaConsulte 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} grandeSimplifique 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 sintaxeRemova qualquer lookahead ou lookbehind e corrija quaisquer erros de sintaxe. Consulte Limitações do JSON Schema.
All tools have defer_loading: trueNenhuma ferramenta visível para o modeloPelo 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 provided ou is not available after the last message: Aqui, <name> é o nome da ferramenta, como web_search. A requisição não define mais a ferramenta. Envie o mesmo array tools de antes e, para uma ferramenta MCP, os mesmos mcp_servers.
  • O stop_reason anterior foi tool_use: Sua mensagem do usuário tinha conteúdo após os blocos tool_result. Envie apenas os blocos tool_result, um para cada bloco tool_use do cliente.
  • O stop_reason anterior foi pause_turn: Você adicionou uma mensagem do usuário. Remova-a para que a requisição termine com a resposta pausada como uma mensagem assistant.

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

SintomaCausa provávelCorreção
Claude se recusa a agir com base em um resultado de ferramenta, ou pede ao usuário que confirme instruções que vieram deleSuas próprias instruções estão sendo entregues dentro do conteúdo do tool_resultClaude é 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

SintomaCausaCorreção
A comparação de strings nas entradas de ferramentas falha com modelos mais novosO escape de Unicode e de barras difere entre versões de modeloAnalise 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?