I Edited One Line of a Tool Description and the Whole Prompt Cache Rebuilt — Where to Place cache_control Breakpoints

Reorder blocks by stability

The whole design comes down to this: the less often something changes, the further upstream it goes. In my pipeline it settled into roughly this order.

My original mistake was baking position 4 — the day's dynamic reference data — plus a current timestamp into position 2, the system prompt. The system prompt should be a very stable block, but I was injecting a daily-changing string into it, so everything from system downward died every day.

The fix was simple. I evicted every mutable value from system and passed the dynamic reference data as a late user message instead. Tools and system became fixed strings, with the first breakpoint at the boundary between them. That alone brought read_ratio back from near zero to the 0.8 range.

You only get four breakpoints — where to spend them

cache_control is capped at four per request. Rather than scattering them, place them at the steps in stability — the points where "everything up to here should match the previous request."

With several breakpoints, Claude automatically reads the longest prefix that matches the previous request. So the earlier breakpoints act as insurance for when a deeper cache expires. If the third (just before the dynamic reference data) is invalidated by today's update, the hits up to the first and second (tools and system) still survive. It is graded protection, not all-or-nothing.

One caveat: there is a minimum cacheable prefix length, and prefixes that are too short are not cached at all (roughly 1,024 tokens for most models, longer for Haiku). When your tool definitions are small, the first breakpoint may not take effect, so confirm whether cache_creation_input_tokens was ever recorded there — that tells you the spot is actually being cached.

Implementation: build messages in "stability layers"

Translating the design into code looks like this. The trick is to push mutable values out to the outermost layer as function arguments and never touch the stable layers.

import anthropic
 
client = anthropic.Anthropic(api_key="YOUR_API_KEY")
 
# ── Stable layer (do not change daily) ──────────────
TOOLS = [
    {
        "name": "publish_article",
        "description": "Registers an article into the target repository.",  # editing this invalidates everything
        "input_schema": {
            "type": "object",
            "properties": {"slug": {"type": "string"}, "locale": {"type": "string"}},
            "required": ["slug", "locale"],
        },
        # breakpoint at the end of tools (1st)
        "cache_control": {"type": "ephemeral"},
    }
]
 
SYSTEM = [
    {
        "type": "text",
        "text": "You are a technical blog editor. The output rules and permanent policy are ... (fixed string only)",
        # breakpoint at the end of system (2nd)
        "cache_control": {"type": "ephemeral", "ttl": "1h"},
    }
]
 
 
def build_messages(daily_reference: str, user_input: str) -> list:
    # ── Volatile layer (changes every call / every day) — placed last, in user
    return [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": f"Today's reference data:\n{daily_reference}"},
                {"type": "text", "text": user_input},
            ],
        }
    ]
 
 
def run(daily_reference: str, user_input: str):
    resp = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=2048,
        tools=TOOLS,
        system=SYSTEM,
        messages=build_messages(daily_reference, user_input),
    )
    return resp

The point is to not put daily_reference (the daily-changing string, like the day's news) inside SYSTEM. Keep SYSTEM and TOOLS as fixed strings and route mutable values through the build_messages arguments into the trailing user message only. Then you can swap the reference data every day and the tools and system caches survive.

When reordering still does not help

Sometimes read_ratio will not recover even after you fix the order. Here are the ones I have hit.

First, leaving a timestamp or UUID inside system. A single line like "Last updated: 2026-06-24 19:45" makes system a different object every time. As a rule, evict anything that looks dynamic from system.

Second, rebuilding tool definitions from a dict per request with unstable key order. If the JSON serialization order wobbles, the content is identical but the string differs, and the match breaks. Build tool definitions once as a module-level constant.

Third, switching models. Caches are separate per model, so a pipeline that bounces between claude-sonnet-4-6 and Haiku warms each cache independently. If your design changes models on fallback, accept that read_ratio will dip temporarily.

Make a hit-rate regression something you'll notice

Even after a good reordering, a casual one-line edit later can put you right back into cascade invalidation. Since I run this unattended, I keep a tiny watchdog that logs whenever the hit rate drops below a threshold.

def assert_cache_healthy(usage, *, min_read_ratio=0.5, warmed=True):
    h = cache_health(usage)
    # on later (warmed) calls, falling below this ratio suggests an ordering regression
    if warmed and h["read_ratio"] < min_read_ratio:
        print(
            f"⚠️ cache read_ratio={h['read_ratio']} "
            f"(created={h['created']}, read={h['read']}) — check upstream volatility"
        )
        return False
    return True

Watching the number lets you catch the moment a "just smoothing the wording" edit shows up in the bill. As an indie developer running this without a babysitter, it took me a few days to notice the first incident — once this watchdog was in place, I could touch the system prompt and tool definitions without holding my breath.

For your next step, log cache_creation_input_tokens and cache_read_input_tokens from one of your own API responses. If creation is still large on the second request, a volatile string is hiding somewhere upstream. Move it to the tail, and the cost numbers answer back honestly.