Technical article

智能体总调错工具？四个要点让调用稳如老狗

一、痛点场景

很多团队一上来就给智能体挂了十几个工具，结果它要么"该调不调"，要么"乱调一气"——让用户改个密码，它顺手把订单也删了；查个库存，它返回一堆看不懂的参数。问题往往不在模型，而在工具本身没设计好。工具是智能体的手脚，手脚没训过，脑子再聪明也干不好活。

二、核心方案：给工具做"岗位培训"

把工具当成新员工来培训——职责单一、说明书清楚、出错有预案、危险动作有闸。四个要点逐一落地，调用成功率能从六成拉到九成以上。

三、步骤实操：四个要点

1. 单一职责。一个工具只干一件事。别做"万能接口"——又查又改又发邮件，出错时你根本分不清是哪一步炸的。拆成"查库存""改库存""发通知"三个，互相独立、好测好查。

2. 清晰的参数 Schema。参数名、类型、取值范围、示例一样不能少。模型不是你肚子里的蛔虫，date 它不知道要 YYYY-MM-DD 还是时间戳，写清楚示例它才不乱填。

工具描述示例（伪 Schema）：
name: query_order
description: 按订单号查询订单状态（只读，不修改数据）
parameters:
  order_id: string, 格式 "NO2026xxxx", 必填
returns: {status, amount, created_at}

3. 失败可恢复。工具报错要返回"人话"——超时、参数错、权限不足分别说清，并给模型重试或换路的机会，而不是甩个 500 让它当场死机。

4. 权限收口。写操作默认加确认闸；能只读绝不给写；可撤销的操作优先。把"删库"这类危险动作锁在人工确认后面。

四、效果 ROI

某 SaaS 团队把 12 个杂糅接口重构成 23 个单一职责工具后，工具调用一次成功率从 61% 升到 93%，因工具误用导致的客诉下降七成。更重要的是，排查问题从"翻三天日志"变成"看一眼工具名就知道坏在哪"。

五、注意事项（三个坑）

① 工具不是越多越好：超过 30 个，模型反而选不准，定期砍掉低频工具。② 别迷信自动执行：写操作先走"草稿+确认"，跑稳了再放开。③ Schema 要随接口迭代：后端改了字段，工具描述不同步就会悄悄出错。

六、动手前先自检

下回给智能体挂工具，先拿这张四要点清单过一遍：职责单不单一？Schema 清不清？出错能不能恢复？危险动作有没有闸？四项全过，工具调用基本就稳了。好工具是设计出来的，不是堆出来的。