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

Annotations already declare mutation and non-idempotence, and the description layers on real operational context: dry_run previews a diff, writes are gated (must be enabled), and a plugin transport plus minimum Xyle Connector version is required. It also discloses that Type V4 text shown blank gets typed as a side effect and that ops=[] performs only that fix.

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-loads the core in-place edit claim, then layers grammar, workflow, preview, and gating in a tight sequence; no sentence is filler. The trailing transport/version clause is slightly incidental but legitimately useful for callers.

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 non-idempotent mutation with no output schema, the definition covers what to feed it, how to obtain the ids, how to preview safely, and the write gating. Return-shape detail is absent, but with dry_run described and no output schema declared, the remaining gap is minor.

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 100%, so the baseline is already 3, and the description adds cross-references not in the schema (wp_v4_style for Editor V4 styling, wp_patch_page for the op grammar) plus dry_run semantics. It still leaves the exact op envelope syntax to the schema rather than restating it.

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 ('Edit a template ... IN PLACE by element id') and pins the scope to surgical single-value changes rather than a rebuild. The reference to 'Same op grammar as wp_patch_page' cleanly separates it from wp_update_template (full rewrite) and from its own sibling page patcher.

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 a clear selection rule ('change one value ... WITHOUT rebuilding it') and a concrete two-step prerequisite workflow (get id from wp_list_templates, read node ids via wp_get_page). It does not explicitly name wp_update_template as the alternative for full rewrites, so the contrast is implied rather than stated.

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