---
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.
---

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](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 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](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 | 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](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 | 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](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 ... 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/troubleshooting-tool-use#a-server-tool-call-has-no-result-block). |
| `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](https://platform.claude.com/docs/pt-BR/build-with-claude/structured-outputs#json-schema-limitations). |
| `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](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`. |

### Uma chamada de ferramenta de servidor não tem bloco de resultado

Uma [ferramenta de servidor](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/server-tools) 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](https://platform.claude.com/docs/pt-BR/build-with-claude/handling-stop-reasons#when-a-server-tool-is-still-waiting) e o [motivo de parada `pause_turn`](https://platform.claude.com/docs/pt-BR/build-with-claude/handling-stop-reasons#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](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 | Analise com `json.loads()` ou `JSON.parse()`. Nunca faça correspondência de strings brutas na entrada serializada. |

## Próximos passos

<CardGroup cols={3}>
  <Card title="Definir ferramentas" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/define-tools">
    Escreva schemas e descrições que direcionem Claude para a ferramenta certa.
  </Card>

  <Card title="Lidar com chamadas de ferramentas" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/handle-tool-calls">
    Execute ferramentas e retorne resultados no formato de mensagem exigido.
  </Card>

  <Card title="Referência de ferramentas" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-reference">
    Diretório completo de ferramentas fornecidas pela Anthropic e suas strings de versão.
  </Card>
</CardGroup>
