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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses non-obvious behavior: id preservation semantics ('an id kept in the edit keeps the styles attached to it; an id you drop loses them') and that `patch` is only for tiny single-property tweaks. This is exactly the kind of behavioral context an agent needs to avoid losing styling.

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 primary action and default target, then the targeting override, then the payload priority, then the id-preservation caveat. Sentences are dense but all earn their place; the flow of preferred/alternative/fallback is easy to scan.

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 complex mutation tool with a deeply nested component tree and no output schema, the description covers targeting, payload selection, and id/style retention — the three things an agent must get right. Complete enough to call correctly without the builder guide.

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 description coverage is 100%, so the baseline is 3; the description still adds value by ranking the mutually exclusive payloads and explaining why `component` is best for structural changes versus `patch`. It stops short of clarifying `summary` requirements or the compact-DSL aliases, leaving that to 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+resource ('Modify an existing component') and implicitly contrasts with the sibling family by emphasizing 'existing' versus add_section/duplicate_section. An agent can tell it edits rather than creates, moves, or deletes without opening the 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?

Explicitly covers when to use each targeting mode (default = selection, `targetPath` = component named/identified via `read_page`, explicit path overrides selection) and ranks the payload options: preferred `component`, alternative `html`, fallback `patch`, with 'Supply exactly one.' Nothing is left to inference.

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