Ferramentas novas no meio da conversa sem perder cache

O que mudou

Em 22 de setembro de 2026, a Anthropic lançou em beta as ferramentas definidas na própria conversa (cabeçalho inline-tools-2026-09-15), segundo as notas de versão da Claude Platform. Com ele, o seu código pode acrescentar uma ferramenta, ou mudar a definição de uma, sem editar o campo tools da requisição.

A ferramenta nova vai num bloco tool_addition, dentro de uma mensagem com papel system no fim de messages. Para tirar uma ferramenta, existe o bloco tool_removal, que só aceita referência pelo nome.

A documentação explica por que isso importa para a fatura. O cache de prompt compara o prefixo da requisição na ordem tools, depois system, depois messages. A comparação é exata, byte a byte. Como tools fica no começo, qualquer mudança ali invalida o cache de tudo o que vem depois. Uma mensagem de sistema no fim da conversa não mexe no que já foi guardado. Só o trecho novo é processado como entrada nova.

Quem pode usar

As mensagens de sistema no meio da conversa valem para Fable 5.1, Opus 5.5, Opus 5, Opus 4.8, Sonnet 5.5 e Haiku 5.5, entre outros listados na documentação. O Sonnet 5 fica de fora e deve continuar usando o campo system do topo.

Passo 1: quanto custa uma sessão com cache funcionando

Premissas do exemplo:

• 20.000 tokens fixos no começo: ferramentas iniciais e instruções.
• Cada passo acrescenta 2.000 tokens ao histórico: resultado de ferramenta, pergunta e resposta.
• 500 tokens de saída por passo.
• Cache de 5 minutos ligado, com todo o histórico relido a cada passo.

Pela tabela de preços do site, atualizada em outubro de 2026, o Sonnet 5.5 cobra US$ 0,10 por milhão na leitura do cache, US$ 2,50 na gravação de 5 minutos e US$ 10,00 na saída.

Somando os 40 passos, a sessão lê 2.360.000 tokens do cache, grava 100.000 e gera 20.000 de saída. Custo da sessão: US$ 0,69.

Passo 2: o que cada troca de ferramenta custava

No jeito antigo, o agente mudava o campo tools três vezes, nos passos 10, 20 e 30. Cada mudança obrigava a gravar de novo todo o contexto acumulado até ali, a US$ 2,50 por milhão, em vez de lê-lo a US$ 0,10.

Três trocas deixam a sessão 61% mais cara: de US$ 0,69 para US$ 1,10. Quanto mais tarde a troca, mais caro, porque o contexto regravado é maior.

Com a definição na conversa, o custo da troca vira o da própria definição. Três ferramentas de 300 tokens, gravadas no cache como trecho novo, somam US$ 0,0023 por sessão.

Passo 3: a conta do mês

Com 50 sessões por dia e 22 dias úteis, são 1.100 sessões no mês.

Os valores em reais usam o dólar de referência do site e não incluem IOF nem impostos.

Passo 4: o peso da troca em cada modelo

A perda por troca depende da distância entre o preço de gravar e o de ler o cache. A tabela usa a troca do passo 20, com 58.000 tokens de contexto:

Preços por milhão de tokens. No Fable 5.1, uma única troca no meio de uma sessão longa custa US$ 0,71. Em agentes caros, o recurso pesa mais.

Quando o recurso não faz diferença

Se você já sabe de antemão todas as ferramentas que o agente pode usar, declarar tudo no começo também funciona. Com cache, carregar 10 ferramentas a mais, de 300 tokens cada, custa US$ 0,0195 por sessão de 40 passos no Sonnet 5.5. É pouco. O ganho real aparece em três situações:

• ferramentas que só existem depois de um evento, como o login do cliente;
• esquemas que mudam no meio da tarefa;
• servidores MCP conectados durante a conversa.

Para ligar e desligar ferramentas já declaradas, a referência por nome resolve, e ela também funciona no Bedrock e no Google Cloud.

Cuidados antes de ligar

• Deixe pelo menos uma ferramenta fixa em tools. Se o campo não tiver nenhuma ferramenta sem defer_loading, a primeira definida por valor muda o começo do prompt e provoca uma falha de cache completa. A ferramenta de busca de ferramentas conta como fixa.
• O cache precisa estar ligado. A mensagem de sistema não cria entrada de cache sozinha. Sem cache_control, nada é guardado.
• Posição importa. A mensagem com tool_addition vem logo depois de um turno user. Colocá-la entre um tool_use e o tool_result correspondente gera erro 400.
• Não reescreva mensagens antigas. Mudar ou reenviar diferente qualquer mensagem anterior quebra o cache a partir dela.
• Nem toda ferramenta entra. A de uso do computador, por exemplo, ainda não pode ser definida na conversa e retorna erro 400.
• Sonnet 5.5 e Haiku 5.5 pedem atenção. A documentação avisa que esses modelos podem tratar como texto não confiável uma mensagem de sistema que vem depois de um resultado de ferramenta. Para repassar algo que o usuário pediu no meio da tarefa, use um bloco de texto na própria mensagem do usuário.

Perguntas frequentes

Definir ferramenta na conversa tem preço extra?

A documentação não traz preço próprio para os blocos tool_addition e tool_removal. O conteúdo novo é processado como entrada nova, e o prefixo já guardado é lido do cache. No exemplo, três definições somam US$ 0,0023 por sessão.

Mudar o prompt de sistema do topo também quebra o cache?

Sim. O campo system vem logo depois de tools no prefixo. Editar uma frase nele tem o mesmo efeito de trocar uma ferramenta: no passo 20 do caso, US$ 0,1392 a mais no Sonnet 5.5. Uma mensagem de sistema no fim da conversa evita isso.

Quanto o recurso economiza no mês do exemplo?

US$ 459,36, cerca de R$ 2.301,21, em 1.100 sessões com três trocas cada. Com uma troca só, no passo 20, a economia do mês fica em US$ 153,12.

Funciona no Bedrock?

Em parte. Ligar e desligar ferramentas já declaradas funciona no Bedrock e no Google Cloud. Definir ferramenta nova por valor e acrescentar servidor MCP no meio da conversa, por enquanto, só na Claude API.

Preciso mudar algo se uso o Sonnet 5?

O Sonnet 5 não aceita mensagens de sistema no meio da conversa. Nele, continue usando o campo system e planeje as ferramentas para não trocá-las durante a sessão.

Quer ver quanto o cache rende no seu agente? Use a calculadora de cache de prompt com o tamanho do seu contexto e a sua taxa de acerto.

Leia também: Ferramentas no Claude: quanto as definições custam