Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Tabelas de sintoma para correçã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 excessivamente genérico | Verifique se há nomes duplicados em sua lista de ferramentas. Adicione input_examples para tornar o uso pretendido concreto. |
| Claude chama com tipos de parâmetros errados | Modelo adivinhando 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âmetro fora do seu enum | Modo estrito ausente ou enum muito grande | 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 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. |
| 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 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 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 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 (mais frequentemente, Claude o chamou junto com uma ferramenta do cliente), e ou 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 Razões de parada e fallback. |
Input schema is not compatible with strict mode: string patterns are not supported | Usando pattern com strict: true | Remova o pattern ou retire strict: true. A palavra-chave pattern ainda não está no subconjunto suportado 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. |
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 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 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 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 novos | 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 bruta de strings na 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?