ConstruirFerramentas

Solução de problemas com uso de ferramentas

Corrija os erros mais comuns de uso de ferramentas com tabelas de diagnóstico de sintoma para solução.

Tabelas de sintoma para solução dos erros mais comuns de uso de ferramentas. Cada solução faz referência cruzada à página que possui o recurso.

Claude chama a ferramenta errada

Sintoma	Causa provável	Solução
Claude chama a ferramenta A quando você queria a ferramenta B	Ambiguidade na descrição	Aguçar descrições. Diferenciar ferramentas por QUANDO usá-las, não apenas O QUE elas fazem. Veja Definir ferramentas.
Claude nunca chama sua ferramenta	Colisão de nome de ferramenta ou esquema muito genérico	Verificar nomes duplicados em sua lista de ferramentas. Adicionar `input_examples` para tornar o uso pretendido concreto.
Claude chama com tipos de parâmetro incorretos	Modelo adivinhando em esquema ambíguo	Adicionar `strict: true` (se seu esquema estiver no subconjunto suportado) ou adicionar `input_examples`.

Sintoma	Causa provável	Solução
Parâmetro que não existe em seu esquema	Geração excessiva do modelo sem modo estrito	Adicionar `strict: true` se seu esquema estiver no subconjunto suportado.
Valores de parâmetro fora de seu enum	Modo estrito ausente ou enum muito grande	Reduzir o enum ou adicionar `input_examples` mostrando escolhas válidas.

Sintoma	Causa provável	Solução
Claude chama ferramentas sequencialmente quando paralelo seria melhor	Formatação do histórico de mensagens	Enviar múltiplos blocos `tool_result` em UMA mensagem do usuário, não um por turno. Veja Uso de ferramentas paralelas.
`disable_parallel_tool_use` parece ser ignorado	Definido muito tarde na conversa	Deve ser definido na solicitação que retorna `tool_use`. Defini-lo em uma solicitação posterior não tem efeito nas chamadas de ferramentas anteriores.

Sintoma	Causa provável	Solução
Cada solicitação é uma falha de cache	`tool_choice` variando entre solicitações	Manter `tool_choice` estável ou colocar o ponto de interrupção `cache_control` antes do ponto de variação. Veja Uso de ferramentas com cache de prompt.
Adicionar uma ferramenta no meio da conversa quebra o cache	Ferramenta adicionada no início do array de ferramentas	Usar `defer_loading: true` com busca de ferramentas para anexar a ferramenta inline em vez de modificar o início do array.

Erro	Causa	Solução
`tool_use ids foram encontrados sem blocos tool_result imediatamente após`	`tool_result` ausente para alguns ids `tool_use`, ou `tool_result` não é o primeiro bloco de conteúdo na mensagem do usuário	Retornar um `tool_result` para cada bloco `tool_use` na resposta do assistente. Colocar blocos `tool_result` antes de qualquer texto. Veja Lidar com chamadas de ferramentas e Uso de ferramentas paralelas.
`Input schema is not compatible with strict mode: string patterns are not supported`	Usando `pattern` com `strict: true`	Remover o padrão ou descartar `strict: true`. A palavra-chave ainda não está no subconjunto de JSON Schema suportado.

Sintoma	Causa	Solução
Comparação de string em entradas de ferramentas falha com modelos mais novos	Escape de Unicode e barra invertida diferem entre versões de modelo	Analisar com `json.loads()` ou `JSON.parse()`. Nunca fazer correspondência de string bruta em entrada serializada.

Escrever esquemas e descrições que direcionem Claude para a ferramenta correta.

Executar ferramentas e retornar resultados no formato de mensagem necessário.

Diretório completo de ferramentas de esquema Anthropic e suas strings de versão.

Was this page helpful?

Claude chama a ferramenta errada

Sintoma	Causa provável	Solução
Claude chama a ferramenta A quando você queria a ferramenta B	Ambiguidade na descrição	Aguçar descrições. Diferenciar ferramentas por QUANDO usá-las, não apenas O QUE elas fazem. Veja Definir ferramentas.
Claude nunca chama sua ferramenta	Colisão de nome de ferramenta ou esquema muito genérico	Verificar nomes duplicados em sua lista de ferramentas. Adicionar `input_examples` para tornar o uso pretendido concreto.
Claude chama com tipos de parâmetro incorretos	Modelo adivinhando em esquema ambíguo	Adicionar `strict: true` (se seu esquema estiver no subconjunto suportado) ou adicionar `input_examples`.

Claude inventa parâmetros de ferramenta

Sintoma	Causa provável	Solução
Parâmetro que não existe em seu esquema	Geração excessiva do modelo sem modo estrito	Adicionar `strict: true` se seu esquema estiver no subconjunto suportado.
Valores de parâmetro fora de seu enum	Modo estrito ausente ou enum muito grande	Reduzir o enum ou adicionar `input_examples` mostrando escolhas válidas.

Chamadas de ferramentas paralelas não funcionam

Sintoma	Causa provável	Solução
Claude chama ferramentas sequencialmente quando paralelo seria melhor	Formatação do histórico de mensagens	Enviar múltiplos blocos `tool_result` em UMA mensagem do usuário, não um por turno. Veja Uso de ferramentas paralelas.
`disable_parallel_tool_use` parece ser ignorado	Definido muito tarde na conversa	Deve ser definido na solicitação que retorna `tool_use`. Defini-lo em uma solicitação posterior não tem efeito nas chamadas de ferramentas anteriores.

Cache continua se invalidando

Sintoma	Causa provável	Solução
Cada solicitação é uma falha de cache	`tool_choice` variando entre solicitações	Manter `tool_choice` estável ou colocar o ponto de interrupção `cache_control` antes do ponto de variação. Veja Uso de ferramentas com cache de prompt.
Adicionar uma ferramenta no meio da conversa quebra o cache	Ferramenta adicionada no início do array de ferramentas	Usar `defer_loading: true` com busca de ferramentas para anexar a ferramenta inline em vez de modificar o início do array.

Erros no momento da solicitação

Erro	Causa	Solução
`tool_use ids foram encontrados sem blocos tool_result imediatamente após`	`tool_result` ausente para alguns ids `tool_use`, ou `tool_result` não é o primeiro bloco de conteúdo na mensagem do usuário	Retornar um `tool_result` para cada bloco `tool_use` na resposta do assistente. Colocar blocos `tool_result` antes de qualquer texto. Veja Lidar com chamadas de ferramentas e Uso de ferramentas paralelas.
`Input schema is not compatible with strict mode: string patterns are not supported`	Usando `pattern` com `strict: true`	Remover o padrão ou descartar `strict: true`. A palavra-chave ainda não está no subconjunto de JSON Schema suportado.

Sintoma

Causa

Solução

Comparação de string em entradas de ferramentas falha com modelos mais novos

Escape de Unicode e barra invertida diferem entre versões de modelo

Analisar com json.loads() ou JSON.parse(). Nunca fazer correspondência de string bruta em entrada serializada.