给 Codex 的 MCP 工具为什么要随页返回 schema？一次重建实验的量化答案

作者用内存 SQLite 重建了 osFoundry 的四个 record 工具，再写一个脚本化的 Codex 跑分拣任务，实测「列表页附带字段 schema」、错误信息详细程度、before_id 游标分页对 agent 成功率的影响。结论很硬：没有 schema 时首次编辑全部失败，补上 schema 后保存率到 97.6% 的天花板，编辑调用次数也从 7 次降到 1.14 次。

问题：工具 schema 里写不下字段定义

• edit_record_item 的 values 参数只是 {"type": "object"}，因为每个 channel 的字段不同，还会被人随时改 Schema tab
• 字段类型固定为 16 种：text、number、date、boolean、email、phone、url、select、multi_select、currency、percentage、rating、relation、file、json、formula
• select 字段存的是 value（如 in_progress），界面显示的是 label（如 In progress），agent 只见过 label 就会发错值
• 所以 Codex 学习字段的唯一途径，是 list_record_items 每页返回的 schema

重建实验怎么搭的

• record_store.py 在内存 SQLite 上实现四个工具，工具名、参数、上限与线上一致，编辑放在 BEGIN IMMEDIATE 事务里：幂等键查找、版本比对、校验、合并、版本号递增、事件追加
• triage.py 是脚本化的 Codex，面对 11 个字段的 bug tracker，每轮 200 条 New 项，意图用人类语言表达（"In progress"、"Aiko"、"Friday"）
• agent 收到拒绝后只修错误信息能指出的部分，修不了的留给人工，绝不擅自截断数字

错误信息写多细，差别有多大

• 测试四档：terse（只有 validation_failed）、field（指出哪个字段）、values（附允许值/范围）、labels（再附 label）
• 无 schema 时：terse 错误导致 agent 把每次编辑拆成 6 个单字段编辑，每项 7 次调用，保存率仅 22.7%
• 只说字段名没用：agent 知道 status 错了但不知道对的是什么，只能丢弃
• 给 allowed values 到 89.3%，剩下的 639 条是 "Won't fix" 对 wont_fix 这类必须靠 label 才能匹配的；加上 label 后无 schema 也能到 97.6%，但每项多一次调用

schema 才是第一次就做对的关键

• 读过 schema 的 agent 无论错误信息多简略，都直接达到 97.6% 上限，每项编辑调用降到 1.14 次
• 剩下的 143 条是用户真想要 20 分但字段上限 13，本来就该拒绝
• schema 的代价是每页约 1,705 字节，只占 16.7 KiB 页面的约 10%
• 结论：服务端校验负责拦住坏值，随页 schema 负责让第一次尝试就正确，两者缺一不可

分页和事件日志的两个细节

• 50 条 preview 页面 16.7 KiB，全量读取同样 50 条要 124.6 KiB，preview 足够 agent 挑出要改的条目再精读
• 频道持续有新数据时 offset 分页会出问题：新增 2 条导致 120 条被读两遍；删除已读条目导致 110 条从未被看到
• before_id 游标指向最后读到的条目，别处的插入删除不会移动它，五种测试全部零重复零遗漏
• 游标期间新进来的条目靠事件日志（poll_resource_events）在下一轮补上

对设计 MCP 工具的启示

• 校验失败的错误信息要直接给出允许值和 label，让 agent 能自我纠正，osFoundry 的做法是把 API 错误原样传给模型
• 列表工具的 description 里要写明 schema 随页返回，这是 agent 唯一能发现它的地方
• 分页用游标而不是 offset，再配一个事件日志覆盖游标间隙
• 预览加 limit 上限，防止大频道撑爆上下文