Tool calling token cost: one call, four stages, four lines on the bill

By Christophe Paka · Facts checked on 23 October 2026

Your agent's API bill keeps climbing. The tools themselves run on your own machine, so they should be free. Yet people say their agents are eating the budget alive, and the invoice has no line called tools.

The cost hides in the text about each tool, not in running it. Once you see where the tool calling token cost lands, you can cut it. A token is a small piece of text, about part of a word, and the model provider bills by the token. The figure below follows one tool call through four stages and marks where each one is billed.

Four boxes left to right: Schema, written once; Call, the model asks; Run, your code executes; Result, sent back. Under each, the bill: input tokens every turn, output tokens once, nothing from the model, input tokens on later turns.
Figure 5.1: One tool call, four stages, four lines on the bill. Your function running is free; everything the model reads and writes about it is not. Read the four stages from left to right.
Use this diagram on your site

Free to share in your blog post, docs, course or slides, as long as the credit link stays. Paste the code below where the figure should go.

How to read this figure

  1. Box 1: the schema you write once. The schema is the tool's name, its description and its input_schema, the list of inputs it takes. You write it once. But the box under it says it is billed as input tokens on every turn of the run, whether a tool is called or not.

  2. Box 2: the call, in orange. The model asks for the tool. Its answer sets stop_reason to tool_use and holds a block with an id, a name and an input. The model wrote that text, so it is billed as output tokens once. On every later turn it goes back as input tokens.

  3. Box 3: the run costs nothing here. Your code executes the function. The model runs nothing. So the model provider bills nothing for this stage. Your own API and compute bill still applies, for example the database or service the tool calls.

  4. Box 4: the result you send back. Your code sends a tool_result block with the tool_use_id and the output. It is billed as input tokens this turn, and again on every later turn that resends the transcript.

  5. Read the line under the dashes. The note at the bottom ties it together. Every turn resends the whole tools array plus everything above it in the transcript. So a schema is billed once per turn, not once per run.

Key takeaways

  • Count your schemas once per turn, not once per run, when you estimate what a run costs.
  • Return only the fields the next step needs: every tool result is billed again on later turns.
  • Rate your tool set by overlap, not count: merge or sharpen two tools whose descriptions blur.

Worked example: ten turns, twelve tools

Take one run of ten turns with twelve tool definitions. Follow each stage of the figure through the run.

  1. Schemas: all twelve go out with every request. Ten turns means the twelve definitions are paid for ten times.
  2. Calls: each request the model writes is billed once as output, then rides along as input on every turn after it.
  3. Runs: the provider bills nothing for your function. Only your own servers and services cost money here.
  4. Results: a long tool result on turn 2 is read again on turns 3 to 10, and billed each time.

Result: Most of the bill is text the model reads again and again. To cut it, use fewer tools, keep results short, and keep the run short.

Questions readers ask

How do I stop my agent burning money on tokens?

Start with what repeats. Your tool schemas and every past result are resent on each turn. Keep the tool set small and distinct, return short results, and cap the number of turns. Then set a spend limit on your account, so a runaway run stops at a known cost.

Is there a separate fee for tool calls?

Not for tools your own code runs. Anthropic's docs say tools you define are priced the same as any other API request, so they show up as input and output tokens. Some tools Anthropic runs itself, such as web search, carry their own fee per search.

Can I track cost per agent, or only the total bill?

You can split it. Count the tokens of one request with and without tools, on the model you run; the difference is your tool surface per turn. Multiply by turns and runs. See the hidden token bill for the fixed part every request carries.

Sources: Tool use overview (Claude docs); Pricing (Claude docs).

This figure is from AI Agents Made Crystal Clear, chapter 5.

The chapter builds the idea step by step, with recipes you can follow, a Try it to check yourself, and every source.

Get the book

All diagrams