Uso de ferramentas com Claude

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

Aqui está um exemplo mínimo usando uma ferramenta de servidor, a ferramenta de busca na web, que a Anthropic executa para você:

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-5-5",
    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)

O Claude executa a busca na infraestrutura da Anthropic e retorna os resultados citados na mesma resposta. Para que o Claude chame uma função que você define, passe uma ferramenta com um input_schema e, em seguida, execute a chamada quando o Claude retornar um bloco tool_use. Como funciona o uso de ferramentas mostra esse ciclo completo de ponta a ponta. Saiba mais sobre como definir ferramentas e como lidar com chamadas de ferramentas.

Como funciona o uso de ferramentas

As ferramentas diferem principalmente pelo local onde o código é executado. As ferramentas de cliente (incluindo ferramentas definidas pelo usuário e ferramentas com esquemas definidos pela Anthropic, como bash e text_editor) são executadas na sua aplicação. O Claude responde com stop_reason: "tool_use" e um ou mais blocos tool_use. Seu código executa a operação e envia de volta um tool_result. As ferramentas de servidor (como web_search, web_fetch, code_execution e tool_search) são executadas na infraestrutura da Anthropic: você vê os resultados diretamente sem lidar com a execução, a menos que o Claude chame a ferramenta no mesmo grupo de chamadas de ferramentas paralelas que uma das suas ferramentas de cliente (consulte Motivos de parada e fallback).

Aqui está esse ciclo completo para uma ferramenta de cliente. A primeira requisição define uma ferramenta get_weather, e o Claude responde à pergunta chamando-a: a resposta traz um bloco tool_use, seu código executa a consulta e uma segunda requisição envia o resultado de volta em um bloco tool_result para que o Claude possa responder com a resposta.

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather for a given location.",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "City and state, e.g. San Francisco, CA",
                }
            },
            "required": ["location"],
        },
    }
]
messages = [{"role": "user", "content": "What's the weather in San Francisco?"}]

# Claude responde com um bloco tool_use indicando a ferramenta e seus argumentos.
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=tools,
    # Solicite no máximo uma chamada de ferramenta por turno.
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
    messages=messages,
)
tool_use = next(block for block in response.content if block.type == "tool_use")
print(f"Claude called {tool_use.name} with {json.dumps(tool_use.input)}")

# Execute a ferramenta e envie o resultado de volta em um bloco tool_result.
weather = "15 degrees Celsius, partly cloudy"  # your weather lookup goes here
messages += [
    {"role": "assistant", "content": response.content},
    {
        "role": "user",
        "content": [
            {"type": "tool_result", "tool_use_id": tool_use.id, "content": weather}
        ],
    },
]
followup = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
    messages=messages,
)

# Claude usa o resultado para responder à pergunta original.
final_text = next(block for block in followup.content if block.type == "text")
print(final_text.text)

Claude called get_weather with {"location": "San Francisco, CA"}
The current weather in San Francisco is 15 degrees Celsius with partly cloudy skies.

Lidar com chamadas de ferramentas aborda cada etapa em detalhes, incluindo a formatação de resultados e a sinalização de erros; Uso paralelo de ferramentas aborda respostas que chamam várias ferramentas de uma vez. Para não precisar escrever esse ciclo você mesmo, use o Tool Runner: os SDKs executam suas ferramentas e enviam os resultados de volta automaticamente.

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

Para se conectar a servidores do Model Context Protocol (MCP), consulte o conector MCP. Para criar seu próprio cliente MCP, consulte o guia do Model Context Protocol sobre como criar um cliente MCP.

Quando o Claude usa ferramentas

Com o tool_choice padrão de {"type": "auto"}, o Claude determina a cada turno se deve chamar uma ferramenta ou responder diretamente. Ele chama uma ferramenta quando a solicitação corresponde à capacidade descrita daquela 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 ajustado por meio do seu prompt do sistema. Se o Claude não estiver chamando ferramentas quando você espera, uma instrução leve como "Use the tools to investigate before responding." aumenta o uso de ferramentas. Uma forma mais forte, como "Always call a tool first before responding.", vai 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 exigir uma chamada de ferramenta em vez de depender de prompts, defina tool_choice.

A página de cada ferramenta de servidor descreve seu próprio limite de acionamento em mais detalhes.

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "get_weather",
  "input": { "location": "New York, NY", "unit": "fahrenheit" }
}

Escolha uma ferramenta

Para strings de type, versões e cabeçalhos beta, consulte a Referência de ferramentas.

Suas próprias ferramentas

Para ferramentas que você define, você escreve o esquema e sua aplicação executa cada chamada.

Ferramentas de cliente com esquema da Anthropic

A Anthropic publica o esquema e treina o Claude nele. Sua aplicação ainda executa cada chamada e retorna o tool_result.

Ferramentas de servidor

As ferramentas de servidor são executadas na infraestrutura da Anthropic, sem código de tratamento na sua aplicação. Consulte Ferramentas de servidor para conhecer a mecânica que elas compartilham.

Preços

As solicitações de "tool use" (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 no uso (por exemplo, a pesquisa na web cobra por pesquisa realizada)

As ferramentas do lado do cliente são precificadas da mesma forma que qualquer outra solicitação da Claude API, embora as ferramentas do lado do servidor possam 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 de API
• Blocos de conteúdo tool_result nas solicitações de API

Quando você usa tools, a API também inclui automaticamente um "system prompt" (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 na tabela a seguir (excluindo os tokens adicionais listados anteriormente). 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.

Model	Tool use system prompt tokens
Name	Tool choice	Token count
Claude Opus 5.5For long-running agentic coding and knowledge work	auto, none	286 tokens
Claude Sonnet 5.5The best combination of speed and intelligence	auto, none	286 tokens
Claude Haiku 4.5The fastest model with near-frontier intelligence	auto, none	496 tokens
	any, tool	588 tokens
Additional models
Claude Opus 5	auto, none	286 tokens
	any, tool	406 tokens
Claude Opus 4.8	auto, none	290 tokens
	any, tool	410 tokens
Claude Opus 4.7	auto, none	675 tokens
	any, tool	804 tokens
Claude Opus 4.6	auto, none	497 tokens
	any, tool	589 tokens
Claude Opus 4.5	auto, none	496 tokens
	any, tool	588 tokens
Claude Opus 4.1	auto, none	313 tokens
	any, tool	315 tokens
Claude Opus 4	auto, none	313 tokens
	any, tool	315 tokens
Claude Sonnet 5	auto, none	354 tokens
	any, tool	474 tokens
Claude Sonnet 4.6	auto, none	497 tokens
	any, tool	589 tokens
Claude Sonnet 4.5	auto, none	496 tokens
	any, tool	588 tokens
Claude Sonnet 4	auto, none	313 tokens
	any, tool	315 tokens
Claude Haiku 3.5	auto, none	264 tokens
	any, tool	355 tokens

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 requisição de API, a resposta inclui as contagens de tokens de entrada e de saída nas métricas de usage relatadas.

Algumas ferramentas de servidor adicionam cobranças baseadas em uso além dos tokens: consulte a Ferramenta de busca na web e a Ferramenta de execução de código para conhecer suas tarifas.

Próximos passos