Agent 好不好用，取决于工具怎么设计

做第一个 Agent 时，我把精力全放在系统提示词上：写行为准则、写思考框架、写few-shot 示例。上线后它依然频繁出错——不是想错了，是做不成。

比如让它"查一下某客户的合同到期时间"，它调了三次工具：第一次参数错，第二次查错了表，第三次超时。最后给我一句"抱歉，我无法获取"。

问题不在模型，在我的工具设计。

原则一：一个工具做一件事

最早我设计了一个万能工具 query_database(sql)。模型生成的 SQL 一半是错的，因为表结构有 30 多张表，它记不住字段名。

改成专用工具：get_customer_by_name、list_contracts_by_customer、get_contract_detail。每个工具参数少、语义清楚，模型几乎不会调错。

原则二：参数尽量是枚举，不是自由文本

自由文本参数是错误的重灾区。让模型传"时间范围"，它可能传 最近一个月、30天、2026-09、last month，什么都有。

我们改成枚举：period: "7d" | "30d" | "90d" | "custom"，选 custom 才要求传具体日期。参数错误率从 30% 降到 4%。

原则三：返回值要短，但要有足够的判断依据

工具返回一大堆原始数据是没用的，模型读不完也抓不住重点。返回一句话总结加几个关键字段，比返回 200 行 JSON 有用得多。

但也别只返回"成功/失败"。模型需要知道为什么失败才能调整。错误信息要写清楚：是参数不对、权限不够、还是数据不存在。

原则四：工具自己处理常见情况

让模型做"如果查不到就用另一种方式查"这种分支，它会乱。不如在工具内部就把降级逻辑写好：按名字查不到，自动按拼音模糊查一次；还是查不到，返回"未找到，最接近的是 XX"。

模型只需要决策"要不要继续"，不需要决策"用什么 SQL"。

原则五：写清楚什么时候不该用

工具的 description 里，大部分人只写"这个工具能做什么"。更重要的往往是"什么时候不要用"。

比如 send_email 的描述里要写："仅在用户明确要求发送邮件时使用。不要用于发送通知、提醒或测试。" 不写这句，模型会在各种奇怪的时候发邮件。

原则六：数量控制在 10 个以内

工具太多，模型选择困难，而且很容易选错相似的。我们的经验是单个 Agent 的工具不超过 10 个，超过就拆成多个 Agent，或者加一层路由先判断意图。

一句话总结：把 Agent 当成一个聪明但不熟悉你系统的新同事。你不会给他一个 SQL 客户端让他自己摸索，你会给他几个明确的按钮。