agent-mcp-">让 AI Agent 工具调用更准确：MCP 工具设计核心技巧（上）

引言：工具“能用”与 Agent“会用”是两回事

越来越多的开发团队开始为 AI Agent 开发工具。无论是通过 MCP（Model Context Protocol）、Skills 脚本，还是直接在模型接口中使用 function calling，一个共性问题正在反复出现：

工具在技术层面完全正确，Agent 却用不好。

具体表现包括：

• 工具本身可以正常执行，schema 定义没有错误，API 调用也能成功返回；
• 但 Agent 总是在多个工具之间选错目标；
• 或者选对了工具，却传入了错误的参数；
• 或者在本应调用工具时，直接回复“我无法完成这个任务”。

如果只从工程实现的角度检查，这些问题似乎“不应该发生”。但如果从 Agent 的行为机制出发，就会发现根源其实非常清晰。

---

一、问题根源：我们仍在用写 API 的思维设计 Agent 工具

1.1 人类开发者与 Agent 的差异

当我们为人类开发者设计 API 时，通常会默认对方具备以下能力：

• 会主动阅读文档；
• 能理解上下文和调用时机；
• 遇到错误会调试、重试、修正参数；
• 能结合业务背景推断接口的真实意图。

但 Agent 完全不同。一个基于大语言模型的 Agent，并不会像人类一样“研究”你的接口文档。它对工具的全部理解，主要来自三个信息源：

• 工具名称
• 工具描述
• 参数 schema

除此之外，它看不到你的代码实现，无法通过调试定位问题，也不会真正“理解”你的业务系统内部逻辑。

1.2 调用成本与选择压力

Agent 的每次工具调用都有实际成本：

• 调用过程需要消耗 token；
• 错误调用可能导致无效等待或副作用；
• 在几十甚至上百个工具中，Agent 需要在极短时间内完成筛选；
• 虽然模型具备一定的试错能力，但试错成本高且结果不稳定。

这意味着，工具设计的核心问题并不是“能不能跑通”，而是：

Agent 能否在有限上下文、有限信息和有限推理步骤内，持续做出正确选择。

---

二、核心理念：Agent 工具是 Agent 的用户界面

2.1 一个关键的思维转换

要解决上述问题，首先要完成一个设计视角的转变：

Agent 工具不是已有 REST API 的封装，而是 AI Agent 的用户界面。

传统 REST API 面向的是人类开发者。人类会阅读文档、理解业务语义、根据上下文调整调用方式。而 Agent 是一种完全不同的“用户”：

• 它不会主动查阅外部文档；
• 它不擅长从模糊上下文推断隐含信息；
• 它每次调用几乎都是从工具元数据重新开始理解用途；
• 它高度依赖名称、描述和 schema 的清晰程度。

换句话说，你并不是在“封装一个接口”，而是在教会一个智能体如何与你的系统交互。

2.2 理解这个“用户”的长处与局限

这个智能体的能力边界非常明确。

它擅长：

• 理解自然语言；
• 推理用户意图；
• 组合多个信息片段；
• 根据描述做出合理判断。

它不擅长：

• 精确数值计算；
• 记住超长上下文中的细节；
• 从模糊描述中猜测正确参数；
• 在信息不足时主动澄清复杂业务规则。

最关键的一点是：它只能看到你暴露出来的 schema 和描述，无法感知你的实现细节。

同时，Agent 的上下文窗口是有限的。随着对话变长，工具调用性能会明显下降。因此，工具设计需要在“信息充分”和“信息简洁”之间找到平衡。

---

三、工具设计的第一原则：让描述足够“可理解”

3.1 工具名称要直接表达动作

很多开发者在命名工具时，会沿用内部系统的方法名或 REST 路径风格，例如：

get_order_detail
query_user_info_v2
fetch_resource_by_id

这些命名对人类开发者来说可能没有障碍，但对 Agent 来说，名称是最先被扫描的信息。模糊或过于简化的名称会显著增加选择错误率。

一个更有效的命名思路是：

• 使用“动词 + 名词”结构；
• 动词要明确表达动作，如 search、create、update、cancel；
• 名词要明确表达对象，避免使用抽象词汇，如 resource、item；
• 尽量避免版本号后缀，除非版本差异会影响调用方式。

例如，将 get_order_detail 调整为 search_order_by_id，将 query_user_info_v2 调整为 search_user_by_account，可以让 Agent 更准确地判断适用场景。

3.2 工具描述要回答“什么时候用、用来做什么”

