主题
07.5 工具规模化与 Tool Search
当你有上百个 MCP 工具时，它们的定义会撑爆上下文。Tool Search 是解药。
读完你能做什么：在接入大量工具的同时，把它们对上下文的占用降到最低。
一、问题：工具定义的固定开销
回顾 03.1：每个工具的定义（名字 + 描述 + 参数 schema）常驻上下文。
text
1 个工具定义 ≈ 100-500 token
装了：
GitHub server ≈ 30 个工具
Jira server ≈ 25 个工具
Slack server ≈ 20 个工具
内部 DB server ≈ 15 个工具
Notion server ≈ 20 个工具
───────────────────────────
合计 110 个工具 ≈ 可能 2-5 万 token 常驻这些 token 在你还没说任何话之前就被占掉了，且每一轮都在消耗。
二、Tool Search 的原理
Tool Search 把工具从"全部常驻"改成"按需加载"：
text
不用 Tool Search：
110 个工具定义全部塞进上下文 → 固定占用 2-5 万 token
用 Tool Search：
上下文里只放一个"搜索工具的工具" → 占用极小
Claude 需要某类工具时，先搜索，只加载匹配的几个类比：不用把整本工具手册背下来，只需要知道"怎么查手册"。
三、工作机制
text
1. 大部分工具被"延迟"（deferred），定义不进上下文，只留个名字
2. Claude 需要工具时，用搜索功能按关键词匹配
3. 匹配到的工具，其完整定义才被加载进来，变成可调用
4. 用完这些工具的定义仍在上下文，但你避免了一次性加载全部这和本手册的运行环境用的是同一个思路 —— 很多工具一开始是"deferred"状态，需要时才加载 schema。
四、配置 Tool Search
4.1 启用
Tool Search 有一个阈值控制何时启动延迟加载。具体配置以官方文档为准，大致形态：
json
{
"mcp": {
"toolSearch": {
"enabled": true
}
}
}4.2 调整阈值
bash
# 用自定义阈值（比如工具占比超过 5% 上下文就延迟）
# 具体 flag 见官方 mcp 文档4.3 完全禁用
text
# 如果你的工具很少，不需要延迟加载，可以禁用4.4 豁免特定 server
有些 server 的工具你希望始终可用（高频使用），可以豁免它们不被延迟：
text
把高频 server 标记为豁免，它的工具始终常驻；
低频 server 走延迟加载。五、给 server 作者的建议
如果你在写 MCP server（见 07.4），让它对 Tool Search 友好：
| 建议 | 理由 |
|---|---|
| 工具名清晰、含关键词 | 搜索靠名字和描述匹配 |
| description 包含使用场景的关键词 | 提高被搜到的准确率 |
| 避免几十个高度相似的工具 | 搜索时难以区分 |
| 相关工具用一致的命名前缀 | 便于成组匹配 |
python
# ✅ 名字和描述都含明确关键词，容易被搜到
@mcp.tool()
async def search_customer_orders(customer_id: str) -> str:
"""搜索指定客户的历史订单。用于查询订单、退款、物流状态。"""六、其他降低工具开销的手段
Tool Search 之外，还有几招：
6.1 按项目隔离（project 作用域）
只在需要的项目加载对应 server：
bash
claude mcp add --scope project --transport http github ...一个纯前端项目就不该加载数据库 server。见 07.2。
6.2 严格模式限定
bash
# 某个会话只加载必要的 server
claude --strict-mcp-config --mcp-config ./minimal-mcp.json6.3 临时禁用不用的 server
text
> /mcp
# 在面板里临时禁用当前不需要的 server6.4 用子代理隔离工具密集的操作
把需要大量特定工具的操作交给子代理，主会话保持轻量：
markdown
---
name: jira-agent
description: 处理所有 Jira 相关操作
mcpServers: ["jira"]
---
你专门处理 Jira。只有你加载 Jira 的工具，主会话不需要。子代理的 mcpServers 字段让它拥有专属的工具集，主会话上下文不受影响。见 06.4。
七、诊断工具开销
text
> /context看 MCP 工具部分占了多少。如果占比很高（比如超过 15-20%），就该考虑上述手段。
text
> /skills按 t 键还能看到各技能的 token 占用（技能也有固定开销）。
八、决策流程
text
你的 MCP 工具总数是多少？
│
├─ < 30 个 → 通常不用特别处理
│
├─ 30-80 个 → 优先用 project 作用域隔离；考虑启用 Tool Search
│
└─ > 80 个 → 必须启用 Tool Search
+ 高频操作用子代理隔离
+ 按项目严格隔离九、一个规模化配置实例
一个大型团队项目，需要接入很多系统：
text
策略：
- GitHub、内部 DB（高频）→ 豁免延迟，始终可用
- Jira、Confluence、Slack、PagerDuty（中低频）→ Tool Search 延迟加载
- 数据分析相关的一大批工具 → 收进一个 analytics 子代理
效果：
- 主会话上下文只常驻 ~2 个高频 server 的工具
- 需要 Jira 时，Claude 搜索并加载
- 复杂的数据分析派给 analytics 子代理，它才加载那批工具
- 主会话始终保持轻量、便宜、快