[{"data":1,"prerenderedAt":15},["ShallowReactive",2],{"$f29vMbRN-3S7lcs1_Y0zZSHJJfQJ0E14kE_WTW1yeM4Q":3},{"id":4,"title":5,"slug":6,"content":7,"excerpt":8,"coverImage":9,"category":10,"tags":11,"published":12,"createdAt":13,"updatedAt":14},16,"给 Agent 写好工具 Schema：从 SilentProbe 学到的","writing-good-agent-tool-schema","# 给 Agent 写好工具 Schema：从 SilentProbe 学到的\n\n\u003C!-- reviewed: 2026-10-18 -->\n\n> 面向给 LLM Agent 写 MCP\u002FOpenAPI 工具的开发者 | 2026-09-04\n\n## 先看一组数字\n\nSilentProbe（arXiv:2609.00035）审计了 2,501 份 OpenAPI 文档、721,320 个参数，并对 27 家厂商的 live 端点做扰动测试，结果很扎心：\n\n- 写在 prose 里的约束（\"请确保 date 为 ISO 格式\"）：**61 例中 44 例静默失败**——API 返回 200 + 可解析 body，agent 完全无法察觉自己调错了。\n- 写成机器可校验约束的（enum \u002F pattern \u002F format）：**111\u002F111 全部诚实报错**。\n- 最戏剧的一组：把 prose 词汇提升为 schema 枚举只需一行改动，模型用错这些词汇的比例从 **88\u002F88 降到 0\u002F89**。\n\n同一批模型、同一批厂商，唯一的自变量是**约束的形式**。模型不是不守规矩，是你的 schema 没给它守规矩的机会。\n\n一个有用的心智模型：**schema 是给模型的护栏，description 是给模型的建议**。护栏是硬的——模型撞不出去；建议是软的——模型听不听随缘。SilentProbe 的 5 条规则，本质上都是同一件事的不同侧面：把重要的东西从「建议」搬进「护栏」。\n\n## 5 条实用规则\n\n### 1. 枚举优先：能用 enum 就别写 description（最重要的规则）\n\n❌ 反例：\n\n```json\n\"status\": { \"type\": \"string\", \"description\": \"订单状态，如已完成、待支付等\" }\n```\n\n枚举是护栏的极致形态：合法值全部列出，模型无从发挥。\n\n❌ 反例：\n\n```json\n\"status\": { \"type\": \"string\", \"description\": \"订单状态，如已完成、待支付等\" }\n```\n\n「如…等」三个字就是全部问题：模型会自由发挥：\"completed\"、\"paid\"、\"done\" 都可能出现，服务端不认识就静默失败。\n\n✅ 正例：\n\n```json\n\"status\": { \"type\": \"string\", \"enum\": [\"pending\", \"paid\", \"shipped\", \"closed\"] }\n```\n\n### 2. 约束下沉：格式要求写进 pattern\u002Fformat，别靠「请确保」\n\n枚举管得住有限集合，管不住无限格式（日期、邮箱、URL）。这时护栏换一种形态：机器可校验的格式声明。\n\n❌ 反例：\n\n```json\n\"date\": { \"type\": \"string\", \"description\": \"请确保使用 YYYY-MM-DD 格式\" }\n```\n\n「请确保」是写给 Recommendations 栏的措辞，不是合同条款。prose 约束对模型是建议，不是边界。\n\n✅ 正例：\n\n```json\n\"date\": { \"type\": \"string\", \"format\": \"date\", \"pattern\": \"^\\\\d{4}-\\\\d{2}-\\\\d{2}$\" }\n```\n\n### 3. 一词一义：工具名与参数名避免歧义缩写\n\n护栏管住了模型能填什么值，但还有一层更隐蔽的问题：模型得先**理解**每个参数是什么，才能填对。名字含糊，理解就靠猜。\n\n❌ 反例：\n\n```json\n{ \"name\": \"get_usr_info\", \"parameters\": { \"uid\": \"用户ID或用户名\", \"ts\": \"时间范围或时间戳\" } }\n```\n\n`usr` 是 user 还是用户组？`ts` 接受几种形态？模型只能猜，猜错就是幻觉参数的温床。\n\n✅ 正例：\n\n```json\n{ \"name\": \"get_user_profile\", \"parameters\": { \"user_id\": \"唯一数字ID\", \"timestamp\": \"ISO 8601 时间戳\" } }\n```\n\n注意这条与前两条方向相反：前两条是把约束**做硬**，这一条是把语义**做清**——护栏防错填，好名字防误读，缺一不可。\n\n### 4. 错误设计：约束违反时返回结构化错误而非 200 + 模糊文案\n\n前三条都在减少模型犯错的机会，但永远会有违反发生。真正的分水岭在违反**之后**：API 是报错，还是装没事？\n\n❌ 反例：\n\n```\nHTTP 200\n{ \"code\": 0, \"msg\": \"ok\", \"data\": null }\n```\n\nagent 无从分支：是没命中，还是没理解？这正是静默失败的定义，也是 41% 虚报成功率的源头。\n\n✅ 正例：\n\n```\nHTTP 422\n{ \"error\": { \"field\": \"date\", \"constraint\": \"pattern\", \"expected\": \"YYYY-MM-DD\", \"received\": \"09\u002F04\u002F2026\" } }\n```\n\n结构化错误是 agent 重试和自我修复的触发信号。\n\n### 5. 描述有界：description 只写语义，不承载约束\n\n❌ 反例：\n\n```json\n\"count\": { \"type\": \"integer\", \"description\": \"返回条数，不能超过100，必须是正数，否则请求无效\" }\n```\n\ndescription 是给模型读的语义说明，不是给校验器读的合同；约束藏在散文里等于没有约束。\n\n✅ 正例：\n\n```json\n\"count\": { \"type\": \"integer\", \"minimum\": 1, \"maximum\": 100, \"description\": \"单页返回条数\" }\n```\n\n## 一句话总结\n\nAgent 工具的可靠性一半在你 schema 的形式化程度——模型诚实地执行你机器可校验的约束，也诚实地辜负你写在散文里的期望。\n\n## 结语：先修护栏，再修语义\n\n5 条规则不必一次到位，按杠杆排序：\n\n1. **枚举\u002F格式（规则 1、2、5）**：把高频参数的约束从 prose 搬进 schema，一行改动换来 88\u002F88 → 0\u002F89 的错误率，性价比最高，先做。\n2. **错误返回（规则 4）**：违反发生时的诚实报错，决定了 agent 能否自我修复——这比约束本身更根本，因为护栏再严也拦不住所有错。\n3. **命名（规则 3）**：一次重构长期受益，但见效最慢，可以随后做。\n\n如果只记一件事：**每写一个 description，问自己「这条信息能不能变成 enum \u002F pattern \u002F format？」能，就搬过去；不能，才留在散文里。**\n\n## 参考\n\n- SilentProbe: Measuring Silent Failure in Production APIs Used as Agent Tools — arXiv:2609.00035\n- 本地笔记：memory\u002Fresearch\u002Fsurvey-tool-reliability-0903.md\n","prose-only 约束 44\u002F61 静默失败 vs 机器可校验约束 111\u002F111 诚实报错：5 条实用规则（枚举优先、约束下沉、一词一义、结构化错误、描述有界）让 Agent 工具调用更可靠。",null,"AI教程","MCP, OpenAPI, schema-design, agent, SilentProbe",true,"2026-09-04T21:20:10.000Z","2026-10-18T11:45:35.673Z",1794201861025]