Articles / claudepromptingllmops
How to prompt Claude with fewer tokens and the same quality
Cut Claude API token spend with structured system prompts, XML tags, prompt caching, compact context and smaller tool outputs. With cost math and a script.
A short prompt and a cheap prompt are different things. A two-line request that leaves Claude guessing gets a vague answer, then three follow-ups, and each follow-up resends everything said so far. A longer prompt that states the task, the inputs and the output shape often finishes in one turn and costs less.
This post covers the habits that lower the token bill on the Claude API and in Claude Code without making answers worse: fixed rules in the system prompt, XML structure, prompt caching, compact context instead of full history, reusable templates, smaller tool outputs and output control. It ends with a worked cost calculation, a script that compares three context strategies, and a check that a compressed context still carries the facts the next task needs.
Prices and limits below were checked against Anthropic's docs on 22 November 2026. They change, so check the pricing page before you budget.
Where the tokens go#
Every Messages API request is stateless. Claude sees what you send in that request and nothing else, so a 20-turn chat sends turn 1 twenty times. The request is assembled in a fixed order, and that order decides what can be cached:
request N
+--------------------------------------------------+
| tools (definitions, rarely change) | <- stable prefix,
| system (role, rules, reference docs) | cacheable
+--------------------------------------------------+
| messages turn 1 user / assistant | <- grows every turn,
| turn 2 user / assistant | resent every turn
| ... |
| turn N user (the new question) | <- changes every turn
+--------------------------------------------------+
|
v
output tokens (answer + thinking) <- billed at 5x the input price
For Claude Sonnet 5.5 the base rates are $2 per million input tokens and $10 per million output tokens; Claude Opus 5.5 is $4 and $20. So there are three levers: send fewer input tokens, make repeated input cheaper through caching, and stop paying for output nobody reads.
1. State fixed rules once, in the system prompt#
People often paste the same paragraph of preferences into every message. Move it to the system prompt and keep user turns for the task. Write the rules as a list, because a list is shorter than prose and each rule is easy to find and edit.
A paragraph like this costs tokens on every turn and buries the rules in filler:
I'd like you to behave as a really experienced Python developer and whenever
I ask for code please make sure it is clean and readable, that it follows the
usual Python conventions, that it handles errors properly, that it has helpful
comments and good variable names, and that you explain the important parts.
The same intent as a system prompt:
You are a senior Python engineer.
Rules:
- Follow PEP 8.
- Prefer small functions over clever ones.
- Handle errors at I/O and network boundaries.
- Comment only where the reason is not obvious from the code.
- After the code, explain any decision a reviewer might question.
The second version is also more precise. "Helpful comments" invites a comment on every line; "comment only where the reason is not obvious" does not. Fewer tokens and clearer rules usually come together, because padding is where the ambiguity hides.
2. Separate instructions from material with XML tags#
When a prompt mixes instructions, reference text and examples, Claude has to work out which part is which. Anthropic's prompting best practices recommend wrapping each kind of content in its own tag, such as <instructions>, <context> and <input>. There is no special tag vocabulary; consistent, descriptive names are what matter.
<task>
Find the recurring complaints in the customer reviews below.
</task>
<instructions>
1. Group complaints into at most six categories.
2. For each category, quote two reviews as evidence.
3. Give three fixes, ordered by how many reviews they address.
</instructions>
<reviews>
{{REVIEWS}}
</reviews>
<output_format>
A table of category, count, evidence; then the three fixes as a numbered list.
</output_format>
Tags save tokens indirectly. A clear output format stops the model from writing an introduction and a recap you didn't ask for, and a separated <reviews> block stops it from treating a review that says "ignore the above" as an instruction. Tags also give you a stable place to cut: the instructions stay fixed and only {{REVIEWS}} changes, which is exactly the shape prompt caching wants.
3. Cache the part that does not change#
Prompt caching lets Claude reuse the processed form of a prefix it saw recently. You mark a breakpoint with cache_control, and later requests that start with the same bytes read that prefix at a fraction of the input price. The numbers, from the prompt caching docs:
| Model | Base input | 5-minute cache write | Cache read | Output |
|---|---|---|---|---|
| Claude Sonnet 5.5 | $2.00 | $2.50 | $0.10 | $10.00 |
| Claude Opus 5.5 | $4.00 | $5.00 | $0.20 | $20.00 |
| Claude Haiku 5.5 (prompts up to 100K) | $0.10 | $0.125 | $0.01 | $0.50 |
All prices are per million tokens. A 5-minute write costs 1.25 times base input, a 1-hour write costs 2 times, and a read costs 0.1 times on most models. Opus 5.5 and Sonnet 5.5 are cheaper still at 0.05 times. The 5-minute timer resets each time the entry is read, so steady traffic keeps it warm.
The rules that trip people up:
- There is a minimum size. On the Claude API the shortest cacheable prefix is 512 tokens for Opus 5.5, Sonnet 5.5 and Haiku 5.5, 1,024 for Sonnet 4.6 and Opus 4.8, and 4,096 for Opus 4.6 and Haiku 4.5. A shorter prefix is processed without caching and no error comes back.
- It is a prefix match. The cache key covers everything up to the breakpoint, in the order tools, system, messages. A timestamp in the system prompt, a tool list in a different order or a per-user ID near the top changes the prefix and every request misses.
- Up to 4 breakpoints. Or put one
cache_controlat the top level of the request and let automatic caching place it on the last cacheable block, moving it forward as the chat grows. - Check the usage fields.
cache_creation_input_tokensandcache_read_input_tokensin the response tell you what happened. If both stay at 0 across repeated requests, you are under the minimum or something in the prefix is changing.
Worked numbers#
Take a support bot on Sonnet 5.5 with a 6,013-token system prompt (rules plus a policy document) and a 20-turn conversation.
Without caching, the system prompt alone costs 6,013 x $2 / 1,000,000 = $0.0120 per turn, or $0.2405 across 20 turns.
With caching, turn 1 writes it: 6,013 x $2.50 / 1,000,000 = $0.0150. Turns 2 to 20 read it: 19 x 6,013 x $0.10 / 1,000,000 = $0.0114. Total $0.0265, about 11% of the uncached figure. The write premium is paid back on the second request, because 1.25 + 0.05 = 1.30 times base input is less than the 2 times you pay for two uncached sends.
That covers only the system prompt. The script further down includes the growing history too.
4. Stop resending history the next task does not need#
A long chat carries old code drafts, dead ends and outputs that were superseded ten turns ago. Each new turn pays for all of it again, and a cluttered context also makes answers worse, because the model has more irrelevant text to weigh.
Replace the transcript with a compact state block when you move to a new subtask:
<project_context>
Project: churn prediction API
Stack: Python 3.12, FastAPI, XGBoost, Docker
Status: model trained, /predict endpoint live
Constraint: do not change the model or its feature order
Open issue: /predict accepts malformed input; needs request validation
</project_context>
<task>
Add request validation to /predict with Pydantic. Return 422 with field-level
errors. Do not touch model loading.
</task>
Keep five things in it: the goal, the stack and key files, what is done, the decisions already made, and what is still broken. For a codebase, that state belongs in a CLAUDE.md file that Claude Code loads at the start of each session (see the memory docs). Keep it short, since it is sent with every request. Claude Code's cost guide also recommends /clear between unrelated tasks and /compact with instructions, for example /compact Focus on code samples and API usage, to steer what the summary keeps.
On the API you have two server-side options:
- Context editing (beta header
context-management-2025-06-27) clears old tool results withclear_tool_uses_20250919, or old thinking blocks withclear_thinking_20251015, once input passes a trigger you set. You can keep the last N tool uses and exclude tools whose results must stay. See context editing. - Compaction replaces older turns with a summary Claude writes on the server, either on demand or at a token threshold. Both modes are in beta. See the compaction overview.
Trimming and caching pull against each other. Clearing or summarising content changes the prefix, so the next request writes a new cache entry instead of reading the old one. The context editing docs suggest clear_at_least so each clearing removes enough tokens to be worth the new write. Summarise in occasional large steps, not a little every turn.
5. Keep templates for repeated work#
If you run the same kind of task every week (code review, SQL tuning, paper summaries, incident write-ups), save the prompt as a file with one slot for the variable part:
<role>Senior Python and ML engineer.</role>
<checklist>
- Correctness, including edge cases
- Performance on large inputs
- Security: injection, secrets, unsafe deserialisation
- Error handling at boundaries
</checklist>
<output>
1. Bugs that would break production, with line references
2. Other improvements, most important first
3. Rewritten code only for the parts that change
</output>
<code>
{{CODE}}
</code>
A template saves the tokens you would spend re-explaining the job and the follow-up turns when you forget a requirement. It also keeps the fixed part byte-identical, so it caches when the fixed part is long enough to pass the minimum. Line 3 of the output block matters: asking for changed parts only stops Claude from reprinting a 300-line file to change four lines.
6. Give tools and retrieval a narrow scope#
In agent workflows, tool results are often the largest part of the context. "Look through the project and find why prediction fails" can pull dozens of files into the window. Name the files and the shape of the answer instead:
Read app/routes/predict.py and app/schemas.py.
Trace how a /predict request is validated.
Report the failing line and a proposed fix. Do not paste whole files.
The same applies to your own tools. Return the 20 log lines around the error instead of the whole log, structured JSON instead of an HTML page, and the top 5 retrieved chunks instead of the top 30. If you run retrieval, the chunking and reranking choices in the RAG cheat sheet decide how many tokens each answer carries. Aim for the smallest set of evidence that still answers the question; cutting below that sends the model guessing and costs you a retry.
7. Control output, the expensive side#
Output costs five times as much as input on these models. Three controls help:
- Ask for the shape you need. "Return only the changed function", "answer in at most five bullets" or a fixed JSON schema all cut length.
- Set effort.
output_config.efforttakeslow,medium,high,xhighormaxand controls how many tokens Claude spends, including thinking. Per the effort docs, most models default tohigh, while Opus 5.5 and Haiku 5.5 default tomedium. Classification and short chat replies often hold up atlow; measure before you lower it on hard tasks. - Set
max_tokensas a ceiling, not a target. It cuts the answer off mid-sentence when hit, which costs a retry. Use it to stop runaway output, and rely on instructions and effort for normal length.
Measure before and after#
Anthropic's token counting endpoint (POST /v1/messages/count_tokens) takes the same system prompt, messages, tools, images and PDFs as a real request and returns input_tokens. It is free, with its own rate limit (5,000 requests per minute on the Start tier) separate from message creation. The docs call the count an estimate that can differ slightly from the billed number. Counts are model-specific, so pass the model you will call. Do not use OpenAI's tiktoken for this; it is a different tokenizer.
The script below compares three ways to run the same 20-turn conversation: resend everything uncached, resend everything with automatic caching, and send a short summary plus the last four turns with only the system prompt cached. It runs offline. Token counts come from a chars/4 estimate, which is labelled APPROX in the output; set USE_REAL_COUNT=1 with an API key and the anthropic package to use the real endpoint instead. That path is not exercised here.
"""Estimate what a multi-turn Claude conversation costs under three context strategies.
Runs offline. Token counts come from a rough chars/4 estimate (labelled APPROX),
not from Claude's tokenizer. Swap in AnthropicCounter to get real counts from the
free /v1/messages/count_tokens endpoint.
"""
import math
import os
# USD per million tokens, from platform.claude.com/docs/en/about-claude/pricing (checked 2026-11-22)
PRICES = {
"claude-opus-5-5": {"input": 4.00, "write_5m": 5.00, "read": 0.20, "output": 20.00},
"claude-sonnet-5-5": {"input": 2.00, "write_5m": 2.50, "read": 0.10, "output": 10.00},
}
MIN_CACHEABLE = 512 # tokens, for Opus 5.5 / Sonnet 5.5 on the Claude API
class ApproxCounter:
"""Offline estimate: about 4 characters per token for English prose. APPROX only."""
label = "APPROX chars/4"
def count(self, system: str, messages: list[dict]) -> int:
text = system + "".join(m["content"] for m in messages)
return math.ceil(len(text) / 4)
class AnthropicCounter:
"""Real counts (input side). Needs `pip install anthropic` and an API key.
Not exercised in the demo run below. In production, read output tokens from
response.usage instead of counting them."""
label = "count_tokens endpoint"
def __init__(self, model: str):
from anthropic import Anthropic
self.client, self.model = Anthropic(), model
def count(self, system: str, messages: list[dict]) -> int:
return self.client.messages.count_tokens(
model=self.model, messages=messages, **({"system": system} if system else {})
).input_tokens
def cost(model, uncached=0, cache_write=0, cache_read=0, output=0):
p = PRICES[model]
return (uncached * p["input"] + cache_write * p["write_5m"]
+ cache_read * p["read"] + output * p["output"]) / 1_000_000
def run(model, counter, system, turns, strategy, keep_last=4, summary=""):
"""Simulate `turns` requests. Returns total cost and input tokens sent."""
system_tokens = counter.count(system, [])
if strategy != "no_cache" and system_tokens < MIN_CACHEABLE:
print(f" warning: system prompt is {system_tokens} tokens, under the "
f"{MIN_CACHEABLE} minimum, so it will not cache")
history, total, sent = [], 0.0, 0
prev_history_tokens = 0
for user_msg, reply in turns:
history.append({"role": "user", "content": user_msg})
if strategy == "summary" and len(history) > keep_last * 2:
visible = [{"role": "user", "content": summary}] + history[-keep_last * 2:]
else:
visible = history
hist_tokens = counter.count("", visible)
out_tokens = counter.count("", [{"role": "assistant", "content": reply}])
sent += system_tokens + hist_tokens
if strategy == "no_cache":
total += cost(model, uncached=system_tokens + hist_tokens, output=out_tokens)
elif strategy == "cache":
# Automatic caching: the breakpoint moves to the last block, so each turn
# reads everything the previous request wrote and writes only the new part.
if prev_history_tokens == 0:
total += cost(model, cache_write=system_tokens + hist_tokens, output=out_tokens)
else:
total += cost(model, cache_read=system_tokens + prev_history_tokens,
cache_write=hist_tokens - prev_history_tokens, output=out_tokens)
else:
# Breakpoint on the system prompt only; the sliding window is sent uncached.
sys_part = {"cache_write": system_tokens} if prev_history_tokens == 0 \
else {"cache_read": system_tokens}
total += cost(model, uncached=hist_tokens, output=out_tokens, **sys_part)
history.append({"role": "assistant", "content": reply})
prev_history_tokens = hist_tokens
return total, sent
if __name__ == "__main__":
model = "claude-sonnet-5-5"
counter = AnthropicCounter(model) if os.getenv("USE_REAL_COUNT") else ApproxCounter()
# A 24,000-character policy document in the system prompt (~6,000 tokens).
system = "You answer questions about the refund policy below.\n" + ("Policy clause text. " * 1200)
# 20 turns: a 600-char question and a 1,600-char answer each (~150 and ~400 tokens).
turns = [("Q" * 600, "A" * 1600) for _ in range(20)]
summary = "S" * 1200 # a ~300-token running summary of older turns
print(f"model={model} counter={counter.label}")
print(f"system prompt: {counter.count(system, [])} tokens\n")
print(f"{'strategy':<26}{'input tokens sent':>18}{'cost (USD)':>12}")
base = None
for name, label in [("no_cache", "full history, no cache"),
("cache", "full history + cache"),
("summary", "summary + last 4 turns")]:
c, sent = run(model, counter, system, turns, name, summary=summary)
base = base or c
print(f"{label:<26}{sent:>18,}{c:>12.4f} ({c / base:.0%} of baseline)")
out = sum(counter.count("", [{"role": "assistant", "content": r}]) for _, r in turns)
print(f"\noutput tokens: {out:,} -> {cost(model, output=out):.4f} USD in every strategy")
Output from python3 token_budget.py:
model=claude-sonnet-5-5 counter=APPROX chars/4
system prompt: 6013 tokens
strategy input tokens sent cost (USD)
full history, no cache 227,760 0.5355 (100% of baseline)
full history + cache 227,760 0.1426 (27% of baseline)
summary + last 4 turns 164,160 0.1943 (36% of baseline)
output tokens: 8,000 -> 0.0800 USD in every strategy
Three things stand out:
- Caching beat summarising in this setup, even though the summary strategy sent 28% fewer tokens. A cache read at $0.10 per million is so cheap that resending a cached history costs less than sending a shorter one uncached. Summarising still matters once the history gets long enough to hurt answer quality or approach the context window, and when you do it, put a breakpoint after the summary so the new prefix caches too.
- Output is now most of the bill. With caching on, $0.08 of the $0.14 is output. The next saving comes from section 7, not from trimming input further.
- The estimate is rough. Real text tokenizes differently from repeated letters, and code or non-English text usually takes more tokens per character. Run the real counter on your actual prompts before you trust a budget. To track real spend per feature over time, log
response.usagewith a tracker like the one in Build an LLM cost and latency tracker in Python.
Check that quality held#
Saving tokens is only a win if the answers stay as good. Two cheap checks catch most regressions.
First, test the compact context itself. A summary that drops a constraint will produce confident wrong work. This check lists the facts the next task depends on and fails if any are missing:
"""Check that a compact context summary still carries the facts the next task needs."""
REQUIRED = {
"stack": ["fastapi", "xgboost"],
"status": ["model trained"],
"constraint": ["do not change the model"],
"open issue": ["input validation"],
}
summary = """<project_context>
Project: churn prediction API. Stack: Python 3.12, FastAPI, XGBoost, Docker.
Status: model trained, /predict endpoint live.
Constraint: do not change the model or its feature order.
</project_context>"""
def missing_facts(text: str) -> list[str]:
low = text.lower()
return [k for k, needles in REQUIRED.items() if not all(n in low for n in needles)]
gaps = missing_facts(summary)
print("missing:", gaps or "nothing")
print(f"summary size: {len(summary)} chars, about {len(summary) // 4} tokens (APPROX)")
missing: ['open issue']
summary size: 218 chars, about 54 tokens (APPROX)
The summary forgot the bug it was written to fix. Keyword matching is crude, but it is free and runs in CI; a model-graded check can replace it once the fact list grows.
Second, run the old prompt and the new prompt over a fixed set of 20 to 50 real inputs and compare the outputs with the same grader you use elsewhere, alongside tokens and cost per input. If the new prompt is cheaper and the scores hold, ship it. If scores drop, find which part of the trim caused it before going further.
Failure modes#
- Cache never hits. The prefix is under the model's minimum, or something in it changes per request: a date, a request ID, unsorted JSON, a tool list built from a set. Compare two request bodies byte by byte.
- Cache hits but the bill barely moves. The cached part is small next to the uncached history or the output. Look at where the tokens are before tuning the wrong part.
- Over-trimmed context. Claude asks for information you removed, or contradicts an earlier decision. That follow-up turn costs more than the tokens you saved.
- Terse prompts that need follow-ups. Count tokens per finished task, not per request. A prompt that takes three rounds is more expensive than one that takes one longer round.
- Switching model or effort mid-conversation. A cache entry belongs to the model that wrote it, so routing turns between models pays the write price again on each switch. The caching docs also list a changed
effortvalue as something that can invalidate cached messages.
Start with caching and a short, stable system prompt, because they need no change to how anyone writes questions. Then measure per finished task, and trim history and output where the numbers show the spend.