To get cache hits, put stable content first and changing content last, keep tool definitions and system text byte for byte identical between requests, append to history instead of rewriting it, and verify hits in the usage fields. Most cache misses come from small edits made early in the prompt.
1. Order from stable to volatile
The prefix is built as tools, then system prompt, then messages. Put long instructions, reference documents, and examples near the top. Put the current user question, the date, and any per user details at the end. Provider guidance for another major API gives the same advice: stable instructions and tool definitions first, dynamic content such as timestamps last.
2. Freeze the tool list
Per the Claude documentation, changing tool names, descriptions, or parameters invalidates the whole cache: tools, system, and messages. If your agent adds or removes tools per request, you reset the cache every time. Keep one fixed list and steer behavior with the tool_choice setting instead of deleting definitions.
3. Watch the settings that look harmless
The invalidation table in the documentation lists several changes people do not expect to matter:
- Toggling web search or citations invalidates the tools level.
- Changing
tool_choiceinvalidates tools and system. - Adding or removing images invalidates tools and system.
- Changing thinking parameters can invalidate cached content, depending on the model.
- Changing a fixed thinking budget between requests invalidates message level breakpoints.
Pick a configuration at the start of a conversation and hold it.
4. Append, do not rewrite
If you trim or summarize earlier turns on every request, the prefix changes and the cache resets. Append new turns. When you must shrink history, do it in larger, less frequent steps so each new prefix gets reused many times.
5. Clean the volatile bits out of the prefix
Search your system prompt template for anything generated at request time: current time, request IDs, random examples, user names, feature flag dumps. Move them below the last breakpoint or into the user message.
6. Place breakpoints on purpose
You can set up to four breakpoints, and automatic caching uses one of them. Mark the end of the large, stable block, not the end of the whole prompt, if the tail changes every time.
7. Verify with numbers
After a change, send the same request twice within the cache lifetime and read the usage object. The second response should show a large cache_read_input_tokens. If both cache fields are zero, check the minimum length for your model first.
8. Remember workspace isolation
Caches are isolated per organization and, on the first party API, per workspace. A staging key in a different workspace will not warm the production cache.
Quick check
What is the fastest way to find out why caching stopped working?
Diff the first thousand tokens of two consecutive requests. A timestamp, reordered tools, or changed setting near the top is the usual cause.
Should every prompt use caching?
No. Short prompts below the model minimum are not cached, and prompts used once gain nothing while a cache write costs a little more than normal input.
Sources
Last reviewed: 19 October 2026.
