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 定义示例

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

{
  "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 工具的选择与命名空间化原则

在大规模工具生态中，简单地增加工具数量往往会导致反效果。本小节总结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评判或人工评审

示例：

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"
    }
]

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

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

• Agent 调用了哪些工具

• 每个工具调用的参数是什么

• 返回结果是否有用

• Agent 最终是否正确完成了任务

关键：

• 记录Agent的"思维过程"（推理步骤）

• 捕捉Agent遇到的困惑或重试

• 量化效率指标：总Token数、API调用次数、完成时间

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

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

做法：

• 将评估日志导入Claude Code或您的编程环境

• 要求Agent分析：哪些工具描述导致了混淆？哪些工具参数不清晰？

• Agent会建议改进方案（优化描述、拆分工具、重命名等）

• 实施改进，重新运行评估，验证是否有改善

实战案例数据

Anthropic 内部的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 运维。如果遇到相关问题，请使用 search_tools 查找具体命令。”

3.6.8 与 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.9 案例推演：企业级运维助手

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 模型上下文协议