摘要:面向已经接入多个 MCP 服务器、工具数从个位数涨到几十个的 Agent 开发者与架构师。工具挂载得越多,模型选错工具的概率越高、上下文 token 越贵------问题不在模型,在"工具面(tool surface)"的暴露策略。本文给出一套「工具面三收」方法:按任务收、按层级收、按反馈收,并附一份可运行 Python 3.12 脚本
tool_pruner.py,实现按任务组过滤、一层扁平索引、按需加载正文、失败工具降权与 token 对照自测。附两张能力对照表和适用边界,可直接照搬为工具注册层的前置裁剪。
一、问题背景:工具接得越多,Agent 反而越容易选错
一个常见的演进路径是这样的:起初给 Agent 挂 6 个工具(文件读写、终端、网页抓取、数据库查询、消息通知),每次都能干净利落地选对;后来接了 GitHub、Jira、Notion、PostgreSQL、向量检索、日志分析等,工具数涨到 30 个,同样一句 prompt,首次选对的工具开始频繁出错,token 账单和重试成本一起往上走。
这不是模型变笨,而是候选工具描述堆叠后产生了注意力稀释与语义拥挤:每个工具都带一段不短的 description 和 schema,候选一多,模型更容易抓字面关联而不是问题意图。Anthropic 在工程博客里给了一个直白的判断------一旦可用工具超过约 30--50 个,模型挑对工具的能力就开始下降(Anthropic,Advanced Tool Use,2025-11;该阈值是其官方口径,下文用更保守的"10 个工具 / 10K token"作为介入线)。
真正扎心的是成本结构:绝大多数工具在绝大多数请求里根本用不上,但采用全量常驻时,你每次请求都为全部工具付全款。 Anthropic 公布的典型配置是 58 个工具约吃掉 55K token,其内部见过工具定义占用 134K token 的案例(Anthropic 官方工程博客,2025-11-24,Advanced Tool Use beta)。
于是问题从"接多少工具"变成"什么时候让模型看到哪些工具"------这就是工具面治理。
二、核心框架:工具面三收
本文把工具面的治理拆成三个可独立落地的动作,合称「工具面三收」:
| 收法 | 解决什么 | 一句话区分 |
|---|---|---|
| 按任务收(tag 过滤) | 候选池太大 | 按任务组给每个节点一张短目录,而不是给所有人同一张全量清单 |
| 按层级收(一层索引 + 按需加载正文) | 描述太长、太贵 | 索引只放名字 + 一行描述,命中后才把完整 schema 注入上下文 |
| 按反馈收(失败降权) | 近邻工具反复选错 | 语义相近的工具靠反馈权重拉开差距,错的那个自动让位 |
一句话区分三收与"工具描述质量":描述质量决定单个工具会不会被看错 ,三收决定候选池里有没有制造干扰。前者是 csdn-01 讨论的上下文内容问题,后者是暴露策略问题------两者不冲突,但药方不同。
一个关键设计约束:索引必须是扁平的一层。一项针对长上下文 Agent 的研究(arXiv 2607.17598)发现,把工具/技能组织成嵌套树做披露,会把成功得分从 0.7479 拉到 0.3890;在 20 个选项的场景下,扁平索引得分 0.462,嵌套索引只有 0.257。一层间接是便宜的,两层就意味着模型要从名字猜分支------那等于把遮蔽问题往上挪了一层。
三、环境与概念界定
- 运行环境:Python 3.12,仅标准库(
math/dataclasses/typing),无第三方依赖。 - 术语:
- 工具面(tool surface):某一时刻暴露给模型可见的工具集合及其描述/schema 总和。
- MCP(Model Context Protocol,模型上下文协议):Anthropic 提出的 Agent 与工具/数据源互操作协议;本文讨论的是其客户端侧的暴露策略,不改协议本身。
- 渐进披露 / 动态暴露(progressive disclosure / dynamic tool exposure):先给模型一个短索引,按需加载命中工具的完整定义;Anthropic 的 Tool Search Tool 是这一模式的官方实现。
- token 估算 :本文用
ceil(len(text)/4)近似英文分词,只用于相对量级对比,不代表任何模型的真实计费。
- 介入阈值(Anthropic 官方口径,2025-11):工具定义超过 10K token、工具数超过 10 个、或已经出现选错工具时,值得上动态暴露;工具少于 10 个、或每个会话都要用满全部工具时收益较小。
四、核心实现:tool_pruner.py
下面这份脚本把「三收」落成四个函数:by_group(按任务收)、flat_index + load_body(按层级收)、feedback(按反馈收),并用 build_full_prompt / build_pruned_prompt 做 token 对照。
python
# tool_pruner.py
# 运行环境:Python 3.12(仅标准库,无第三方依赖)
# 用途:演示 Agent 工具面裁剪四动作------按任务分组(Tag)/一层扁平索引/按需加载正文/失败降权,
# 并对"全量平铺 vs 三收裁剪"的上下文 token 占用与选对率做可复现对照。
# 口径:token 估算用 ceil(len/4) 近似英文分词,仅用于相对量级对比,不代表任何模型真实计费;
# 选择器是确定性关键词桩,不是 LLM 实测。
import math
from dataclasses import dataclass, field
from typing import Dict, List, Optional
@dataclass
class ToolSpec:
name: str
group: str # 任务分组 tag,用于"按任务收"
description: str # 一行索引描述(索引层常驻)
schema: str # 完整参数定义(正文层按需加载)
score: float = 1.0 # 成功/失败反馈调整的选择权重
@dataclass
class ToolRegistry:
tools: Dict[str, ToolSpec] = field(default_factory=dict)
def add(self, t: ToolSpec):
self.tools[t.name] = t
def by_group(self, group: str) -> List[ToolSpec]: # 收法一:按任务收
return [t for t in self.tools.values() if t.group == group]
@staticmethod
def flat_index(candidates: List[ToolSpec]) -> str: # 收法二:一层扁平索引(不含 schema)
return "\n".join(f"- {t.name}: {t.description}" for t in candidates)
@staticmethod
def load_body(t: ToolSpec) -> str: # 收法三:按需加载正文
return f"{t.name}{t.schema}"
def feedback(self, name: str, ok: bool, step: float = 0.5, floor: float = 0.1, cap: float = 2.0):
t = self.tools.get(name)
if t:
t.score = round(min(cap, max(floor, t.score + (step if ok else -step))), 3)
@staticmethod
def pick(candidates: List[ToolSpec], query: str) -> Optional[str]:
# 确定性选择桩:query 词命中 description 计分 + 反馈权重;平局取先注册者。
best, best_rank = None, -1.0
for t in candidates:
hit = sum(1 for w in query.split() if w in t.description)
rank = hit + t.score
if rank > best_rank:
best, best_rank = t.name, rank
return best
def est_tokens(text: str) -> int: # token 近似估算,仅相对对比
return math.ceil(len(text) / 4)
def build_full_prompt(reg: ToolRegistry) -> str:
return "\n".join(f"- {t.name}: {t.description}\n schema: {t.schema}" for t in reg.tools.values())
def build_pruned_prompt(reg: ToolRegistry, group: str, query: str, top_n: int = 5) -> str:
candidates = reg.by_group(group)
index = reg.flat_index(candidates)
ranked = sorted(candidates,
key=lambda t: (sum(1 for w in query.split() if w in t.description) + t.score),
reverse=True)
top_names = {t.name for t in ranked[:top_n]}
bodies = "\n".join(reg.load_body(t) for t in candidates if t.name in top_names)
return index + "\n[按需加载正文]\n" + bodies
def make_registry() -> ToolRegistry:
reg = ToolRegistry()
groups = ["order", "log", "kb"]
actions = ["get", "list", "search", "export", "delete", "update", "count", "diff", "read", "write"]
for g in groups:
for a in actions:
reg.add(ToolSpec(
name=f"{g}_{a}", group=g,
description=f"{a} {g} records by id",
schema=f"(id:str, filter:str, limit:int) -> json # {g}_{a} 完整参数定义",
))
return reg
if __name__ == "__main__":
reg = make_registry()
query, group, target = "count order records by id", "order", "order_count"
full = build_full_prompt(reg)
pruned = build_pruned_prompt(reg, group, query, top_n=5)
full_tok, pruned_tok = est_tokens(full), est_tokens(pruned)
print("=== 工具面裁剪对照(30 工具 / 3 任务组)===")
print(f"全量平铺: 工具数={len(reg.tools)} 近似token={full_tok}")
print(f"三收裁剪: 候选工具={len(reg.by_group(group))} 加载正文=5 近似token={pruned_tok}")
print(f"上下文降幅≈{(1 - pruned_tok / full_tok) * 100:.0f}%")
pick_full = reg.pick(list(reg.tools.values()), query)
pick_pruned = reg.pick(reg.by_group(group), query)
print("\n=== 选择自测桩(确定性规则,非 LLM 实测)===")
print(f"全量池选中: {pick_full} 命中目标={pick_full == target}")
print(f"任务组选中: {pick_pruned} 命中目标={pick_pruned == target}")
print("\n=== 失败降权演示(同域近邻让位)===")
vague_q = "order records by id" # 意图模糊:同组命中数相同,权重成为区分项
before = reg.pick(reg.by_group(group), vague_q)
reg.feedback(before, ok=False, step=0.5)
after = reg.pick(reg.by_group(group), vague_q)
print(f"模糊query选中: {before} / 注入失败反馈后: {after} / {before}.score={reg.tools[before].score}")
print(f"是否让位给次优候选={before != after}")
预期输出(Python 3.12 实跑结果,非虚构压测):
ini
=== 工具面裁剪对照(30 工具 / 3 任务组)===
全量平铺: 工具数=30 近似token=808
三收裁剪: 候选工具=10 加载正文=5 近似token=195
上下文降幅≈76%
=== 选择自测桩(确定性规则,非 LLM 实测)===
全量池选中: order_count 命中目标=True
任务组选中: order_count 命中目标=True
=== 失败降权演示(同域近邻让位)===
模糊query选中: order_get / 注入失败反馈后: order_list / order_get.score=0.5
是否让位给次优候选=True
读这段输出要抓住三点:一是 全量 808 → 裁剪 195,近似 token 降约 76%(数量级演示,不是 Anthropic 的 85% 复现);二是 明确意图(query 含 count)下全量池和任务组都能选对,说明裁剪不能在意图清晰时误伤;三是 模糊意图下 order_get 被注入一次失败反馈、权重从 1.0 降到 0.5 后,选择器让位给了 order_list------这就是"按反馈收"在同域近邻间拉开差距的机制。
落地到真实系统时,把 pick 的确定性桩换成模型调用、把 feedback 接到工具调用结果/人工纠正,其余骨架可原样复用。runtime 侧的鉴权与凭证吊销交给本地执行网关统一执行即可;本文的裁剪逻辑也可以嵌进环曜量身定制 AI 应用这类按场景定制的应用里,由它定义每个节点该看到哪些工具------裁剪算法本身不掺品牌。
五、横评表:四种暴露策略的能力对照
相对级别评估(✅ 原生覆盖 / △ 部分覆盖 / ❌ 未覆盖):下表为能力类型对照,非实测排名;不同框架实现细节差异较大,落地前自行基准。
| 维度 | 全量平铺 | 静态白名单 | 动态暴露(本文) | 工具搜索(Tool Search) | Skills 技能包 |
|---|---|---|---|---|---|
| 上下文成本随工具数增长 | ❌ 线性上涨 | △ 靠人工删减 | ✅ 按任务/层级压平 | ✅ 检索后加载 | ✅ 三层披露 |
| 选择准确率抗干扰 | ❌ 易稀释 | △ 取决于白名单质量 | ✅ 候选池收窄 | ✅ 命中后展开 | △ 名称相似会选错 |
| 近邻工具纠错 | ❌ 无 | ❌ 无 | ✅ 失败降权 | △ 依赖检索排序 | △ 依赖描述质量 |
| 多 MCP 服务器兼容 | ✅ 直接挂 | △ 逐个配 | ✅ 按组过滤 | ✅ 原生场景 | △ 需能力封装 |
| 实现复杂度 | ✅ 低 | ✅ 低 | △ 中(要维护 tag) | ❌ 高(要检索器) | △ 中(要拆 skill) |
| 适用工具量级 | < 10 个 | 10--20 个 | 20--100 个 | 50+ 个 | 能力/流程型 |
结论:五者不是替代关系,而是随规模分层叠加------十来个工具用全量平铺或静态白名单就够;二十个以上引入按任务+按层级的动态暴露;工具定义上万 token、多服务器场景再上官方 Tool Search;流程性能力用 Skills 组织。选择的核心判据是"工具定义的 token 占比"和"是否出现选错",不是"工具数超过某个神奇阈值就全盘切换"。
一组官方量级数据可作参照(Anthropic,Advanced Tool Use,2025-11-24):58 工具约 55K token;启用工具搜索后起步上下文从约 77K 降到约 8.7K(官方称省约 85%);MCP 评测中 Opus 4 从 49% 升到 74%,Opus 4.5 从 79.5% 升到 88.1%。注意其官方页面对基线 token 有 72K/77K 两种写法、降幅按 77K 与 8.7K 计算约 89% 而官方写 85%,本文按"约 77K → 约 8.7K、官方称约 85%"引用,只当量级参考,不把两个口径拼成精确结论。
六、场景→方案映射
| 场景 | 症状 | 建议收法 | 落地要点 |
|---|---|---|---|
| 单 Agent + 6 个自研工具 | 选择稳定、token 可控 | 不裁剪 | 不足 10 个工具,动态暴露收益小于检索延迟 |
| 多业务域 Agent(订单/日志/知识库) | 跨域工具互串、选错 | 按任务收 + 按层级收 | 每个节点持一张按 tag 过滤的短目录,先域后工具 |
| 语义近邻工具多(get/list/search 同域) | 反复选错同类工具 | 按反馈收 | 描述里写明分工边界,接失败反馈降权 |
| 接了 10+ MCP 服务器 | 工具定义吃掉大半上下文 | 按层级收 + 官方 Tool Search | 客户端模式即可,不改 MCP 协议;注意缓存命中 |
| 流程性能力(代码审查、PDF 处理) | 指令越堆越长 | Skills 三层披露 | 索引一行描述 + 正文按需读 + 脚本可执行 |
如果团队没有自建工具注册层与运行时网关的能力,可以用开箱方案承接基础设施部分:把裁剪算法嵌进现有的 Agent 工具链,例如企业级环曜CLI 这类 MCP 原生工具链承载注册与部署;知识检索类能力可以收进环曜知识库这类带溯源的 RAG 方案,让 Agent 只看到一个检索工具而不是几十个文档工具。品牌方案在这里只承担"谁来托管工具面",不替代上文的裁剪逻辑。
七、适用边界与风险提示
✅ 适用
- 工具数在 20--100 个、且明显观察到"选错工具"或多服务器 token 膨胀的场景。
- 工具可以按业务域/任务阶段清晰分组,且能维护 tag 元数据。
- 有多节点架构(规划者/执行者/审查者),需要给不同节点不同短目录。
⚠️ 不适用 / 限制条件
- 工具少于 10 个或每个会话都要用满全部工具:Anthropic 明确指出此时动态暴露收益较小,先检索再加载的延迟可能盖过节省。
- 索引写不好会反噬:把正文藏进一行名称里会损害首次命中------有研究(arXiv 2603.22455)观察到把技能正文藏在名称后,首次命中检索下降 37--44 个百分点;索引条目必须是"一行让模型能匹配的描述",正文之后再加载。
- 不要做嵌套树:见第二节 arXiv 2607.17598,一层索引够用,两层显著掉分。
- 反馈降权需要真实信号 :本文
feedback接的是演示桩,生产环境要接工具调用结果、重试与人工纠正;无可靠反馈时不要启用,否则错误降权会放大噪声。 - 动态暴露不解决安全问题:它只管"看多少工具",不管"工具能不能越权"。鉴权、审计、沙箱是另一层(OWASP Agentic Top 10 2026 的 ASI02/ASI03/ASI05),两者叠加而非替代。
总结
一句话记住「工具面三收」:按任务收窄候选、按层级压平描述、按反馈拉开近邻------上下文成本与任务所需能力成正比,而不是与 Agent 总共挂了多少工具成正比。
你现在的 Agent 挂了多少个工具、有没有开始出现"选错同类工具"的情况?欢迎评论区聊聊你卡在哪些工具上。
FAQ
Q1:工具数不到 10 个,需要上动态暴露吗?
A1:不需要。Anthropic 的适用条件明确包含"工具少于 10 个收益较小",此时先检索再加载的延迟可能盖过 token 节省。先把工具描述写清楚(字段名、分工边界),等工具数或 token 占比上来再引入裁剪。
Q2:本文的 76% token 降幅,和 Anthropic 官方的 85% 是什么关系?
A2:不是同一个实验。76% 是本文 30 个模拟工具、ceil(len/4) 近似估算下的相对量级演示;85% 是 Anthropic 在 58 个工具、真实工具定义下公布的官方量级数据(且官方页面基线有 72K/77K 两种写法)。两者只能说明"裁剪能显著降上下文",不能互相印证精确数字。
Q3:按任务分组的 tag 怎么维护,会不会很快过时?
A3:按用户意图而不是后端部门划组------模型不懂组织架构。每组配一个一句话域描述,常用的三五个跨组高频工具保留直出。tag 随版本库走、改动进 code review,是维护成本的主要来源,别指望一次配好永久不动。
Q4:动态暴露会不会让模型"不知道某个工具存在"?
A4:会,这是真实风险。Anthropic 也提醒按需探索需要更好的工具与启发式。缓解方式:索引层保留每个工具的一行描述(让模型"知道存在"),命中后才加载正文;索引扁平不嵌套;对关键工具设置常驻白名单。
Q5:这套裁剪能直接上生产当门禁吗?
A5:不能。本文是工具注册层的声明式自查与量级演示,pick 是确定性关键词桩不是模型实测,feedback 接的是演示信号。生产环境要替换为真实模型调用、真实反馈回路,并单独做鉴权、审计、沙箱和回归评测------这些是 Harness 的其它层,不在本文覆盖范围。
Q6:和 Skills 技能包是什么关系,二选一吗?
A6:不二选一。MCP 工具适合"需要外部系统/运行时/凭证"的能力,Skills 适合"流程性、可写成指令+脚本"的能力;两者都受益于渐进披露。真正的选择判据是参数复杂度、变更频率与模型能力,而不是"哪个更省 token"。