Caching is a prefix match, and that single fact decides everything about it. The first byte that changes invalidates every byte after it, so one volatile line — a timestamp, a request id, the user's question — sitting in front of twenty-five thousand stable tokens means none of those tokens are cached. The fix is always the same shape: stable content first, volatile content last. What is not obvious is the cost of getting it wrong, which is why this puts a number on it. Enter the blocks of your request with how often each one changes, and it sorts them, measures the prefix, and prices the difference across as many requests as you make.
Features
Blocks sorted into the order that maximises the prefix
Names which stable blocks are stranded behind volatile ones
Measures the cacheable prefix and the part paid for every time
Warns when the prefix is below the minimum and will silently not cache
Prices the difference across a run of requests
Flags occasionally-changing blocks, which invalidate everything after them
Cache-read rates per model, with the date they were checked
Editable block sizes, so it matches your request
How to use the Prompt Cache Planner
List the blocks of your request with their sizes
Mark how often each one changes
Read the recommended order and what it saves
Move your cache breakpoint to the end of the stable prefix
Example
Input
User question (300) sent first
Output
29,500 stable tokens cannot be cached
One volatile block at the front invalidates everything behind it.
Common errors & troubleshooting
My cache hit rate is zero. — Something volatile is inside the prefix. A timestamp, a request id, or a tool list that is not in a stable order will each do it on their own.
The prefix is below the minimum. — Short prefixes are not cached at all, and nothing tells you. Either make the prefix larger or accept that caching will not apply.
It caches sometimes and not others. — Usually a block that changes occasionally sitting early. Every change invalidates everything after it, so an occasional change is an occasional full-price request.
Reordering would change the meaning. — Then it is a real trade-off. Anything that must stay in place is a constraint; the tool shows what it costs so the decision is informed rather than accidental.
Frequently asked questions
How does prompt caching actually work?
The request is matched against what was cached by prefix. Everything up to the first difference is served from the cache at a fraction of the price; everything after it is charged in full. This is why order is the whole game.
What invalidates a cache silently?
Anything that changes bytes early: a timestamp in the system prompt, a request id, a tool list built from an unordered map, a per-user field. None of them raise an error — the hit rate simply drops.
Why is there a minimum prefix?
Below a model-dependent size, caching is not applied at all. It fails quietly, so a small system prompt you believe is cached may never have been.
Where should the cache breakpoint go?
At the end of the last stable block. Everything before it is reused; everything after is fresh each time, which is exactly the split the ordering here produces.
Is caching always worth it?
When a large prefix is genuinely reused, yes — the read rate is a fraction of the input rate. It is not worth contorting a request that has no stable prefix to begin with, which is what the error here tells you.
Related tools
Agent Loop Cost Estimator — Cost an agent loop turn by turn, with history re-sent and caching applied.
Context Window Planner — Budget a context window across prompt, tools, history and the reply.