工具发现与渐进式加载

何时使用

• 接入的 MCP 服务器越来越多，system prompt 被工具 schema 占掉几千到几万 token
• 工具库增长到上百个，模型开始选错工具、漏掉工具
• 设计"只暴露索引、按需加载定义"的工具披露层
• 实现主动工具发现：Agent 声明能力缺口 → 系统语义匹配 → 动态注入 schema
• 需要在工具数量、token 成本、准确率之间做架构取舍
• 动态加载工具后 Prompt Cache 命中率下降，需要定位原因
• 为小参数量模型（4B 级）设计可用的上百工具接入方案

核心原则

• 规模本身伤害正确性。 工具数超过 100 个时，即使最先进模型也容易在工具选择上出错；全部平铺还占大量 token，且每次工具集变动都击穿 KV Cache。
• 三层答案，一层比一层"按需"：① 层次化组织 + 按需加载（定义事先备好，不全量注入）；② 主动工具发现（Agent 意识到缺口，主动声明需求，系统匹配注入）；③ Skills（不把工具当正式定义，当可随手翻阅的参考资料）。
• 披露策略与能力形态是两个独立决策。 挂着几百个 MCP 工具的服务器可以只暴露一份索引；二十来个 skill 也可能需要分层检索。别把"全量常驻上下文"当默认。
• 只暴露索引是第一件事。 Cursor 的做法：把工具描述同步到文件夹，Agent 默认只看工具名索引，需要时再查具体定义。A/B 测试显示 MCP 相关任务总 token 减少 46.9%。
• 约 200 token 的代理工具（pi-mcp-adapter）就能支撑"搜索 → 查看定义 → 调用"的完整按需发现流程，MCP 服务器还可延迟到首次使用才启动。是否用 MCP 作协议与会话开始时是否暴露全部工具定义，是两个独立决策。
• 一次性检索有内在局限。 检索式预筛选按用户的初始查询做一次匹配，而 "Debug the file" 这类请求实际牵出文件访问、代码分析、命令执行的多步骤跨领域工具链，任务开始时无法预见全部需求。
• 匹配必须层次化。 工具按服务器（类似 App）分组，先定位服务器、再在服务器内匹配工具，把搜索空间从"数千个工具"缩到"数十个服务器 × 每个数十个工具"，既省算力也减少跨领域语义混淆。
• schema 固定原位，静态前缀只增不改。 新工具的完整 schema 追加到上下文末尾并固定在首次注入的位置，作为普通历史消息继续命中缓存, , "工具定义必须在上下文最前面"不再是铁律。

实践模式

1. 方案选型（按工具数量与场景）

工具规模	推荐方案
十几个	全量注入，无需额外机制
几十个	只暴露索引，按需查定义
上百个	检索式预筛选（top-k 后注入）
上百至上千	主动工具发现（元工具 + 两层语义路由）或 Skills 渐进式披露
上千	Skills / Skill Hub；专用工具须另建索引层

层次化组织按信息源性质分类，并在系统提示词中显式说明，帮助 LLM 快速定位工具组：搜索工具（主动查找：网络/知识库/文件搜索）、读取工具（从已知位置提取：网页阅读、文档读取、DB 查询）、解析工具（处理非结构化数据：OCR、视频分析、音频转录）、查询工具（访问结构化数据源：天气、股票、公开数据库 API）。