工具 schema 声明 协议

它是什么

工具 schema 声明是写给模型看的「说明书」：工具叫什么（name）、什么时候用（description）、参数长什么样（parameters）。模型只能看到这份声明、看不到实现代码——description 写得越清楚，模型选对工具的概率越高。OpenAI 兼容接口里它挂在请求体的 tools 数组下（type: 'function' + function: { name, description, parameters }），Anthropic 里则是 { name, description, input_schema } 的扁平结构——参数 schema 直接叫 input_schema，没有 function 包装层。

参数描述用的正是 JSON Schema

parameters 本身就是一个 JSON Schema：type: 'object' + properties 声明每个参数的类型与说明 + required 标记必填。第 05 章手写过 JSON Schema 校验器，这里直接复用它的结论——schema 是给模型看的契约，模型按它填参数。官方还推荐用 enum 收窄可选值、把「什么时候该调我」写进 description，都能显著减少模型填错参数。

常见坑

• description 写得太模糊（「随便查点东西」），模型选错工具；
• 参数 schema 与实际实现手抄两份、互相漂移——用第 08 章的「从声明式 spec 生成 schema」根治；
• 嵌套参数的类型与约束描述不完整，模型只能靠猜。

小结

工具 = schema 声明（给模型看）+ 实现（给我们用）。schema 是工具调用的「用户界面」，值得像写 API 文档一样认真对待。