Doco Outline

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

注解已声明 readOnlyHint=true、idempotentHint=true、destructiveHint=false，覆盖了只读、幂等和非破坏性等安全特性。描述在此基础上补充了该工具只返回标题结构（而非完整文档内容），并强调 block_id 是稳定的，这对调用者理解输出性质和规划后续读取非常有价值。没有与注解矛盾之处。

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?

描述用一句话简洁地涵盖了功能（读取大纲）、输出特征（block_id、heading_path、顶层块区间）和适用场景（先规划再局部读取），无冗余信息，关键信息前置，结构高效。

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?

该工具只有 1 个必需参数，且 schema 覆盖完整、有输出 schema 和全面的注解。描述已经提供了足够的信息让代理正确调用：它做什么、返回什么性质的数据、什么时候用。具体返回字段由输出 schema 承担，无需在描述中重复。

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 对 document_id 的说明覆盖率为 100%，描述中未额外解释参数含义或格式。根据规则，当 schema 描述覆盖率高时，参数语义得分的基线为 3，描述没有超越 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?

描述使用明确的动词'读取'和资源'文档结构大纲'，并具体说明输出内容为每个标题的 block_id、heading_path 和顶层块区间。这与 sibling 工具如 doco_read（读取正文内容）和 doco_get_tree（获取树结构）能清晰区分，代理无需打开 schema 即能理解该工具的作用。

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?

描述中明确提到'适合先规划再局部读取'，给出了具体使用场景：先获取大纲规划，再按需读取局部内容。虽然没有指名替代工具或给出排除条件，但使用上下文已足够清晰，未达到最高分是因为缺少显式的 when-not-to-use 指引。

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