tool-search

参考资料（存档）： SCAFFOLD_SKILLS_ARCHIVE_MAP.md — 来自 everything-claude-code backend-patterns、tdd-workflow 的基于嵌入的语义工具发现。

工具搜索技能

身份

工具搜索 - 使用嵌入提供语义工具发现能力，可将工具规模从数十个扩展到数千个，同时减少 90% 以上的上下文占用。

能力

• 语义工具搜索：根据任务上下文查找相关工具
• 基于嵌入的匹配：使用嵌入实现准确的工具发现
• 按需加载：仅在需要时加载工具
• 上下文效率：工具定义令牌减少 90% 以上

问题

传统的工具加载方式：

• 一次性加载所有工具
• 58 个工具 ≈ 55K 个令牌
• 上下文很快就会被占满
• 难以扩展到 100 个以上工具

解决方案

使用嵌入进行工具搜索：

• 初始仅加载工具搜索工具（约 500 个令牌）
• 通过语义搜索按需发现工具
• 每次搜索加载 3–5 个相关工具（约 3K 个令牌）
• 总计：约 8.7K 个令牌，而传统方式约为 77K（减少 85%）

工作原理

1. 初始状态：仅加载工具搜索工具和关键工具
2. 工具发现：Agent 根据任务搜索工具
3. 语义匹配：嵌入将工具与任务上下文相匹配
4. 工具展开：将匹配的工具展开为完整定义
5. 工具使用：Agent 使用已发现的工具

配置

MCP 配置（.claude/.mcp.json）

{
  "betaFeatures": ["advanced-tool-use-2025-11-20"],
  "toolSearch": {
    "enabled": true,
    "autoEnableThreshold": 20,
    "defaultDeferLoading": true
  },
  "mcpServers": {
    "repo": {
      "deferLoading": true,
      "alwaysLoadTools": ["search_code", "read_file"]
    },
    "github": {
      "deferLoading": true,
      "alwaysLoadTools": ["create_pull_request", "get_issue"]
    }
  }
}

始终加载关键工具

始终加载 3–5 个最常用的工具：

• 核心文件操作：read_file、write_file、search_code
• 必备集成：create_pull_request、get_issue
• 常用工具：take_screenshot、navigate_page

使用模式

何时使用工具搜索

最适用的情况：

• 工具定义占用超过 10K 个令牌
• 工具库中有 10 个以上的工具
• 遇到工具选择准确性问题
• 构建由 MCP 驱动、包含多个服务端的系统

较不适用的情况：

• 工具库较小（少于 10 个工具）
• 每次会话都会频繁使用所有工具
• 工具定义较精简

工具发现

Agent 工作流：

1. Agent 需要某项能力（例如，“创建拉取请求”）
2. Agent 搜索：“github pull request creation”
3. 工具搜索返回：create_pull_request 工具
4. 将工具展开为完整定义
5. Agent 使用该工具

示例：

User: "Create a pull request for my changes"

Agent searches: "github pull request creation"
Tool Search finds: create_pull_request tool
Tool loaded and used

最佳实践

1. 使用清晰的工具名称和描述

良好示例：

{
  "name": "search_customer_orders",
  "description": "Search for customer orders by date range, status, or total amount. Returns order details including items, shipping, and payment info."
}

不良示例：

{
  "name": "query_db_orders",
  "description": "Execute order query"
}

2. 系统提示词指导

在 Agent 提示词中添加指导：

You have access to tools for Slack messaging, Google Drive file management,
Jira ticket tracking, and GitHub repository operations. Use the tool search
to find specific capabilities when needed.

3. 始终加载关键工具

不要延迟加载以下工具：

• 核心文件操作
• 必备集成
• 常用工具

4. 监控工具使用情况

跟踪发现了哪些工具：

• 搜索次数最多的工具
• 工具发现模式
• 实现的上下文节省量

实现

基于嵌入的工具搜索

工具搜索使用嵌入将工具与查询相匹配：

