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 核心机制：按需加载 (Deferred Loading)

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

1. 定义：在 tools 列表中，可以提供数千个工具，但将绝大多数标记为 defer_loading: true。

2. 隐藏：对于这些延迟加载的工具，Claude 初始时看不到它们的完整定义。它只知道“这里有很多关于数据库和代码的工具”。

3. 索书号：不仅如此，为了帮助 Claude 找到它们，会提供一个特殊的工具搜索工具。

4. 发现：当用户问“重启数据库”时，Claude 意识到自己当前手中的工具不够用，于是调用“搜索工具”。

5. 加载：搜索工具返回了最相关的 3 个工具（如 restart_db_service）。此时，这 3 个工具的完整定义才真正进入上下文窗口。

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

3.6.3 内置搜索变体

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

内容搜索 (BM25 Variant)

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

• Type ID: tool_search_tool_bm25_20251119

• 原理：经典的 BM25 算法。它根据工具的 name 和 description 计算相关性。

• 适用场景：你的工具描述写得非常自然语言化，或者用户提问比较模糊。

  • User: "服务器卡死了"

  • Search: "server performance lag"

  • Match: check_cpu_usage, restart_nginx

正则搜索 (Regex Variant)

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

• Type ID: tool_search_tool_regex_20251119

• 适用场景：拥有严格命名规范的工具库。

  • Pattern: aws_ec2_.* (查找所有 EC2 相关工具)

  • Pattern: (?i)user (查找所有包含 user 的工具，忽略大小写)

3.6.4 API 定义示例

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

{
  "tools": [
    // 1. 立即加载的核心工具 (Eager)
    {
      "name": "help",
      "description": "获取系统帮助",
      "input_schema": { ... }
    },
    
    // 2. 引入搜索能力 (Search Tool)
    {
      "type": "tool_search_tool_bm25_20251119",
      "name": "search_tools" // 自定义名称
    },
    
    // 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 最佳实践：构建可搜索的工具库

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

命名规范化

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

• category_action_object

• ✅ github_issue_create, github_issue_close

• ❌ new_task, close_it

关键词填充 (Keyword Stuffing)

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

• description: "Updates user permissions. Keywords: admin, auth, rbac, grant, revoke."

• 这样即使用户说“修改权限”或“授权”，都能被 BM25 命中。

引导地图 System Prompt

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

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

3.6.6 与 MCP 的天作之合

工具搜索是 MCP (Model Context Protocol) 生态的关键粘合剂。

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

1. Filesystem Server: 20 个文件操作工具

2. Postgres Server: 50 个数据库操作工具

3. Slack Server: 15 个通讯工具

4. GitHub Server: 30 个代码管理工具

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

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

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

1. Claude思考: 用户提到了数据库死锁。我当前没有直接的工具。系统提示说我有数据库工具。

2. Claude行动: search_tools(query="database deadlock lock kill")

3. API返回: 用于延迟加载的工具定义：

   • pg_stat_activity: 查看当前查询

   • pg_terminate_backend: 杀进程

   • pg_locks: 查看锁信息

4. Claude思考: 我需要先看锁。

5. Claude行动: pg_locks()

6. API返回: "Table users is locked by PID 1024."

7. Claude行动: pg_terminate_backend(pid=1024)

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

---

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

➡️ 第四章：MCP 模型上下文协议