工具设计规范

工具是智能体的"双手"，工具定义的质量直接决定模型调用得准不准。设计不当的工具会被模型误用、漏用，甚至引发安全事故。本章给出一套可执行的工具设计清单，并配正反例对照。

命名：动词开头

工具名用英文动词短语开头，让人和模型一眼看懂"做什么"，避免含糊名词或缩写：

反例	正例	说明
data、util_1	get_user_info	动词 + 宾语，含义明确
email	send_email / list_emails	动作与对象分开

描述：写清何时用、参数含义与边界

description 是模型决定"要不要调用"的唯一依据，要写清楚触发时机、参数含义与能力边界：

• 何时用：什么场景该调用（用户问天气时）；
• 何时不用：明确排除（不知道城市时不要瞎猜调用）；
• 参数含义：每个字段的格式、单位、取值来源；
• 边界：不支持的能力（仅支持国内城市）。

{
  "name": "get_weather",
  "description": "查询国内城市实时天气。用户询问天气、出行建议时使用；用户未给出具体城市时先反问，不得猜测城市名。",
  "parameters": {
    "type": "object",
    "properties": {
      "city": { "type": "string", "description": "城市中文名，如 北京" }
    },
    "required": ["city"]
  }
}

参数 Schema：精简 + 枚举

参数能少则少，能用枚举就用枚举，避免让模型自由发挥文本；单位与取值范围写进 description：

"parameters": {
  "type": "object",
  "properties": {
    "unit": { "type": "string", "enum": ["celsius", "fahrenheit"], "default": "celsius" },
    "days": { "type": "integer", "minimum": 1, "maximum": 7 }
  },
  "required": ["unit"]
}

错误返回约定

函数要返回结构化结果而不是抛异常——模型看不见堆栈。约定统一错误格式，让模型能读懂并自行补救（如换参数重试或如实告知用户）：

return {"ok": False, "error": "city_not_found", "message": "查无此城市，请检查拼写"}
# 输出示例：模型读到 ok=False 后向用户解释并请求更正

幂等与副作用提示

写操作（下单、转账、发邮件）可能被模型重复调用，需在描述中声明副作用并设计幂等键；不确定是否有副作用的工具，宁可标注"执行后不可撤销"。

敏感操作需确认

涉及扣款、删除、对外发送等高风险动作，应拆成"创建待确认动作 + 确认执行"两步，或在描述中强制模型先向用户复述确认。

设计检查清单

检查项	要求
命名	动词开头，语义唯一，不与系统提示冲突
描述	含触发条件、参数含义、排除场景、边界
参数	精简、带枚举与取值范围、必填最小化
返回	永远结构化 JSON，错误带 code 与可读 message
副作用	描述中显式声明，必要时幂等设计
敏感度	高风险操作走确认流程

小结

工具设计四原则：动词命名、说明书式描述、Schema 精简带约束、错误结构化可恢复。写完工具后用"模型视角"通读一遍描述，想象它会不会误用——这就是最好的验收测试。