最佳实践（入门版）

如果你只记住几条经验，先记这几条：

1. 一个工具只做一件事

不要把“搜索 + 下单 + 发消息 + 改数据库”塞进一个工具。

好的工具应该：

• 边界清晰
• 易于描述
• 易于审计
• 易于测试

2. 把描述写给模型，不是写给程序员

工具 description 不是注释，它是模型决策的重要输入。

坏描述：

{ "description": "搜索" }

好描述：

{ "description": "搜索公开文档并返回最相关的标题、链接和摘要，不执行网页点击" }

3. 副作用工具一定要收权限

以下能力属于高风险工具：

• 发消息
• 删文件
• 执行 shell
• 调支付接口
• 改数据库
• 发布外部内容

这类工具必须有：

• 明确用途
• 参数校验
• 审计日志
• 必要时二次确认

4. 错误返回要结构化

不要只返回一行 failed。

更好的做法：

{
  "ok": false,
  "error_code": "TIMEOUT",
  "message": "weather upstream timed out after 5s",
  "retryable": true
}

5. 让工具尽量幂等

特别是写操作工具，最好支持：

• 重复调用不产生额外副作用
• 可以识别是否已执行
• 有 request id / operation id

否则一旦模型重试或网络重放，很容易出事故。