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

Annotations only say non-readonly and non-destructive; the description adds substantial context beyond them: edits apply in order, a non-unique anchor causes nothing to be written and an explanatory failure, base_hash provides optimistic concurrency from read_site_file, and validation rules (keep sc-track.js, data-sc-carry tags, sc-badge block; no noindex / 'Disallow: /' on a custom-domain site). No contradiction with destructiveHint=false, since only targeted substrings are swapped.

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 prerequisite, then purpose, then edit shapes, then the alternative, then constraints — good ordering with no filler. The trailing parenthetical constraint list is dense and slightly harder to scan, but each item is actionable.

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 mutation tool with no output schema and minimal annotations, the description covers failure modes, ordering, concurrency guarding, and content-validation rules. It stops short of describing what a successful response contains and how partial failures across multiple edits are reported.

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 0%, so the description carries the load and does it well for the two non-obvious params: the edits array's two accepted shapes ({find, replace} and {after, insert}), ordering, and anchor uniqueness, plus base_hash's purpose. slug and path are left entirely unexplained, which is the only remaining gap.

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 resource (change an existing draft file in place) and explicitly frames it as 'the way to modify a page', which distinguishes it from whole-file writes. It also names the sibling it replaces (write_site_files), so an agent can choose without opening schemas.

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?

Gives an explicit prerequisite ('Call get_site_context first') and an explicit preference with reasoning ('Prefer this to rewriting the page with write_site_files: whole-file rewrites from memory drop or duplicate things'). It also specifies when a patch is refused (anchor must appear exactly once) and when to supply base_hash.

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