一个文档工具该做多大？按可验证的动作拆接口
文档工具的粒度应围绕一个能独立解释、验证和恢复的动作确定。工具过大，模型难以预知副作用；工具过碎，完成一件简单工作又要串起几十次调用。判断标准是一次失败之后，能否说清哪些对象发生了变化。
不要从接口数量决定工具数量
一个后台接口可能同时支持创建、改名、移动和删除。直接封装成 manage_document，再放一个 action 字段，看起来节省了定义工作，却把性质差异很大的动作放进同一个入口。调用者需要先理解所有分支，错误处理也容易只剩下笼统的成功或失败。
反过来，把一段正文拆成“输入第一个字、输入第二个字”同样没有价值。业务原子动作可能是“在指定章节追加一条已确认事项”，底层可以包含多次请求，但工具要对整体结果负责，并披露不能原子完成的部分。
用三问寻找合理边界
- 这个动作是否有单一业务目的，例如创建草稿或设置标题？
- 动作完成后能否用一个明确条件验证，例如草稿 ID 存在且标题一致？
- 失败时是否能独立恢复，而不需要猜测其他动作已经做了什么？
把“生成季度报告并替换旧版再通知所有人”拆开，就能看出差异：内容生成、原文件替换、消息发送分别有不同的结果和恢复方式。拆分不意味着每一步都交给用户决定，而是让执行系统拥有清楚的边界和台账。
一个适合文档团队的拆分例子
| 工具职责 | 返回证据 | 失败后的动作 |
|---|---|---|
| 读取指定章节 | 章节对象和读取版本 | 重新获取目标 |
| 生成修改提案 | 差异与预期原值 | 调整方案 |
| 应用修改 | 变更标识与新版本 | 先查是否已写入 |
| 导出附件 | 导出任务和文件清单 | 恢复原导出任务 |
MCP 提供工具名称、描述、输入与可选输出 Schema，以及行为注解。注解有助于表达工具特性，但不能代替服务端的真实实现。声明只读不会自动使一个会写数据的接口变成只读，声明幂等也不会替开发者消除重复请求。
用实际任务评估拆分是否过度
选一个常见任务，例如从项目资料整理周报草稿，记录完整调用路径。若模型反复在近似工具中选择错误，应改进命名和职责；若大量调用只传递上一条响应的固定字段，可以考虑在确定性服务中组合，减少模型参与。组合后的工具仍需给出分项结果，不能用一次整体成功掩盖内部失败。
工具设计完成后再接入真实企业文档环境进行验证。本文的拆分方式是接口设计建议，不代表石墨已提供这些同名工具。已有 API、插件或 CLI 能力需要逐项映射，确认支持的动作、失败方式和结果读取入口，才能形成可持续维护的文档 Agent。
在企业文档中验证
如果要把本文方法用于企业文档，可预约演示，结合实际资料核对协作、权限与集成方式。
需要在自己的环境中验证时，可先了解私有化部署方案，再确定试用范围与验收要求。