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

Annotations already declare destructiveHint=true and idempotentHint=false, and the description adds the context behind that: edits are validated by a collaborative editor, large removals require the allowRemoval flag, and retries must be idempotent via a preserved requestId. This is exactly the operational detail the booleans cannot convey.

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?

Four short sentences, purpose first, then editing strategy, then the two cautionary behaviors. No filler, no restatement of the title, and each clause carries an actionable instruction.

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 and rich per-field, per-enum descriptions in the schema, the description only needed to cover workflow semantics — preconditions, edit strategy, removal gating, and conflict recovery — all of which it does. Nothing material for correct invocation is missing.

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 100%, so the baseline is 3; the description goes further by explaining why allowRemoval exists (the editor checks large removals) and tying requestId to the retry-after-conflict workflow. It restates some schema content, but the gating rationale and retry contract add real meaning.

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 opens with a precise verb+resource+mode: 'Apply targeted Markdown edits to a doc after reading its current content,' and the emphasis on targeted edits implicitly separates it from the coarser update_doc sibling. It never names update_doc outright, so an agent must still infer which of the two doc-mutation siblings to pick in edge cases.

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?

It gives the prerequisite (read the doc first), the preferred mode (exact text or block edits), the discouraged mode (full rewrites and large removals, which the collaborative editor inspects), and an explicit gating condition for allowRemoval. Conflict handling is also spelled out: re-read, do not blindly retry, keep requestId on retries.

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