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

Adds behavior the annotations don't carry: optimistic concurrency (a stale base_version is refused), a locking constraint on live pages, and a cost signal ('Free'). The annotations only declare the safety profile (readOnly=false, destructive=false, idempotent=false), so this is genuine added value. It stops short of explaining what happens if a find string is ambiguous or whether multi-edit application is atomic, leaving a small gap.

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?

Three tight sentences, front-loaded with the action and its modes, then preconditions, then the sibling routing. Every clause carries actionable information; no filler.

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?

For an 11-parameter mutation tool with an output schema and full annotation coverage, the description supplies what structured fields cannot: concurrency semantics, the live-page lock, and routing to revise_page. Return values are covered by the output schema, so nothing essential 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 64%, so the schema documents several parameters itself; the description reinforces which fields are editable (markdown, edits, title, goal, reader, angle) and repeats the base_version dependency. It adds the semantic framing of 'replace its Markdown' vs 'exact find-and-replace edits' as alternative modes, which helps mode selection, but does not document brand or idempotency_key beyond the 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?

Names a specific verb (change/edit) plus resource (page) and enumerates the concrete capabilities: replace Markdown, find-and-replace edits, and title/goal/reader/angle edits. It also distinguishes itself from the sibling revise_page by stating that live pages are locked. An agent can identify this tool without opening any 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?

Explicit preconditions ('Pass base_version from get_page') and an explicit exclusion with a named alternative ('A live page is locked: revise_page first'). The when-to-use versus revise_page routing is unambiguous, which is exactly the distinction siblings create.

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