# Tool Discovery

Agent 工具数量变多、上下文被工具定义占满时使用, , 设计工具发现与渐进式披露机制、实现 discover_tools...

- Repository: https://github.com/bojieli/ai-agent-book (56844 stars)
- Category: AI and agents
- License: Apache-2.0
- Last updated: 2026-10-08
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add bojieli/ai-agent-book --skill tool-discovery -g -a claude-code -y`
Codex: `npx skills add bojieli/ai-agent-book --skill tool-discovery -g -a codex -y`
Cursor: `npx skills add bojieli/ai-agent-book --skill tool-discovery -g -a cursor -y`
Gemini CLI: `npx skills add bojieli/ai-agent-book --skill tool-discovery -g -a gemini-cli -y`

## Description

Agent 工具数量变多、上下文被工具定义占满时使用, , 设计工具发现与渐进式披露机制、实现 discover_tools 元工具与两层语义路由、选择索引式/检索式/主动发现/Skills 方案、处理动态加载破坏 KV Cache 的问题、评估 token 成本与工具选择准确率时查阅。含渐进式加载五步流程、工具数量阈值与关键实验数据。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 工具发现与渐进式加载

## 何时使用
- 接入的 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）。

The rest: https://github.com/bojieli/ai-agent-book/blob/HEAD/skills/tool-discovery/SKILL.md