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

Annotations already establish readOnly, idempotent, non-destructive, and closed-world, so the description's job is to add operational context, which it does: cursor continued 'with cursor alone', state:true reporting pending work and human presence, after_revision+wait_ms as a bounded wait for the next human change, and drawings reading at full detail even while open in Draw. It does not cover what happens when conflicting selectors are combined, which is a real risk across 23 optional parameters.

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?

Every sentence carries information and the when-to-use guidance is front-loaded, but the text reads as semicolon-joined fragments that are hard to scan, mixing selection modes, pagination, presence checks, and guide routing in one block. 'Check human context and omissions before editing' is also vague relative to the precision elsewhere.

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 no output schema, the description correctly assumes the burden of explaining what comes back: text, outline, image, next_cursor, and state. It is largely sufficient for the common read paths, though the decade of auxiliary parameters for history, versions, and comparisons remain unexplained, so an agent cannot confidently use those capabilities.

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 coverage is only 39% and the description adds genuine meaning for roughly ten parameters, notably the as enum values (outline as a heading/fence map, image as PNG of a block or lines), plus state, after_revision, wait_ms, and cursor/next_cursor. However, history, versions, version, comparison, return_id, operation_id, preferences, since, note, and agent are undocumented in both schema and description, leaving a substantial share of a 23-parameter surface unexplained.

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?

States a specific verb and its outputs: exact text, a heading/fence map via as:"outline", or a PNG via as:"image", scoped to a page, block, heading, or lines. It also separates itself from near-neighbors by explaining that query finds lines here while search lists Notes, so an agent can choose without opening the 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?

The opening sentence gives an explicit trigger ('before you change a Rapier document', and when the person asks what it says or changed), and it routes the agent away from this tool for two confusable cases: query vs search for Notes, and guide resource URIs not being document IDs. It stops short of stating exclusions for the remaining selectors, but the primary when-to-use is unambiguous.

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