--- title: Solução de problemas de uso de ferramentas url: https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/troubleshooting-tool-use description: 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/define-tools). | | 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/strict-tool-use). | | 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/parallel-tool-use). | | `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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-use-with-prompt-caching) e [Pensamento e cache de prompt](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#thinking-and-prompt-caching). | | 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/handle-tool-calls) e [Uso de ferramentas em paralelo](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/parallel-tool-use). | | `was found without a corresponding _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 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](https://platform.claude.com/docs/pt-BR/build-with-claude/handling-stop-reasons#tool-use). | | `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](https://platform.claude.com/docs/pt-BR/build-with-claude/structured-outputs#json-schema-limitations). | | `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](https://platform.claude.com/docs/pt-BR/api/errors#thinking-blocks-cannot-be-modified) 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](https://platform.claude.com/docs/pt-BR/build-with-claude/mid-conversation-system-messages). Mantenha no resultado da ferramenta apenas os dados. Consulte [Mitigar jailbreaks e injeções de prompt](https://platform.claude.com/docs/pt-BR/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks#indirect-prompt-injection). | ## 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 | 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.