o problema
Um modelo de linguagem responde com o que está no contexto e com o que ficou dos dados de treino. Pergunte o clima em São Francisco agora e nenhuma dessas duas fontes sabe a resposta. O caminho óbvio é deixar o modelo pedir a informação a alguém que sabe — mas aí aparece o problema real, que é o formato do pedido.
Se a saída do modelo é texto livre, quem pede vira quem faz parser. Você inventa um marcador, escreve uma regex, trata o caso em que ele escreveu o nome da função errado, trata o caso em que ele passou um argumento a menos. E sobra a segunda metade do problema: decidir quando pedir. Uma pergunta sobre a capital da França não precisa de chamada externa nenhuma; uma sobre o rover em Marte precisa. Essa decisão tem que morar em algum lugar, e o único lugar que enxerga a pergunta e o catálogo ao mesmo tempo é o modelo.
a ideia
Tool use resolve as duas metades com uma peça só: você descreve a ferramenta, e a descrição é ao mesmo tempo a documentação que o modelo lê para decidir e o contrato que ele preenche para chamar. Nome, description em prosa e um input_schema em JSON Schema. Claude usa a descrição para julgar se a pergunta cai naquela capacidade, e usa o schema para emitir uma chamada estruturada — um bloco tool_use com id, nome e input já validável — em vez de uma frase que você teria que interpretar.
Em cima disso, a documentação organiza o resto por um eixo que não é temático: é operacional. A pergunta não é o que a ferramenta faz, é de quem é o processo que executa. Isso divide o mundo em client tools, que rodam na sua aplicação, e server tools, que rodam na infraestrutura da Anthropic. Tudo que muda na sua vida — quem escreve o handler, quem trata erro, quanto isso custa, quantas viagens de rede você faz — cai desse lado da divisão.
como funciona
O ciclo de uma client tool tem duas requisições. Na primeira você manda a lista de tools junto com as mensagens. Claude volta com stop_reason: "tool_use" e um ou mais blocos tool_use. Você executa a operação e faz a segunda requisição com o histórico acrescido de duas mensagens: a resposta do assistant como veio, e uma mensagem de user contendo blocos tool_result com o tool_use_id correspondente.
tools = [{
"name": "get_weather",
"description": "Get the current weather for a given location.",
"input_schema": {
"type": "object",
"properties": {"location": {"type": "string"}},
"required": ["location"],
},
}]
response = client.messages.create(
model="claude-opus-5", max_tokens=1024, tools=tools,
tool_choice={"type": "auto", "disable_parallel_tool_use": True},
messages=messages,
)
tool_use = next(b for b in response.content if b.type == "tool_use")
messages += [
{"role": "assistant", "content": response.content},
{"role": "user", "content": [
{"type": "tool_result", "tool_use_id": tool_use.id, "content": weather}
]},
]Server tool é outra história: você declara {"type": "web_search_20260209", "name": "web_search"} e pronto. A busca roda do lado da Anthropic e os resultados voltam citados na mesma resposta, sem handler nenhum.
Os controles ficam em tool_choice. O default é auto — Claude decide a cada turno. disable_parallel_tool_use limita a uma chamada por turno. any e tool forçam a chamada em vez de torcer por ela. E strict: true na definição garante que o input venha exatamente no formato do seu schema.
o que isso custou
O custo mais fácil de ignorar é o de existir. A API injeta um system prompt próprio de tool use sempre que você passa ferramentas: 286 tokens no Claude Opus 5 com auto ou none, 406 com any ou tool. E esse número não segue uma curva — o Opus 4.7 cobrava 675, o Sonnet 5 cobra 354. É tabela para consultar, não intuição para aplicar. Só o caso de zero ferramentas com tool_choice: none custa zero.
Somam-se a isso o próprio bloco tools, os tool_use e os tool_result — e como o round trip reenvia o histórico, cada passo de um loop agêntico carrega todos os anteriores. Não à toa a documentação tem páginas separadas para gerenciar contexto de ferramentas e para combinar tool use com prompt caching. Server tools ainda cobram por uso, além dos tokens: web search cobra por busca realizada.
O comportamento também não é determinístico por construção. Se Claude não está chamando a ferramenta quando você espera, o ajuste sugerido é redação de system prompt — “Use the tools to investigate before responding.” empurra, “Always call a tool first before responding.” empurra mais, “Use your judgment” segura. Isso é influência, não garantia; a garantia é tool_choice. E a separação limpa entre client e server tem uma fresta admitida: se Claude chama um server tool no mesmo grupo de chamadas paralelas de um client tool seu, você volta a lidar com a execução.
onde isso aparece hoje
O round trip manual virou opcional: o Tool Runner dos SDKs executa suas ferramentas e devolve os resultados sozinho. O catálogo de client tools com schema da Anthropic — bash, text editor, memory, computer use, browser use — é o substrato dos agentes de código; são as mesmas primitivas, publicadas como interface estável.
Do lado do escalonamento, a tool search tool existe porque declarar tudo de uma vez não sobrevive à conta de tokens acima: com milhares de ferramentas, você descobre e carrega sob demanda. E o MCP connector conecta servidores MCP remotos direto pela Messages API, sem cliente MCP separado — o mesmo formato de chamada, com o catálogo vindo de fora.