Claude Messages API 的工具定义有三个字段。每个都重要：name 标识、description 选择、input_schema 参数化。弱描述只产出 52% 准确率。模糊的 schema 字段名产出校验错误。三个都需要关注。
三个字段
name — 唯一标识符。出现在 tool_use block 中。起描述性的名字：get_order_status > tool_1。
description — 主要的选择机制。模型决定调哪个工具时，它读取和评估 description。这是路由可靠性最重要的字段。
input_schema — 定义参数的 JSON Schema。类型、必填字段、约束。告诉模型该提供什么数据。
描述质量 → 准确率数据
| 描述质量 | 准确率 |
|---|---|
| 40-50 词（用途、I/O、消歧） | 93-96% |
| 5-8 词（“Runs analysis”、“Summarize content”） | 52-61% |
详细描述稳定产出 93%+ 准确率。简略描述在 50-60% 徘徊——对多工具 agent 来说仅比随机好一点。
input_schema 字段描述很重要
一个工具有 {query: {type: "string"}} 和描述”Look up an order”，被调用时传了 {query: "John Smith"} 而不是 {query: "ORD-12345"}。模型不知道 query 指的是订单号。
修复：字段重命名为 order_id，加描述：“Order number (e.g., ORD-12345)“。Schema 中的字段名和描述引导模型的参数构造。
“字段名不言自明”——错了。file 可以是文件路径、文件内容或文件名。options 不说明有什么选项就毫无意义。字段描述的 token 成本很小，但换来的校验错误减少远超这点开销。
完整定义模板
每个工具约 50 词内：
- 用途：工具具体做什么
- 输入：接受什么（带格式引导）
- 输出：返回什么
- 什么时候用：具体用例
- 什么时候不用：消歧并重定向到正确工具
加上带描述和示例的 schema 字段名。
常见混淆
- “prompt”代替”description”：description 是选择指南，不是系统指令
- “parameters”代替”input_schema”：用 JSON Schema 格式，不是简单列表
- 定义中的实现细节：端点、handler、运行时配置是后端的事。定义是面向模型的
- MCP 命名：MCP 中
inputSchema（camelCase）vs Claude API 中input_schema（snake_case）
一句话总结： 工具定义需要描述性名称、详细描述（40+ 词带用途、I/O 和消歧产出 93%+ 准确率）、以及带字段级描述和示例的 input_schema——简略描述（5-8 词）只产出 52-61% 准确率。