很多工具描述只写了功能，没有写使用条件。例如：

查询订单信息

这个描述没有告诉 Agent：

• 什么情况下应该使用这个工具；
• 输入是什么；
• 输出是什么；
• 与其他查询工具的区别是什么。

更好的描述应该包含以下要素：

• 功能：这个工具能完成什么；
• 适用场景：用户提出什么需求时应该调用；
• 不适用场景：什么情况下不应该调用；
• 关键输入：最重要的参数是什么；
• 输出摘要：返回结果包含哪些关键信息。

示例：

根据订单号查询单个订单的详细信息，包括状态、金额、商品列表和时间信息。
适用场景：用户询问某个具体订单的状态、金额或详情。
不适用场景：用户需要按时间范围批量查询订单时，应使用 search_orders_by_time_range。
关键输入：order_id，必须是纯数字字符串。
输出：订单详情对象；如果订单不存在，返回 not_found。

这种描述虽然更长，但能够显著降低 Agent 的选择与参数填充错误率。

---

四、参数设计：少而明确，避免“自由发挥”

4.1 减少非必要参数

Agent 的参数填充能力受限于当前上下文和 schema 描述。参数越多，填充错误的概率越高。设计时应遵循：

• 只保留完成任务所必需的参数；
• 能通过工具内部逻辑推导的值，不要让 Agent 填写；
• 能用枚举约束的值，不要完全开放。

例如，一个内部方法需要传入租户 ID。但这个 ID 完全可以从当前会话或认证信息中获取，就不应该暴露给 Agent。

4.2 为参数提供清晰的类型和取值约束

参数 schema 不能只定义 type: string。应当充分利用约束能力：

• 使用 enum 限定可选取值；
• 使用 description 说明格式和示例；
• 对数字范围进行限制；
• 对字符串长度、日期格式进行明确说明。

一个容易出错的例子是日期参数：

{
  "start_time": {
    "type": "string"
  }
}

Agent 可能会传入：

2024年1月
昨天
2024-01-01 00:00:00
20240101

更合理的设计是：

{
  "start_time": {
    "type": "string",
    "description": "查询开始时间，格式为 YYYY-MM-DD，例如 2024-01-01",
    "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
  }
}

4.3 避免让 Agent 做复杂计算

如果工具需要某个时间范围，不要要求 Agent 根据“近一周”自行计算起止日期。可以提供两个选择：

• 暴露一个显式的时间范围参数；
• 或者提供 period 枚举，如 today、last_7_days、last_30_days。

后一种方式将计算任务从模型侧转移到了工具实现侧，这正是设计工具时应当承担的责任。

---

五、边界控制：让工具“知道什么时候不该用”

5.1 明确失败条件

Agent 在遇到信息不足时，容易产生两种行为：

• 胡乱猜测参数并调用工具；
• 直接拒绝回答用户。

要减少这两种情况，工具描述中应明确列出失败条件。例如：

如果 order_id 参数缺失或格式不合法，返回参数错误对象，不要尝试推测。

将“失败路径”显式化，可以帮助 Agent 更理性地决定是否继续调用。

5.2 区分相似工具

当系统中有多个功能相近的工具时，Agent 的选择准确率会显著下降。例如：

• search_order_by_id
• search_order_by_user
• search_orders_by_time_range

如果三个工具的描述都很简短，Agent 很容易混淆。此时需要在每个工具的描述中加入“与其他工具的区别”字段，甚至在系统提示层面对工具分组进行说明。

5.3 控制工具数量

工具数量越多，选择空间越大，错误率越高。一个实践中常被忽视的思路是：

与其暴露大量细粒度工具，不如提供少量高内聚工具。

例如，将 get_user_info、get_user_orders、get_user_invoices 合并为 get_user_overview，返回聚合信息，可以在很多场景下降低选择复杂度。

---

六、总结：从“接口正确”走向“交互正确”

为 Agent 开发工具，本质上是在设计一种新的交互方式。技术实现的正确性只是基础门槛，真正的挑战在于：

• Agent 能否快速理解工具用途；
• 能否在合适场景调用正确工具；
• 能否用最少信息完成参数填充；
• 能否在信息不足时做出合理判断。

实现这一切的前提，是完成从“写 API”到“设计用户界面”的思维转变。

在下半部分中，我们将进一步讨论工具返回结果的设计、错误处理策略、上下文管理，以及如何通过测试和评估持续优化 Agent 的工具调用质量。