Ferramentas no Claude: quanto as definições custam

Onde as ferramentas entram na conta

A documentação de uso de ferramentas da Anthropic lista três fontes de tokens extras quando você passa tools numa chamada:

• o parâmetro tools, com nome, descrição e esquema de cada ferramenta;
• os blocos tool_use, que o modelo gera ao pedir uma ferramenta;
• os blocos tool_result, que o seu código devolve com o resultado.

Há ainda um quarto custo, menos conhecido. Sempre que há ferramentas, a API acrescenta um prompt de sistema próprio para o uso delas. No Sonnet 5.5, no Opus 5.5 e no Haiku 5.5, são 286 tokens com tool_choice em auto, segundo a página de preços consultada em 20/10/2026. Em modelos mais antigos, o número é maior:

Esses 286 tokens parecem pouco. Mas, no Sonnet 5.5, somam US$ 572,00 a cada milhão de chamadas, antes de qualquer definição sua.

O ponto central é outro. As definições vão inteiras em toda chamada, e o modelo lê todas, use ou não. Num agente com dezenas de ferramentas, elas viram a maior parte da entrada.

Passo 1: monte o tamanho de cada chamada

As premissas do caso, todas de exemplo:

• 60 ferramentas com 300 tokens cada, em média: 18.000 tokens de definições. Meça as suas com o endpoint de contagem de tokens da API, porque descrições longas e esquemas com muitos campos pesam mais.
• 286 tokens do prompt de sistema de ferramentas do Sonnet 5.5.
• 2.000 tokens de instruções da empresa.
• 1.500 tokens que mudam a cada chamada: histórico curto, pergunta do cliente e resultados de ferramentas.
• 300 tokens de saída por chamada.

A parte fixa, que se repete igual em todas as chamadas, é de 20.286 tokens. Somada à parte variável, cada chamada leva 21.786 tokens de entrada. As definições são 83% disso.

No mês: 1.000 pedidos × 4 chamadas × 30 dias = 120.000 chamadas.

Passo 2: a conta sem nenhuma otimização

Pela tabela de preços do site, atualizada em outubro de 2026, o Sonnet 5.5 cobra US$ 2,00 por milhão de tokens de entrada e US$ 10,00 por milhão de saída.

• Entrada: 120.000 × 21.786 tokens a US$ 2,00 por milhão.
• Saída: 120.000 × 300 tokens a US$ 10,00 por milhão.

Total: US$ 5.588,64 por mês, cerca de R$ 27.996,85 pelo dólar de referência do site. Só as definições das ferramentas custam US$ 4.320,00. A saída, que muita gente olha primeiro por ser a mais cara por token, custa US$ 360,00.

Passo 3: ligue o cache de prompt

As definições ficam no começo da requisição, antes do prompt de sistema e das mensagens. Isso faz delas o candidato ideal ao cache de prompt: são grandes e não mudam entre chamadas.

No Sonnet 5.5, a leitura do cache custa US$ 0,10 por milhão, e a gravação de 5 minutos, US$ 2,50. Com 4.000 chamadas por dia, o prefixo é lido o tempo todo no horário de trabalho. Usamos 95% de acerto como exemplo.

O prefixo de 20.286 tokens passa a custar, em média, US$ 0,2200 por milhão, em vez de US$ 2,00. O mês cai para US$ 1.255,55, uma queda de 78%.

É de longe a mudança que mais rende. E não exige mexer no agente: basta marcar o ponto de cache depois das ferramentas e das instruções fixas.

Passo 4: some a busca de ferramentas

A Anthropic oferece uma ferramenta de busca de ferramentas (tool search). Você continua enviando todas as definições, mas marca as menos usadas com defer_loading: true. Essas não entram no contexto. Quando o agente precisa de uma delas, faz uma busca no catálogo, e a API carrega só as encontradas, até 5 por busca no padrão.

A documentação traz um exemplo próprio: um conjunto de servidores comuns (GitHub, Slack, Sentry, Grafana e Splunk) consome cerca de 55 mil tokens em definições, e a busca costuma reduzir isso em mais de 85%. A busca não é cobrada como ferramenta de servidor. As definições carregadas contam como entrada normal.

No nosso caso, de exemplo:

