⚡

工具搜索技能Skill tool-search

工具搜索技能是一种利用嵌入技术实现语义工具发现的AI应用，通过按需加载工具大幅减少上下文使用，提升工具库的可扩展性和使用效率。关键词：语义搜索、工具发现、嵌入技术、上下文优化、AI代理、MCP集成、按需加载、可扩展工具库。

AI应用 0 次安装 0 次浏览 更新于 3/10/2026

名称: 工具搜索 描述: 使用嵌入进行语义工具搜索，实现可扩展工具发现。支持按需工具加载，将大型工具库的上下文使用减少90%以上。 版本: 1.0 模型: sonnet 调用者: 两者 用户可调用: true 工具: [读取, 写入, 搜索, 全局] 最佳实践:

  • 用于10个以上工具的工具库
  • 始终保持3-5个最常用工具加载
  • 使用清晰、描述性的工具名称
  • 添加系统提示指导 错误处理: 优雅 流式支持: 支持 已验证: false 最后验证时间: 2026-02-19T05:29:09.098Z

参考（存档）: SCAFFOLD_SKILLS_ARCHIVE_MAP.md — 来自everything-claude-code backend-patterns, tdd-workflow的嵌入/语义工具发现。

工具搜索技能

身份

工具搜索 - 提供使用嵌入的语义工具发现，从数十个扩展到数千个工具，实现90%以上的上下文减少。

能力

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

问题

传统工具加载：

  • 所有工具预先加载
  • 58个工具约55K令牌
  • 上下文快速填满
  • 难以扩展到100个以上工具

解决方案

使用嵌入的工具搜索：

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

工作原理

  1. 初始状态: 仅加载工具搜索工具 + 关键工具
  2. 工具发现: 代理基于任务搜索工具
  3. 语义匹配: 嵌入将工具匹配到任务上下文
  4. 工具扩展: 匹配工具扩展为完整定义
  5. 工具使用: 代理使用发现的工具

配置

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个工具）
  • 所有工具在每个会话中频繁使用
  • 工具定义紧凑

工具发现

代理工作流:

  1. 代理需要能力（例如，“创建拉取请求”）
  2. 代理搜索：“github拉取请求创建”
  3. 工具搜索返回：create_pull_request工具
  4. 工具扩展为完整定义
  5. 代理使用工具

示例:

用户: “为我的更改创建拉取请求”

代理搜索: “github拉取请求创建”
工具搜索找到: create_pull_request工具
工具加载并使用

最佳实践

1. 清晰工具名称和描述

好:

{
  "name": "search_customer_orders",
  "description": "按日期范围、状态或总金额搜索客户订单。返回包括物品、运输和支付信息的订单详情。”
}

差:

{
  "name": "query_db_orders",
  "description": “执行订单查询”
}

2. 系统提示指导

在代理提示中添加指导：

您可以访问用于Slack消息、Google Drive文件管理、
Jira票务跟踪和GitHub仓库操作的工具。在需要时使用工具搜索
查找特定能力。

3. 始终保持关键工具加载

不要延迟加载：

  • 核心文件操作
  • 基本集成
  • 频繁使用工具

4. 监控工具使用

跟踪发现的工具：

  • 最常搜索的工具
  • 工具发现模式
  • 实现的上下文节省

实现

基于嵌入的工具搜索

工具搜索使用嵌入来匹配工具到查询：

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

工具搜索工具

工具搜索工具本身：

  • 语义搜索工具库
  • 基于查询返回相关工具
  • 将工具扩展为完整定义
  • 维护工具索引

好处

上下文效率

  • 85%减少 在工具定义令牌
  • 52.5%总上下文 （从87%下降）
  • 在最佳范围内 （60-70%目标）

提高准确性

  • 11%改进 在工具选择准确性
  • 79.5% → 88.1% （Opus 4.5）
  • 对复杂查询更好的工具匹配

可扩展性

  • 扩展到 数千个工具
  • 无上下文限制问题
  • 动态工具发现

示例

示例1: GitHub操作

用户: “创建拉取请求”

代理工作流:
1. 搜索: “github拉取请求创建”
2. 工具搜索找到: create_pull_request工具
3. 工具加载（3K令牌）
4. 代理使用工具
5. 总上下文: 约8.7K令牌（vs. 55K传统）

示例2: 文件操作

用户: “搜索认证代码”

代理工作流:
1. 搜索: “代码搜索文件操作”
2. 工具搜索找到: search_code, read_file工具
3. 工具加载（5K令牌）
4. 代理使用工具

示例3: 多集成

用户: “检查Slack消息并创建Jira票”

代理工作流:
1. 搜索: “slack消息阅读”
2. 工具搜索找到: read_slack_message工具
3. 搜索: “jira票创建”
4. 工具搜索找到: create_jira_ticket工具
5. 两个工具加载（6K令牌总）

集成

与MCP服务器

工具搜索与MCP服务器工作：

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

与代理系统

所有代理受益于工具搜索：

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

故障排除

工具未找到

  • 检查工具名称和描述是否清晰
  • 验证工具搜索已启用
  • 审查搜索查询
  • 检查工具索引是最新的

上下文仍然高

  • 验证deferLoading已启用
  • 检查alwaysLoadTools列表（应最小）
  • 审查工具定义（可能太冗长）
  • 监控实际工具使用

工具选择问题

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

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

工具搜索与程序化工具调用（PTC）完美工作：

  1. 工具搜索 找到相关工具（按需加载）
  2. PTC 高效协调工具（减少上下文）
  3. 结果: 最小令牌消耗下的最佳工具使用

示例工作流:

# 工具搜索找到工具
tools = search_tools(“github问题管理”)

# PTC协调多个工具调用
team = await get_team_members(“engineering”)
issues = await asyncio.gather(*[
    get_issue(member["github_username"]) for member in team
])
# 仅最终结果在上下文中，不是所有中间数据

参见 PTC模式指南 获取全面的PTC文档。

相关文档

参考

<examples> <usage_example> 示例命令:

# 搜索git相关工具
node .claude/tools/tool_search.mjs --query “git”

# 搜索数据库工具
node .claude/tools/tool_search.mjs --query “database” --limit 3

# 搜索测试工具
node .claude/tools/tool_search.mjs --query “testing”

</usage_example> </examples>

内存协议（强制）

开始前: 读取 .claude/context/memory/learnings.md

完成后:

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

假设中断: 如果不在内存中，就没有发生。