Melhores Práticas de Uso de Ferramentas

Práticas numeradas para design de esquema, tratamento de erros e loops de ferramenta de múltiplos turnos - um resumo de toda a seção que você pode usar como um checklist antes de publicar uma integração de uso de ferramentas baseada no SDK oficial anthropic para Python.

Como Usar Esta Lista

• Leia de cima para baixo na primeira vez - o design de esquema e a escolha de ferramenta (tool_choice) vêm primeiro porque afetam se Claude chama a ferramenta certa ou não, antes de você chegar à mecânica do loop.
• Trate os itens 1-2 como trabalho em tempo de design (feito uma vez por ferramenta), os itens 3-6 como comportamento em tempo de requisição e tempo de loop (feito em cada chamada), e os itens 7-9 como preocupações de escalabilidade que você adota assim que o conjunto de ferramentas ou o tráfego cresce.
• Volte a esta página sempre que adicionar uma nova ferramenta ou vir Claude escolhendo a ferramenta errada, perdendo um tool_result, ou em loop por mais tempo que o esperado.
• Emparelhe isso com as páginas mais aprofundadas vinculadas em "Relacionados" - esta página é deliberadamente concisa; as páginas vinculadas carregam as explicações completas e exemplos práticos.

A - Design de Esquema

• Dê a cada ferramenta um nome claro e descritivo. Use get_weather, não w ou tool1 - Claude compara sua description com a intenção do usuário, e um nome vago lhe dá menos com o que trabalhar.
• Escreva descrições que digam QUANDO chamar a ferramenta, não apenas o que ela faz. "Chame isso quando o usuário perguntar sobre preços atuais" supera uma descrição que apenas afirma a funcionalidade - modelos Claude recentes alcançam ferramentas de forma mais conservadora por padrão, então uma descrição prescritiva e com palavras-gatilho melhora medidamente a precisão do "deve chamar".
• Dê a cada propriedade input_schema sua própria description. Claude lê as descrições por propriedade para decidir qual valor extrair e como formatá-lo - uma propriedade não documentada é uma propriedade sobre a qual Claude tem que adivinhar.
• Use enum para parâmetros de escolha fixa. Se um parâmetro só pode ter um de um conjunto conhecido de valores (por exemplo, "unit": ["celsius", "fahrenheit"]), restrinja-o com enum em vez de deixá-lo como texto livre.
• Marque apenas campos verdadeiramente obrigatórios em required. Marcar campos em excesso como obrigatórios força Claude a fabricar um valor ou fazer uma pergunta de esclarecimento desnecessária quando o campo não se aplica.
• Defina "strict": true quando precisar de validação exata do esquema. Adicione-o no nível superior da definição da ferramenta junto com additionalProperties: false e required - isso faz com que tool_use.input valide exatamente contra o esquema em vez de desviar em casos extremos.

B - Mantenha o Conjunto de Ferramentas Focado

• Não registre mais ferramentas do que a tarefa necessita. Muitas ferramentas, nomes vagos ou descrições sobrepostas podem fazer com que Claude escolha a ferramenta errada ou pule a chamada de uma delas - um grande conjunto de ferramentas indiferenciado é pior para a precisão do que um pequeno e bem descrito.
• Verifique sobreposição de descrições antes de adicionar uma nova ferramenta. Se duas ferramentas puderem plausivelmente satisfazer a mesma solicitação, restrinja a linguagem "chame isso quando" em cada uma delas até que sejam mutuamente distinguíveis.

C - tool_choice

• Use {"type": "auto"} como padrão para agentes de propósito geral. Deixe Claude decidir se deve chamar uma ferramenta e qual delas, com base na conversa.
• Use {"type": "any"} quando o turno deve terminar com alguma ação, mas você não se importa com qual ferramenta. Isso garante uma chamada de ferramenta sem escolher em nome de Claude.
• Use {"type": "tool", "name": "..."} para forçar uma ferramenta específica. Use isso quando o fluxo de trabalho exigir uma chamada de função específica, independentemente do que Claude escolheria de outra forma.
• Use {"type": "none"} para suprimir temporariamente chamadas de ferramentas sem remover tools da requisição. Remover definições de ferramentas inteiramente invalida o cache do prompt - none mantém as definições no lugar e apenas impede que esse turno chame uma ferramenta.
• Adicione disable_parallel_tool_use: true a qualquer valor de tool_choice quando seu código não puder lidar com mais de uma chamada de ferramenta por turno. Funciona em conjunto com auto, any, tool ou none e limita Claude a uma única chamada de ferramenta nessa resposta.

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    tools=[weather_tool, calculate_tool],
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
    messages=[{"role": "user", "content": "Qual é o tempo em Austin, TX?"}],
)

D - Tratamento de Erros em Blocos tool_result

• Retorne is_error: true em caso de falha da ferramenta em vez de descartar o resultado ou gerar uma exceção. Claude pode então tentar novamente a chamada, tentar uma ferramenta diferente ou pedir esclarecimentos ao usuário - um tool_result ausente ou uma exceção não tratada deixa a conversa em um estado quebrado.

