Canonical: https://botbento.com/blog/claude-tool-definition-token-cost/
Format: Markdown representation of the public HTML page.

[Home](/) / [Blog](/blog/)

FIELD NOTES / 5 MIN READ

# How Much Do Your Bot's Tool Definitions Actually Cost on the Claude API?

Declaring a tool in Claude's API adds input tokens to every request that includes it, and a default agent loop resends the full tool list, system prompt, and transcript on every turn. Anthropic's own documentation gives concrete token overheads for its computer-use toolset and explains why uncached multi-turn tasks scale roughly with the square of turn count. This piece works through what that means for a small-team bot with several custom tools, and which levers (caching, compaction, batching) actually cut the bill.

By BotBento Editorial · Published 2026-11-09 · Updated 2026-11-09

AI-assisted editorial: researched and drafted with AI using the primary sources linked below. Check the cited evidence and any stated test scope. Illustrative examples are not measured product results. [Editorial policy](/editorial/).

## In this article

- [Tool definitions are billed on every call, whether or not the model uses them](#the-direct-answer)
- [Illustrative example: a 20-turn support bot without caching](#worked-example)
- [Prompt caching is the first lever, and the discount depends on the model](#what-shrinks-the-bill)
- [What to actually check before you add another tool](#decision)[Read as Markdown ](/text/blog/claude-tool-definition-token-cost/index.md)

## Key takeaways

- A tool definition is tokenized and billed as input on every call that includes it, not just the call that uses it — Anthropic reports about 735 input tokens per tool definition for its computer-use tool and roughly 4,500 tokens for the default computer-use toolset.
- Without prompt caching, an agent loop resends the system prompt, every tool definition, and the whole prior transcript each turn, so a 40-turn task effectively pays for turn one 40 times and cost grows close to the square of turn count.
- Turning on prompt caching before any other cost lever is the single highest-leverage fix: cache reads cost 5-10% of the standard input price depending on the model, versus the full resend cost without it.

## Tool definitions are billed on every call, whether or not the model uses them

When you declare a tool in Claude's tools array, the API tokenizes that definition and counts it as input on every request that includes it — not just requests where the model actually calls it. Anthropic's pricing documentation gives a concrete figure for its own computer-use tool family: declaring the default computer-use toolset adds roughly 4,500 input tokens to a request, with small per-model variation, and disabling the zoom capability removes about 410 of those tokens. For the earlier, per-tool version of the same capability, Anthropic reports the system prompt overhead separately from the tool itself: a few hundred tokens for the system prompt plus about 735 input tokens for each tool definition.

Those numbers are specific to Anthropic's own server-side tools, but the mechanism is general: every tool your bot declares, custom or built-in, gets serialized into the request and counted. Anthropic's documentation points builders to two ways to find the exact number for their own tool set: the usage field returned with every response, and a dedicated token-counting endpoint you can call before you ship. If you are running five or ten custom tools with detailed JSON schemas, that overhead is not hypothetical — it is a line item on every single call your bot makes, successful or not.

Sources: [Pricing - Claude Platform Docs](https://platform.claude.com/docs/en/about-claude/pricing).

## Illustrative example: a 20-turn support bot without caching

Here is an illustrative scenario to show the shape of the problem, not a measured BotBento result. Say a small-team support bot carries five tool definitions (ticket lookup, calendar write, email draft, a web search tool, and a file reader) plus a system prompt, and it runs a 20-turn task resolving one ticket. By default, an agentic loop resends the entire growing conversation on every turn: the system prompt, every tool definition, and every prior turn's messages and tool results. Anthropic's own cost guidance states this plainly for its own agent loops: a 40-turn task sends its first turn 40 times, so total task cost grows with roughly the square of turn count, not linearly with it.

Apply that shape to the 20-turn illustrative bot: turn 1 pays for the system prompt and tool definitions once. Turn 2 pays for all of that again, plus turn 1's output. Turn 20 pays for everything from turns 1 through 19, plus the tool definitions, one more time. If your five tool definitions and system prompt together run a few thousand tokens — not unusual once JSON schemas, descriptions, and examples are included — that fixed cost gets multiplied by every turn of every run, and it is the same few thousand tokens whether or not any given turn actually calls a tool.

Sources: [Optimizing for cost and intelligence - Claude Platform Docs](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence).

## Prompt caching is the first lever, and the discount depends on the model

Anthropic's cost-optimization guidance is explicit that prompt caching is the lever to turn on before any other: it does not stop the resending, but it changes what each resend costs. A cache write costs 1.25x the base input price for a 5-minute cache or 2x for a 1-hour cache, and a cache hit (reading from that cache on a later turn) costs a fraction of the standard input rate — 10% generally, but only 5% on Claude Opus 5.5 and Claude Sonnet 5.5, and 2.5% on Claude Fable 5.1 and Claude Mythos 5.1. Anthropic's release notes for Claude Opus 5.5 confirm this model is the current flagship covered by that lower cache-read rate, which is worth checking directly if you are weighing whether to route a tool-heavy loop through it. In practice this means the same resent system prompt and tool definitions can cost a tenth, a twentieth, or a fortieth of the uncached price depending on which model is running the loop.

Two further details matter once caching is on. First, if your loop relies on context compaction instead of (or alongside) caching, Anthropic recommends setting the compaction trigger a little below 100,000 tokens minus your prompt's largest single-turn growth, rather than leaving the default at 150,000; in Anthropic's own test with 10,000-token turns, a trigger of 90,000 cost 70% less per request than the default. Second, cache duration is a real choice, not a formality: Anthropic's guidance says to use the 1-hour cache when roughly one turn in twenty follows a pause between five minutes and an hour, because a duration mismatch forces a full rewrite of the cached prefix at the write price. Anthropic's own example puts that miss at $0.80 for a 100,000-token prompt on Claude Opus 5.5, against roughly $0.02 for a normal cache read.

Sources: [Optimizing for cost and intelligence - Claude Platform Docs](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence), [What's new in Claude Opus 5.5 - Claude Platform Docs](https://platform.claude.com/docs/en/models/opus-5-5/whats-new-opus-5-5).

## What to actually check before you add another tool

Three checks are worth doing before you bolt another tool onto a bot's connected set. First, measure the fixed overhead: call the token-counting endpoint or read the usage field on a representative request with your full tool list attached, so you know the per-call baseline before a single turn of real work happens. Second, turn on prompt caching for the system prompt and tool definitions as a default, not an optimization you'll get to later — Anthropic's own guidance frames it as the first lever precisely because every other saving (compaction, batching, trimming schemas) compounds on top of it rather than replacing it. Third, if your bot's loop is long-running and non-interactive, route it through the Batch API, which Anthropic's pricing documentation describes as a 50% discount on both input and output tokens for asynchronous processing, and check whether that discount stacks with your cache hit rate for your specific model.

The practical takeaway for a small-team bot: the cost of connecting a tool is not just whatever the tool itself does when called. It is a recurring line item on every request your bot sends while that tool is declared, and in an uncached multi-turn loop, that line item gets paid again on every single turn. Before you decide whether a tool is worth connecting, check its definition's token size with the counting endpoint, and before you decide whether a model is affordable for a tool-heavy agent loop, check that model's specific cache-read discount — the difference between a 5% and 10% cache-read rate is the difference between a resend costing twice as much or not, turn after turn.

Sources: [Optimizing for cost and intelligence - Claude Platform Docs](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence), [Pricing - Claude Platform Docs](https://platform.claude.com/docs/en/about-claude/pricing).

## Primary sources

Sources checked 2026-11-09. Standards and product documentation can change; follow the linked version when implementing.

- [Pricing - Claude Platform Docs](https://platform.claude.com/docs/en/about-claude/pricing) — Anthropic
- [Optimizing for cost and intelligence - Claude Platform Docs](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence) — Anthropic
- [What's new in Claude Opus 5.5 - Claude Platform Docs](https://platform.claude.com/docs/en/models/opus-5-5/whats-new-opus-5-5) — Anthropic

BotBento is in development. [Suggest a correction](/contact/).
