> For the complete documentation index, see [llms.txt](https://yeasy.gitbook.io/claude_guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yeasy.gitbook.io/claude_guide/di-er-bu-fen-gong-ju-pian/03_tools/3.6_tool_search.md).

# 3.6 工具搜索：大规模工具库的管理之道

## 3.6.1 大规模工具库的挑战：上下文污染与 Token 黑洞

随着 Agent 能力的增长，很快会面临一个棘手的问题：**工具数量爆炸**。 一个成熟的企业级助手可能集成了 Jira、GitHub、Salesforce、AWS 和内部数据库，可用工具轻易超过 100 个。

如果尝试将这 100 个工具的完整定义（名称+描述+参数Schema）全部塞进 API 请求：

1. **Token 成本激增**：每次对话的 Overhead 可能高达几万 Token。
2. **注意力分散**：过多的选项会“稀释”模型的注意力，导致它混淆相似的工具（如 `delete_user` 和 `remove_member`）。
3. **延迟增加**：庞大的 Prompt 处理速度变慢。

**工具搜索 (Tool Search)** 正是为了解决这一问题而生。它引入了类似“图书馆索引”的机制，通过 **按需加载 (Deferred Loading)**，让 Claude 有能力在数千个工具中精准找到所需的那一个，而无需预先加载所有细节。

## 3.6.2 核心机制：按需加载

工具搜索的工作流程打破了传统的“一次性全部提供”模式：

1. **定义**：在 `tools` 列表中，可以提供数千个工具，但将绝大多数标记为 `defer_loading: true`。
2. **隐藏**：对于这些延迟加载的工具，Claude **初始时看不到它们的完整定义**。它只知道“这里有很多关于数据库和代码的工具”。
3. **索书号**：不仅如此，为了帮助 Claude 找到它们，会提供一个特殊的 **工具搜索工具**。
4. **发现**：当用户问“重启数据库”时，Claude 意识到自己当前手中的工具不够用，于是调用“搜索工具”。
5. **加载**：搜索工具返回了最相关的 3 个工具（如 `restart_db_service`）。此时，这 3 个工具的完整定义才真正进入上下文窗口。

这是一个典型的 **Retrieve-Read** 模式在工具使用上的应用。

## 3.6.3 内置搜索变体

Anthropic API 提供了原生的搜索能力，这意味着不需要自己写向量数据库来实现工具检索（虽然完全可以这么做）。

### 内容搜索

这是最通用的搜索模式，基于关键词匹配。

* **Type ID**: `tool_search_tool_bm25_20251119`
* **原理**：经典的 BM25 算法。它根据工具的 `name` 和 `description` 计算相关性。
* **适用场景**：你的工具描述写得非常自然语言化，或者用户提问比较模糊。
  * *User*: “服务器卡死了”
  * *Search*: "server performance lag"
  * *Match*: `check_cpu_usage`, `restart_nginx`

### 正则搜索

基于 Python 风格的正则表达式进行精确匹配。

* **Type ID**: `tool_search_tool_regex_20251119`
* **适用场景**：拥有严格命名规范的工具库。
  * *Pattern*: `aws_ec2_.*` (查找所有 EC2 相关工具)
  * *Pattern*: `(?i)user` (查找所有包含 user 的工具，忽略大小写)

## 3.6.4 API 定义示例

下面是如何在一个请求中混合使用“立即加载”工具和“搜索”工具的示例：

```jsonc
{
  "tools": [
    // 1. 立即加载的核心工具 (Eager)
    {
      "name": "help",
      "description": "获取系统帮助",
      "input_schema": { ... }
    },

    // 2. 引入搜索能力 (Search Tool)
    {
      "type": "tool_search_tool_bm25_20251119",
      "name": "tool_search_tool_bm25" // 固定名称，必须与 type 变体对应
    },

    // 3. 延迟加载的海量工具 (Deferred)
    {
      "name": "get_customer_data",
      "description": "查询 CRM 中的客户详情",
      "input_schema": { ... },
      "defer_loading": true // <--- 关键标记
    },
    {
      "name": "update_inventory",
      "description": "更新库存",
      "input_schema": { ... },
      "defer_loading": true
    }
    // ... 更多 500 个工具
  ]
}
```

## 3.6.5 工具的选择与命名空间化原则

在大规模工具生态中，简单地增加工具数量往往会导致反效果。本小节总结Anthropic实战中发现的工具设计关键原则。

**原则一：选择正确的工具而非所有工具**

许多团队的误区是“如果某个系统有API，我们就为它创建工具”。但**更多工具≠更好的Agent**。

关键问题是：**让Agent选择大量工具会分散它的注意力，导致它混淆相似的工具或做出次优选择。**

建议：

* 从少而精的工具开始（10-15个核心工具）
* 通过评估识别哪些工具被频繁使用、哪些被忽视
* 只增加经过验证确实能改善性能的工具
* 对于重复功能的工具，优先保留最清晰、最常用的那个

**原则二：工具命名空间化与前缀设计**

当工具库扩展到数十个乃至数百个时，命名空间变得关键。

命名空间的目的有两个：

1. **帮助Agent理解工具分类**：通过前缀，Agent能推断出哪些工具属于同一类
2. **减少工具搜索空间**：好的前缀能帮助工具搜索算法更精准地定位

命名模式对比：

| 模式           | 示例                                            | 优点              | 缺点            |
| ------------ | --------------------------------------------- | --------------- | ------------- |
| **无前缀**      | `create_user`, `update_config`                | 简洁              | 难以分类，大规模下容易混淆 |
| **前缀命名（推荐）** | `user_create`, `user_update`, `config_update` | 清晰的分类，BM25搜索更高效 | 名字略长          |
| **嵌套命名**     | `github.repo.create`, `github.issue.list`     | 最清晰的层级          | 可能与某些API限制冲突  |

**实践建议**：

* 使用 `service_resource_action` 或 `service_action` 模式
* 相似功能的工具应使用相同前缀：`slack_send_message`, `slack_list_channels`, `slack_delete_channel`
* 避免通用词：“list” 比 “get\_all” 更清晰，“create” 比 “new” 更标准

**原则三：精确化工具选择而非参数扩张**

一个常见的设计陷阱是在一个工具上不断添加参数，试图覆盖所有用例。但结果往往是：

* Agent 面对大量可选参数感到困惑
* 工具的语义变得模糊（“这个工具到底是用来做什么的？”）
* Token 消耗增加（每个请求都要传入完整的参数定义）

更好的做法：

* 创建多个专注的工具而不是一个包罗万象的工具
* 每个工具应该有清晰、单一的职责
* 可选参数应该少于3个；如果超过，考虑拆分工具

示例：

* ❌ `send_message(channel, text, emoji_reaction, thread_id, scheduled_time, format, encrypt)`
* ✅ `send_message(channel, text)`, `add_reaction(message_id, emoji)`, `schedule_message(channel, text, time)`

***

*融入自 Anthropic 的《Writing effective tools for agents》中关于工具选择与命名空间化的最佳实践*

## 3.6.6 评估驱动的工具改进流程

理想的工具设计不是一次性完成的，而是通过评估、测试和迭代逐步优化的过程。Anthropic 在内部大规模应用了这个流程，并取得了显著成果。

**三步循环：评估 → 分析 → 改进**

1. **第一步：建立评估框架**

在改进工具之前，需要有量化的衡量标准：

* 定义代表性的任务集（来自实际使用场景）
* 对于每个任务，明确验证标准（什么样的结果算成功）
* 评估标准可以是精确匹配、AI评判或人工评审

示例：

```python
evaluation_tasks = [
    {
        "query": "Schedule a meeting with Jane next week to discuss our latest Acme Corp project.",
        "expected_tools": ["schedule_event", "find_availability"],
        "success_criteria": "Event created with correct date, attendee, and context"
    },
    {
        "query": "Customer ID 9182 was charged three times. Find all related logs.",
        "expected_tools": ["search_logs", "filter_by_customer"],
        "success_criteria": "Identified all three duplicate charges and their timestamps"
    }
]
```

2. **第二步：运行评估并分析结果**

执行Agent在所有任务上的表现，收集详细的执行日志：

* Agent 调用了哪些工具
* 每个工具调用的参数是什么
* 返回结果是否有用
* Agent 最终是否正确完成了任务

关键：

* 记录可审计轨迹：输入、输出、工具名、参数 schema/hash、工具结果摘要、错误、token、耗时和 grader 结果
* 捕捉Agent遇到的困惑或重试，但不要依赖或长期保存隐藏推理、extended thinking 原文或包含敏感信息的完整工具参数
* 量化效率指标：总Token数、API调用次数、完成时间

3. **第三步：与Agent合作迭代改进**

这是最关键的一步——使用Agent本身来分析和改进工具。

做法：

* 将评估日志导入Claude Code或您的编程环境
* 要求Agent分析：哪些工具描述导致了混淆？哪些工具参数不清晰？
* Agent会建议改进方案（优化描述、拆分工具、重命名等）
* 实施改进，重新运行评估，验证是否有改善

**实战案例数据（示意重构）**

Anthropic 在《Writing effective tools for agents》中介绍了用 Claude 自动优化其内部 Slack MCP 服务器工具、以评估驱动迭代的做法（原文以图表呈现提升幅度，并未给出具体百分数）。下面用一组示意数字还原这类迭代的典型轨迹：

* 初始版本（人工编写）：准确率 62%
* 第一轮迭代（Agent优化描述）：准确率 71%
* 第二轮迭代（Agent优化参数设计）：准确率 78%
* 第三轮迭代（Agent建议拆分工具）：准确率 85%

典型的改进方向（示意）：

* 明确“何时”调用工具：从 “发送消息” 改为 “发送文本消息到特定频道（而不是创建频道）”
* 优化参数：合并了5个“可选”参数，只保留了2个关键参数
* 拆分工具：将“message\_search”拆分为“search\_by\_text”和“search\_by\_author”

**最佳实践建议**

1. 从小规模评估开始（10-20个任务）
2. 重点关注“失败案例”的根本原因
3. 优先改进高频工具（被调用次数多但成功率低的）
4. 定期运行全量评估以检测回归
5. 建立基准测试集，确保改进不会伤害已有的功能

***

*融入自 Anthropic 的《Writing effective tools for agents》中关于评估驱动迭代的最佳实践*

## 3.6.7 最佳实践：构建可搜索的工具库

为了让搜索更高效，开发者需要像 SEO 专家一样优化工具定义。

### 命名规范化

使用具有层级结构的命名，便于正则搜索和人类理解。

* `category_action_object`
* ✅ `github_issue_create`, `github_issue_close`
* ❌ `new_task`, `close_it`

### 关键词填充

在描述中显式加入同义词或标签。

* `description`: "Updates user permissions. Keywords: admin, auth, rbac, grant, revoke."
* 这样即使用户说“修改权限”或“授权”，都能被 BM25 命中。

### 引导地图 System Prompt

虽然 Claude 看不到具体的工具细节，但需要在 System Prompt 中给它一张“地图”。

* *Prompt*: “你拥有以下类别的工具库：数据库管理、CRM 操作、AWS 运维。如果遇到相关问题，请使用 `tool_search_tool_bm25` 查找具体命令。”

## 3.6.8 与 MCP 的天作之合

工具搜索是 [**MCP (Model Context Protocol)**](/claude_guide/di-er-bu-fen-gong-ju-pian/04_mcp.md) 生态的关键粘合剂。

想象连接了 5 个 MCP 服务器：

1. **Filesystem Server**: 20 个文件操作工具
2. **Postgres Server**: 50 个数据库操作工具
3. **Slack Server**: 15 个通讯工具
4. **GitHub Server**: 30 个代码管理工具

总计 100+ 工具。如果没有工具搜索，每次对话的上下文 (Context) 都会爆满。有了工具搜索，可以轻松挂载所有这些服务器，让 Claude 成为真正的全能 Agent，而只在真正需要“读文件”时才加载文件系统的工具定义。

## 3.6.9 案例推演：企业级运维助手

**User**: “生产数据库好像有死锁，帮忙看看。”

1. **Claude思考**: 用户提到了数据库死锁。我当前没有直接的工具。系统提示说我有数据库工具。
2. **Claude行动**: `tool_search_tool_bm25(query="database deadlock lock kill")`
3. **API返回**: 用于延迟加载的工具定义：
   * `pg_stat_activity`: 查看当前查询
   * `pg_cancel_backend`: 尝试取消正在运行的查询
   * `pg_terminate_backend`: 终止后端连接（破坏性操作）
   * `pg_locks`: 查看锁信息
4. **Claude思考**: 我需要先看锁。
5. **Claude行动**: `pg_locks()`
6. **API返回**: “Table users is locked by PID 1024.”
7. **Claude行动**: 先读取 `pg_stat_activity(pid=1024)`，确认 SQL、事务年龄、用户、业务影响和是否可重试。
8. **Claude行动**: 如需干预，先请求值班人员确认并优先 `pg_cancel_backend(pid=1024)`；只有取消失败且影响明确时，才升级到 `pg_terminate_backend(pid=1024)`。

整个过程流畅自然，且只消耗了必要的 Token。

***

随着工具的增多，不仅面临管理的挑战，还面临连接的挑战。如何标准化地连接本地文件、远程服务和各类数据库？

➡️ [第四章：MCP 模型上下文协议](/claude_guide/di-er-bu-fen-gong-ju-pian/04_mcp.md)