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

Annotations only declare the tool is a non-read-only, destructive write. The description adds substantial context beyond that: atomicity ('Applied in order, all or nothing'), the refusal behavior ('A refused edit changes nothing and says why'), that untouched content including the user's own edits is preserved, and that the change is immediately visible and undoable. That is a rich behavioral profile for a mutation tool.

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?

Front-loaded with the core mechanism (find/replace exactly-once semantics) before the routing advice, and every clause carries information. It is a dense, long paragraph with several stacked ideas, which slightly hurts scannability, but nothing is 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 a six-parameter mutation tool with no output schema, the description covers what an agent needs: the edit mechanism, atomic failure semantics, page/shared selection, the undo guarantee, and even the return ('The reply shows the page as it looks now'). Nothing material is left unstated.

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 already 83%, so the schema carries most parameter documentation. The description still adds meaning the schema does not: the relationship between page and shared ('One page per call, or shared: true for the code every page shares') and the guarantee that untouched content survives. It does not add anything for deck_id or the find/replace length limits, but the schema covers those.

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 and resource ('Change part of a design that already exists') and pins down the mechanism precisely: surgical find/replace against text from read_page, one page per call. This clearly separates it from siblings like read_page, create_deck, and write_outline, which either read or author whole pages.

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 an explicit when ('any change the person asks for in an existing design — a headline, a colour, a picture, moving or removing something') and an explicit alternative to avoid ('instead of sending the whole page again'). It also scopes the shared:true branch ('Only when the person asks to change the whole design') and states the refusal condition, leaving little to inference.

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