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

Goes well beyond the annotations by naming the permitted roles, the fact that the actor identity is captured, and that the action is recorded in the audit log — meaningful context for a mutation tool. It does not describe what a second acknowledgment does, though idempotentHint covers that.

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?

A single front-loaded sentence carrying the action, the actor, the optional note, and the audit consequence with no filler.

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 two-parameter mutation with no output schema, the description covers action, permissions, side effect (audit log) and the optional note. Only the relationship to dismiss/resolve remains unaddressed.

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 both parameters are already documented. The description adds only the illustrative 'planned fix' use of the note, which the schema also mentions almost verbatim, so baseline 3 is right.

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 ('Mark an open advisory as acknowledged') and pins the acting identity. It does not name the closest siblings (dismiss_advisory, resolve_advisory), so an agent must infer that acknowledgment is a distinct, milder state transition.

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 word 'open' implies a precondition (only unacknowledged/advisory-state items), which is useful. But there is no explicit guidance on when to acknowledge versus dismiss or resolve, despite those tools being listed as siblings.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial context the annotations cannot: GuardPress-conditional outputs, the explicit statement that sites without GuardPress report 'account changes were not checked', the not_reported state for older Royal MCP, and the fact that the background hourly sweep (royally_security_sweep / royally_account_check, never both) is what actually raises alerts with a 7-day acknowledgement lifecycle. That tells the agent this call is passive and that alerts live elsewhere — exactly the kind of behavior it needs before calling.

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 bulk is one enormous sentence with deeply nested parentheses listing output fields, followed by a second long block on the hourly alert lifecycle. The purpose is buried behind a return-field inventory, and the important framing ('read only, raises no alerts') arrives late; much of the alert-sweep detail is arguably tangential to invoking this tool.

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?

With no output schema, the description carries the return-value burden and does so exhaustively: every top-level field is defined, conditional behavior per plugin is spelled out, and the empty/absent states (not_reported, not checked) are named. An agent has enough to call it with no parameters and correctly interpret the result.

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% and the single site_ids parameter is already documented as "Omit for every eligible site." The description restates the same default ("Optional site_ids (default every connected site)") without adding format, id-shape, or max-size guidance, so it neither compensates nor detracts. 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?

The opening enumerates exactly what the tool returns — administrator accounts per site with user_id, display name, roles, registered_at, extra_caps, plus derived fields (new, users_with_extra_caps, extra_caps_checked, flags) and GuardPress account-change history — so an agent can tell it is an administrator-account audit rather than a generic user listing. It never states a verb up front (no 'Lists'/'Returns') and never names the siblings it differs from (e.g. wp_get_users, security_triage), so differentiation is inferred rather than stated.

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?

"Use it to spot an administrator nobody recognises, a recent role change or a hidden administrator" gives concrete motivating scenarios, and "Read only; it raises no alerts itself" clarifies it is investigative rather than remediating. However, no alternative tool is named and no when-not-to-use condition is given, so the agent must infer routing against security_triage or wp_get_users.

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

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

Adds substantial context beyond annotations: plugin precedence order, per-plugin undo semantics (Royally for Wordfence/GuardPress, Kadence itself), the human approval gate, permanence of blocks once applied, and refusal conditions. This resolves the apparent tension between the tool's name and destructiveHint=false by making the preview-only nature explicit.

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?

Purpose and ordering are front-loaded, and nearly every clause carries real information. It is somewhat dense and run-on, with nested parentheticals that make the plugin-order/undo mapping harder to parse than it needs to be.

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?

With no output schema, the description covers the return shape (per-site plugin decision, undoability, sites lacking plugins, approve_url) and the approval deadline semantics. An agent has everything needed to call it and interpret the result.

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 the schema already documents all three parameters. The description restates ip format, optional reason, and site_ids default ('every connected site' vs the schema's 'every eligible site' – minor wording drift) but adds no syntax, limits, or format detail beyond structured data. 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 and scope: it *previews* blocking one IP across chosen sites, per security plugin (Wordfence, GuardPress, Kadence Security), and explicitly notes nothing changes until a human approves. An agent can distinguish this preview behavior from an actual block operation without reading the 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 clear context: it returns an approve_url and a person reviews and applies the block in Royally before approve_before. It also names fleet__undo as the reversal path and states edge cases (allowlisted addresses refused, GuardPress refuses the site's own address). No explicit 'use X instead if you want an immediate block' routing, so not a 5.

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

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

Despite the sparse annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description discloses an unusual amount: that sites are only read during preview, that applying re-verifies the preview state, per-change-type undo semantics (including which edits made since are lost or left), backup-before-update behavior, 72-hour undo window, and every refusal/left-out condition with reasons. The only mild tension is 'Nothing is written by this tool' versus readOnlyHint=false, but the text clarifies the pending change is applied later from Royally, so this is not a genuine 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?

The purpose is front-loaded, and most content is genuinely load-bearing given 29 modes, but it is delivered as one enormous run-on paragraph mixing argument shapes, preconditions and undo semantics per tool with no headings, bullets or line breaks. An agent must parse a wall of semicolon-separated clauses to locate the args for a single chosen tool, so structure substantially undercuts the value of the content.

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?

With no output schema, the description still specifies the return shape ('per site, what would change (counts and up to 20 before/after examples)', sites with nothing to change, approve_url, approve_before) and the auto-applied variant (state, applied_by_rule, preview_url, one undo per site). For a 29-mode, high-risk bulk tool this is complete enough to call correctly.

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?

The schema only enumerates the 29 tool strings and describes args as 'the shape the chosen tool takes'; the description supplies the actual argument shapes for each tool (e.g. {find, replace, case_insensitive?, scope:{post_types, post_status?, post_ids?, limit?}}, {users:[{username,email,role,...}]}) plus limits like 50 sites, 15 updates, 5 plugins/users. It also explains site_filter semantics ('omit it for every site', tag_match any/all), far exceeding the 67% schema coverage.

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 opening sentence gives a specific verb, resource and scope: 'Preview one content or design change across many client sites at once (up to 50)'. Combined with 'Nothing is written by this tool' and the approve_url hand-off, an agent can immediately tell this apart from the apply-style sibling fleet__run_across_sites without opening either 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 states how to select sites (site_filter with selection_id from fleet__list_site_groups, tags with tag_match, status, plugin_slug; omit for every site), what the agent must do with the result (show the summary, give approve_url, 'You cannot apply it yourself'), and the auto-apply exception when every site is in an auto-apply group. It never explicitly names an alternative tool to use instead, so it stops short of a 5.

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

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

Beyond readOnly/idempotent annotations, it discloses the 100-links-per-site cap with a total count, the checked:false plus reason response for unsupported sites, the critical caveat that this does not mean no links are broken, and the freshness caveat that SEObolt rechecks on its own schedule. These are exactly the non-obvious behaviors an agent needs before trusting the result.

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 resource and definition are front-loaded and every clause carries information (scope, fields, caps, caveats), with zero filler. It is dense and slightly run-on, pushing close to a wall of text for a two-parameter read tool, so it is efficient but not maximally scannable.

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?

With no output schema, the description fills the gap by listing returned fields (URL, status, post_id and title, anchor text, redirect) and the per-site total, plus the checked:false edge case. Nothing needed to interpret the response or decide whether the result is trustworthy 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?

Schema description coverage is 100%, so both parameters are already documented; the description restates the search filter and the site_ids default without adding syntax, format, or edge-case detail. Baseline 3 applies when the schema carries parameter meaning.

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?

