# 工具使用与 prompt caching
跨轮次缓存工具定义，了解什么会导致缓存失效。
---
本页介绍工具定义的 prompt caching：在哪里放置 `cache_control` 断点，`defer_loading` 如何保护你的缓存，以及什么会导致缓存失效。有关一般 prompt caching，参见 [Prompt caching](/docs/en/build-with-claude/prompt-caching)。
## 工具定义上的 cache_control
在 `tools` 数组的最后一个工具上放置 `cache_control: {"type": "ephemeral"}`。这会缓存整个工具定义前缀，从第一个工具到标记的断点：
```json
{
"tools": [
{
"name": "get_weather",
"description": "Get the current weather in a given location",
"input_schema": {
"type": "object",
"properties": {
"location": { "type": "string" }
},
"required": ["location"]
}
},
{
"name": "get_time",
"description": "Get the current time in a given time zone",
"input_schema": {
"type": "object",
"properties": {
"timezone": { "type": "string" }
},
"required": ["timezone"]
},
"cache_control": { "type": "ephemeral" }
}
]
}
```
对于 `mcp_toolset`，`cache_control` 断点位于集合中的最后一个工具上。你无法控制 MCP toolset 内的工具顺序，因此将断点放在 `mcp_toolset` 条目本身上，API 会将其应用到最后展开的工具。
## defer_loading 与缓存保护
延迟加载的工具不包含在系统提示前缀中。当模型通过 [tool search](/docs/en/agents-and-tools/tool-use/tool-search-tool) 发现延迟工具时，定义作为 `tool_reference` 块内联追加到对话历史中。前缀未被修改，因此 prompt caching 得以保留。
这意味着通过 tool search 动态添加工具不会破坏你的缓存。你可以从一小组始终加载的工具（已缓存）开始对话，让模型根据需要发现额外工具，并在每一轮保持相同的缓存命中。
`defer_loading` 也独立于 [strict mode](/docs/en/agents-and-tools/tool-use/strict-tool-use) 的语法构建而工作。语法从完整工具集构建，无论哪些工具被延迟，因此 prompt caching 和语法缓存在工具动态加载时都得以保留。
## 什么会导致缓存失效
缓存遵循前缀层次结构（`tools` -> `system` -> `messages`），因此一个层级的更改会使该层级及之后的所有内容失效：
| 更改 | 失效范围 |
|---|---|
| 修改工具定义 | 整个缓存（tools、system、messages） |
| 切换 web search 或 citations | System 和 messages 缓存 |
| 更改 `tool_choice` | Messages 缓存 |
| 更改 `disable_parallel_tool_use` | Messages 缓存 |
| 切换图片存在/不存在 | Messages 缓存 |
| 更改 thinking 参数 | Messages 缓存 |
如果你需要在对话中途变化 `tool_choice`，考虑将缓存断点放在变化点之前。
## 各工具交互表
| 工具 | 缓存注意事项 |
|---|---|
| [Web search](/docs/en/agents-and-tools/tool-use/web-search-tool) | 启用或禁用会使 system 和 messages 缓存失效 |
| [Web fetch](/docs/en/agents-and-tools/tool-use/web-fetch-tool) | 启用或禁用会使 system 和 messages 缓存失效 |
| [Code execution](/docs/en/agents-and-tools/tool-use/code-execution-tool) | 容器状态独立于 prompt cache |
| [Tool search](/docs/en/agents-and-tools/tool-use/tool-search-tool) | 发现的工具作为 `tool_reference` 块加载，保留前缀缓存 |
| [Computer use](/docs/en/agents-and-tools/tool-use/computer-use-tool) | 截图存在与否影响 messages 缓存 |
| [Text editor](/docs/en/agents-and-tools/tool-use/text-editor-tool) | 标准客户端工具，无特殊缓存交互 |
| [Bash](/docs/en/agents-and-tools/tool-use/bash-tool) | 标准客户端工具，无特殊缓存交互 |
| [Memory](/docs/en/agents-and-tools/tool-use/memory-tool) | 标准客户端工具，无特殊缓存交互 |
## 下一步
了解完整的 prompt caching 模型，包括 TTL 和定价。
按需加载工具而不破坏缓存。
浏览所有可用工具及其参数。