update_document

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

无任何注解，描述承担了完整的行为披露责任。它披露了非常关键的非显然副作用：正文变化时自动重新普查全部划线，失联的进孤儿区，且绝不静默删行。这种透明度远超普通更新操作，但未提及权限要求、返回结果或并发处理，因此不是满分。

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

两句话，第一句直接说明用途，第二句解释重要的行为副作用，没有冗余内容。信息密度高且高效。

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

工具是修改操作，无输出 schema，描述提供了核心用法和关键副作用，引用了外部 brief 作为补充。但缺少返回/成功标准、失败处理或并发控制的上下文。对于这个复杂度而言已经足够，但仍有提升空间。

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

schema 描述覆盖率仅 25%（仅 idempotency_key 有描述），描述中隐含 title 和 content_md 是可更新字段，但未明确说明 document_id 的含义或 idempotency_key 的使用时机。由于描述只部分补偿了 schema 的低覆盖率，参数语义仅达到及格水平。

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

描述明确说明该工具用于更新已有文档的标题和/或正文，并指明是“报告修订版”，动词和资源都很具体。与同级别的 add_document（新增）、update_lesson（更新课程）等兄弟工具区分明确。

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

描述隐含使用场景：修改已有文档，而非新建文档，与 add_document 形成对比。但没有显式说明“何时不使用”或推荐替代工具，缺少明确的排除性指引。上下文清晰，但未达到最高标准。

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.