• 5 ferramentas mais usadas ficam sempre carregadas, como recomenda a documentação. O prefixo cai para 3.786 tokens.
• Em cada chamada, o agente carrega 3 ferramentas pela busca: 900 tokens a preço normal de entrada.
• A busca acrescenta cerca de 40 tokens de saída por chamada.

A conta não inclui os tokens da definição da própria ferramenta de busca, que a documentação não informa. Meça no seu caso.

Com cache, o mês fica em US$ 1.083,95. Sem cache, só com a busca, em US$ 1.892,64.

A comparação lado a lado

A leitura é direta. O cache faz o trabalho pesado. A busca de ferramentas, somada ao cache, ganha mais 14% no custo.

O ganho da busca não é só dinheiro. A documentação da Anthropic diz que a precisão na escolha da ferramenta piora quando o agente tem mais de 30 a 50 ferramentas disponíveis. Com 60, o caso já está nessa faixa.

E se trocar de modelo?

O mesmo agente, com todas as ferramentas carregadas, em três modelos Claude:

O Haiku 5.5 cobra mais caro quando o prompt passa de 100 mil tokens por requisição. Com 21.786 tokens por chamada, o caso fica abaixo desse limite. Um agente com centenas de ferramentas carregadas pode cruzar a linha, e aí a busca de ferramentas ajuda também a manter o preço menor.

Erros comuns

• Descrição longa demais. Cada ferramenta carregada paga a descrição inteira em toda chamada. Corte exemplos e repetições que não ajudam o modelo a escolher.
• Conectar servidores MCP inteiros sem filtrar. Um servidor pode trazer dezenas de ferramentas que o seu agente nunca usa. Desligue as que sobram ou marque como defer_loading.
• Mudar a lista de ferramentas a cada chamada. Qualquer mudança em nome, descrição ou parâmetro de uma ferramenta invalida o cache. No caso, cada regravação do prefixo custa US$ 0,0507. Isso é pouco uma vez, mas vira muito se a lista muda sempre.
• Pôr cache_control numa ferramenta adiada. A API devolve erro 400. Coloque o ponto de cache numa ferramenta que fica sempre carregada.
• Adiar todas as ferramentas. Pelo menos uma precisa ficar carregada, normalmente a própria busca. Senão, a API devolve erro 400.
• Usar busca com poucas ferramentas. A documentação indica a busca a partir de 10 ferramentas ou de 10 mil tokens em definições. Abaixo disso, carregar tudo costuma ser melhor.

Perguntas frequentes

As ferramentas são cobradas mesmo quando o modelo não usa nenhuma?

Sim. As definições enviadas em tools contam como entrada em toda chamada. No exemplo, são 18.000 tokens por chamada e US$ 4.320,00 por mês no Sonnet 5.5 sem cache.

Quantos tokens o uso de ferramentas soma por conta própria?

O prompt de sistema de ferramentas tem 286 tokens no Sonnet 5.5, no Opus 5.5 e no Haiku 5.5, com tool_choice em auto. No Sonnet 5.5, isso dá US$ 572,00 por milhão de chamadas. As suas definições vêm por cima disso.

A busca de ferramentas tem preço à parte?

Não. Pela documentação, ela não é medida como ferramenta de servidor. As definições que a busca carrega contam como tokens de entrada comuns. No caso, as 3 ferramentas carregadas por chamada somam US$ 216,00 por mês.

Mudar uma ferramenta quebra o cache?

Sim. As ferramentas ficam no começo do prefixo, e qualquer mudança nelas obriga a gravar tudo de novo. Com todas as ferramentas carregadas, cada regravação custa US$ 0,0507. Com a busca, o prefixo é menor e a regravação cai para US$ 0,0095.

Vale mais a pena usar cache ou busca de ferramentas?

Comece pelo cache. No exemplo, ele leva o mês de US$ 5.588,64 para US$ 1.255,55. A busca, depois do cache, baixa para US$ 1.083,95 e ainda ajuda o agente a escolher a ferramenta certa quando a lista é grande.

Quanto fica o caso em reais?

Sem otimização, R$ 27.996,85 por mês. Com cache e busca de ferramentas, R$ 5.430,16, pelo dólar de referência do site.

Quer refazer a conta com o seu número de ferramentas, o seu modelo e o seu volume? Use a calculadora de custo da API de IA e, para o efeito do cache, a calculadora de cache de prompt.