Claude Fable 5 Tool Use: Guia Prático de Function Calling

Quando a conversa com a API passa de "me responde isso" para "faz isso por mim", entra em cena o Claude Fable 5 tool use: o mecanismo que permite ao modelo pedir que seu código execute funções, retorne o resultado e continue o raciocínio. Function calling em outras APIs, tool use no vocabulário da Anthropic — mesma ideia, interface diferente. Para contexto geral do modelo, veja o Claude Fable 5.

Este guia cobre o ciclo tool_use/tool_result, como escrever um input_schema que o modelo entenda, como forçar comportamento com tool_choice, o que muda com parallel tools e — a parte que a maioria dos tutoriais ignora — quanto Claude Fable 5 tool use custa em tokens e como tratar erros sem quebrar o loop.

O que é tool use e por que não é "só JSON"

O Claude Fable 5 tool use é o canal estruturado pelo qual o modelo declara que precisa de uma função executada antes de continuar. Você envia a lista de ferramentas disponíveis no parâmetro tools; quando o modelo decide usar uma, o stop_reason da resposta vem como "tool_use" e o content traz um bloco com o nome da tool e os argumentos preenchidos.

A diferença entre tool use e "pedir JSON no prompt" é que o modelo valida os argumentos contra o input_schema que você forneceu. Argumento faltando, tipo errado, enum fora da lista — isso é problema do modelo resolver, não seu. Em troca, você aceita um ciclo de ida e volta: a conversa precisa de pelo menos duas chamadas de API por tool executada.

Anatomia de um tool: name, description e input_schema

Um tool tem três campos obrigatórios: name, description e input_schema. Parecem triviais, mas a descrição é a variável mais importante de todas — é ela que decide se o modelo chama a tool certa quando a pergunta é ambígua.

Por experiência, prefiro descrições que explicam quando usar e quando não usar a tool, não só o que ela faz. Algo como "busca preço atual de uma ação na B3; use quando o usuário pedir cotação em tempo real; não use para gráficos históricos". Isso corta falso-positivo melhor do que qualquer instrução no system prompt.

O input_schema segue JSON Schema padrão. Tipo object no topo, properties com cada parâmetro, required com os obrigatórios:

{
  "name": "get_stock_price",
  "description": "Busca preço atual de uma ação na B3. Use quando o usuário pedir cotação em tempo real;
 não use para gráficos históricos.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "Código do papel na B3, ex: PETR4, VALE3"
      },
      "currency": {
        "type": "string",
        "enum": ["BRL", "USD"],
        "default": "BRL"
      }
    },
    "required": ["ticker"]
  }
}

Nome do campo também importa. "ticker" é melhor que "symbol" para contexto brasileiro — o modelo adapta a extração conforme a nomenclatura que você escolhe. Enum sempre que possível: fecha o espaço de valores que o modelo pode alucinar. É assim que Claude Fable 5 tool use entrega estrutura previsível.

O loop tool_use → tool_result passo a passo

O ciclo canônico tem quatro passos, e todo bug sério de Claude Fable 5 tool use mora em algum deles. Primeiro: você chama messages.create passando tools e o histórico. Segundo: inspeciona response.stop_reason. Se for "end_turn", acabou. Se for "tool_use", o content traz um ou mais blocos tool_use com id, name e input.

Terceiro passo é executar cada bloco. Importante: você devolve a resposta do modelo intacta como assistant, e cria uma nova mensagem user contendo apenas blocos tool_result, cada um apontando para o tool_use_id correspondente. Esquecer de reenviar o content do assistant é o erro mais comum — a próxima resposta vem truncada ou alucinada.

const response = await client.messages.create({
  model: "claude-fable-5",
  max_tokens: 1024,
  tools,
  messages
});

if (response.stop_reason === "tool_use") {
  const toolBlocks = response.content.filter(b => b.type === "tool_use");
  const toolResults = await Promise.all(
    toolBlocks.map(async (block) => ({
      type: "tool_result",
      tool_use_id: block.id,
      content: await runTool(block.name, block.input)
    }))
  );
  messages.push({ role: "assistant", content: response.content });
  messages.push({ role: "user", content: toolResults });
}

Quarto passo é repetir até stop_reason virar "end_turn". Para a maioria dos agentes de produção eu coloco um maxIterations de 10 — se o loop não termina em 10 round trips, algo está errado no schema ou no system prompt, não vale continuar queimando token.

Controlando comportamento com tool_choice

O parâmetro tool_choice tem quatro modos. "auto" (padrão) deixa o modelo decidir se chama tool ou responde direto. "any" força o uso de alguma tool, mas o modelo escolhe qual. "tool" força uma tool específica pelo nome. "none" desabilita tool use mesmo com tools definidas.

