WordPress: Diagnose site

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

Annotations already declare readOnlyHint=true, and the description reinforces this with "Changes nothing on the site," so no contradiction and the safety profile is confirmed. It adds genuine value beyond the annotations by disclosing the result taxonomy (fail / warn / info / ok / skip), that each finding carries a concrete fix, and edge cases it detects such as HTTP Basic auth walls and a stripped Authorization header.

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?

The definition is front-loaded with the verb, the read-only guarantee, and the return shape before descending into the check list, and every listed check is a distinct capability rather than filler. The single dense block is slightly hard to parse, but no sentence is wasted.

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 read-only diagnostic with no output schema, the description does the important work of describing what comes back (severity-graded findings each with a fix) and what side effects do not occur. The remaining gap is input specification — nothing tells the agent what form the "site" value takes or what the optional boolean toggles — which for a two-parameter tool is noticeable but not fatal.

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 0%, so the description must carry the burden for the two parameters, and it largely does not. The required "site" parameter is never explained (URL, slug, or ID?), and "include_site_health_tests" is only obliquely hinted at by the mention of "WordPress core Site Health tests" as one of the performed checks — an agent cannot infer the default or what disabling it removes.

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?

The description opens with a specific verb and resource ("Run a read-only health diagnosis of the WordPress site") and enumerates the concrete checks performed, so the agent knows exactly what class of operation this is. It does not explicitly differentiate itself from siblings such as wordpress_get_site_health or wordpress_site_health beyond the vague "[UNIFIED]" prefix, which keeps it short of a 5.

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?

Usage is implied rather than stated: an agent can infer this is the tool to call when it wants an overall site health verdict with prioritized findings. There is no explicit when-not guidance and no named alternative, which matters here because sibling tools with overlapping names (get_site_health, site_health, woocommerce_diagnose_store) exist and the description does nothing to route between them.

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