工具设计的艺术

为什么工具 > 提示词

假设我总是漏掉某个步骤,或者老拿到脏数据。你有两条路修:一是往提示词里加更多叮嘱(「记得先验证输入!」「一定要检查返回码!」),二是重新设计工具让错误根本发生不了(让工具自己验证输入、返回结构化的成功/失败)。前者是在劝我,劝对概率性系统永远只是提高概率;后者是在约束我,把正确性变成结构上的必然。

一个具体例子:与其在提示里写「编辑文件前请务必先读文件,确认它没被别人改过」,不如设计一个 edit 工具,让它在文件自上次读取后被改动时直接拒绝写入。前者靠我记得,后者靠代码保证。这就是「好工具比好提示词更重要」的本质——把易错的约定,变成工具层的硬保证。

bash 还是专用工具?

一个绕不开的设计抉择。你可以只给我一个万能的 bash 工具(能跑任意 shell 命令),也可以给我一堆专用工具(read_file、edit_file、run_tests、send_email……)。两者的权衡很本质:

• bash 给我最大的能力面——几乎什么都能干。但它给你的宿主程序的只是一个不透明的命令字符串:每次都长一样,你没法针对性地拦截、渲染、审计或并行化。bash -c "curl -X POST ..." 和 bash -c "ls" 在你眼里没区别,都只是「一条命令」。
• 专用工具给你的是带类型的钩子——一个 send_email(to, body) 调用,你能在执行前弹窗让用户确认、能在日志里清楚记下「发了封邮件给谁」、能把只读的 grep 标记为可并行、把危险的 send_email 标记为需审批。

什么时候该把一个动作从 bash 里「提拔」成专用工具?判断标准:

• 需要安全闸门:难以撤销的动作(发消息、删数据、调外部付费 API)值得做成专用工具,好在执行前拦一道。
• 需要不变量检查:比如「文件改了就拒写」,只有专用 edit 工具能强制。
• 需要特殊渲染:比如「向用户提问」做成工具,好在 UI 上弹成一个模态框、阻塞循环等回答。
• 需要并行调度:只读工具(glob、grep)可以标为并行安全,而 bash 里你分不清一条命令是安全的读还是危险的写,只能串行。

经验法则:用 bash 打底求广度,把需要拦截/渲染/审计/并行的动作提拔成专用工具。不是非此即彼,而是分层。

description:写清楚「何时用」,而不只是「是什么」

上一章说过 description 是我选择工具的唯一依据。这里给你写好它的三条原则:

• 说触发条件,不只说功能。「查天气」不如「当用户问到天气、气温、是否下雨时,调用此工具查询某城市当前天气」。当代模型对工具的调用比过去更克制,把「什么情况下该叫我」写进 description,能明显提高该调时就调的比例。
• 给参数写说明和例子。每个字段配一句 description,复杂格式配个示例值。含糊的参数说明 = 我填错参数。
• 枚举能用就用。取值固定的参数(单位、状态、模式)用 enum 锁死,别让我自由发挥填字符串。

工具粒度:别太碎,也别太粗

工具太多太碎(几十上百个),会挤占上下文、让我在选择时犯迷糊——「该用 list_users 还是 query_users 还是 find_users?」。工具太少太粗(一个 do_everything(action, params)),又等于把复杂度全塞进一个参数里,我照样容易填错。

好的粒度是贴着任务的自然动作切:一个动作一个工具,名字明确不重叠,数量控制在我一眼能理解的范围。如果你确实有几百个工具(比如接了一大堆 API),现代方案是工具搜索(tool search)——不把所有工具定义一股脑塞给我,而是让我先「搜」出这次任务相关的少数几个,按需加载。这能同时解决「上下文太满」和「选择困难」。