Uso de ferramentas com Claude

O "tool use" (uso de ferramentas) permite que Claude chame funções que você define ou que a Anthropic fornece. Claude decide quando chamar uma ferramenta com base na solicitação do usuário e na descrição da ferramenta, e então retorna uma chamada estruturada que sua aplicação executa (ferramentas do cliente) ou que a Anthropic executa (ferramentas do servidor).

Aqui está o exemplo mais simples usando uma ferramenta do servidor, onde a Anthropic cuida da execução:

import anthropic

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=[{"type": "web_search_20260209", "name": "web_search"}],
    messages=[{"role": "user", "content": "What's the latest on the Mars rover?"}],
)
print(response.content)



Como o uso de ferramentas funciona

As ferramentas diferem principalmente por onde o código é executado. Ferramentas do cliente (incluindo ferramentas definidas pelo usuário e ferramentas com esquema da Anthropic, como bash e text_editor) são executadas na sua aplicação: Claude responde com stop_reason: "tool_use" e um ou mais blocos tool_use, seu código executa a operação e você envia de volta um tool_result. Ferramentas do servidor (web_search, code_execution, web_fetch, tool_search) são executadas na infraestrutura da Anthropic: você vê os resultados diretamente sem precisar lidar com a execução.

Para o modelo conceitual completo, incluindo o loop agêntico e quando escolher cada abordagem, consulte Como o uso de ferramentas funciona.

Para conectar-se a servidores MCP, consulte o conector MCP. Para construir seu próprio cliente MCP, consulte modelcontextprotocol.io.

O acesso a ferramentas é uma das primitivas de maior alavancagem que você pode dar a um agente. Em benchmarks como LAB-Bench FigQA (interpretação de figuras científicas) e SWE-bench (engenharia de software do mundo real), adicionar até mesmo ferramentas básicas produz ganhos de capacidade desproporcionais, frequentemente superando baselines de especialistas humanos.



Quando Claude usa ferramentas

Com o tool_choice padrão de {"type": "auto"}, Claude decide a cada turno se chama uma ferramenta ou responde diretamente. Ele chama uma ferramenta quando a solicitação corresponde à capacidade descrita dessa ferramenta e a resposta ainda não está no contexto; ele responde diretamente para conhecimento estável, tarefas criativas e turnos conversacionais.

Esse limite pode ser direcionado através do seu prompt do sistema. Se Claude não estiver chamando ferramentas quando você espera, uma instrução leve como "Use the tools to investigate before responding." aumenta mensuravelmente o uso de ferramentas; uma forma mais forte como "Always call a tool first before responding." vai ainda mais longe. Por outro lado, "Use your judgment about whether to call a tool or respond directly." mantém o comportamento de acionamento conservador.

Para uma garantia rígida em vez de um incentivo, use tool_choice.

A página de cada ferramenta do servidor descreve seu próprio limite de acionamento em mais detalhes. Veja, por exemplo, a ferramenta de busca na web ou a ferramenta de execução de código.



Exemplos de uso de ferramentas

Para um passo a passo prático completo, consulte o tutorial. Para exemplos de referência de conceitos individuais, consulte Definir ferramentas e Lidar com chamadas de ferramentas.



Preços

As solicitações de uso de ferramentas são precificadas com base em:

1. O número total de tokens de entrada enviados ao modelo (incluindo no parâmetro tools)
2. O número de tokens de saída gerados
3. Para ferramentas do lado do servidor, precificação adicional baseada em uso (por exemplo, a busca na web cobra por busca realizada)

As ferramentas do lado do cliente são precificadas da mesma forma que qualquer outra solicitação à API do Claude, enquanto as ferramentas do lado do servidor podem incorrer em cobranças adicionais com base em seu uso específico.

Os tokens adicionais do uso de ferramentas vêm de:

• O parâmetro tools nas solicitações de API (nomes, descrições e esquemas das ferramentas)
• Blocos de conteúdo tool_use nas solicitações e respostas da API
• Blocos de conteúdo tool_result nas solicitações de API

Quando você usa tools, a API também inclui automaticamente um prompt do sistema especial para o modelo que habilita o uso de ferramentas. O número de tokens de uso de ferramentas necessários para cada modelo está listado abaixo (excluindo os tokens adicionais listados acima). Observe que a tabela pressupõe que pelo menos 1 ferramenta seja fornecida. Se nenhuma tools for fornecida, então uma escolha de ferramenta none usa 0 tokens adicionais de prompt do sistema.

Essas contagens de tokens são adicionadas aos seus tokens normais de entrada e saída para calcular o custo total de uma solicitação.

Consulte a tabela de visão geral dos modelos para os preços atuais por modelo.

Quando você envia um prompt de uso de ferramentas, assim como qualquer outra solicitação de API, a resposta exibirá as contagens de tokens de entrada e saída como parte das métricas de usage reportadas.



Próximos passos



Escolha seu caminho