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

Annotations already flag destructive=true and non-idempotent, but the description adds substantially more: all removals collapse into ONE new draft version, operations are validated against the actual tree, the batch is all-or-nothing (a single missing node id rejects everything), root nodes are refused, and there is a 50-removal cap. These are failure and atomicity semantics an agent cannot infer from the annotations.

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 action and scope, then alternatives, then failure semantics — a sensible order with no filler. The closing 'Up to 50 removals per call' duplicates the schema's maxItems, and the traversal detail overlaps node_ids, so it is slightly longer than strictly needed.

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 destructive batch mutation with no output schema, the description supplies everything an agent needs: what gets created (a new draft version), atomic failure behavior, root protection, the count limit, and the safer-alternative framing. Nothing material 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?

node_ids already carries a detailed schema description covering traversal locations, splice behavior, root-node refusal, uniqueness, and the 50 cap — the prose largely restates this. site_id is undocumented in both places (schema coverage 50%), and the description adds nothing about it. Adequate, but little value 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?

States a specific verb and resource (delete many nodes from a site) plus the scope constraint (in ONE call, batched into one new draft version). The concrete examples — dropping a testimonials section, removing a nav link, cutting a card from a grid — make the operation unmistakable and distinguish it from siblings like delete_page, move_nodes, and patch_nodes.

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?

Explicitly names the use case ('structural subtraction ... whenever the brief calls for the template's layout minus something') and the alternative (patch_fixture's JSON-Patch 'remove' ops), with the reasons selecting this tool: no hand-constructed paths, tree-validated, no root removal. It also routes root-node deletion to delete_page, so both the when and the when-not are covered.

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