Names a specific verb and resource ('Broken links in each chosen site's content') and pins down the definition precisely: 4xx/5xx, unreachable, or status_code null, sourced from SEObolt Pro's broken link checker. That definition distinguishes it from adjacent siblings like emcp-tools-find-broken-links and rank_math_get_404_logs without opening 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?

States the defaults (site_ids omitted = every connected site) and the search narrowing rule, plus the important precondition that sites lacking SEObolt Pro or with the checker off return checked:false. It gives clear context for invoking it but never explicitly routes the agent away from a similar sibling tool, so it falls short of a full when/when-not statement.

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

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

With readOnlyHint/idempotentHint already declared, the description still adds substantial unseen context: updates_reported: false means 'not known rather than none waiting', must-use plugins and drop-ins are never update-checked so their staleness is unknown, and ignored updates remain listed with their ignore scope and reason. These are interpretation rules an agent could not infer from the annotations or schema and that change how results get reported.

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 with the action and return content, and every clause (must-use/drop-ins, ignored-update semantics) carries decision-relevant information. Structure suffers slightly from being one long semicolon-chained paragraph, which makes the caveats harder to scan than a short list would.

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?

There is no output schema, and the description compensates fully by explaining the returned fields, the updates_reported flag, the not_update_checked category, and the ignored-annotation shape. An agent can both call this and correctly interpret ambiguous results without further documentation.

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?

One optional parameter with 100% schema description coverage, so the schema already carries the meaning and the baseline is 3. The description's 'default every connected site' adds only marginal value over the schema's 'Omit for every eligible site' and even introduces a slight wording drift ('connected' vs 'eligible').

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 ('List the plugin updates waiting on each chosen site') plus the exact per-plugin fields returned, so the agent knows this is fleet-wide pending-update inspection, not general plugin listing. It never names a sibling (e.g. fleet__list_plugins or single-site wp_list_plugin_updates) to draw the boundary explicitly, so it stops short of the top band.

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 clear scope defaults ('Optional site_ids (default every connected site)') and an explicit behavioral exclusion ('don't suggest or plan ignored updates unless the person asks'). It does not route between alternatives (e.g. when to use this versus a per-site plugin update tool), so the guidance is contextual rather than comparative.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds the critical caveat that an empty list on a site with vulnerability_checking off is not a clean bill of health, and notes whether results were validated against a current feed. That is real behavioral context an agent would otherwise get wrong; it stops short of covering cost/latency for fleet-wide calls.

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 with the core action and source, and every clause carries information. The final sentence runs long with several nested qualifiers, which costs a little readability but nothing is filler.

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?

With no output schema, the description usefully sketches the per-site return shape (severity, fix, patched version, active exploitation, feed freshness). It omits anything about how many sites can be checked at once or expected runtime, but it covers what an agent needs to call and interpret the tool.

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% and the single parameter is fully documented there. The description only restates the default scope ('every connected site' vs the schema's 'every eligible site'), which adds marginal meaning rather than syntax or formatting detail.

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 (check known vulnerabilities in plugins, themes, and WordPress core) and names the source of truth (GuardPress, falling back to Wordfence or Kadence Security). The phrase 'read now from its security plugin' implicitly separates it from the scan-triggering siblings such as fleet__scan_security.

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?

Covers the default scope ('Optional site_ids, default every connected site'), but never says when to choose this over fleet__scan_security, fleet__security_triage, fleet__list_advisories, or recipe__run_security_sweep. Usage is implied by the verb, not contrasted against alternatives.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is carried structurally. The description confirms the required reason and rules out an approve action via this connection, but never says what denial does to the execution (cancelled vs. re-queued) or whether the denial can be reversed.

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 short sentences, zero redundancy, with the action and the required input stated before the negative guidance. Every clause carries decision-relevant 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 two-parameter mutation with full schema coverage, rich annotations and no output schema, the definition is nearly sufficient. The only real gap is the post-condition of a denial, which an agent may want before committing to an irreversible-looking state change.

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%: the schema already documents the non-empty reason, the audit-row recording, the uuid format, and the pending_approval precondition. The description only echoes that a reason is required, adding no new parameter meaning, so the 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?

Specific verb (turn down/deny) plus a precise resource (a change awaiting approval) and a scope qualifier (requires a reason). It also distinguishes itself from the approval path, so an agent knows this is the rejection-side tool, not a decision hub.

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?

Explicitly states the use case (a change in the pending-approval queue) and the exclusion: approving happens by a person in Royally under Approvals, never through this connection. That eliminates the main mis-selection risk for a decision tool.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond them: the required signer role, the mandatory-reason rule, and that the action is written to the audit log — meaningful consequences for a mutation.

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?

One sentence, front-loaded with the effect (hide, not resolve) and then the actor and audit constraint. No filler or redundancy.

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 two-parameter mutation with strong annotations and a fully documented schema, the essential context is present: who may act, what the action does and doesn't do, and that it is audited. It stops short of stating reversibility (a fleet__undo exists) or whether a dismissed advisory still counts toward risk scoring.

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%; both advisory_id (UUID) and reason (non-empty rationale) are fully documented in the schema, including the anti-abuse rationale. The description only restates that a reason is required, adding no syntax or format detail. 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 and resource ("Hide an advisory") plus the key semantic distinction: the advisory is hidden, not resolved. That implicitly separates it from fleet__resolve_advisory and fleet__acknowledge_advisory without naming either sibling.

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 phrase "without resolving it" hints at the choice against resolve_advisory, and the permission note (owner, admin or member) sets a precondition. But it never explicitly says when to dismiss versus resolve or acknowledge, leaving the sibling choice to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description earns credit for adding response-content behavior the annotations cannot express: that resolved/dismissed timestamps are included, i.e., the record is not filtered to open advisories.

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?

A single sentence with no filler, and the most decision-relevant content (single advisory, full lifecycle detail) is front-loaded. The parenthetical clarifies the only ambiguous phrase rather than padding it.

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 one-parameter, annotated, read-only tool with no output schema, the description tells the agent what it gets back (full lifecycle detail including resolution/dismissal timestamps), which is the main open question. Minor gap: no mention of not-found error behavior.

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?

Only one parameter exists and schema description coverage is 100% ("The advisory id to fetch."), so the schema already does the work. The description adds nothing about the id format (uuid) or what happens with an unknown/foreign id, 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 and resource ("Fetch a single advisory") plus a scope qualifier ("full lifecycle detail"), which implicitly contrasts with the list-style sibling fleet__list_advisories. It stops short of naming the sibling explicitly, so an agent must infer the list-vs-single split from the word "single".

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 only implied: an agent can infer this is the detail lookup to run once an id is known (e.g., after fleet__list_advisories or fleet__security_triage). There is no explicit when-to-use/when-not guidance and no alternative named, even though acknowledge/dismiss/resolve siblings are the obvious follow-on actions once this is read.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description still adds real behavior: the kit is read from one of the client's own sites, 'kit is null when the client has no kit yet, or the site has no client', and the data source is limited to Royally's records — the null case is the kind of detail an agent cannot infer from annotations.

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 with what the kit is, then when to read it, then how to address it, then the null case — a sensible order with no filler sentences. The colour/font/variable/class enumeration is repeated in the usage sentence, a minor redundancy that costs it a point.

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?

No output schema exists, and the description compensates by describing the return shape (Site Settings colours and fonts, variables, classes) and the null case for 'kit'. For a two-optional-parameter read-only lookup with full annotation coverage, nothing an agent needs to call it correctly 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?

Schema coverage is 100%, so baseline is 3; the description earns an extra point by clarifying the selection logic beyond the schema — site_id resolves to 'the kit of that site's client' and either site_id or client_id may be passed (they are alternatives, not independent filters). That relationship is not obvious from two flat optional string properties.

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 (read/get) and resource (a client's brand kit) and enumerates its contents: Elementor Site Settings colours and fonts, Elementor 4 variables and Elementor 4 classes. It also scopes the retrieval ('read from one of their sites' and 'Reads Royally's records only'), which separates it from generic Elementor settings readers, though it never names the closest conceptual sibling (royal-mcp__elementor_get_kit_globals) explicitly.

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?

"Read it before you build or restyle an Elementor page on a client's site" gives a clear triggering condition, and "use these colours, fonts, variables and classes rather than inventing new ones" states the intended downstream behavior. No when-not condition or named alternative is given, so it stops short of full routing guidance.

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

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

Annotations already cover readOnly/idempotent/non-destructive, and the description goes well beyond them: it discloses that failure rows without receipts are included, that args_json is permission-gated with an args_withheld marker, and that secrets are redacted. This is exactly the contextual value the description should add, though it omits pagination/response-size behavior.

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 with the action and resource, then the return surface, then the permission/redaction caveat — a sensible priority order. It is dense but every clause carries information; no filler.

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?

With no output schema, the description sensibly enumerates the returned surface (args_hash, hash chain, response_summary, timestamps, receipt_id) and explains conditional omission of args_json, which is enough to set expectations. Missing only edge cases like not-found behavior or response size.

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?

With one parameter and 0% schema description coverage, the description only restates that the id identifies an execution row; it gives no format, provenance (where to obtain the id), or error behavior for unknown ids. Since parameter count is one, the burden is light, but the description still adds only marginal meaning beyond the schema.

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 a single execution row by id') and clarifies the scope by noting it includes failure-status rows that never got a receipt — implicitly distinguishing it from the receipt-oriented siblings. It never names get_receipt or list_recent_receipts directly, so an agent must infer the routing rather than being told.

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 'by id' framing implies the lookup use case, but there is no explicit when-to-use/when-not statement and no named alternative. Given the siblings fleet__get_receipt and fleet__list_recent_receipts, a clear rule (e.g. 'use get_receipt when you have a receipt id') would materially help.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds that each row carries a reason and timestamp and that aggregate counts are returned, which is genuinely useful. It says nothing about ordering, pagination, or volume limits for an agency-wide listing.

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?

A single front-loaded sentence packing scope, per-row contents, and returned aggregates with no filler. Every clause earns its place.

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?

With no output schema, the early mention of reason/timestamp and total_active/total_killed counts is the right instinct and partly fills that void. However, an undocumented plugin_slug filter and no pagination or result-size guidance leave gaps for an agency-wide listing tool.

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 50%: site_ids is documented in-schema while plugin_slug has no description anywhere. The description adds no parameter meaning at all, so it neither compensates for the gap nor clarifies the default 'every eligible site' scope. Baseline 3 applies since the description is silent but the schema covers half.

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 ('List') and resource ('currently-killed manifests in the agency') plus what is returned (reason, timestamp, active/killed counts). The title's 'switched-off plugins' disambiguates the jargon. It does not explicitly name the counterpart mutators (fleet__kill_manifest, fleet__restore_from_snapshot), so sibling differentiation is only implicit.

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 only implied: reading 'currently-killed' state before acting suggests an inspection-before-restore workflow, but the description never says when to call this versus fleet__restore_status, fleet__undo_status, or fleet__get_execution. No exclusions or prerequisites are given.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuine context beyond that: the specific budget windows reported and the intended self-throttling use. It does not say what the response looks like or whether an omitted site_id returns a fleet-wide aggregate, which keeps it off a 5.

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?

A single tight sentence with the action and the breakdown window list front-loaded and the purpose clause trailing. No filler or redundant restatement of the title.

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?

There is no output schema, so the description should carry more weight on what the report contains and how the optional parameters change it. It names the windows adequately but leaves the two parameters and the aggregate-vs-scoped behavior undefined.

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% and neither of the two parameters is documented anywhere. The phrase 'per-site-minute' weakly hints that site_id scopes the report, but tool_name is never mentioned and it is unclear whether these params filter the budget or report a hypothetical budget for a site/tool pair.

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 ('Report') and resource ('current rate-limit budget') and enumerates the exact windows covered (per-agency-minute, per-site-minute, runaway-same-minute, daily). No sibling covers this domain, so the scope statement alone is enough to distinguish it.

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?

'Enables LLM self-throttling' implies the use case (poll before issuing heavy calls), but there is no explicit when-to-call guidance, no stated cadence, and no note on when it is unnecessary or what to do with the numbers returned.

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

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

Annotations already cover readOnly/idempotent/non-destructive, so the description is freed to add real content: it itemizes exactly what is returned, including whether the change is still undoable and its expiry window, and it explicitly discloses that the undo token is NOT returned here. That negative disclosure is genuinely useful context that no annotation or schema carries.

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, front-loaded with the verb and the returned payload, with no filler. The second clause is slightly run-on ("receipt_url, the receipt in Royally where a person can undo it"), but every part conveys a distinct fact.

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?

There is no output schema, so the description must carry the return-shape burden, and it does by naming each returned component plus the deliberate omission of the undo token. It stops short of describing error behavior for an unknown or expired receipt_id, a minor gap for a single-param read.

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% and the single parameter is self-documenting ("receipt id returned in the original mutation envelope"), so the schema does the heavy lifting. The description adds no format, sourcing, or failure-mode detail about receipt_id beyond what is already structured — 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 and resource ("Fetch a full receipt for a prior change") and enumerates the payload: the receipt, the execution it records, undo status/expiry, and receipt_url. It is unambiguous on its own, but never names a sibling (e.g. fleet__list_recent_receipts or fleet__get_execution), so an agent must infer the boundary itself.

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 only implied by "for a prior change" and the schema note that receipt_id comes from the original mutation envelope. The description never says when to prefer this over list_recent_receipts (to discover ids) or get_execution (to inspect the execution alone), leaving the routing decision to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world; the description reinforces the last point with 'Reads Royally's records only.' It adds valuable behavioral detail beyond annotations — the with/without site_id result shape and that client is null when a site has none — but does not discuss pagination or payload size.

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 what the context is, then the usage directive, then the two result shapes. Every sentence carries information; the only mild cost is that the long opening sentence packs many clauses together.

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?

No output schema exists, so the description carries the return-value burden, and it does describe both branches of the result including the null-client edge case. It stops short of naming the exact fields an agent should expect, leaving some ambiguity about the response envelope.

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 schema documents site_id and points to fleet/list_sites. The description still adds semantic value by explaining the consequence of omitting the parameter (agency context plus every client that has context), which the schema does not convey.

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 (read) and resource (AI agent context) and enumerates the two content types it returns: agency house rules (agency_notes) and per-client context such as brand colors, tone, and contacts. An agent can distinguish this from siblings like fleet__list_sites or royal-mcp__wp_get_site_info without opening the 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?

Explicitly prescribes when to call it ('Read it before changing a site's content or design') and gives a precedence rule ('follow it unless the person you are working with says otherwise'). It also spells out the two calling modes: with site_id vs. without site_id and exactly what each returns.

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

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

Annotations already cover read-only, closed-world, idempotent and non-destructive, so the bar is lower, yet the description adds substantive behavior: the data comes from scheduled checks rather than live site calls, muted problems count toward a warn light, vulnerable components return null when the security plugin isn't checking, and a feed older than a week is marked stale. Those are non-obvious data semantics an agent could not derive from structured fields.

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 lead clause is front-loaded and every element earns its place — the long field enumeration is justified because no output schema exists. The cost is that it reads as one run-on sentence with nested parentheses around the vulnerability states, which is harder to parse than a short enumerated list would be.

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?

With no output schema, the description carries the return-shape burden and does so thoroughly, including null and stale-feed semantics. What is left implicit is freshness: 'scheduled checks' never says how often those checks run, which matters for interpreting an 'at a glance' health light.

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% and the single site_ids parameter is fully documented in the schema ('Omit for every connected site in the agency'). The description reinforces the per-site default with 'one row per connected site' but adds no format or filtering nuance beyond the schema, 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?

The description names the resource and its scope precisely: a per-site fleet health rollup drawn from scheduled checks, one row per connected site, with an explicit column list (light, alerts, muted count, backup, vulnerable components, WP/PHP versions, SEO audit). It also separates itself from the recipe/* siblings, so an agent can pick it over a detail tool without opening the 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 states the boundaries clearly: 'Reads Royally's records only and never calls a site; use the recipe/* tools for detail or a fresh check.' That gives both a when-to-use and a named alternative. It doesn't address the other plausible alternatives (fleet__list_sites, fleet__security_triage, fleet__get_kill_switch_status), so routing against the full sibling set is still partly inferred.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new context: the blast radius (all subsequent tool dispatch through the manifest is blocked) and a recovery route (fleet__undo). It doesn't mention the dry-run-by-default behavior or the approval requirement, but the core behavioral picture is materially clearer than 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?

Two tight sentences: the action and blast radius come first, the reversibility guarantee second. No filler, no repetition of the title, and the most decision-relevant fact is front-loaded.

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 destructive, non-idempotent mutation with no output schema and 40% parameter coverage, the description covers consequences and recovery but leaves key invocation details unaddressed: what a manifest is, that the operation is site-scoped, and when the acknowledgment/approval path applies. An agent can call it, but with avoidable uncertainty.

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 only 40%, so the description carries the burden of explaining parameters—yet it mentions none of them. 'reason', 'site_id' and 'plugin_slug' are undocumented in both places, and the description doesn't clarify that the target is scoped to one site or what a plugin_slug identifies.

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 ('kill a single manifest') plus the resulting effect ('blocks all subsequent tool dispatch'). The word 'single' implicitly separates it from the sibling fleet__kill_manifests_by_plugin, but that sibling is never named, so the differentiation is inferred rather than stated.

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 description gives a lifecycle context ('until cleared') and points to fleet__undo as the reversal path, which helps an agent understand recovery. However, it never says when to choose this over fleet__kill_manifests_by_plugin or fleet__deny, nor does it state preconditions such as the approval flow implied by the acknowledgment parameter.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds what the annotation cannot: that the effect is retroactive on existing manifests, that a confirmation phrase gates real runs, and that recovery is per-site via fleet__undo. It does not discuss partial failures across sites or permission requirements, so it is not a full 5.

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?

Three sentences, scope first, then the approval gate, then the escape hatch — well front-loaded with no filler. The compressed phrasing "for real-run" is slightly telegraphic, which keeps it just below a 5.

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 6-parameter destructive fleet-wide operation with no output schema, the description covers the essentials: scope, the approval gate, and reversibility. Missing details like behavior on partial success across sites and what a preview returns keep it from being complete.

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 67%, with dry_run, site_ids, and acknowledgment already documented in the schema. The description confirms plugin_slug is the match key and that the tool spans all sites when unrestricted, but adds no format, default, or interaction detail beyond what is already structured — appropriate baseline 3.

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?

"Agency-wide bulk kill: retroactively disable every manifest matching a plugin_slug across all sites" gives a specific verb (disable), a specific resource (manifests matching a slug), and an explicit scope (all sites). The phrase "every manifest ... across all sites" implicitly separates it from the singular fleet__kill_manifest sibling, so an agent can pick correctly without opening either 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 names the preconditions for a real run (an acknowledgment phrase) and points to fleet__undo for per-site recovery, which is the key operational context for a destructive tool. It stops short of explicitly telling the agent to preview with a dry_run first or directly naming fleet__kill_manifest as the narrower alternative, so it stops at 4.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, non-destructive, closed-world), so the description's job is context — and it adds real value: default scope is *open* advisories, results are severity-ordered, and each row carries an actively-exploited flag. It does not clarify what 'open' excludes (dismissed/resolved) or pagination behavior, which is the remaining gap.

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, front-loaded with scope and ordering, and the final sentence earns its place by describing return content absent from any output schema. Slightly dense in the middle clause where five filters are compressed into one list.

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 6-param read tool with annotations and no output schema, the description covers scope, ordering, filtering, and a key return field (exploited status). The main omission is the advisory lifecycle model — with dismiss/resolve/acknowledge siblings present, an agent needs to know what 'open' excludes.

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% and every filter is documented in-schema, including defaults and enum values, so the baseline of 3 applies. The description's enumeration of severity/category/site/source/acknowledged largely restates the schema, though pairing 'acknowledged' with the open-advisory framing adds modest interpretation.

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 ('Open advisories for the agency') plus default scoping (open only) and ordering (severity-first), which is far more than the tautological title 'List alerts'. It does not explicitly name the sibling it differs from (fleet__get_advisory, fleet__security_triage), so sibling differentiation is left implicit.

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 filter list implies when this list view is appropriate, but the description never says when to use it versus fleet__get_advisory (single advisory), fleet__security_triage, or the lifecycle siblings acknowledge/dismiss/resolve_advisory. No prerequisites or exclusions are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered structurally. The description adds that results are aggregated per agency with site counts, which is useful context, but says nothing about auth requirements, pagination, or shape of the returned entries.

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, no filler. The positive definition comes first and the disambiguation second, which is the right order for a scanner reading the first clause only.

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?

No output schema exists, yet the description mentions the key return attribute (site counts) and rules out the most likely misselection. For a zero-parameter read-only lister this is nearly complete; only the exact response shape per integration is left implicit.

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?

The tool takes zero parameters and the schema is an empty closed object, so there is nothing for the description to disambiguate. Baseline 4 applies; the note about site counts incidentally signals the aggregation granularity of the output.

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 resource and scope: the Royal MCP integrations/tool sets each site exposes to Royally, aggregated across the agency with site counts. It also explicitly disclaims the near-identical sibling concept (installed WordPress plugins), so an agent can distinguish it from wp_list_plugins or get_plugins 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 an explicit negative case and names the correct alternative: 'This is not the list of WordPress plugins installed on sites; use recipe__fleet_inventory for that.' What is missing is positive framing of when an agent should reach for this (e.g. auditing which sites expose which tool sets), but the disambiguation is clear and actionable.

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

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

Annotations already cover read-only/idempotent safety, yet the description adds substantial non-obvious behavior: hourly log ingestion, 30-day retention, absence of receipts/approvals/undo, and a visibility limit to changes made as the WordPress user Royally's connection signs in as. It also warns that `target` never contains written values, which matters for privacy expectations.

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?

Purpose and ordering are front-loaded, and every clause carries information (return shape, retention, visibility, param interactions). It is dense — the seven-field enumeration of `outside_royally` is delivered as one long run-on clause, which makes it harder to scan than a bulleted field list would be.

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?

With no output schema, the description usefully supplies the return shape for both top-level keys and the connection enum, plus retention and visibility caveats. The main gap is paging: `limit` is capped at 200 but nothing says how to retrieve older changes beyond that window, and there is no note that no site-level filter exists.

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 baseline is 3, but the description adds genuinely non-obvious semantics: `since` and `limit` apply to both lists, while `authored_by` empties `outside_royally` entirely. That interaction is not visible from the schema and materially affects how an agent constructs a query.

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 with scope: an activity feed across every site in the agency, newest first, split into `changes` and `outside_royally`. It indirectly distinguishes itself from receipt-based siblings by saying these have no receipt, approval or undo in Royally, but it never names `fleet__list_recent_receipts` or `royal-mcp__mcp_list_recent_changes` as the per-site alternative.

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 prescribed: the feed is for seeing what happened, and the note that entries have no receipt/approval/undo hints at when to prefer receipt tooling instead. There is no explicit when-to-use, when-not-to-use, or named alternative among the many sibling list tools.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuine value on top: newest-first ordering, the agency-wide scope, the pagination ceiling, and that each row exposes has_available_undo for spotting reversible operations. It stops short of describing rate limits or response shape details, but the extra context is real.

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 dense sentences, zero filler, with the core identity ('paginated audit log, newest-first') front-loaded and the payoff field (has_available_undo) placed last where it is easy to find.

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?

There is no output schema, and the description compensates by naming at least one returned field (has_available_undo) and the sort order. For a zero-required-param read tool with fully documented parameters, this is nearly complete; a hint about how expensive a large limit is or how to page forward would close the last gap.

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 the schema already documents every filter including defaults and the 200 cap; the description's restatement of tool_name/site_id/since/only_reversible/limit/offset adds almost nothing beyond it. Baseline 3 applies when structured data carries the semantics.

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 ('list recent receipts') and pins the scope ('audit log ... across the agency, sorted newest-first'), which is far more than the title alone. It does not, however, distinguish itself from the similar-sounding sibling fleet__list_recent_changes, so an agent must infer the difference (receipts vs. changes).

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 description enumerates the filters available, which implies how to narrow results, but gives no explicit when-to-use guidance or exclusions — e.g., that fleet__get_receipt should be used for a single receipt or that list_recent_changes covers a different audit surface. 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.

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior: a 'filter' group is re-matched on each use, and the site count reflects the current match, which matters for reasoning about freshness of the result.

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?

Information-dense but the opening is a fragment ('The agency's saved site groups, by name:') and the deeply nested parenthetical defining 'kind' is hard to parse on a first read. It could be restructured into short, front-loaded clauses without losing content.

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?

With no output schema, the description carries the burden of describing the return shape, which it does (selection_id, kind, site count). It also points at the consuming tools, leaving only minor gaps such as ordering/formatting details.

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?

The tool takes zero parameters, so the baseline is 4. The description goes slightly further by explaining the semantics of the returned selection_id and how to consume it, though there are no inputs to disambiguate.

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 resource ('the agency's saved site groups') and enumerates exactly what each entry contains: selection_id, kind (sites vs filter), and current site count. An agent can distinguish this from list_sites and other siblings without opening 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?

Explicitly routes the agent onward: pass a selection_id into fleet__list_sites filter or fleet__bulk_edit site_filter, and call fleet__list_sites to resolve actual sites. It also implies this is a prerequisite/discovery step, though it does not state any exclusion or 'when not to use' condition.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: each result carries the client association, the agency's assignment, and the connected services (e.g. Cloudflare zone), plus a pointer to which tools to use for those services.

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 with the scope and return shape front-loaded and no filler. The second sentence is a dense run-on involving the service/Cloudflare routing idea, costing a little readability.

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?

Return contents are described, filtering is delegated to a well-documented nested schema, and no output schema exists to lean on, so the description carries its share. What's missing is a note on result volume or pagination behavior for a fleet-wide enumeration.

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?

The description only says results are 'optionally filtered' without naming or explaining any filter field. The nested schema does document each filter (tags, status, tag_match, plugin_slug, selection_id) so the baseline of 3 applies, and the description adds nothing on top of 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 ('Enumerate connected sites') and scopes it to 'the current agency', which is real information an agent can't get from the name alone. It does not explicitly distinguish itself from close siblings like fleet__list_site_groups or recipe__fleet_inventory, so it stops 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 only implied: 'optionally filtered' suggests using it as a listing step before acting on a site. There is a useful routing hint ('use that service's tools for the site'), but no explicit when/when-not versus list_site_groups or fleet_inventory.

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

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

Annotations already declare non-destructive and idempotent, and the description adds genuinely new behavior: content is untouched, pages re-cache naturally on visitor load, there is nothing to undo, and it executes immediately. It also discloses the response payload — each site's cache plugin plus a list of sites with none.

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 with the action and scope, then plugin order, then parameter default, then safety/return behavior. Every clause carries information; nothing is repeated from the title or schema.

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?

With no output schema, the description covers the reply shape, and for a one-optional-parameter mutation it covers safety, reversibility, batching limits, and plugin fallback. An agent has everything needed to call it and interpret the result.

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 site_ids is already documented, but the description adds two facts the schema lacks: the omit-default of every connected site and the 50-site cap on a single call. That is meaningful added semantics beyond the structured field.

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 ('Clear the page cache') plus the exact scope ('on each chosen site') and the plugin precedence order (ForgeCache → LiteSpeed → W3 Total Cache). No sibling tool performs cache purging, and the definition makes that scope unmistakable.

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 clear operating context: the default is every connected site when site_ids is omitted, and the batch is capped at 50. It does not name any when-not-to-use conditions (e.g., mid-deploy or during a maintenance window), but with no comparable sibling the routing risk is low.

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

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

Beyond the annotations (destructiveHint=true, idempotentHint=true) the description adds real context: the action is audited, it is attributed to the signed-in user, and accepted_risk only suppresses the alert for 30 days unless it worsens. It stops short of saying whether the closure can be undone via fleet__undo or what state the advisory ends in.

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?

Three tight sentences with the operation front-loaded, then permissions, then the one non-obvious behavioral caveat. No filler and nothing repeated from structured fields without added meaning.

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 two-parameter mutation with annotations covering the safety profile and no output schema, this covers permissions, auditing, and the validity window of one method. The only material gap is what the caller gets back and whether the resolution can be reversed.

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 both parameters are already documented, and the description largely restates the four enum values the schema enumerates. It does add meaning for accepted_risk that the enum description does not carry, but advisory_id gets no additional semantics; 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 and resource ('Close an advisory') plus the closed set of resolution methods, so the operation is unmistakable. It does not, however, distinguish itself from close-adjacent siblings such as fleet__acknowledge_advisory or fleet__dismiss_advisory, which an agent must choose between.

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 an authorization precondition (owner, admin or member of the agency) and specifies the special case where accepted_risk applies. It never says when to pick this over acknowledge_advisory or dismiss_advisory, so the usage guidance is implied rather than explicit.

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

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

Annotations declare readOnlyHint=false, while the description says 'Nothing changes here' and frames the tool as a pure preview. That is a direct contradiction about whether the caller can expect state changes. The description does add useful context about SiteVault refusing unrestorable backups and the irreversible nature of the actual restore, but the read-only contradiction is serious.

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?

Four sentences, front-loaded with the purpose, then behavioral context, then the follow-up tool. There is no filler, and each sentence contributes to understanding the workflow.

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?

With no output schema, the description usefully explains what the preview returns (backup time, size, number of changed posts) and where the actual restore happens. It omits guidance on the acknowledgment parameter and is undermined by the read-only contradiction, but it is otherwise complete for this complexity level.

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 75%, so most parameter meaning is already structured. The description adds context for snapshot_id (backup id from fleet__trigger_backups) and implies a preview mode, but site_id remains undocumented and the description does not compensate for the coverage gap.

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 names a specific verb ('Preview restoring') and resource ('one site from a SiteVault backup'), and it ties the tool to the backup id returned by fleet__trigger_backups. This distinguishes it from fleet__restore_status and fleet__trigger_backups without opening either 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?

The description clearly places the tool as a preview step after fleet__trigger_backups and before fleet__restore_status, and notes that a person applies the restore in Royally. It does not explicitly state when not to use it or contrast it with other preview/restore alternatives, but the workflow context is strong.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so safety is covered. The description still adds value by enumerating the possible states and what each carries (stage/percent for running, SiteVault's message for failure), which the annotations do not convey.

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?

Three short sentences, front-loaded with the outcome states and ending with the read-only guarantee. Nothing is padded or redundant beyond the brief safety restatement.

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?

There is no output schema, so the description must describe returns — and it does, covering all three terminal/in-progress states and their payloads. Combined with the annotations, an agent has everything needed to call and interpret this tool.

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 only 50%, with site_id entirely undocumented. The description compensates by tying restore_id to 'the restore_id shown on the applied restore', telling the agent where to source the value; site_id is left implicit but is reasonably self-evident as the site being restored.

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?

Names the specific resource (a restore of one site) and the exact information returned: running with stage and percent, or completed/failed with SiteVault's message. This clearly separates it from fleet__restore_from_snapshot (which starts a restore) and fleet__undo_status (a different operation).

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 phrase 'the restore_id shown on the applied restore' implies the tool is called after a restore has been applied, giving an implicit usage context. However, it never states when to poll versus when to re-apply, nor does it name any sibling as an alternative or exclusion.

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

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

Adds substantial context beyond the annotations: reads are synchronous, writes wait per site under Approvals grouped into one approvable run via approve_url, an automatic backup runs beforehand (backup_first, default true) via SiteVault/UpdraftPlus, the change cannot be undone, and the result cannot be verified. This is exactly the behavioral disclosure an agent needs for a fan-out mutation tool.

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?

Dense but front-loaded: the core action and scope come first, then read/write behavior, then return shape. Nearly every sentence carries distinct information; it is long but appropriate for the tool's complexity, with only minor redundancy.

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?

Although there is no output schema, the description specifies the per-site return states (ran, waiting with execution_id, refused with reason). Combined with the annotation coverage and the approval/backup explanation, an agent has everything needed to decide and invoke correctly.

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?

With 100% schema coverage the baseline is 3, but the description adds real meaning: it shows the tool-name formats accepted (e.g. emcp-tools-update-post or <server>/<tool>), clarifies that args must be identical on every site, and confirms site_ids defaults to every eligible site and backup_first defaults to true.

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: run one tool of another (non-Royal) MCP server with identical arguments across up to 50 chosen sites. The scope constraint (only where the server offers it and the tool is enabled for its connection) and the exclusion of Royal MCP tools make it immediately distinguishable despite the large sibling set.

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 clear conditions: reads run immediately; changes are queued for approval; only non-deleting/non-overwriting tools may fan out, while others are 'refused here and run one site at a time.' This effectively names the alternative path. It doesn't name a specific sibling tool for the single-site case, which keeps it just below a 5.

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

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

Adds real behavioral context beyond annotations: scans run synchronously with GuardPress but in the background with Wordfence, nothing is changed on the site, and the response lists sites with no scanner. The 'changes nothing on the site' phrasing sits in mild tension with readOnlyHint=false, but the description explains enough (a scan job is still being started) to avoid being misleading.

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 core action and the resulting behavior are front-loaded, and the follow-up pointer comes last in the right place. The definition stays information-dense, though it packs mechanism, limits, fallback, and rerouting into one sentence plus a fragment, which reads as slightly dense rather than clean.

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?

With one optional parameter, no output schema, and all safety hints in annotations, this definition covers what is needed to call it: what it does per-site, what changes, what the reply lists, and where to find results. It does not describe the shape or timing of scan results, but it delegates that to fleet__check_vulnerabilities, which is a reasonable design.

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 schema already documents site_ids, but the description adds information the schema does not contain: a hard cap of 50 sites and an explicit statement that omitting the field scans every connected site. That is a genuine value-add over the structured field, though it is brief.

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 ('Start a fresh security scan on each chosen site') with scope limits (up to 50) and a concrete mechanism (per-site security plugin: GuardPress or Wordfence). It is clearly distinct from sibling tools, and it even names the follow-up tool (fleet__check_vulnerabilities) an agent should use next, so the agent can route correctly without opening either 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 context for when the parameter is needed ('Optional site_ids (default every connected site)'), states when to follow up ('Use fleet__check_vulnerabilities afterwards'), and notes a limitation (sites with no scanner, Kadence Security cannot scan). It does not state when *not* to run a scan (e.g., rate limits, whether a concurrent scan is in progress), so it stops short of a 5.

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

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

Although annotations already declare readOnly/idempotent/non-destructive, the description adds substantial context annotations cannot express: per-site caps (50 sites, 50 plugins, 20 patterns), a non-obvious correctness caveat that an empty summary never proves a site is clean, the meaning of `partial`, that no secrets/emails/usernames leave the site, and the receipt_id audit trail. It is fully consistent with readOnlyHint=true ("Changes nothing on the sites").

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?

Almost every clause earns its place, and purpose precedes parameters which precede return shape, so it is front-loaded. However the whole thing is one dense run-on paragraph with no separation between input semantics, output shape and caveats, which makes it hard to scan in a tool-selection context.

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?

There is no output schema, so the description carries the return contract itself: per-site summary, indicators, partial, checks_run/checks_skipped, the detailed report fields, guardpress payload and receipt_id are all enumerated. Combined with parameter semantics and failure behavior, an agent has everything needed to call and interpret it.

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 already 100%, yet the description goes well past it: `since` is explained as flagging changes to plugins/mu-plugins/drop-ins/upgrade leftovers and admin registrations after that date, `plugin_names` as matched against regular, unregistered, must-use and drop-in files, and `option_patterns` as returning presence and count only under a single-`*` prefix/suffix rule. This is meaning the schema does not carry.

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?

Opens with a specific verb, resource and scope: a read-only security check across up to 50 chosen sites returning one combined result, then enumerates exactly what is inspected (plugins, mu-plugins, drop-ins, upgrade folder, users, options, GuardPress). The main gap is that it never distinguishes itself from the near-identical fleet__scan_security or recipe__run_security_sweep siblings, so an agent must infer the boundary from the parameter detail alone.

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?

"For sites you suspect were compromised" supplies a clear triggering condition, and the closing note that sites without the check return errors tells the caller when to expect failure. There is no explicit when-not or named alternative tool, so the routing guidance stops short of the top score.

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

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

Goes well beyond the annotations: explains the operation is additive and non-destructive in effect, starts immediately and runs asynchronously in the background, and describes the response shape (per-site plugin and backup id, plus a list of sites skipped for missing plugin or an in-progress backup). That is exactly the material an agent needs and annotations alone do not supply.

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 dense sentences, front-loaded with the action and target, then defaults, then runtime behavior and response. No filler, though the long second sentence carries several distinct ideas that a reader must parse in one pass.

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?

With no output schema, the description correctly takes on the burden of describing the reply, and it covers the async lifecycle, plugin selection fallback, and the follow-up tool for results. Nothing an agent needs in order to invoke and interpret this tool 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?

Adds defaults absent from the schema (site_ids omitted means every connected site, type defaults to full) and enumerates the three backup scopes in prose, which the schema only exposes as bare enum values. Only the 50-site cap is left implicitly tied to the call rather than the parameter, so not quite a full 5.

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 (start) and resource (backup) plus the mechanism (each site's own plugin, SiteVault with UpdraftPlus fallback) and a scope bound (up to 50 sites). This clearly separates it from siblings like recipe__backup_status, fleet__verify_backup_health and royal-mcp__updraftplus_list_backups.

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?

Explicitly routes the agent to recipe__backup_status for checking finished backups, and the defaults (all connected sites, type full) tell the agent when the call can be made with no arguments. It stops short of naming an alternative to use instead when a backup is already running, only noting that such sites are reported back.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, yet the description still adds real value: partial results with not_restored item lists, later edits being preserved, and a refused undo leaving the token usable. The retry_with_force sentence is confusing — it names a parameter absent from the schema and mentions 'Royally' and 'on the receipt of that change' without explaining the workflow — which keeps it below a 5.

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 core operation is front-loaded, but the middle sentence about retry_with_force is tangled and references a parameter that does not exist in the schema, plus an unexplained product reference ('Royally'). That sentence costs more confusion than it earns.

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?

The description covers the three outcomes that matter for a destructive undo — full reversal, partial with reasons, and refusal with token preserved — which is strong coverage given no output schema exists. It stops short of saying how to retrieve the resulting receipt beyond 'it is recorded with its own receipt', which the agent must infer maps to fleet__get_receipt.

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% and the undo_token property already documents the 168h window, hashing and lookup. The description restates the expiry rather than adding new semantics, so the schema does the heavy lifting and 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 precise verb+resource ('Reverse a reversible-write') and the mechanism ('using its undo_token'), which immediately separates it from read-only siblings like fleet__undo_status and fleet__list_recent_changes. An agent knows exactly what this does without opening the 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?

The 168h validity window and the requirement for an undo_token imply when the tool is applicable, but the description never routes the agent between this, fleet__undo_status (to check whether an undo is available) and fleet__restore_from_snapshot. Usage 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.

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered. The description adds real value beyond that: it defines the failure state ('unavailable: the site can no longer run its own undo') and names every returned field, which is the main thing an agent cannot infer from structured data here.

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?

One dense sentence with the status enumeration and the return-field list front-loaded and no filler. It is packed close to the limit but every clause (including the 'unavailable' gloss) 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?

With no output schema, the description takes on the return-value burden and discharges it by listing expires_at, seconds_remaining, receipt_id, and the reverse-op provider/tool_name. What remains missing is the provenance of the undo token and how this relates to fleet__undo, which is a meaningful but bounded gap for a one-parameter read tool.

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 0% and the single parameter is a bare string, so the description must carry the load. It names the token's role but never says where an agent obtains an undo token, whether it is opaque or formatted, or what happens with an invalid/unknown token.

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 ('Look up an undo token and report ... status') and enumerates the exact status vocabulary returned. It does not, however, distinguish itself from the closely-related siblings fleet__undo and fleet__restore_status, so an agent must infer the boundary itself.

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 only implied: checking a token's status before acting is the obvious reading, but the description never says 'call this before fleet__undo' or 'do not call this to perform the undo.' No alternative or exclusion is named despite fleet__undo and fleet__restore_status sitting in the same namespace.

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

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

With annotations already declaring openWorldHint and non-idempotency, the description adds the context that matters: preview applies once, writes are only triggered via approve_url or the site-group auto-apply rule (where preview_url replaces approve_url and applied_by_rule names the groups), and undo is available for 168 hours. This also reconciles readOnlyHint=false with 'nothing is written by this tool' – the write path exists but is not the tool's own call.

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?

Purpose and the no-write guarantee are front-loaded, and almost every sentence carries operational information. It is a single dense paragraph of roughly 200 words with nested parentheticals (the plugin roster, the fallback_from aside) that would read faster as short bullets, but nothing is truly 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 mutation-adjacent, open-world tool with no output schema, the description covers the return payload (before/after per changing post, unchanged count, approve_url, approve_before), the auto-apply variant response shape, the follow-up receipt lookup, and the undo window. Nothing an agent needs to call it correctly or explain the result 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?

Schema coverage is 100%, so the baseline would be 3, but the description genuinely adds semantics the schema cannot express: 'A field left out of an update is not touched; null clears a value back to the plugin's default.' That distinction between omitted and null is the single most error-prone aspect of this payload and it is spelled out, along with the 100-post cap and the plugin-detection fallback affecting where the values land.

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 first sentence names a specific verb and resource (preview changes to SEO titles, meta descriptions, focus keywords, noindex, canonical) scoped to up to 100 posts of one site. It also resolves the tension between the tool name (update_seo_meta) and its actual behavior by stating explicitly that nothing is written. An agent can distinguish it from royal-mcp__wp_update_seo_meta or mcp-easy-ai__wp_ability_rank_math_get_post_seo_meta 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?

It prescribes the full workflow: show the diff, hand over approve_url, and it states the exclusion outright ('You cannot apply it yourself'). It also names the sibling follow-up path (fleet__list_recent_receipts with site_id filter, then fleet__get_receipt), so an agent knows exactly what to do before and after.

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

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

Goes well past the annotations by disclosing latency characteristics (minutes per site), the 50-site cap, the decryption step performed on the site, and the exact response shape including per-site backup id, timestamps, encryption flag, and plain-language issues. It also states the negative case — a site with no completed full backup is reported as an issue rather than silently omitted.

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 with the core action and dense with useful detail, with no filler sentences. It is a single long paragraph, which makes scanning harder, but nearly every clause carries information an agent needs.

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?

There is no output schema, and the description compensates fully by enumerating the returned fields and failure semantics. Combined with annotations covering safety and idempotency, an agent has everything needed to call this correctly and interpret the result.

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% and the single parameter is already documented as 'Omit for every eligible site,' so the description largely repeats it. It does add one piece of real information absent from the schema: the 50-site upper bound on how many sites can be checked in a call.

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 with precise scope: verifying that the newest completed full backup on each chosen site can actually be restored, and explains the mechanism (archive is opened and decrypted). This is clearly distinguishable from trigger_backups, restore_from_snapshot, and restore_status in the sibling list without opening 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?

Gives clear operating context: optional site_ids default to every connected site, capped at 50, and warns that large or encrypted backups can take minutes per site. It does not explicitly route against alternatives such as trigger_backups or restore_from_snapshot, but the read-only verification framing makes the intended use unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, and the description's 'its server marks it read-only, so it runs straight away' merely restates that rather than adding new behavioral context. It does clarify the return is a list of registered abilities, which is modest added value.

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?

Three short sentences with the core purpose front-loaded. The trailing 'Through Royally' clause is redundant with the annotations and could be dropped, but otherwise there is no padding.

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 simple read-only discovery tool this is nearly adequate, but with no output schema the description should say more about what 'basic information' per ability looks like (names, descriptions, input hints) so an agent knows what it can do next.

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?

Only one optional parameter (site_id) with full enum documentation in the schema, so the schema carries the semantics. The description adds nothing about scoping to a site, 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?

Clear specific verb and resource: 'Discover all available WordPress abilities' plus what is returned. It does not, however, distinguish itself from the sibling mcp-adapter-get-ability-info or execute-ability, which an agent could easily confuse it with.

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?

No statement of when to use this versus get_ability_info or execute_ability; the only extra clause is a note that it runs immediately, which is not usage guidance. The discovery-then-execute workflow is left entirely implicit.

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

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

Adds real information beyond the annotations: an approval gate in Royally for any non-read-only ability, and that the change is recorded but cannot be reversed. This elaborates on destructiveHint rather than contradicting it. Return shape and latency of approval are still unstated.

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?

Purpose first, then the approval semantics, then the irreversibility warning — well ordered. The closing sentence partly repeats the destructive hint, but every sentence still carries usable signal.

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 an untyped generic dispatcher with no output schema, the description covers the essential operational facts: it can run anything, some calls block on human approval, and results are not reversible. The one meaningful omission is guidance on discovering available ability names and their parameter shapes.

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 ability_name, parameters and site_id are already documented. The description only restates that parameters are passed through, without clarifying that the keys inside 'parameters' are ability-specific or where to find the abilities' own schemas — 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+resource (execute a registered WordPress ability) and identifies itself as the generic execution layer that can run any ability. The distinction from discover-abilities / get-ability-info is only implied via 'registered ability', not named, so it falls short of the 5 bar.

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?

Implies usage context (read-only abilities run immediately, others require approval) but never says to call discover-abilities first to obtain a valid ability_name, nor names any exclusion or alternative execution paths such as the many royal-mcp__* wrappers in the sibling list.

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

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

The description repeats the readOnly annotation ('its server marks it read-only') and adds the useful consequence that it 'runs straight away' without approval. It also discloses the shape of the payload (schemas, description, examples), which annotations can't convey. The 'Through Royally:' phrasing is garbled and adds no actionable context.

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 front-loaded sentences: the core purpose and return contents come first. The second sentence is somewhat redundant with the annotations, but it is short and justifies itself by explaining the no-confirmation behavior.

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?

There is no output schema, and the description compensates by naming the returned fields (input/output schema, description, usage examples). Combined with read-only annotations and a fully documented two-parameter schema, an agent has what it needs to call this correctly.

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%, with both ability_name and the enum-constrained site_id documented in the schema. The description adds no format hint for ability_name (e.g. namespace/name convention), so the baseline of 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 and resource — retrieving detailed information about one WordPress ability — and enumerates what that detail includes (input/output schema, description, usage examples). The word 'specific' implicitly contrasts with the sibling discover-abilities tool, but the contrast is never made explicit.

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 only implied: an agent can infer this is the step between discovering an ability and executing it, but the description never says when to prefer it over discover-abilities or execute-ability. No preconditions, no when-not guidance.

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

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

Beyond the annotations it adds one genuinely useful behavioral fact: results come back as semantically similar chunks rather than ranked page hits. The trailing sentence about the server marking it read-only merely restates readOnlyHint in garbled form and adds no information, and it says nothing about result count, chunk size, or empty-result behavior.

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?

Purpose and usage are front-loaded correctly, but the bulk of the text is a nine-line product enumeration that could be compressed, and the final 'Through Royally...' clause is noise that dilutes an otherwise clean two-part structure.

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-query read-only search with no output schema, the definition covers purpose, domain coverage, and result shape (semantic chunks), which is close to sufficient. Missing only practical details such as approximate result volume and how to phrase the query, which are minor for a tool this simple.

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% with only two parameters, one of which is a single-value enum site_id already documented in the schema. The description adds no meaning to 'query' — nothing on whether natural-language questions, keywords, or product names work best — so it sits at the baseline the rich schema earns.

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 ('Search the Cloudflare documentation') and then enumerates the product surface it covers (Workers, R2, D1, Zero Trust, CDN, Billing, etc.), so an agent knows exactly what corpus is being searched. The scope list also separates it from sibling tooling like mcp-cloudflare-api__execute and the WordPress/SEO search tools.

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?

Explicitly says it 'should be used to answer any question about Cloudflare products or features', which is a clear usage condition. It does not, however, address when to prefer it over the sibling mcp-cloudflare-api__search or say what to do when a query spans several products — no exclusions or alternatives are named.

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

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

Annotations already declare destructive=true, readOnly=false, and non-idempotent, but the description adds genuinely new context: changes wait for a human to approve them in Royally and nothing changes until then, and the connection has no undo. The response-envelope explanation is truncated mid-sentence ('the spec's re…'), leaving the return shape only partly disclosed.

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 critical instruction is front-loaded, which is good, but the body is padded by a long interface block and then visibly corrupted: a sentence cut off at 'the spec's re…' spliced into unrelated 'Through Royally:' approval text. The garbling costs real comprehension, so the structure is only adequate.

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 destructive, open-world code-execution tool with no output schema, the definition covers the essentials: the request helper signature, the response envelope (in truncated form), the approval gate, no-undo, and output truncation. The broken response-envelope sentence is the one real hole an agent would want filled.

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%, and the schema itself already explains truncate, account_id, and site_id well, so the baseline of 3 applies. The TypeScript block adds meaning about what the `code` payload can call (method/path/query/body/contentType), but it says nothing extra about the three non-code parameters.

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 opening sentence gives a specific verb (Execute) plus resource (JavaScript code) and the exact scope of side effects (read, create, update, delete resources via the Cloudflare API). It is immediately distinguishable from the mcp-cloudflare-api siblings (search, docs, whoami), which are lookups rather than an execution surface.

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 prescribes a concrete workflow: 'First use the "search" tool to find the right endpoints, then write code using the cloudflare.request() function.' That names a real sibling and the condition for calling it first. It does not say when to prefer docs or whoami instead, nor when not to use execute at all, so it falls short of a full 5.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description earns credit for going beyond them: it states that $refs are pre-resolved inline and describes the response envelope (`{ success, errors, messages, result }` plus `result_info` on paginated lists). The truncate semantics live in the schema, but the return-shape context here is genuinely additive.

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 first sentence is well front-loaded, but the body degenerates into a truncated 172-item product list and a truncated TypeScript interface, ending in a garbled fragment ('Through Royally: its server marks it read-only...'). Large amounts of the text do not earn their place and the corruption undermines trust in the rest.

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 code-execution tool, an agent needs to know what the async arrow function receives and what it should return, plus when to pick this over execute. The description partially answers the first via the OperationInfo shape but omits the return contract and any sibling routing, and the truncation leaves the definition visibly incomplete.

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 the baseline is 3. The OperationInfo type block does add value for the `code` parameter by revealing which fields (summary, tags, parameters, requestBody, x-api-token-group) are available to query, but the block is cut off mid-sentence ('// Each schema d…'), leaving the code contract incomplete.

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 opening sentence gives a specific verb and resource: 'Search the Cloudflare OpenAPI spec', and the schema confirms the mechanism (a JS arrow function run against the spec). However, it never distinguishes this from the obvious siblings mcp-cloudflare-api__docs and mcp-cloudflare-api__execute, so an agent must infer the split between searching, reading docs, and executing an operation.

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?

There is no explicit when-to-use guidance and no alternatives named, despite three sibling tools in the same server that overlap heavily (docs, execute, whoami). The only usage-adjacent statement is the trailing fragment about a server marking something read-only, which reads as an artifact rather than routing advice.

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

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

Annotations already declare readOnlyHint/destructiveHint=false, so the safety profile is covered; the description adds genuinely new context: the id survives token refresh, reconnection and permission changes (a caching/dedup hint), and it discloses that Royally's server auto-approves it so there is no gating pause. It does not describe the returned fields, which is the remaining gap.

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?

Four short sentences, front-loaded with purpose, then the no-args fact, then the stability property, then the approval behavior. The 'Through Royally' framing is slightly meta but each sentence carries distinct 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 no-argument read-only identity probe with no output schema, the description covers what is returned at a conceptual level and how it behaves. It does not enumerate the concrete fields (email, account id, token scopes), which is the only notable omission.

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% and the single site_id parameter is documented in-schema with its enum, so the baseline is 3. The description's 'Takes no arguments' is mildly at odds with the schema's optional site_id envelope parameter, but it correctly conveys that no content arguments need to be supplied.

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 precise verb and resource: 'Return the Cloudflare user or account that this connection is authenticated as.' That is unmistakably distinct from the WP/Elementor get_user_info siblings, which report WordPress users rather than connection credentials, though the description never says so explicitly.

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?

'Takes no arguments' and 'runs straight away' tell the agent it is cheap and frictionless, which implies it as a pre-flight identity check. However, there is no explicit statement of when to call it (e.g., before account-scoped operations) and no named alternative it is preferred over.

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

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

With no output schema, the description usefully discloses the return contents in detail, including that raw AI model responses are included. It also notes the read-only nature, though that merely restates the readOnlyHint annotation, and it omits rate limits and auth context.

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 purpose and payload enumeration are front-loaded in one dense sentence, which is effective. The trailing parenthetical ability identifier and the 'Through Royally' read-only sentence add little and one of them repeats an annotation.

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 retrieval tool with no output schema, the description covers what is returned thoroughly and the schema covers the inputs. Error behavior and rate limits are unaddressed, but nothing essential for calling it correctly 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?

Schema description coverage is 100%, so the schema already documents both site_id and brand_id, including where to obtain the brand UUID. The description adds no parameter-level meaning beyond the schema, which is the baseline-3 case.

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 — 'Returns the full analysis results for a single brand' — and enumerates the payload (score, rank, sentiment, mention/citation counts, competitor breakdown, per-query results). The word 'full' implicitly distinguishes it from the overview sibling, but no sibling is named explicitly, leaving some differentiation to inference.

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 only implied by 'single brand' and 'full analysis results'; there is no explicit when-to-use, when-not-to-use, or named alternative. The pointer to get-ai-visibility-overview for brand_id lives in the schema, not the description, so a reader relying on the description alone gets no routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the sentence "its server marks it read-only, so it runs straight away" only restates structured data. What does add value is the disclosure that the response distinguishes enabled queries from auto-generated baseline queries, but nothing is said about volume, ordering, or whether usage metrics accompany each query.

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 purpose is correctly front-loaded in the first sentence, but the trailing "(ability: rank-math/get-ai-visibility-brand-queries) Through Royally: its server marks it read-only, so it runs straight away" is routing boilerplate that duplicates the annotations and dilutes the payload.

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 simple, two-parameter read tool with 100% schema coverage and no output schema, the description gives enough: what is returned and at what granularity. The main missing piece is the relationship to the adjacent AI-visibility tools, which an agent would need to pick correctly.

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% and both parameters carry descriptions, including how to obtain brand_id, so the schema does the work. The description adds no additional meaning about the two parameters; baseline 3 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 ("Returns the list of search queries being monitored for a brand") and adds what the list contains (enabled vs. auto-generated baselines). It never names the sibling it is not — get-ai-visibility-brand-insights / get-ai-visibility-overview — so the boundary with those closest tools must be inferred.

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?

There is no explicit "use this when…" statement or exclusion against the brand insights/overview tools. The only routing hint lives in the schema's brand_id description ("Obtain from get-ai-visibility-overview or get-ai-visibility-brand-insights"), which tells an agent how to get an ID but not when to prefer this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the description's 'read-only... runs straight away' largely restates structured data. It does add that all fields are returned by default unless filtered, which is genuine behavioral detail, but pagination, response shape and permission context are not discussed.

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 purpose and default behavior are front-loaded in the first two sentences. The '(ability: core/get-environment-info)' tag and the Royally execution note add some noise, but the definition remains short and readable.

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 simple, two-parameter, read-only tool with no output schema and full annotation coverage, the description says what is returned and how filtering works. Nothing critical for correct invocation is missing, though a brief note on differentiation from site-info tools would complete it.

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%, including the enum of field names and the site_id, so the schema already carries parameter meaning. The description only echoes the default-all-versus-filtered-subset behavior, which is the documented baseline for high-coverage schemas.

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 states a specific verb and resource ('Returns core details about the site's runtime context') and enumerates the four fields, which differentiates it in substance from siblings like get_site_info or get_site_status. It stops short of naming a sibling it is not, so it lands at 4 rather than 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?

The phrase 'for diagnostics and compatibility' implies a use context, but there is no explicit when-to-use versus when-not guidance and no named alternative (e.g., site info vs environment info). Usage is inferable, not stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false. The description's 'its server marks it read-only, so it runs straight away' merely restates that readOnly profile (with a minor hint that no confirmation is required), and it says nothing about openWorldHint meaning a remote/network call or about rate limits.

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 core behavior is front-loaded and useful, but the trailing '(ability: core/get-site-info)' tag and the 'Through Royally…' sentence are meta-noise that partly duplicates the annotations. Half the text does not earn its place.

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?

A zero-required-parameter read tool with full schema coverage and no output schema. The description covers what is returned conceptually and how to narrow it, which is enough to call correctly; only the concrete field set and response shape are left implicit, and the enum covers those.

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%: both `fields` (with an explicit enum) and `site_id` are documented in-schema. The description's 'returns all fields, or optionally a filtered subset' echoes the schema's note but adds no field list, format, or interaction detail, 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?

Specific verb and resource: 'Returns site information configured in WordPress', with scope clarified as all fields by default or a filtered subset. It does not distinguish itself from close siblings such as wp_get_site_info, core-get-site-info, wp_get_site_settings or wp_get_site_health, so an agent cannot tell from the description alone which of these overlapping info tools to pick.

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 description explains the default vs filtered behavior of the call but gives no when-to-use/when-not guidance and names no alternative. With several near-identical site-info siblings in the fleet, the omission is meaningful rather than cosmetic.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered. The sentence 'its server marks it read-only, so it runs straight away' merely restates that annotation rather than adding new behavioral context, though it does clarify that no confirmation gating occurs. Otherwise it is silent on error behavior, permission failures, or what a filtered subset omits.

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 first two sentences are front-loaded and efficient, but the trailing '(ability: core/get-user-info) Through Royally: its server marks it read-only, so it runs straight away.' is connector/marketing noise that repeats the annotations and dilutes the signal.

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 simple, zero-required-parameter read of the current user with no output schema, the description covers what is returned (profile details, all fields by default, selectable subset) and the schema enum lists the exact fields. Nothing critical is missing; only the response envelope shape is left implicit.

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% and both parameters are documented, including the enumerated field list and the site_id enum. The description's 'default returns all fields, or optionally a filtered subset' duplicates the schema's own wording on `fields` rather than adding new semantics, 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 and resource ('Returns profile details') and narrows scope to 'the current authenticated user', which clearly separates it from sibling user tools like wp_get_user and wp_list_users that operate on arbitrary users. It stops short of naming those siblings explicitly, so differentiation relies on inference.

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 framing 'to support personalization, auditing, and access-aware behavior' implies usage contexts, and 'By default returns all fields, or optionally a filtered subset' gives a selection hint. However, there is no explicit when-to-use / when-not-to-use statement or named alternative, so the agent must infer this is the right tool when the target is the caller themselves.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so 'its server marks it read-only, so it runs straight away' largely restates structured data. It does add a small amount of return-content context ('basic information'), but does not say what fields that includes or whether results are paginated.

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 purpose is good, but sentences 1 and 2 overlap, and the trailing 'Through Royally: its server marks it read-only...' is awkwardly phrased and redundant with the annotations.

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?

A simple, non-destructive, no-parameter list tool, so the burden is low. Still, with no output schema the vague phrase 'basic information' leaves the agent unsure what each ability record contains before deciding to call get_ability_info.

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?

One optional parameter with a single-value enum and 100% schema description coverage, so the schema fully documents site_id. The description adds no meaning beyond that, which is the expected baseline for full coverage.

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 ('Discover all available WordPress abilities') and says it returns the registered abilities, so the agent knows the operation. However, it never distinguishes itself from near-identical siblings such as mcp-adapter-default__mcp-adapter-discover-abilities or royal-mcp__discover_tools, which an agent in this fleet would need.

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?

There is no explicit when-to-use statement, no prerequisite, and no routing to alternatives like get_ability_info or execute_ability. Discovery-before-execution is only weakly implied by 'Returns a list of all registered abilities'.

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

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

The description's behavioural claim ('its server marks it read-only, so it runs straight away') merely restates the existing readOnlyHint annotation, warranting no credit. The parenthetical mapping to the underlying ability id 'mcp-adapter/get-ability-info' is a small piece of genuinely additive context, but error behaviour for a bad ability_name and response shape are unaddressed.

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, front-loaded with the substantive capability statement. The trailing 'Through Royally: its server marks it read-only, so it runs straight away' is packaging noise that duplicates annotation data and could be dropped without loss.

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 small read-only lookup tool with no output schema, the description does say what information comes back, which is the main gap it needs to fill. Missing only the edge case of an invalid or unavailable ability name.

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% and the ability_name parameter is documented in the schema, so the schema baseline applies. The description adds no syntax, naming-convention, or format guidance for ability_name, nor does it clarify the site_id enum scope beyond what the schema already states.

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 first sentence names a specific verb and resource ('Get detailed information about a specific WordPress ability') and enumerates the payload (input/output schema, description, usage examples), which is more than a restatement of the name. It does not, however, contrast itself with the very close sibling mcp-adapter-discover-abilities, so an agent must infer the distinction.

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 only implied: 'a specific ability' hints that you must already know an ability name, suggesting it follows a discovery step. There is no explicit statement of when to prefer this over discover_abilities, nor what happens if the ability name is unknown.

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

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

Adds real context beyond the annotations: it explains why the tool exists (the scoring engine only runs client-side, so the agent must do the analysis), and it names the non-obvious return keys (content, metadata, tests_to_run, kb_link) that the agent must use to proceed. The 'server marks it read-only, so it runs straight away' clause largely restates readOnlyHint/destructiveHint, which is mildly redundant but not harmful.

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?

Purpose is front-loaded in the first clause, and the three sentences stay dense with useful information. Minor waste in the trailing read-only sentence, which duplicates an annotation, and the embedded HTML entity is sloppy but harmless.

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?

With no output schema, the description carries the burden of explaining returns, and it does so by naming content, metadata, tests_to_run, and kb_link plus how they are consumed. Combined with the read-only/idempotent annotations, an agent has everything needed to call this and interpret the result.

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% — post_id, keyword (override semantics), and the single-value site_id enum are all documented in the schema. The description adds no parameter-level detail beyond that, so the 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 concrete verb and resource — gathers raw content, metadata, and the list of on-page SEO tests for a saved post — which is a distinct payload from siblings like get_post_seo_meta or get_seo_scores. It also explains the differentiator (client-side scoring engine) that separates it from a precomputed-scores tool, though it never names an alternative tool outright.

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 an explicit follow-on workflow: combine tests_to_run and content with kb_link (the rubric for all 24 tests) to score each test and emit a status and fix message. That is unusually actionable guidance. It stops short of an explicit exclusion (e.g. 'use get_seo_scores instead when you only need stored scores'), so not a 5.

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

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

Adds real behavioral context beyond the annotations: the audit fuses local site-wide checks with remote rankmath.com API calls (explaining the openWorldHint network dependency) and returns per-test findings with remediation hints. The line about the server marking it read-only largely restates readOnlyHint, which is the only redundancy.

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?

Three compact sentences, front-loaded with the action and return value. The trailing "Through Royally: its server marks it read-only, so it runs straight away" is slightly promotional and partly duplicates the annotations, but it is short enough not to bloat the definition.

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?

With no output schema, the description correctly compensates by describing the returned score and per-test findings. Combined with 100% parameter coverage and full annotations, an agent has enough to call this correctly; only sibling disambiguation 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?

Schema description coverage is 100%, so url/refresh/site_id are already fully documented in the schema, including the important nuance that passing a url runs only remote tests. The description adds no parameter-level detail of its own, 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 and resource ("Runs Rank Math's site-wide SEO audit") and adds the return shape (structured score plus per-test findings with fix hints). It is clear what the tool does, but it never names the nearby alternatives such as rank_math_get_seo_scores or wp_audit_seo_bulk, so the agent must infer the boundary itself.

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 description implies usage (site-wide audit, local + remote checks) but gives no explicit when-to-use / when-not guidance relative to the many SEO siblings in this fleet. The only routing hint lives in the url parameter's schema text, not in the description.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, and the description largely restates that ('its server marks it read-only, so it runs straight away'). It does add useful content information (hit counts, referer, user-agent), but says nothing about log retention, empty-log behavior, or result volume beyond the per_page cap in the schema.

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 short sentences, with the core purpose front-loaded. The ability-id parenthetical and the read-only reassurance are mostly metadata already carried by annotations, so there is minor waste.

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, fully-described five-parameter log fetch with no output schema, the description supplies the resource, the payload shape and the safety profile. Nothing essential for correct invocation 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?

Schema description coverage is 100%, so all five parameters (page, order, orderby, site_id, per_page) are already documented in the schema with defaults, enums and bounds. The description adds nothing beyond a passing mention of 'hit counts', which loosely corresponds to the orderby=hits option.

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 ('Returns the 404 error monitor log entries') and names the returned data (hit counts, referer/user-agent), which separates it from sibling log/report tools like get_redirections or wp_get_error_log. It lacks an explicit sibling differentiation statement, so a 4 rather than 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 only implied by the resource name: an agent can infer it should call this when investigating 404s. There is no explicit when-to-use, no mention of alternatives such as the redirections log or the general error log, and no prerequisites stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive; the description largely restates this ('its server marks it read-only, so it runs straight away'), adding only that execution is immediate with no approval step. It gives no additional behavioral context such as caching effects or data freshness beyond what the schema's refresh parameter already says.

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, front-loaded with the return payload, followed by a short provenance/behavioral note. No filler, though the 'Through Royally' clause is somewhat templated boilerplate.

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?

With no output schema, the description usefully enumerates the return contents (site-level summary plus brand list with scores, ranks, sentiment, status), which is exactly what an agent needs. Parameter behavior and safety are covered by annotations and the schema, so little 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?

Schema description coverage is 100%, so all three parameters (search, refresh, site_id) are already fully documented, including the cache-bypass behavior of refresh. The description adds no parameter-level meaning beyond that; the 3 baseline 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?

The description names a specific verb and resource ('Returns the site-level AI Visibility summary') and enumerates the returned fields (scores, ranks, sentiment, analysis status). It does not explicitly distinguish itself from the sibling brand_insights and brand_queries tools, so it falls 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?

The word 'overview' plus the list of aggregate fields implies this is the entry-point summary tool, and the siblings' names hint at the drill-down alternatives. However, there is no explicit statement of when to use this versus rank_math_get_ai_visibility_brand_insights or brand_queries, so guidance is only implied.

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

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

Beyond the readOnly/idempotent annotations, it discloses that several fields (broken links, redirects, nofollow counts, status distribution) are PRO-gated, which materially changes what comes back. It also notes the source is the Link Genius audit and that the server marks it read-only so it executes without confirmation. This is real added context; only the return shape for the optional per-post data is left unstated.

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 core sentence is front-loaded and information-dense, but the trailing '(ability: rank-math/get-link-report)' identifier and the 'Through Royally: its server marks it read-only, so it runs straight away' clause partly restate the annotations. Useful routing info, yet it dilutes an otherwise tight definition.

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?

With no output schema, the description usefully enumerates what the report contains and flags the PRO-only subset, which is the key completeness risk here. Parameters are fully covered by the schema. Only the response shape when include_posts=true is left implicit.

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% — both site_id and include_posts are fully documented in the schema. The description mentions 'post counts' but adds no new meaning about include_posts or the site_id enum, so the baseline 3 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?

The description states a specific verb and resource ('Returns a site-wide link health report') and enumerates the metrics returned (internal/external totals, posts without links, broken links, redirects, nofollows, HTTP status distribution). It implicitly distinguishes itself from per-post tools like rank_math_get_post_links, but never names a sibling to make the boundary explicit.

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?

There is no statement of when to use this versus alternatives such as rank_math_get_post_links, fleet__check_broken_links, or emcp-tools-find-broken-links. The reader can infer it is an aggregate/site-wide view, but no exclusions, prerequisites, or routing guidance are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, and the description's 'server marks it read-only, so it runs straight away' largely restates that. It does add useful disclosure that the response includes generated Markdown content, which is beyond the annotations, but nothing about size, freshness, or failure modes when llms.txt is disabled.

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 return-value sentence is front-loaded and earns its place. The parenthetical ability ID and the 'Through Royally...' sentence are meta-commentary of marginal value, but they are short and do not bury the essential 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?

With no output schema, the description steps up by naming the three returned fields (enabled status, URL, Markdown content). Combined with full schema coverage on the single site_id parameter and rich read-only annotations, an agent has enough to invoke it correctly; only the behavior when the file is disabled is unspecified.

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?

Only one parameter (site_id) exists and schema description coverage is 100%, with the enum value and site URL documented in the schema. The description adds nothing about the parameter, but with full schema coverage the baseline of 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?

The description names a specific resource (llms.txt) and enumerates exactly what is returned: the enabled flag, the URL, and the generated Markdown content. It is clearly distinguishable from nearby siblings like get_robots_txt or get_sitemap_status by resource, though it does not explicitly contrast itself with them.

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?

There is no guidance on when to call this versus alternatives such as rank_math_get_robots_txt or get_settings. The only hint is that it is a read that 'runs straight away,' which is behavioral, not usage-oriented. An agent must infer the intent from the resource name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds that results are paginated and that the server marks it read-only so it 'runs straight away' (execution-approval behavior), but it repeats the read-only fact already in annotations and says nothing about permissions or result limits.

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 core purpose and return fields are front-loaded in the first sentence with no fluff. The trailing ability-ID parenthetical and the 'Through Royally' sentence are secondary metadata that could be trimmed, but they are short.

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?

With no output schema, the description usefully enumerates the return shape (URL, link type, target post details for internal links) and notes pagination. Minor gap: it claims pagination but the schema exposes no page/per_page parameters, leaving an agent unsure how to paginate.

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% – both post_id and site_id are documented with descriptions and an enum – so the schema carries the parameter burden. The description adds no syntax or format detail beyond 'for a given post', making the baseline 3 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 ('Returns a paginated list of internal and external links stored for a given post') and even enumerates returned fields. The per-post scoping implicitly distinguishes it from sibling site-wide tools like rank_math_get_link_report, though no sibling is named explicitly.

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 only implied by 'for a given post' – an agent can infer this is per-post link retrieval rather than a site-wide report, but there is no explicit when-to-use guidance, no exclusion against get_link_report or check_broken_links, and no stated prerequisites.

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

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

It provides operational context by stating the tool runs 'straight away' because the server marks it read-only, adding value beyond the simple `readOnlyHint` annotation. It also documents the specific recommendation branching logic that occurs post-execution.

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 description is dense but efficient. The core purpose is front-loaded, and subsequent sentences incrementally add crucial information (workflow sequence, logic, environment) without wasted words.

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?

While there is no output schema, the tool's functional completeness is achieved through the detailed workflow and recommendation rules provided. It tells the AI exactly how to use this tool in a sequence of operations.

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?

With 100% schema coverage, the baseline is high. The description adds specific guidance on the `include_available_types` parameter, clarifying that it 'must' be true when evaluating schema recommendations.

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 tool clearly states its purpose is to retrieve schema markup attached to a post and check available schema types. It successfully differentiates itself by focusing on 'schema markup' rather than general post meta, contrasting it with siblings.

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 description provides explicit usage instructions, specifically advising agents to use it after checking `rank-math/get-post-seo-meta`. It also details complex conditional logic regarding recommendation failures and upgrade messages.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false. The description's "server marks it read-only, so it runs straight away" largely restates the read-only annotation, though it usefully adds that no approval step intervenes. Nothing is said about what happens when post_id does not exist or lacks SEO meta.

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, front-loaded with the return payload so an agent immediately sees scope. The trailing parenthetical ability name and the read-only remark are mildly redundant with the tool name and annotations but not wasteful enough to hurt.

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?

With no output schema, the field enumeration (title, description, focus keyword, robots, canonical, OG/Twitter overrides, score) is exactly the information an agent needs to know what comes back. Only the empty/missing-meta case and the site_id scoping are left uncovered.

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% and both parameters (post_id, site_id with a single-value enum) are documented in the schema, so the baseline is 3. The description adds nothing about the post_id meaning beyond "for a post" and never mentions site_id.

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 ("Returns the full SEO metadata for a post") and then enumerates the concrete fields returned, which clearly separates it from generic meta readers like wp_get_post_meta. It never names a sibling tool as an alternative, so differentiation is implied rather than explicit.

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?

There is no when-to-use vs when-not-to-use guidance and no mention of alternatives such as wp_get_seo_meta, rank_math_get_seo_scores, or rank_math_get_post_schema. The only contextual cue is "for a post," which leaves the routing decision to inference.

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