O uso prático de "tool" com nome fixo substitui com folga o "JSON mode" que muita gente ainda implementa via prompt. Em vez de pedir "responda em JSON com os campos X, Y, Z", você define uma tool extract_data com schema estrito e força a chamada. O modelo preenche o schema e você recebe os argumentos já validados.

Opinião direta: desde que tool_choice "tool" virou confiável no Fable 5, abandonei por completo prompts com "retorne em JSON". A taxa de erro de parsing caiu para quase zero, e o schema vira documentação viva do contrato que o Claude Fable 5 tool use entrega.

Parallel tool use: ganho real e quando desabilitar

Por padrão, o modelo emite múltiplos blocos tool_use na mesma resposta quando a pergunta pede ações independentes. "Qual o preço de PETR4, VALE3 e ITUB4?" produz três blocos em um único round trip. Você executa os três em paralelo, devolve três tool_result e segue.

Quando desabilitar: ordem importa, ou uma tool depende do resultado da anterior. Nesses casos, passe disable_parallel_tool_use true dentro de tool_choice com type "auto". O modelo volta a emitir uma tool por vez e espera o resultado antes da próxima.

Não desabilite por reflexo. Perder paralelismo em um agente que faz cinco lookups independentes multiplica a latência pelo mesmo fator. Testei em um workflow de leads: desabilitar levou a resposta final de 4s para 19s, sem ganho de qualidade.

Structured outputs: substituto oficial do JSON mode

Em 2026 a Anthropic liberou structured outputs em beta pública para o Fable 5 e o Opus 4.1. A promessa é conformance garantido ao schema — não "o modelo tenta seguir", mas "o modelo não emite nada fora do schema". Para dados críticos (payload de pagamento, estrutura de banco), é a diferença entre try/catch e código linear.

A ativação é via header beta na requisição e strict true no tool. Fora da beta, a conformance é alta mas não garantida — para 95% dos casos Claude Fable 5 tool use normal basta; para o restante, structured outputs resolve o 5% que faltava.

Custo em tokens: a conta que ninguém faz

Claude Fable 5 tool use não é mágica barata. Cada round trip reenvia o histórico completo da conversa mais todas as definições das tools. Em um agente com dez tools médias (cada uma com descrição detalhada e schema), as definições sozinhas podem representar 2.000 tokens de input por chamada. Em um loop de cinco round trips, são 10.000 tokens só com tools, antes de contar o histórico.

A conta real: para um workflow típico de três ferramentas usadas em quatro round trips, medi consumo total entre 8.000 e 15.000 tokens de input. No preço do Fable 5 isso dá alguns centavos por conversação — barato por chamada, caro em escala com milhões de usuários.

A mitigação óbvia é prompt caching nas definições das tools. Elas são estáticas (não mudam entre chamadas) e caras (schemas grandes), ou seja, o cenário perfeito para caching. Marcar o bloco de tools com cache_control "ephemeral" corta o custo delas em até 90% nos hits de cache.

Outra alavanca é controlar max_tokens do output. Tool calls geralmente não precisam de 4.096 tokens de saída — se seu schema tem cinco campos, 512 sobra. Reduzir o limite não muda o preço por token gerado, mas evita que o modelo divague antes do bloco tool_use quando a temperatura está alta.

Tratando erros com is_error true

Sua função pode falhar. API externa cai, parâmetro inválido escapa da validação, timeout. O jeito certo de reportar isso para o modelo não é fingir que deu certo — é devolver um tool_result com is_error true e o conteúdo descrevendo o problema de forma curta e acionável.

{
  "type": "tool_result",
  "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
  "content": "Erro: ticker INVALIDO4 nao encontrado na B3. Confirme o codigo.",
  "is_error": true
}

Com essa flag, o modelo entende que precisa decidir: tenta de novo com argumento diferente, pede esclarecimento ao usuário, ou admite que não consegue. Na prática o Fable 5 reage bem a mensagens de erro específicas — "ticker não existe" funciona melhor que um stack trace cru. Pense na mensagem como um prompt dentro do prompt.

Limitações honestas do Claude Fable 5 tool use

Fora da beta de structured outputs, não há garantia de 100% de conformance ao schema. Em schemas com muitos campos opcionais ou enums grandes, o modelo às vezes alucina valores. A mitigação é reduzir o espaço do schema e manter enums fechados.

Latência também pesa: cada round trip adiciona 500ms–2s dependendo do tamanho do histórico. Um loop de cinco passos síncrono pode levar dez segundos de resposta final. Para UX conversacional isso é lento — considere streaming do raciocínio intermediário ou cache agressivo em tools frequentes.

Próximos passos

Claude Fable 5 tool use é a primitiva mais poderosa da API — abre caminho para agentes, structured output confiável e integrações profundas com seu sistema. Comece com um tool simples, meça o custo, aplique caching, depois escale para o loop multi-step. Para outros guias de IA aplicada publicados pela ModoDev, visite o site.