给 Agent 设计工具时，我踩过的 4 个坑

最近在做一个能帮我整理待办、查资料的小 Agent。核心机制是工具调用：我把一组函数描述给模型，模型决定什么时候调用哪个、传什么参数。看起来简单，实际踩了不少坑。

坑一：工具太多，模型选不准

一开始我一口气给了十几个工具，结果模型经常选错，或者在相似的工具之间犹豫。后来把功能相近的合并，只保留最核心的几个，准确率明显提升。

经验：工具宁少勿多，每个工具的职责要清晰、不重叠。

坑二：描述写得太简略

search(query) 这样的描述，模型并不知道它能搜什么、不能搜什么。把描述写成给新同事看的说明：什么时候该用、返回什么、有什么限制。

{
  "name": "search_notes",
  "description": "在我的个人笔记中做全文搜索。适合查找我以前记录过的结论或代码片段；不能搜索互联网。返回最多 5 条结果，每条包含标题和摘要。",
  "parameters": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "搜索关键词，尽量具体" }
    },
    "required": ["query"]
  }
}

坑三：出错时只返回“失败”

工具报错时如果只告诉模型“调用失败”，它往往会原样重试。返回具体原因和建议——比如“日期格式应为 YYYY-MM-DD”——模型通常能自己修正参数再试一次。

坑四：返回内容太长

把整篇文档原样塞回给模型，很快就会挤占上下文。现在我的工具都会先截断或摘要，只返回模型做下一步决策需要的信息。

总结

设计工具，本质上是在给一个聪明但不了解背景的同事写接口文档。站在模型的角度想一想“我拿到这个工具会怎么用”，大部分坑都能提前避开。