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

Goes well beyond the destructiveHint/readOnlyHint annotations: it discloses case-sensitive literal matching with no regex, all-occurrences replacement, the expected_count abort guard, read-after-write verification, and critically the Royally approval gate where nothing changes on the site until a person approves. That approval workflow is behavior an agent cannot get from annotations alone.

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 action in the first clause, then parenthetically layers semantics and the approval caveat. Dense but each clause carries information; the '(site: ...)' inline note is slightly noisy but minor.

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?

Covers mechanism, safety guards, and the human-approval gate for a 6-parameter mutation tool with no output schema. What's missing is any indication of what the tool returns (occurrence counts, diff, approval status), which the agent would need since there is no output schema to fall back on.

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 already 83%, with find, replace, dry_run, expected_count and site_id all documented. The description restates dry_run preview and expected_count guard rather than adding syntax or edge-case detail (e.g. what happens on zero matches), so baseline 3 applies.

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 (find/replace) and resource (a page's content), plus the key efficiency claim 'without resending the full body'. It explicitly positions itself as the page-typed variant of wp_replace_in_post, so an agent can distinguish it from that sibling and from wp_replace_text_in_blocks.

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?

The 'page-typed variant of wp_replace_in_post — same semantics' line routes the agent toward the post tool for posts and this one for pages, and mentions dry_run preview as the safe pre-check. It stops short of explicitly naming the when-not cases (e.g. block-level edits vs. content edits), leaving some inference.

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