def run_tool(tool_use):
    try:
        output = execute(tool_use.name, tool_use.input)
        return {
            "type": "tool_result",
            "tool_use_id": tool_use.id,
            "content": str(output),
        }
    except Exception as exc:
        return {
            "type": "tool_result",
            "tool_use_id": tool_use.id,
            "content": f"Erro: {exc}",
            "is_error": True,
        }

E - Higiene de Loop de Múltiplos Turnos

• Anexe o response.content completo de volta em messages, não apenas o texto extraído. A API precisa dos blocos tool_use preservados no turno do assistente - removê-los para conteúdo apenas de texto quebra a próxima requisição.
• Proteja cada loop com um limite max_iterations. Um loop de uso de ferramenta sem teto pode ficar descontrolado se Claude continuar chamando ferramentas sem produzir uma resposta final.
• Lide com stop_reason == "pause_turn" reenviando a conversa como está. Esta razão de parada significa que uma ferramenta do lado do servidor atingiu seu limite interno de iteração - não injete uma mensagem extra "Continuar"; a API retoma automaticamente porque detecta o bloco server_tool_use final.

messages = [{"role": "user", "content": "Qual é o tempo em Austin, TX?"}]
 
for _ in range(max_iterations := 8):
    response = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1024,
        tools=[weather_tool],
        messages=messages,
    )
    messages.append({"role": "assistant", "content": response.content})
 
    if response.stop_reason == "pause_turn":
        continue  # reenviar como está, sem mensagem "Continuar" injetada
 
    if response.stop_reason != "tool_use":
        break
 
    tool_results = [run_tool(block) for block in response.content if block.type == "tool_use"]
    messages.append({"role": "user", "content": tool_results})

F - Chamadas Paralelas de Ferramentas

• Espere e lide com múltiplos blocos tool_use em um turno. Claude pode solicitar várias ferramentas em paralelo por padrão - execute-as concorrentemente onde for prático, em vez de assumir exatamente uma chamada por turno.
• Retorne TODOS os blocos tool_result juntos em uma única mensagem user. Nunca os divida em várias mensagens - fazer isso pode degradar o comportamento futuro de chamadas paralelas de Claude.
• Corresponda a cada tool_use_id que Claude enviou com um tool_result, incluindo chamadas falhas. Um bloco tool_use sem um tool_result correspondente (mesmo um com is_error: true) deixa o turno incompleto.

G - Escalando para Muitas Ferramentas

• Adote a Ferramenta de Busca de Ferramentas assim que uma biblioteca de ferramentas crescer para dezenas a centenas. Use tool_search_tool_regex_20251119 ou tool_search_tool_bm25_20251119 com defer_loading: true em ferramentas raramente usadas para cortar o uso de tokens em aproximadamente 85%.
• Mantenha a própria ferramenta de busca e pelo menos outra ferramenta não adiadas. Adiar todas as ferramentas, incluindo a ferramenta de busca, torna a requisição 400 - Claude precisa de pelo menos uma ferramenta carregada imediatamente para raciocinar.
• Prefira o conector MCP em vez de um wrapper do lado do cliente para capacidades remotas/hospedadas. Quando um servidor MCP adequado já existe, use mcp_servers mais uma entrada mcp_toolset correspondente (beta mcp-client-2025-11-20) em vez de reimplementar um cliente que chama a mesma API remota.

H - Cache de Prompt com Ferramentas

• Lembre-se de que as definições de ferramentas são renderizadas primeiro no prompt, antes do sistema e das mensagens. Adicionar, remover ou reordenar ferramentas invalida o tier de cache de ferramentas/sistema - alternar tool_choice sozinho não o faz.
• Mantenha a ordenação das ferramentas determinística se você construir a lista tools dinamicamente. Ordene por nome (ou outra chave estável) para que o mesmo conjunto de ferramentas sempre serialize na mesma ordem e não quebre o cache desnecessariamente.

I - Análise de JSON

• Sempre leia tool_use.input através do objeto analisado do SDK, nunca comparando a string bruta. Modelos Claude recentes podem escapar Unicode ou barras invertidas de forma diferente em JSON gerado, então a correspondência de strings com o payload bruto é frágil de maneiras que um objeto analisado não é.

FAQs

Relacionados

• Noções Básicas de Uso de Ferramentas - o ciclo completo de requisição/resposta que essas práticas assumem
• Definindo Esquemas de Ferramentas com nome, description e input_schema - o mergulho profundo por trás dos itens de design de esquema acima
• Referência de Opções de Escolha de Ferramenta - referência completa para os quatro modos de tool_choice
• Construindo um Loop de Uso de Ferramenta de Múltiplos Turnos - o exemplo prático por trás dos itens de higiene de loop acima
• Executando Chamadas Paralelas de Ferramentas em um Único Turno - a explicação completa do tratamento paralelo de tool_use
• Escalando para Centenas de Ferramentas com a Ferramenta de Busca de Ferramentas - o mergulho profundo por trás do item de escalabilidade acima

Versões de Stack: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão), e Claude Haiku 4.5 - e o SDK oficial anthropic para Python (última versão 0.x). Nomes de modelos, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.