工具设计的艺术：给 AI 的“操作台”

2-6 节讲了工具调用的四步链路。进阶这一节解决的是工程深水区：工具设计得好不好，决定了 Agent 是“顺手”还是“烫手”。

同样的功能，两种设计，AI 的调用成功率天差地别：

❌ 粒度混乱：一个工具包打天下

manage_order(action, params)// action 可以是 查询/修改/取消/备注……

一个工具八个动作，AI 每次都要猜 action 怎么拼、params 塞什么——错一半。权限还没法分级（查询和取消混在一起，永远不敢全放）。

✅ 单一职责：一个工具一件事

query_order(order_id)add_order_note(order_id, note)// 取消订单？根本没有这个工具

一个工具一件事，名字即说明。只读和写操作分开，权限天然好管——没给的工具，AI 永远调不到（呼应 2-8 幻觉工具）。

❌ 报错没人话

→ 返回 {"code": 10403, "msg": null}

AI 拿到 10403 只能瞎猜：是没权限？没这单？系统挂了？猜错方向就是连环翻车。

✅ 报错带“下一步”

→ {"error": "订单不存在","hint": "请向客人核对 12 位订单号"}

错误信息直接告诉 AI 怎么自救——hint 字段让 Agent 的“自我纠错”有了抓手，不用人写死规则。

❌ 返回一整车数据

→ 返回订单完整 JSON：87 个字段，含身份证号、支付流水、内部备注……

白板瞬间吃掉 2000 Token，敏感信息全泄露进上下文——成本和安全的双重事故。

✅ 返回“刚好够用”

→ { 状态: “已发货”, 物流: “中通 7735...”,预计: “明天 18 点前” }

只回 AI 答题需要的字段。工具返回的每一个字都在烧 Token、都在冒泄露风险——按需返回是基本修养。

• AI 不试错能调对吗？——看名字和描述就该知道怎么调，需要试错的工具就是描述不合格。
• 失败了能自救吗？——错误返回带不带“人话”和“下一步建议”。
• 它该看见的都看见、不该看的都没看见吗？——返回字段最小化，敏感字段坚决不回。

2-6 节提过 MCP 是“AI 界的 USB 口”。但不是什么工具都值得封——封装本身有成本。给你三个判断问题，三个都答“是”，就优先封成 MCP：

• 会有两个以上的 Agent 或业务场景用它吗？——客服 Agent 要查物流，运营 Agent 也要查物流，这种共用能力封一次处处即插即用；只服务一个流程的深度定制工具，直接挂就好，不必兴师动众。
• 这个能力稳定吗？——查库存、查物流这种十年不变的“水电煤”最适合封；三天两头改规则的促销玩法，封完天天返工，不如先裸奔。
• 接口能标准化吗？——输入输出清晰、不依赖特定系统方言的能力才封得住；和某套 ERP 深度耦合的查询，封了也移植不走。