Doco Get Document

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile with no contradiction. The description adds real behavioral context beyond annotations: the returned payload carries a version that must be attached to later writes, and annotate=anchors injects <!--@block=<id>--> anchors per top-level block to preserve block IDs across full-document rewrites. The 'warnings 降级提示' behavior is mentioned but not concretely defined, keeping this from a 5.

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?

The description is one dense, front-loaded passage that opens with the main purpose before covering formats, version contract, and anchor workflow. Every clause carries information — format trade-offs, the version-carry requirement, and write-back behavior — so nothing is redundant. It is long but justifiably so, and the logical flow is clear; splitting it into shorter sentences would improve readability slightly.

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?

With an output schema present, a 4-parameter signature, and annotations covering the read-only/idempotent safety profile, the description completes the key functional gaps: it names the version field, explains format fidelity differences, and describes the anchor-preservation workflow for round-trip edits. The weakest point is locale — both schema and description mention docset_ID and language versions without explaining fallback behavior when a locale is absent — so it is strong but not fully complete.

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 description coverage is 100%, so the baseline is 3. The description adds meaning for two of four parameters: it explains why to choose each format (markdown for semantic reading vs tiptap-json for lossless editing) and what the annotate anchors accomplish (preserving unchanged block IDs on write-back). document_id and locale receive no additional meaning beyond the schema, so the added value is partial — above baseline but not complete.

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?

The description states a specific verb+resource: '读取整篇文档正文' (read the entire document body). The scope qualifier '整篇' (entire) and the format list distinguish it from block-level siblings like doco_get_blocks, doco_outline, and doco_get_tree. However, it never explicitly references overlapping siblings such as doco_read, so the differentiation is implicit rather than stated.

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?

The description gives explicit format-selection guidance: markdown for semantic reading (with warnings downgrade hints), tiptap-json for lossless precise editing, and html as a third option. It also explains the annotate=anchors write-back workflow — injecting block IDs and preserving unchanged block IDs on PUT — and the version field requirement for subsequent writes. It lacks explicit tool-selection exclusions against siblings like doco_read or doco_get_blocks, leaving that to inference.

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