在Agent项目上线后，用户反馈频繁遇到工具调用失败的问题。这背后的原因有60%源自设计阶段。本文将深入探讨PM在工具颗粒度、描述与失败处理上的三大决策点，通过实战案例展示如何避免Agent失控。
--91likeyou---
用户让Agent帮他查一份合同，Agent调了十几次工具，绕了一大圈，最后要么超时，要么返回错误结果。工程师说“模型不稳定”，但你隐约感觉，问题不只在模型。
你的感觉是对的。Agent工具调用的质量，60%由设计阶段决定，不是推理阶段。
作为PM，你不需要写代码，但你必须在以下三个决策点上给出清晰答案。
一、工具颗粒度：太粗还是太细，都是灾难
工具设计最常见的两种错误：
太粗：一个工具做太多事。比如 processOrder()，内部包含校验、扣库存、发消息、写日志。Agent调用一次就触发了一堆副作用，出错了不知道哪步出了问题，也没法重试局部步骤。
太细：工具拆得太碎，Agent要完成一个任务需要连续调用十几个工具，上下文窗口被工具结果撑满，推理质量急剧下降。有研究显示，工具调用超过8次后，主流模型的任务完成率会下降20%以上。
正确的颗粒度原则：一个工具完成一个原子操作，结果可验证，副作用可预期。
拆分标准不是“技术上能不能拆”，而是“Agent能不能独立判断这个工具的结果是否符合预期”。如果工具返回的结果需要另一个工具来验证，说明颗粒度已经太细了。
PM的决策动作：在工具列表评审时，对每个工具问一个问题——“Agent调用这个工具后，它能自己判断成功还是失败吗？”如果不能，要么合并，要么补充返回值设计。
二、工具描述：模型靠这个决定调不调
很多PM认为工具描述是工程师的事。这是个认知误区。
工具描述（tool description）直接影响模型的工具选择决策。模型不看代码实现，只看描述。一段写得含糊的描述，会让模型在两个功能相近的工具之间随机选择，或者在不该调用的时候调用。
常见的烂描述：
- search(query) — “搜索相关内容”
- get_data(id) — “获取数据”
- update(params) — “更新信息”
这类描述在工具少的时候没问题，但当工具超过10个时，模型的调用准确率会显著下降。
好的描述应该包含四个要素：
这个工具做什么（动作） 适用的场景（When to use） 不适用的场景（When NOT to use）——这点最容易被忽视 返回值的结构和含义 举个例子，把 search_contract(query) 的描述从“搜索合同”改成：
“在合同数据库中全文检索合同。适用于用户提供关键词、合同编号、甲方名称时。不适用于查询合同状态或审批流程（请用 get_contract_status）。返回匹配合同列表，每项包含 id、标题、签署日期。”
这一改，工具调用准确率通常能提升30-40%。
PM的决策动作：在工具上线前，组织一次“工具描述评审”，让非技术成员（如运营、客服）读完描述后说出“这个工具适合在什么场景下用”——如果说不出来，描述需要重写。
三、失败处理：Agent失控的根源
工具调用失败有三种情况：
硬失败：网络超时、接口报错，有明确错误信息 软失败：调用成功，但返回空结果或不符合预期的结果 幻觉调用：模型以为调用成功了，但实际上没有（参数格式错误、工具不存在等） PM最容易忽视的是软失败。
当工具返回空结果，模型往往不会停下来报错，而是继续推理，用“假设这个结果存在”的逻辑往下走。这就是为什么你会看到Agent明明查不到数据，却返回一个“看起来合理”的编造答案。
解决方案是为每个工具设计明确的失败语义：
- 返回值中增加 success: boolean 和 reason 字段
- 空结果不返回空列表，返回带原因的失败对象：{“success”: false, “reason”: “no_match”, “suggestion”: “try broader keywords”}
- 在工具描述中明确告诉模型：”当返回 success=false 时，不要继续假设数据存在，应告知用户”
PM的决策动作：在PRD中为每个工具补充“失败场景处理规范”，明确规定软失败时Agent的行为——是重试、是降级、还是直接告知用户。这不是工程实现细节，是产品行为设计。
总结：PM在工具设计上的三个决策
| 决策点 | PM需要回答的问题 | 常见失误 |
|——–|—————-|———|
| 工具颗粒度 | Agent能独立验证结果吗？ | 太粗导致副作用失控，太细导致上下文超载 |
| 工具描述 | 非技术人员能理解适用场景吗？ | 缺少“不适用场景”，导致工具选择混乱 |
| 失败处理 | 软失败时Agent该做什么？ | 空结果被模型当成“没有限制”继续推理 |
Agent项目失败，工程师通常先看模型、先看推理链。但在这之前，先问自己：工具设计评审做了吗？
如果没有，从这三个问题开始。
题图来自 Unsplash，基于CC0协议
🔥 热词：#agent tools · #agent-specific · #agent程序 · #agent功能 · #agentlib · #agent handler · #agent client · #agentpath