Deferred Tools
将大量 MCP/外部工具的完整 schema 延迟到需要时再加载的工具发现机制，用“先搜索、后展开”降低 Agent 初始上下文成本。
简介
Deferred Tools 是 Claude Code 工具调用体系中的一种规模化工具加载机制，用来解决 MCP server 和外部工具数量不断增长后，工具 name、description 和 input schema 全部塞进初始请求导致上下文成本过高的问题。它的核心思路是：工具先以“可被搜索的候选能力”存在，不一定在每次模型请求中带完整 schema；当模型需要某类工具时，先调用工具搜索能力发现名称；下一轮请求构造时，客户端再把已发现工具的完整定义加入工具列表。
这套机制把工具加载从“一次性全量暴露”改为“按需发现、渐进展开”。它与 Skill 的渐进式披露有相似哲学：Skill 启动时先加载 name + description，任务命中后再读取完整 SKILL.md 和 references；Deferred Tools 则先避免把所有工具 schema 放进模型上下文，等模型通过搜索找到某个工具后，再让该工具完整可调用。两者都在解决同一个底层问题：Agent 能力越来越多，但上下文窗口和注意力是有限资源。
关键信息
- 类型：Agent 工具发现与延迟加载机制
- 解决问题：MCP/外部工具数量过多时，完整 schema 占用大量 prompt token
- 核心流程：客户端过滤未发现工具 → 模型调用搜索工具 → 搜索结果写入对话 → 下一轮客户端解析已发现工具名 → 加载完整 schema
- 关键原则：工具是否进入请求由客户端本地过滤决定，不是服务端动态决定
- 默认模式：文章核对到
ENABLE_SEARCH_EXTRA_TOOLS未设置时默认tst - 相关概念：Claude Code 工具调用机制、MCP 模型上下文协议、Function Calling、上下文工程、Skill
核心特性
本地过滤：未发现工具不进入本次请求
Deferred Tools 的关键不只是“服务端少展示 schema”，而是客户端在构造请求前就会过滤工具列表。客户端会扫描对话历史，找出已经被搜索结果暴露过的工具名，得到“已发现集合”。之后只有三类工具会进入本次请求：不需要延迟的核心工具、搜索工具本身、已经被发现过的 deferred 工具。尚未发现的 deferred 工具直接不进 tools 数组。
这意味着模型第一轮并不知道所有工具的完整定义。它需要通过 SearchExtraToolsTool 一类搜索工具提出需求，先发现工具名，再在后续轮次里调用。工具可见性从“静态全量”变成了“会话历史驱动”。
发现编码：搜索结果以文本写回对话
原文指出，搜索结果不再依赖 API 原生的 tool_reference 内容块，而是以纯文本格式写入工具结果，例如 “Found N deferred tool(s): …”。客户端后续用正则从对话历史中解析这些工具名。这样做的好处是可以兼容不同 provider 和历史格式，代价是客户端必须维护一套从历史消息中提取已发现工具的逻辑。
这种设计也说明 Deferred Tools 并不是“模型看到轻量 schema 后直接调用”，而是“搜索结果成为下一轮请求构造的证据”。真正让工具进入下一轮完整工具列表的是客户端历史扫描，而不是本次搜索调用立即修改工具列表。
三种模式：tst、tst-auto、standard
文章核对后的配置为 ENABLE_SEARCH_EXTRA_TOOLS：
ENABLE_SEARCH_EXTRA_TOOLS 模式
auto / auto:1-99 tst-auto
true / auto:0 tst
false / auto:100 standard
(未设置) tst- tst：默认延迟加载模式，MCP 工具和 deferred 工具固定带上延迟加载标记。
- tst-auto：只有延迟工具定义 token 总量超过阈值时才真正启用延迟，否则退化为全部内联。
- standard：关闭延迟加载，所有工具完整内联；部分不支持 beta 特性的网关代理可能需要这种兜底模式。
tst-auto 的阈值按“当前模型上下文窗口 × 百分比”计算，默认百分比为 10%，也可以用 auto:N 指定。百分比越低越容易触发延迟加载，节省初始 prompt token，但模型可能多花一轮搜索工具。
与 MCP 的关系
Deferred Tools 对 MCP 模型上下文协议 特别重要，因为 MCP server 往往会暴露大量工具。如果每个 server 的每个工具都把完整 schema 放进模型请求，用户还没开始任务，上下文就可能被工具定义占掉大量空间。Deferred Tools 让 MCP 工具生态可扩展：连接更多 server 不必线性增加每轮请求的 schema 成本。
但它不替代 MCP。MCP 负责外部工具和数据源的标准化接入；Deferred Tools 负责在 Agent 会话里何时让这些工具的完整定义进入上下文。可以理解为：MCP 是“工具从哪里来、如何调用”，Deferred Tools 是“工具什么时候被模型看见”。
不同素材中的观点
- 2026-07-05-juejin-claude-code-tool-calling：文章把 Deferred Tools 放在 Claude Code 工具调用机制的“规模化设计”部分，指出其核心是让大量 MCP/外部工具先不全量占用上下文，而是通过 SearchExtraToolsTool 搜索后再进入后续请求。它特别纠正了若干旧命名：实际环境变量是
ENABLE_SEARCH_EXTRA_TOOLS，默认模式是tst；搜索结果是纯文本编码而非 API 原生tool_reference；工具是否进入请求是客户端本地过滤决定的。
实用信息
什么时候需要 Deferred Tools
- MCP server 很多：连接多个 SaaS、数据库、搜索、设计、部署工具时，完整 schema 会迅速膨胀。
- 工具长尾明显：大多数任务只会用少数工具，不值得每轮都加载全部定义。
- 模型上下文昂贵：长任务更需要把上下文留给代码、日志、业务材料和推理，而不是工具说明。
- 工具描述相似：大量相似工具内联时容易干扰模型选择，先搜索可减少初始混淆。
设计类似机制的注意点
- 搜索工具本身必须永远可见，否则无法自举。
- 已发现工具集合需要能跨会话压缩或上下文压缩保留，否则压缩后模型可能反复搜索同一工具。
- 搜索结果格式要稳定，方便客户端从历史中解析工具名。
- 如果 provider 或网关不支持延迟加载 beta，需要能退回 standard 全量内联模式。
- 延迟加载会节省上下文，但可能增加一轮工具搜索，适合工具很多的场景，不一定适合极少工具的小项目。
与相近概念的区别
| 概念 | 解决什么 | 机制 |
|---|---|---|
| Function Calling | 模型如何请求调用函数 | 模型输出函数名和 JSON 参数，应用执行 |
| MCP 模型上下文协议 | 外部工具如何标准化接入 | 用协议暴露工具、资源和数据源 |
| Deferred Tools | 工具太多时如何少占上下文 | 未发现工具先不进请求，搜索后再加载完整 schema |
| Skill 渐进式披露 | 程序性知识太多时如何按需读取 | 先用 name/description 触发，再读 SKILL.md 和 references |