Your agent burned 7,600 tokens before it said hello

Tool definitions ship on every single turn and nobody adds them up. I costed a real agent loop using the numbers in Anthropic's own documentation.

Bu yazının Türkçesi: Türkçe sürüm.

When people build an AI agent, all the attention goes to the output. How many tokens did it write, what did that cost. Meanwhile most of the bill is incurred before the model writes a single word: tool definitions.

Telling a model "here are the tools you may use" is not free. Every tool's name, description and JSON schema goes into the request. And it goes in again on every turn of the conversation. Anthropic publishes these numbers one by one in its pricing documentation. I sat down and added them up, and the total surprised me.

The price list for tool definitions

The figures below are for Claude Opus 5, as of 1 August 2026. Other models move by a few hundred tokens.

Read that line again: the browser toolset is 6,610 tokens. That is as much text as a whole blog post. And you have not written the user's question yet.

Setting up an agent, you typically switch on several at once. Browser plus bash plus text editor:

6,610  browser toolset (includes the tool-use system prompt)
  325  bash
  700  text editor
------
7,635  tokens, before the user has said anything

Opus 5 input is $5 per million tokens. So 7,635 × 5 / 1,000,000 = 3.8 cents per request. For a single request that is a laughable amount of money. Hold on.

What happens across a thirty-turn loop

Agents do not make single requests. The model calls a tool, a result comes back, it thinks again, it calls another. Thirty turns is an ordinary number — an agent that finds and fixes a bug in a codebase will comfortably do that.

And on every turn the full set of tool definitions is sent again. The model does not remember the conversation; you re-send the entire history and every tool definition each time.

The cached row works out like this: the first turn writes to cache at 1.25x base input, i.e. $6.25 per million, so 7,635 × 6.25 / 1,000,000 = $0.048. The remaining 29 turns read at a tenth of base input, i.e. $0.50 per million: 29 × 7,635 × 0.50 / 1,000,000 = $0.111. Total $0.16.

Seven times cheaper. And the only thing producing that difference is putting a cache_control field on top of the tool definitions. One line.

Anthropic's docs state the rule clearly: a 5-minute cache pays for itself after one read, a 1-hour cache after two. In an agent loop the second turn arrives seconds later. So there is no argument for leaving tool definitions uncached.

The real danger: large documents entering the context

Tool definitions are fixed and predictable. The genuine shock comes from what the agent fetches itself.

The web fetch tool carries no surcharge — you only pay for the tokens of what it brings back. Anthropic's docs give example sizes:

Say your agent pulls a PDF on turn five. Those 125,000 tokens are now in the context and they will sit there for the rest of the conversation. Across the remaining 25 turns they are billed again every time:

• Uncached: 25 × 125,000 = 3.1 million tokens, which is $15.60 on Opus 5
• Cached: one write ($0.78) plus 24 reads ($1.50) = $2.28

One PDF. Fifteen dollars. Now multiply by the three tabs the agent opened because it decided to "do some research".

The rule I took from this: always pass max_content_tokens on web fetch calls. The docs already recommend it; what nobody says out loud is why. Without a limit, a file your agent happens to download determines the cost of the entire session.

Server-side tools have their own separate bills

There are line items outside tokens too. These belong in your spreadsheet as their own rows:

Web search is measured in cents and looks trivial: ten searches, ten cents. But the results enter the context and the arithmetic above takes over from there. The search is cheap; carrying its results is expensive.

Code execution being free alongside the web tools looks like a deliberate incentive, and if it suits your workload, take it.

The detail I like most in managed agent sessions: runtime only accrues while the model is actually working. Time spent idle waiting for the user's next message is not billed. So leaving a conversation open costs nothing.

Four things I do in practice

1. Always cache tool definitions. That seven-times difference above has exactly one cause. One line of change.
2. Turn off toolset members I don't use. Disabling zoom on the computer toolset gives back ~410 tokens; not enabling the browser toolset's four optional members saves ~880. Small on its own, not small across thirty turns.
3. Cap everything fetched. I make no web fetch call without max_content_tokens.
4. Prune long context. Once the agent has read a file and finished with it, the whole file does not need to stay in the conversation. Replacing it with a summary is a discount on every remaining turn.

One measurement to run yourself

Every number here is an estimate published by Anthropic; the only way to know what a specific request of yours actually cost is to look at the usage field on the response. There is also a token counting endpoint if you want to know in advance.

Here is the experiment I recommend everyone building agents runs once: send a request that does nothing at all, just says "hello" — but with all of your tools declared. Look at usage.input_tokens. That number is the fixed tax you pay on every turn. Most people are surprised the first time they see it.

← All posts