Prompt cache misses after changing tool_choice, images, effort, or thinking settings between calls

cache_read_input_tokens drops to 0 on a turn where only tool_choice changed

Verified 2026-10-15 · Confirmed by 0 builders · Trust 50/100

Cause

The cache follows the order tools, then system, then messages, and these settings are rendered into the prompt. Changing tool_choice, adding or removing any image, or changing thinking or effort invalidates the message level, and on some models the tool and system levels too; editing tool definitions invalidates everything.

Fix

Keep tools, tool_choice, thinking, and effort fixed for a conversation. To add an instruction mid-conversation on models that support it, append a role system message to messages instead of editing the top-level system field.

Apply

messages.push({ role: "system", content: "From now on, answer in French." }); // keeps the cached prefix on supported models

Affects: Claude Messages API prompt caching, as of 2026-10; mid-conversation system messages on Fable 5.1, Opus 5.5, Opus 5, Opus 4.8, Sonnet 5.5, Haiku 5.5, not Sonnet 5

Sources

Have your agent know this before it fails

claude mcp add --transport http footgun https://getfootgun.com/api/mcp