Repository Public
1---2title: Tool use with prompt caching3url: https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching4description: Cache tool definitions across turns and understand what invalidates your cache.5---67This page covers prompt caching for tool definitions: where to place `cache_control` breakpoints, how `defer_loading` preserves your cache, and what invalidates it. For general prompt caching, see [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching).89## cache\_control on tool definitions1011Place `cache_control: {"type": "ephemeral"}` on the last tool in your `tools` array. This caches the entire tool-definitions prefix, from the first tool through the marked breakpoint:1213```json14{15 "tools": [16 {17 "name": "get_weather",18 "description": "Get the current weather in a given location",19 "input_schema": {20 "type": "object",21 "properties": {22 "location": { "type": "string" }23 },24 "required": ["location"]25 }26 },27 {28 "name": "get_time",29 "description": "Get the current time in a given time zone",30 "input_schema": {31 "type": "object",32 "properties": {33 "timezone": { "type": "string" }34 },35 "required": ["timezone"]36 },37 "cache_control": { "type": "ephemeral" }38 }39 ]40}41```4243For `mcp_toolset`, the `cache_control` breakpoint lands on the last tool in the set. You don't control tool order within an MCP toolset, so place the breakpoint on the `mcp_toolset` entry itself and the API applies it to the final expanded tool.4445The [computer use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool) and [browser use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool) toolset entries follow the same rule: place `cache_control` on the toolset entry itself, and the breakpoint lands after the toolset's definition. It isn't accepted inside a member's `configs` entry, because the toolset's members load as one definition. Within a [batch action](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool#batch-actions), a `cache_control` marker on any of the turn's member `tool_use` or `tool_result` blocks is accepted and takes effect at the end of that batch, so several markers in one batch act as a single breakpoint. Each marker still counts toward the request's limit of [four breakpoints](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#when-to-use-multiple-breakpoints), so use one per turn.4647## defer\_loading and cache preservation4849Deferred tools are not included in the system-prompt prefix. When the model discovers a deferred tool through [tool search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool), the definition is appended inline as a `tool_reference` block in the conversation history. The prefix is untouched, so prompt caching is preserved.5051This means adding tools dynamically through tool search does not break your cache. You can start a conversation with a small set of always-loaded tools (cached), let the model discover additional tools as needed, and keep the same cache hit across every turn.5253`defer_loading` also acts independently of grammar construction for [strict mode](https://platform.claude.com/docs/en/agents-and-tools/tool-use/strict-tool-use). The grammar builds from the full toolset regardless of which tools are deferred, so prompt caching and grammar caching are both preserved when tools load dynamically.5455## What invalidates your cache5657The cache follows a prefix hierarchy (`tools` → `system` → `messages`), so a change at one level invalidates that level and everything after it:5859| Change | Invalidates |60| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |61| Modifying tool definitions | Entire cache (tools, system, messages) |62| Toggling web search or citations | System and messages caches |63| Changing `tool_choice` | Messages cache |64| Changing `disable_parallel_tool_use` | Messages cache |65| Toggling images present/absent | Messages cache |66| Changing thinking parameters | Messages cache always; tool and system caches too on models that render the thinking configuration ahead of them ([details](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-prompt-caching)) |67| Changing `output_config.effort` | Same as thinking parameters; setting the model's default explicitly is equivalent to omitting it |6869<Note>70 If you need to vary `tool_choice` mid-conversation, consider placing cache breakpoints before the variation point.71</Note>7273## Server tool results are cached automatically7475When your request has prompt caching enabled and Claude uses a [server tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools) such as web search, web fetch, or code execution, the API automatically places a cache breakpoint on the server tool result before running the next iteration of the agentic loop. This lets later iterations within the same request read the growing prefix from cache instead of reprocessing it.7677This automatic breakpoint always uses the default 5-minute TTL, independent of any TTL you set on your own `cache_control` markers. In the response `usage`, these writes appear under `cache_creation.ephemeral_5m_input_tokens`, so you may see 5-minute cache writes even when every `cache_control` you set uses a 1-hour TTL.7879This behavior only applies when your request already has at least one `cache_control` marker. Requests without prompt caching do not receive the automatic breakpoint.8081## Per-tool interaction table8283| Tool | Caching considerations |84| --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |85| [Web search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool) | Enabling or disabling invalidates the system and messages caches |86| [Web fetch](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool) | Enabling or disabling invalidates the system and messages caches |87| [Code execution](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool) | Container state is independent of prompt cache |88| [Tool search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool) | Discovered tools load as `tool_reference` blocks, preserving prefix cache |89| [Computer use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool) | Screenshot presence affects messages cache; `cache_control` goes on the toolset entry (see [cache\_control on tool definitions](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching#cache-control-on-tool-definitions)) |90| [Browser use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool) | Screenshot presence affects messages cache; `cache_control` goes on the toolset entry (see [cache\_control on tool definitions](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching#cache-control-on-tool-definitions)) |91| [Text editor](https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool) | Standard client tool, no special caching interaction |92| [Bash](https://platform.claude.com/docs/en/agents-and-tools/tool-use/bash-tool) | Standard client tool, no special caching interaction |93| [Memory](https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool) | Standard client tool, no special caching interaction |9495## Next steps9697<CardGroup cols={3}>98 <Card title="Prompt caching" icon="database" href="https://platform.claude.com/docs/en/build-with-claude/prompt-caching">99 Learn the full prompt caching model, including TTLs and pricing.100 </Card>101102 <Card title="Tool search" icon="magnifying-glass" href="https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool">103 Load tools on demand without breaking your cache.104 </Card>105106 <Card title="Tool reference" icon="book" href="https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference">107 Browse all available tools and their parameters.108 </Card>109</CardGroup>110