给文档 Agent 定义工具参数：先把输入契约写清楚
给文档 Agent 设计工具时，先把“允许传什么、缺什么必须拒绝、结果怎么验证”写成输入契约。只让模型提交一段自然语言指令，后端再猜它想改哪里，会把不确定性留到真正写入文档的时刻。
从一次具体修改开始定义字段
假设任务是把项目周报中的截止日期从周五改到下周一。工具至少需要文档标识、目标段落或业务对象、预期原值和新值。日期不能只有“下周一”四个字，还应在调用前结合明确的基准日期解析为具体年月日；如果用户没有给出足够上下文，应返回需要补充的信息，而不是由服务端采用服务器当天日期。
MCP 的工具规范把 inputSchema 定义为描述预期参数的 JSON Schema。它适合约束必填项、类型和枚举，但字段含义仍需说明。一个叫 target 的字符串可以通过类型检查，却不能说明它是文档 ID、链接还是标题。把名称改成 document_id，并解释稳定性和获取方式，能减少调用者试错。
必填、可选和默认值分别承担什么责任
| 字段 | 建议约束 | 原因 |
|---|---|---|
| 文档标识 | 必填，不以名称模糊匹配 | 同名文件不能自动当作同一对象 |
| 修改范围 | 使用明确对象或范围 | 避免把局部修改变成全篇替换 |
| 缺失值处理 | 显式选择保留、清空或拒绝 | 空字符串和未提供不能混用 |
| 批量上限 | 服务端验证范围 | 避免一次调用意外覆盖大量对象 |
格式校验通过之后还有一层检查
Schema 可以确认日期是字符串，不能独自保证结束日期晚于开始日期，也不能知道编号是否属于当前项目。进入写操作前应验证这些业务关系。结构校验和语义校验需要配合：合法的文本并不等于正确的目标，合法的数字也不等于适用的单位。
可以把失败反馈写成“结束日期早于开始日期，请修改 end_date”，而不是返回整段服务端堆栈。错误应指向具体字段，并说明当前文档是否尚未变化。模型据此修正参数，用户也能理解为什么任务没有继续。
用反例检验契约是否足够清楚
准备一组小样本：缺少文档 ID、同名文件、空日期、跨月份日期、重复对象、超过批量上限、把文本编号传为数字。每个输入都先写出预期结果，再检查工具是否遵守。验收重点不是“模型一次调用成功”，而是错误输入能否在写入前被稳定拒绝，正确输入是否产生可读回的单一变化。
对石墨等企业文档系统的接入，可以先整理现有接口实际支持的标识、范围与数据类型，再据此封装工具。不要把协议里能描述的字段当成产品已经具备的能力。清晰的输入契约应忠实表达真实接口，缺少的能力需要单独实现和验证。
在企业文档中验证
如果要把本文方法用于企业文档，可预约演示，结合实际资料核对协作、权限与集成方式。
需要在自己的环境中验证时，可先了解私有化部署方案，再确定试用范围与验收要求。