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

With annotations covering read-only, open-world, non-idempotent, and destructive flags, the description still adds real value: it discloses the credit cost, that execution is server-side with 'no page changes', and that the output is a graded, severity-ranked report with fixes. The 'Read-only / no page changes' claim matches readOnlyHint=true but sits uneasily next to destructiveHint=true in the annotations, a tension the description does not address.

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?

Two sentences, both front-loaded: the first names the operation, scope, and full check list; the second covers return shape, execution model, and cost. No filler or restated boilerplate — every clause carries information.

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 single-parameter, no-output-schema tool, the description is nearly complete: it explains what is inspected, what is returned (A–F grade, severity ranking, concrete fixes), how it runs, and that it consumes credits. It could go slightly further on cost magnitude or prerequisites (e.g., that the site must be connected first), but nothing essential 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?

There is a single parameter and schema description coverage is 100% — the schema already documents site_id as a connected WordPress site UUID sourced from list_wordpress_sites. The description adds nothing about the parameter, so the baseline 3 for fully-covered schemas is appropriate.

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 ('Read-only WordPress security posture audit of a connected site') and then enumerates the exact checks performed (core-version currency, plugin/theme inventory, user-enumeration, XML-RPC, version-leak files, headers, directory listing). This clearly separates it from sibling WordPress tools like get_site_health, technical_health, or wp_capabilities without needing to open any 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?

It gives useful context for invoking it — the site must be a connected WordPress site, it runs server-side, and no wp-cli/SSH is required — plus a cost warning. However it never routes the agent between this and adjacent tools (technical_health, get_site_health, plan_search_audit), and gives no when-not conditions, so usage is implied rather than directed.

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