Tool Calling 最佳实践

1. 工具设计：短、小、稳

一个好工具通常具备三个特征：

• 短：名称和 schema 不冗长
• 小：职责单一
• 稳：参数稳定、结果结构稳定

好例子

{
  "name": "search_docs",
  "description": "搜索文档并返回标题、链接和摘要",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {"type": "string"},
      "limit": {"type": "integer", "minimum": 1, "maximum": 10}
    },
    "required": ["query"]
  }
}

坏例子

{
  "name": "do_everything",
  "description": "执行各种操作",
  "parameters": {
    "type": "object",
    "properties": {
      "payload": {"type": "string"}
    }
  }
}

2. 副作用操作必须可审计

发送消息、执行命令、修改文件、调用外部 API，这些都是副作用行为。

至少要有：

• 参数记录
• 执行结果记录
• 失败原因记录
• 必要时用户确认

3. 错误结构要统一

推荐至少包含：

{
  "ok": false,
  "error_code": "INVALID_ARGUMENT",
  "message": "field city is required",
  "retryable": false
}

4. 工具结果尽量对模型友好

不要只把底层异常栈扔回去。更好的做法是返回：

• 简洁状态
• 核心字段
• 必要解释
• 下一步建议

5. 对并行与重试保持克制

并行不是越多越好，重试也不是越猛越好。

要先确认：

• 工具是否无共享状态
• 上游是否有限流
• 操作是否幂等
• 失败是否值得重试

6. 给工具命名留长期空间

工具名一旦进入 prompt / schema / 代码 / 监控体系，就不适合频繁改动。

所以：

• 名称要清楚
• 不要过度品牌化
• 不要把临时实现细节写进工具名