1. 工具索引：为所有工具定义创建嵌入
2. 查询嵌入：为用户查询创建嵌入
3. 相似性搜索：查找嵌入相似的工具
4. 工具展开：将匹配的工具加载到上下文中

工具搜索工具

工具搜索工具本身：

• 以语义方式搜索工具库
• 根据查询返回相关工具
• 将工具展开为完整定义
• 维护工具索引

优势

上下文效率

• 工具定义令牌减少 85%
• 总上下文占用率为 52.5%（从 87% 降低）
• 处于最佳范围内（目标为 60–70%）

提高准确性

• 工具选择准确率提高 11%
• 79.5% → 88.1%（Opus 4.5）
• 复杂查询的工具匹配效果更好

可扩展性

• 可扩展至数千个工具
• 无需担心上下文限制
• 动态工具发现

示例

示例 1：GitHub 操作

User: "Create a pull request"

Agent workflow:
1. Searches: "github pull request creation"
2. Tool Search finds: create_pull_request tool
3. Tool loaded (3K tokens)
4. Agent uses tool
5. Total context: ~8.7K tokens (vs. 55K traditional)

示例 2：文件操作

User: "Search for authentication code"

Agent workflow:
1. Searches: "code search file operations"
2. Tool Search finds: search_code, read_file tools
3. Tools loaded (5K tokens)
4. Agent uses tools

示例 3：多个集成

User: "Check Slack messages and create Jira ticket"

Agent workflow:
1. Searches: "slack message reading"
2. Tool Search finds: read_slack_message tool
3. Searches: "jira ticket creation"
4. Tool Search finds: create_jira_ticket tool
5. Both tools loaded (6K tokens total)

集成

使用 MCP 服务

工具搜索适用于 MCP 服务：

• GitHub MCP：35 个工具 → 按需加载 3–5 个
• Slack MCP：11 个工具 → 按需加载 2–3 个
• 自定义 MCP：任意数量的工具 → 按需加载

使用 Agent 系统

所有 Agent 都能从工具搜索中受益：

• 减少上下文用量
• 更好地选择工具
• 可扩展的工具库

故障排除

未找到工具

• 检查工具名称和描述是否清晰
• 确认已启用工具搜索
• 检查搜索查询
• 确认工具索引为最新版本

上下文仍然过多

• 确认已启用 deferLoading
• 检查 alwaysLoadTools 列表（应尽可能精简）
• 检查工具定义（可能过于冗长）
• 监控实际工具用量

工具选择问题

• 改进工具描述
• 为搜索查询添加更多上下文
• 检查工具命名规范
• 检查嵌入质量

与程序化工具调用（PTC）集成

工具搜索与程序化工具调用配合效果出色：

1. 工具搜索查找相关工具（按需加载）
2. PTC 高效编排工具（减少上下文用量）
3. 结果：以最少的 token 消耗实现最佳工具使用效果

工作流示例：

# Tool Search finds tools
tools = search_tools("github issue management")

# PTC orchestrates multiple tool calls
team = await get_team_members("engineering")
issues = await asyncio.gather(*[
    get_issue(member["github_username"]) for member in team
])
# Only final results in context, not all intermediate data

请参阅 PTC 模式指南，了解全面的 PTC 文档。

相关文档

• 高级工具使用 - 全面的工具使用指南
• PTC 模式 - 程序化工具调用模式
• 上下文优化 - 上下文管理

参考资料

• 使用嵌入进行工具搜索 Cookbook
• 程序化工具调用 Cookbook
• 高级工具使用文档

**示例命令**：

# Search for git-related tools
node .claude/tools/tool_search.mjs --query "git"

# Search for database tools
node .claude/tools/tool_search.mjs --query "database" --limit 3

# Search for testing tools
node .claude/tools/tool_search.mjs --query "testing"

</usage_example>

记忆协议（强制）

开始之前： 阅读 .claude/context/memory/learnings.md

完成之后：

• 新模式 -> .claude/context/memory/learnings.md
• 发现问题 -> .claude/context/memory/issues.md
• 做出决策 -> .claude/context/memory/decisions.md

假设任务会中断：如果没有记录在记忆中，就等于没有发生。