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

Goes well beyond the annotations: write-gating, round-trip validation, custom_css being stripped, Pro widgets auto-downgraded to free composites, GSAP lazy-loading with reduced-motion honored, the `elementor-invisible` pitfall of native entrance animations, and force_builder's deletion of Elementor data. Minor tension: "Replace ... content" is a full-overwrite operation while destructiveHint=false implies additive-only, but the mitigations (dry_run, preview-before-publish, validated writes) keep it defensible rather than a hard contradiction.

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 correctly (purpose, then PREFERRED param), and the ALL-CAPS labels (SECTION STYLING, STYLING, ANIMATION, BRAND TOKENS) make it scannable, but the description is very long and re-states material already present in the parameter descriptions (html, sections, atomic, blocks, force_builder), so the density costs more than it should.

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 10-parameter, no-output-schema write tool, an agent has everything needed: which parameter to choose, the accepted specs, styling/animation vocabulary, brand-kit workflow, the 409 refusal path, and the preview/verification loop. No output schema exists, so omitting return-value detail is appropriate.

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 baseline is 3; the description earns the bump by adding concrete shape and vocabulary the schema omits — container/section JSON layout, bg/gradient/overlay/shape divider keys, the style object and responsive breakpoints, anim presets, and brand-token syntax (@primary, typographyToken). It meaningfully disambiguates the four content paths (sections/blocks/atomic/html).

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+scope: "Replace a PAGE/POST's content (refine/design in place)", and explicitly fences the scope with "EDITS A PAGE/POST ONLY — never a Theme Builder header/footer template or the site kit". That exclusion alone separates it from template/kit siblings without opening a 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?

Gives explicit when-to-use and when-not: PREFER `sections`, `html` is a last-resort escape hatch and never the whole page, call wp_get_brand_kit first, use elementor_search/elementor_get for widget fields, use native `animate` only on sites lacking the latest connector, and review via render_screenshot before publishing. Alternatives (sections vs blocks vs atomic vs html) are all routed.

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