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

The description goes well beyond the annotations by disclosing that activation runs the plugin's code immediately and can fatal the site if incompatible with the current WordPress/PHP version. This is significant behavioral risk context that an agent would not otherwise know. No contradiction with 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?

The description is compact and front-loaded: it states the purpose first, then adds the critical risk warning in a single follow-up sentence. There is no redundancy or 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 simple three-parameter activation tool with no output schema or nested objects, the description covers the purpose, the installed-plugin precondition, the main risk, and a mitigation strategy. Nothing essential is missing for correct invocation.

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 each parameter already has a clear description in the schema. The free-text description adds no parameter-specific semantics beyond the schema, so the baseline of 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: 'Activate an installed plugin.' It clearly scopes the operation to already-installed plugins, which distinguishes it from install/delete/deactivate siblings. The title and description align without being tautological.

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 clear context: the tool targets installed plugins and should be used with caution. The warning to prefer testing on staging first provides actionable guidance for when to proceed. It does not explicitly name alternatives like install_plugin or deactivate_plugin, 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?

Annotations flag readOnlyHint=false and destructiveHint=true, but the description adds that the change is immediate, affects all visitors, and that widget/menu assignments may not carry over. It also explains the confirm requirement, which is beyond the annotation. Minor gap: doesn't state reversibility or how to revert, but the destructive nature is well 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?

Three sentences, each informative: the core action/effect, the caveat about widget/menu assignments, and the alternative workflow. No fluff, everything 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?

Given the tool's complexity (a destructive action with a confirm flag) and with no output schema, the description adequately covers the key behavioral caveats, the confirm requirement, and the alternative. A small gap: no mention of failure modes or how to revert, but the description is sufficient for an agent to select and 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?

Schema already has 100% coverage for all parameters: stylesheet is described as 'theme directory name', confirm as 'Required — this changes the live site's appearance', and site_id explains optionality and default behavior. The description mentions confirm explicitly but doesn't add extra meaning beyond the schema; 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 clear action ('Switch the site's active theme') and its immediate effect ('changes the entire front-end appearance immediately'), which distinguishes it from theme management siblings like install_theme or list_themes. It also contrasts with the draft workflow.

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 tells the agent when to use it (activating an existing theme) and when not to (when iterating on a theme being built), explicitly suggesting publish_draft_theme instead. This is strong 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 signal a non-read, non-destructive, non-idempotent mutation, and the description adds useful behavioral detail about supported link types and how parent and menu_order affect the item. It does not contradict the annotations and provides adequate transparency for a creation action.

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 two well-organized sentences that front-load the core action and then cover link target types plus nesting/positioning. Every sentence earns its place 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 14-parameter mutation tool, the description plus a fully documented schema covers the key decisions: what the item can link to, required parameters, and how to nest or order the item. It does not explain return values or behavior on an invalid menu_id, but those are minor gaps given the absence of an output schema and the completeness of the input schema.

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 parameters are already documented in the input schema. The description adds a useful mental model for object_id/object pairing and calls out parent and menu_order, but it does not provide substantive 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?

The description states a specific action ('Add an entry to a navigation menu') and clearly identifies the resource being modified. It also distinguishes this from sibling tools like update_menu_item, delete_menu_item, and reorder_menu_items by focusing on creation and listing the supported link target types.

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 clear context for when to use the tool: adding a new menu item that can point to a post, term, or URL, with optional nesting and ordering. It does not explicitly name alternatives like update_menu_item or delete_menu_item, but the create-oriented wording and target coverage make the intended usage reasonably clear.

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 (readOnlyHint=true, destructiveHint=false), the description reveals important behavior: it returns a structured summary with capped text, includes only notices/forms/links, and authenticates server-side with a single-use token so no cookie reaches the client. This adds meaningful context about how the tool operates.

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 every sentence earns its place: it explains what the tool returns, gives usage context, and discloses the auth mechanism, all front-loaded with the key distinction from raw HTML. No filler or redundant 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?

For a read-only screen inspection tool with a well-described schema and no output schema, the description provides all necessary context: what fields come back, how to address a screen, why this tool exists, and how auth works. Nothing critical 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?

The input schema already documents both parameters fully (100% coverage) and even includes examples for url_or_page. The description reinforces this with concrete URL examples, but adds no new parameter-level meaning 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 description uses a specific verb ('View'), names the resource ('wp-admin screen'), and clearly states the output is structured data rather than raw HTML. It gives concrete examples like 'admin.php?page=wpseo_titles', which sets it apart from get_page_html and other sibling 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?

The description explicitly states when to use this tool: to read a plugin's settings screen that has no REST route. It also implies the alternative of raw HTML by contrasting 'structure rather than raw HTML', though it does not name the specific sibling tool (get_page_html) or mention cases where this tool should not be used.

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?

Whereas the annotations only signal readOnlyHint=false and destructiveHint=true, the description discloses exactly what is destructive — a full variation 'replaces the user's global-styles customisations' — and reveals the safety valve: state is preserved as a global-styles revision and the endpoint to undo is given. The dry-run/diff behavior without confirm_token is also explicitly spelled out, which is substantial context beyond the 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 four sentences are front-loaded with the core action and then cover dry-run behavior, mutation semantics, and undo path — each earns its place and the ordering is logical. It is somewhat dense with parenthetical asides, but nothing is wasted or repetitive relative to the 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?

For a destructive mutating tool with no output schema, the description covers the full call lifecycle: preview and diff output, commit via confirm_token, replace-vs-merge behavior, and precisely how to undo via revisions. Given the tool's complexity and its destinations, nothing an agent needs to invoke it correctly or safely 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%, and each parameter is already well documented in the schema (enums, defaults, source from list_style_variations, confirm-token semantics). The description does usefully tie kind and mode to real side effects (full replaces vs partial merges), but that relationship mostly duplicates the schema's auto-mode explanation, so it does not add much beyond the documented baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb plus resource ('apply one of the active theme's style variations to the site's global styles') and grounds it in a familiar UI action ('what choosing it in Site Editor → Styles does'), so an agent immediately understands the purpose. It is also easy to distinguish from siblings like get_global_styles, update_global_styles, diff_global_styles, and list_style_variations because it names the precise action and the input source.

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 clear, actionable usage conditions: omit confirm_token for a dry-run preview and include it to commit; it also explains how the tool behaves depending on kind (full replaces, partial merges). It does not explicitly name when-not-to-use alternatives such as update_global_styles or diff_global_styles, but the Site Editor analogy and the dry-run/confirm contract give a strong practical usage frame.

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 reveals that the default mode 'replaces the item's terms' and that 'remove' detaches terms, both of which are destructive actions. However, the annotations declare destructiveHint: false, which contradicts the described behavior. Per the rubric, a description that contradicts annotations receives a 1.

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 two sentences, front-loads the main action, and includes the most important behavioral nuance (default replace) without any filler. Every sentence adds value.

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 core operation and mode semantics, but with no output schema and 7 parameters, it omits information about return values and potential side effects beyond the annotation conflict. It is adequate but not fully complete for a tool with this complexity.

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 description restates what the schema already says about modes and term creation (e.g., 'names that do not exist are created for you') without adding new parameter-level 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?

The description states a specific action ('Assign taxonomy terms to any content item') with a clear resource and additional detail about modes. It clearly distinguishes from sibling tools like get_content_terms (which retrieves) and create_term (which creates standalone terms).

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 when to use different modes (replace, add, remove) and mentions auto-creation of unknown names. It does not explicitly name alternatives like create_term or get_content_terms, but the mode guidance gives strong practical usage context.

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 and destructiveHint=false, and the description reinforces these with 'Read-only' without contradicting them. It adds value beyond annotations by disclosing that the tool reports both the issues and the entity IDs, which is useful behavioral information given there is no output schema. It does not mention potential performance costs of sweeping large content sets, but the schema's limit parameter covers that partially.

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 no filler: the first states the action and output scope, the second clarifies the read-only nature and the downstream fix path. The checklist of issues is long but each item is specific and 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 description does important work by naming the output shape (issues plus IDs) and linking to corrective tools. It could go further by stating the exact response structure or warning about timeouts on large sweeps, but given the schema covers all inputs and the annotations cover safety, the description is adequately 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 description coverage is 100%, and every parameter—type, limit, status, site_id, thin_content_words—already has a clear, meaningful description. The tool description adds no parameter-specific detail beyond what the schema provides, 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?

The description uses a specific verb ('Sweep') with a clear resource ('a content type') and enumerates the exact problem categories reported, so the tool's function is unmistakable. This distinguishes it from siblings like list_content, audit_media, or update_content by focusing on quality auditing rather than listing, media-specific checks, or modification.

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 explicitly frames the tool as a read-only diagnostic step and names the follow-up tools (bulk_update_content or update_content) for fixing the issues it finds, which gives an agent a clear workflow. It does not explicitly contrast with other audit-style siblings like audit_media or check_links, but the problem list is specific enough to imply when it applies.

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 discloses the specific behavior: checking for missing alt text and unreferenced attachments, consistent with readOnlyHint=true and destructiveHint=false. It adds detail beyond the annotations by naming the exact findings, though it does not describe the result format or potential performance impact beyond the schema note on check_unused.

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 no waste: the first states the action and scope, the second gives the rationale. The core behavior is front-loaded and every sentence 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?

Given the read-only annotations and fully described parameters, the tool is callable as-is. The main gaps are the lack of an output description and no explicit routing against check_accessibility, but these are not blocking for a simple read-only audit.

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 parameter already has a meaningful description including defaults and trade-offs (e.g., check_unused is slower). The main description adds no parameter semantics, 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?

The description names a specific verb and resource ('Audit the media library') and enumerates two concrete checks: images missing alt text and attachments not referenced by any content. This clearly separates it from retrieval siblings like list_media and get_media by its analytic intent.

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 practical rationale for running the audit (accessibility value and disk usage), but it never names alternatives or states when not to use it. The agent must infer that list_media is for retrieval and that check_accessibility may overlap on the alt-text dimension.

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 establish read-only, non-destructive behavior. The description adds meaningful context beyond the annotations: host-level backups are invisible to WordPress and are flagged as unknown, and the tool 'Needs the companion plugin.' It clearly discloses limitations and prerequisites.

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 efficiently structured: the main purpose is front-loaded, followed by usage timing, a host-level caveat, and a dependency note. Every sentence adds value, and the plugin list is compact and relevant.

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 status tool with one optional parameter and no output schema, the description covers the report scope, warning conditions, operational context, and a known limitation. The only small gap is that 'Needs the companion plugin' is slightly vague, and the exact output shape is not described, but the report semantics are clear enough.

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 input schema has 100% coverage for the single optional parameter, site_id, with a clear description. The tool description does not add any additional parameter detail, but the schema already fully explains the parameter. 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 uses a specific verb ('Report') with a clear resource: the site's backup plugin and last completed backup. It even enumerates the recognized plugins and the warning behavior, making the tool's function unambiguous. It is easily distinguished from all sibling tools, none of which cover backup status.

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 explicitly says when to run the tool: 'Run this before any risky change — updates, theme publishes, search-replace, bulk deletes.' This is strong situational guidance. It doesn't explicitly state when not to use it or name alternative tools, but no backup-status alternative exists among the 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?

It discloses a critical two-step behavior: the initial call returns a confirm_token and nothing is written without it. This goes beyond the annotations (readOnlyHint=false, destructiveHint=false) by explaining the actual write gate. It also notes that items with no matches are skipped, which is useful 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 sentences, front-loaded with the core purpose and then the critical preview/confirm requirement. No filler or redundant wording.

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?

Given the complexity (7 params, nested objects, no output schema), the description covers the essential flow (preview → confirm token → apply) and mentions skipping non-matching items. It does not describe the return format, but since no output schema exists, the description could have said more; however, the critical usage constraints are present.

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 description provides a high-level summary of the change types (status, author, category, find/replace) but does not add specific parameter details beyond what the schema already documents. It adds no new semantic meaning for 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 description clearly states the tool's purpose: applying the same change to many items at once, and enumerates concrete operations (set status, reassign author, add category, find/replace). It distinguishes itself from single-item tools like update_content by emphasizing 'many items at once'.

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 the use case (bulk vs. single) and explicitly outlines the required preview-confirm flow. However, it does not name alternative tools for single-item edits or state when not to use it, though the context is clear enough for an agent.

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 mark it read-only and non-destructive, and the description adds a substantial amount beyond that: it does not run JavaScript or compute CSS, it is deterministic, and every issue includes a WCAG reference, severity, snippet, and fix. This is especially valuable because there is no output schema to document the return shape.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The definition is front-loaded with the core action and then lists the checks and limitations in one dense paragraph. The exhaustive rule list and issue-format details all earn their place, though the single paragraph could be more scannable with bullets or separation between purpose, checks, output, and limitations.

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 tool with no output schema and a complex rule set, the description is complete: it covers what it checks, what each issue contains, what it cannot do, and how it relates to preview URLs and browser audits. An agent has enough context to invoke it correctly and interpret results.

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 five parameters, including preview-token and rules semantics. The description does not add parameter-level meaning beyond what the schema provides, but it does not need to; 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 opens with a specific verb and resource: 'Fetch a page on the configured site and run deterministic accessibility checks on its server-rendered HTML.' It enumerates the exact rule set and explicitly positions the tool as a complement to browser audits, so an agent can distinguish it from generic audit or validation 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?

It gives clear context for when to use the tool: server-rendered HTML, draft-theme preview URLs from get_preview_url, and situations where a full browser audit is unnecessary or out of scope. It does not, however, explicitly name sibling alternatives or state 'use this instead of X', so it stops short of full when-to-use/when-not-to-use 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=true and destructiveHint=false, so the agent knows this is a safe read operation. The description goes well beyond annotations by revealing several non-obvious behavioral traits: internal-only default with opt-in external checks, automatic skipping of private/loopback/link-local hosts, bounded concurrency, per-call link cap, the cost implication ('each checked link costs 1–2 outbound requests, which matters on Cloudflare Workers'), and the cursor-based continuation mechanism. These are exactly the kind of behavioral details an agent cannot infer from annotations or schema 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?

The description is dense but efficiently organized: it front-loads the core function ('Find broken links and images in rendered content'), lists the failure categories, states the three scan modes, clarifies the default scope and opt-in external behavior, and ends with the crucial pagination/concurrency caveat. Every sentence earns its place. No filler or tautology. The structure moves from 'what' to 'how' to 'when to know you're not done', which is ideal for an agent deciding whether and how to call 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?

Despite having 12 parameters and no output schema, the description answers the key questions an agent would have: what to pass to scope the scan, how pagination works, what the cost/limit behavior is, and what safety restrictions apply. The absence of an output schema means the description doesn't need to explain return values, but the description still tells the agent enough about the response shape ('follow next_cursor for the rest') for correct usage. It also mentions the `next_cursor` field by name, signaling what the response contains. This is complete for a read-only scanning tool of this complexity.

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 parameter's meaning. The description adds context around the parameters (e.g., that 'a content type' corresponds to the `type` param and that 'one front-end URL' corresponds to `url`), and it explains the relationship between `ids`, `type`, `url`, `limit`, `status`, and `cursor`. However, most of the per-parameter semantic weight is already in the schema, so the description's added value is contextual rather than definitional. Baseline 3 is appropriate for full schema coverage; the description provides some context but doesn't add deep parameter nuances 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?

The description clearly identifies the tool's purpose: finding broken links and images in rendered content, and enumerates specific categories of failures (4xx/5xx, network failures, redirect chains, mixed content, links to draft/trashed/missing content). It also specifies scan targets ('given ids, a content type, or one front-end URL'), which distinguishes it from sibling tools like check_accessibility or internal_link_report. It uses a precise verb ('find broken links and images') and resource ('rendered content'), so an agent can tell it apart 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 description explicitly states what it scans ('given ids, a content type, or one front-end URL'), explains the default scope ('internal links only by default; external checks are opt-in'), and flags the important constraint that external checks 'never reach private or loopback addresses'. It also implies when to use it versus alternatives like check_accessibility, internal_link_report, or seo_site_check, all of which are sibling tools with related but different functions. The 'Scans given ids, a content type, or one front-end URL' sentence serves as a clear usage condition. It also explains the pagination pattern ('follow next_cursor for the rest'), which is essential for correct use on large scans.

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 only indicate destructiveHint=true; the description goes far beyond by disclosing the dry-run preview with confirm_token, the exact return contents (what would change, bytes saved, refusals), the permanent refusal of core WordPress options, and the risk that deleting an option resets a plugin's settings. This is exactly the behavioral context an agent needs to safely invoke a destructive 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?

The description is dense but not bloated; every sentence carries operational weight. It front-loads the three modes, then the two-step process, then limitations and risks. The only slight deduction is for the density – a reader must parse carefully – but there is 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?

Given there is no output schema, the description compensates by specifying exactly what the dry run returns (what would change, bytes saved, refused items, confirm_token). It also covers prerequisite dependencies (companion plugin), safety constraints (core options refused), and the downstream risk of plugin settings. For a destructive, multi-mode tool, this is comprehensive.

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 value: it tells the agent that names must be 'exactly as listed by inspect_options', explains that confirm_token comes from the dry-run preview, and clarifies that names is ignored for delete_expired_transients (matching the schema but reinforcing it). It also defines the three action modes in user-oriented terms beyond the raw enum.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ('Reduce options-table weight') and then enumerates the three distinct actions (delete_expired_transients, set_autoload_off, delete_options), each with a brief explanation. This clearly distinguishes the tool from siblings like get_options, set_option, or inspect_options, which deal with reading/writing individual options rather than bulk cleanup.

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 strong usage context: it explains the mandatory two-step dry-run/apply flow, warns to 'check owners in inspect_options first' before deleting, and notes the dependency on the companion plugin. It also declares that core/lock-out options are refused, setting expectations. It doesn't explicitly name alternative tools for the same purpose (e.g., when to use purge_cache instead), which prevents a 5, but the guidance 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?

The description adds important behavioral details beyond the annotations: new snippets are always created DISABLED and must be activated in wp-admin after reading the code, and PHP snippets are syntax-checked before saving so parse errors are reported rather than fatalling the site. This is critical safety context not present in the schema or 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?

The description is concise and front-loaded: it states the core value proposition first, then covers the two most important behavioral safety details. No filler or repetition of schema 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 multi-action tool with no output schema, the description thoroughly covers creation behavior and safety. It does not describe list/get/update/delete behavior or return values, but the schema plus the disabled-by-default and syntax-check notes make the tool safely callable for its primary purpose.

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 parameters are already documented in the schema. The description adds context about creation workflow (disabled by default, syntax-checked) but does not add new per-parameter semantics beyond what the schema already provides.

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 clearly states what the tool does: add PHP, CSS, or JavaScript as managed snippets rather than editing theme files. It also names the specific benefit—surviving theme updates and being switchable without touching code—which differentiates it from related theme-file 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?

The description gives clear context for when to use this tool: when you want managed snippets instead of editing theme files, with the advantage of surviving updates. It does not enumerate when not to use it or compare it to plugin creation explicitly, but the primary use case is well specified.

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 and destructiveHint=false, so the agent knows it is safe. The description adds valuable behavioral context: it reports grouped-by-week data, past cadence, stale drafts, and gaps. This goes beyond the annotations and clarifies the analytical nature of the tool without contradicting them.

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 core purpose and then the reporting dimensions. No redundant phrases or 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?

For a read-only view tool with no output schema, it sufficiently describes the major output categories (scheduled, cadence, stale, gaps). It does not specify the exact data structure or how results are presented (e.g., per-week breakdown vs totals), but given the tool's nature and the lack of output schema, it is reasonably complete. Slightly more detail on return format would push it to 5.

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 all parameters have individual descriptions. The description adds meaning by explaining how the parameters relate to the output (e.g., 'gaps against a target posts-per-week' ties to target_per_week, 'stale drafts not touched in N days' ties to stale_draft_days). It integrates the parameters into a coherent narrative, adding value over the schema alone.

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 ('grouped by ISO week'), resource ('content calendar'), and scope ('scheduled future content', 'publishing cadence', 'stale drafts', 'gaps'). Clearly distinguishable from individual content tools like list_content or get_content, as it is an aggregate view.

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?

Provides a clear context: 'Useful for content teams planning what to publish next.' This implies it is for high-level planning rather than individual item operations, but it does not explicitly name alternative tools or state when NOT to use it. The context is present but lacks explicit exclusions.

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 establish read-only, non-destructive behavior, so the description correctly adds value by disclosing output shape ('one row per item' with a detailed field list), format options (JSON/CSV), field selection, and cursor pagination. It also notes the conditional Yoast SEO field exposure. This goes beyond the annotations without contradicting them.

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 two sentences, front-loaded with the primary action ('Export a content inventory'), and every clause earns its place. It packs the output contract, formats, pagination, and use cases without redundancy or fluff.

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 export tool with 7 fully documented optional parameters and no output schema, the description covers the essential behavioral context: row contents, formats, pagination, and purpose. It does not detail edge cases like empty results or cursor chaining, but those are already addressed by the schema, and the description is sufficient for an agent to call the tool 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%, and the schema already documents each parameter (types, cursor, fields, format, status, site_id, per_page) with meaningful detail. The description adds a high-level summary (e.g., 'field selection and cursor pagination') but no additional parameter-level semantics beyond what the schema provides. 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 clearly states a specific verb ('Export') and resource ('content inventory'), enumerates the exact fields included in each row, and names the output formats (JSON/CSV). It also distinguishes this tool from sibling content tools by conveying a bulk-export/audit purpose, unlike list_content or get_content which have different scopes.

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 clear context: 'for content audits, migrations and spreadsheets' implies when an agent would reach for this tool — when a comprehensive, exportable snapshot is needed. It does not explicitly name alternatives or state when not to use it, but the use-case framing provides strong implied guidance without exclusions.

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 generic annotations (readOnly=false, destructive=false), the description discloses that the theme is created as a draft and enumerates the exact files generated, including style.css, functions.php, templates, theme.css, and Tailwind CDN setup. It does not mention return values or post-creation publication steps, but the safety profile is already covered by 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?

The description is dense and well-structured: a one-sentence summary, a brief rationale, then a concrete list of generated files. Every sentence earns its place with no filler or repetition.

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 what the tool creates and the draft nature, but with no output schema it does not explain what the tool returns or how to follow up (e.g., publishing or activating the draft). The rich input schema compensates for invocation clarity, but the missing return/post-condition information leaves a gap for chaining 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?

Schema coverage is 100%, and every parameter including the nested token object has individual descriptions. The tool description itself only adds the context that tokens are written into theme.css as CSS custom properties, which is useful but not necessary for understanding the 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 description opens with a specific verb and resource: 'Scaffold a complete classic PHP theme styled with Tailwind, as a draft.' It clearly differentiates this from block-based theme creation by emphasizing classic templates with utility classes versus nested block markup, which is useful against siblings like create_draft_theme.

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 clear context for when to choose classic templates over block markup, calling the output 'readable, diffable and predictable.' It does not explicitly name alternative sibling tools such as create_draft_theme or state when not to use this tool, so it falls just 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?

Annotations only indicate non-read-only and non-destructive; the description adds the moderation workflow (approve vs queue) and the permission requirement for approve. This goes beyond what annotations and schema already say, providing useful behavioral 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 sentences, front-loaded with the main action and threading option, then the moderation nuance. No redundant text.

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 creation tool with a well-documented schema, the description captures the essential purpose and the critical moderation behavior. It omits some prerequisites (comment_status must be open) but those are in the schema.

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 covers all parameters at 100%, so description adds limited extra meaning. It clarifies the effect of the status parameter ('approve' publishes immediately) which is a slight addition to the schema's description, but not substantial.

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 'Post a comment on a content item' with a specific verb and resource, plus the optional threading nuance. Clearly distinguishes from sibling tools like update_comment, delete_comment, and moderate_comments by focusing on creation.

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?

Implicitly indicates usage for creating comments, but does not explicitly mention when to use it vs alternatives like update_comment or moderate_comments. The moderation queue mention hints at post-creation behavior but not explicit routing.

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 discloses critical behavior beyond annotations: content defaults to DRAFT, this server never publishes implicitly, scheduling requires status 'future' with a future date, and taxonomy terms are created if missing. These safety-relevant details are not visible in annotations and add real 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 tightly written sentences, front-loaded with purpose and immediately followed by the most important behavioral guardrails. No filler or redundant restatement of the 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?

For a 20-parameter tool, the schema already provides exhaustive parameter descriptions, so the description only needs to carry the behavioral and safety context. It covers the default draft state, publishing guardrail, scheduling requirement, and taxonomy auto-creation, which is enough for an agent to invoke the tool 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%, so the baseline is 3. The description adds meaning beyond the schema by specifying the default status behavior (DRAFT unless 'publish' is explicit) and by clarifying how taxonomy terms behave when missing. Most parameter details are already in the schema, but the added defaults are valuable.

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: create a post, page, or custom post type. It clearly distinguishes itself from sibling tools like update_content, delete_content, create_comment, and create_media by stating exactly what kind of entity it creates.

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 makes the core use case obvious: create new content. It does not explicitly list when-not-to-use or name alternatives, but the context is clear enough for an agent to select this tool over update/delete or media/comment creation. It could be stronger with an explicit pointer to update_content for edits.

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 indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true. The description adds the key behavioral detail that the draft is isolated and doesn't touch the live site, and that publishing backs up the previous theme. This context is valuable beyond the annotations and helps the agent understand the safety of the operation.

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 three sentences, each earning its place. It is front-loaded with the core purpose, then explains the workflow, and ends with a critical parameter nuance. No fluff, highly efficient.

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?

Given the tool's simplicity (3 params, none required) and the rich annotations, the description fully covers what an agent needs to call it correctly. It explains the purpose, the isolation, the workflow steps, and the default behavior for the optional parameter. No output schema is needed as the tool's return value is likely a draft identifier or status, not critical for invocation.

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 documents all parameters. The description adds semantics: it names the key parameter `from_theme` and explains that omitting it clones the active theme. This goes beyond the schema's 'Stylesheet to clone. Defaults to the active theme.' by clarifying the default behavior in context. The description also contextualizes the workflow around these 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 description clearly states the verb (Clone) and resource (installed theme into an isolated draft copy), and differentiates from siblings like publish_draft_theme and list_draft_themes. It explicitly positions this tool within the draft workflow.

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 explicitly states when to use this tool: 'Every theme edit should go through a draft', and provides a clear workflow: write files, preview, then publish. It also mentions the alternative publish_draft_theme with the backup behavior. This is excellent 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 indicate readOnlyHint=false, so the description rightly implies mutation. It goes beyond annotations by disclosing that WordPress runs its image pipeline and generates thumbnail sizes, and that the tool downloads URLs before uploading. The description also states the requirement for alt_text, which is a behavioral expectation beyond the schema. Given the annotations are minimal (just non-read-only), the description adds good behavioral context, though it could mention response or error 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?

The description is a compact two-sentence block that front-loads the core purpose and sources, then adds the alt_text guideline. The only minor inefficiency is a bit of parenthetical detail that could be trimmed, but overall it's appropriately sized for a complex multi-source 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?

Given the tool has 13 parameters all documented in the schema Michel, the description effectively focuses on the non-obvious aspects: source selection, local vs. remote paths, and the alt_text requirement. It compensates for the lack of an output schema by clarifying the upload process (download then upload, thumbnail generation). The description is complete for an agent to decide when and how to use 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 100%, so per guidelines baseline is 3. The description adds value by explaining how file_path relates to the local machine, and that base64_data requires filename. It also explains the relationship between sources (mutually exclusive) and that alt_text is required for accessibility. This exceeds baseline by adding clarifications that are not in the schema, hence 4.

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 clearly states the verb 'Upload' and the resource 'media library', and enumerates three distinct sources with precise names (file_path, url, base64_data). It distinguishes this from sibling tools like update_media/edit_media by focusing on creation, and even explains the meaning of file_path in the context of the local machine, which is a common source of confusion.

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 explicitly explains the three input sources and when to use each: file_path for local screenshots, url for remote downloads, and base64_data for raw data. It also adds a critical guideline: 'Always set alt_text for images' with rationale, which is actionable usage guidance not present in the schema. The description implicitly covers exclusions like local-network URLs being refused, guiding the agent away from invalid input.

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 indicate this is a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds behavioral nuance by specifying that the menu is created 'empty' and that it does not add entries itself—this is beyond what the annotations convey. It also mentions the optional assignment to theme locations. No contradictions with 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?

The description is a single, well-structured sentence that front-loads the core action ('Create an empty navigation menu') and then adds the optional detail and the follow-up workflow. Every clause earns its place; there is 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 simple creation tool with 5 parameters (1 required), no output schema, and no nested objects, the description is nearly complete. It covers the purpose, the optional locations behavior, and the next step. It lacks explicit notes about error handling or failure modes, but those are not typically required for a creation operation. The only minor gap is not mentioning that updating an existing menu is handled by a different tool, but that is not essential for correct invocation.

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 each parameter is already documented. The description adds minimal extra meaning—it mentions the optional locations assignment and that entries are added later, which indirectly clarifies that there is no items parameter. However, it does not add significant cross-parameter semantics beyond what the schema provides, so it stays at the baseline of 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?

The description states a specific verb ('create') and resource ('empty navigation menu'), and explicitly notes that it optionally assigns theme locations. It distinguishes itself from add_menu_item by clarifying that entries are added afterwards, so an agent can tell it apart from the sibling tools 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 description gives clear usage context: it is for creating a new menu, and it points to the natural next step ('Add entries afterwards with add_menu_item'). It does not explicitly name alternatives like update_menu or delete_menu, but the workflow implication is sufficient for an agent to know when to use this tool. It could be more explicit about when not to use it, but it is not misleading.

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 mark this as non-read-only and non-destructive, and the description adds the key behavior of downloading/installing from WordPress.org. It does not disclose side effects like filesystem changes, network requirements, or non-idempotence, but it does not contradict annotations either. This is adequate but not rich behavioral 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 short sentences, both purposeful: the first states the operation and source, the second preempts naming confusion with install_plugin. No filler or redundant schema repetition.

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 3-parameter tool with full schema coverage and no output schema, the description plus schema is sufficient to call the tool correctly. It clearly identifies the operation and source, and the schema handles parameter details. It could mention expected return values, but that is not essential for invoking the install.

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 slug, status, and site_id are fully documented in the input schema. The description itself adds no parameter-level detail beyond stating the operation, 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?

The description names a specific verb ('Install'), a resource ('plugin'), and a source ('WordPress.org repository'), and immediately clarifies that it is the same operation as install_plugin. This makes the tool's function unmistakable and distinguishes it from plugin deletion, activation, or searching.

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 clear context: use this tool to install plugins from WordPress.org, and notes that install_plugin is the clearer equivalent name. It does not explicitly state when not to use it or contrast it with alternatives like activate_plugin or delete_plugin, but the alias explanation prevents confusion with the similarly named install_plugin sibling.

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 indicate this is a non-read-only, non-idempotent, non-destructive operation. The description adds valuable behavioral context: it warns that WordPress rejects duplicates, which is a key behavior. It also implicitly notes that list_terms is a safer alternative for reading. This goes beyond annotations to inform the agent of a non-obvious behavior (rejection on duplicate) that affects decision-making.

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 two sentences: the first states the core purpose, and the second provides critical pre-call guidance. It is front-loaded with the primary verb and resource, then adds a caution. It is concise with no fluff, but could be slightly more structured (e.g., separate 'When to use' from 'What it does'), but the current structure is efficient and informative.

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?

Given the tool's moderate complexity (7 params, 1 required), the schema covers all parameters, and the description adds the critical duplicate-rejection context. The annotations cover read/write characteristics. The description is sufficient for an agent to call the tool correctly, including the need to pre-check for duplicates. It is complete for the intended use.

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% for parameters, so the schema already documents each parameter. However, the description adds important semantic context for the 'name' parameter by highlighting the uniqueness constraint, which affects how the 'name' parameter should be chosen. It also mentions the 'parent' parameter's restriction to hierarchical taxonomies (in the schema) but the description reinforces the overall creation context. The description goes beyond schema by explaining the duplicate-rejection behavior that depends on the 'name' value.

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 clearly states the action ('Create a term') and the resource ('in any taxonomy'), with an explicit caveat about duplicate names. It distinguishes itself from sibling tools by naming the alternative (list_terms) and the condition for using it, which helps an agent identify when to use create_term versus searching first.

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 explicitly states when to use this tool ('search with list_terms first when you might be duplicating') and implies the alternative tool (list_terms). This gives clear usage guidance, including a caution about potential rejection. This is a strong example of when-to-use 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?

The description adds significant behavioral context beyond the annotations: it discloses permission requirements and warns that the 'administrator' role grants full site control including plugin and theme installation. Annotations already establish non-readonly and non-idempotent behavior, so the extra role-security warning is valuable.

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 with no filler. The core purpose is front-loaded, followed immediately by the most important prerequisite and safety warning.

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 create operation with 11 parameters and no output schema, the description covers the key prerequisite and security implications. The remaining parameter details are fully present in the schema, so nothing critical is missing for correct invocation.

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 description adds meaningful meaning to the roles parameter by explaining the risk of 'administrator' and advising deliberate selection, which is not in the schema's generic role-slug description.

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 'Create a WordPress user' with a specific verb and resource. It clearly differentiates from sibling tools like update_user, delete_user, and list_users.

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 provides a clear prerequisite ('Requires an Administrator account') and vital selection guidance for the roles parameter. It does not explicitly name alternatives or when-not-to-use, but the context is strong enough for an agent to know when to invoke 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=false, idempotentHint=false, and destructiveHint=false, so the mutation profile is known. The description adds genuinely useful behavioral context about how block widgets store markup in instance.content, which is beyond the schema. It does not disclose side effects, auth needs, or error behavior, but the annotation coverage lowers the bar and the added block-widget note earns some credit.

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 with no filler. The core action is front-loaded, and the second sentence adds the one non-obvious detail (block widget storage) that an agent needs to invoke the tool correctly. Every word 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?

Given five parameters, a nested instance object, and no output schema, the description covers the trickiest part — how block widgets store content — while the schema covers parameter formats and references list_sidebars and list_sites. It does not mention return values or failure modes, but annotations and schema carry enough of the safety and parameter burden to make the description reasonably complete for selecting and invoking 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 description coverage is 100%, so the schema already documents all five parameters thoroughly, including the block widget instance.content example. The description reinforces the id_base options and block-widget content requirement, but adds little meaning that is not already in the schema. This matches the baseline 3 for high 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 description opens with a specific verb and resource: 'Add a widget to a sidebar.' It clearly distinguishes this create operation from sibling update_widget and delete_widget, and it adds useful type context via id_base examples. An agent can immediately tell what the tool does and that it creates, not modifies or removes.

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 by the verb 'Add' — use this when creating a new widget. However, the description does not explicitly state when to prefer this over update_widget or delete_widget, nor does it mention any prerequisites or exclusions. It relies on the reader inferring the create-vs-update distinction from the tool name and 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?

Annotations indicate readOnlyHint=false and destructiveHint=false, which already tell the agent this is a mutating but non-destructive action. The description adds useful context: features cease immediately, settings/data are 'normally' retained, and it acknowledges possible exceptions with the word 'normally'. This goes beyond the annotations without contradicting them.

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 states the action, the target, and the key behavioral outcome with no filler. Every clause earns its place, and the caveat 'normally retained' is valuable precision.

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 fully documented parameters and a clear statement of immediate and long-term effects, an agent has enough to invoke the tool correctly. Minor omissions such as reversibility or permission requirements are acceptable given the annotations and simple two-parameter schema.

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 description coverage is 100%, thoroughly documenting the plugin identifier with an example and the site_id behavior including the default-site logic. The description itself adds no parameter-specific detail, so the baseline of 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 uses the specific verb 'Deactivate' with the resource 'active plugin', which clearly states the operation. It also names the immediate effect (features stop working) and the non-destructive consequence (settings/data retained), distinguishing it from delete_plugin and activate_plugin.

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 'active plugin' implies the precondition that the plugin must be active, and the retained-data note hints at a non-destructive alternative to deletion. However, it does not explicitly name alternatives or provide clear when-not-to-use guidance, leaving usage largely 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 destructiveHint=true, and the description adds crucial nuance: deletion goes to trash by default and is recoverable, while force: true makes it permanent and requires confirm: true. This gives the agent the exact behavioral profile needed 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?

Two sentences with no filler. The core action is stated first, and the critical trash-vs-permanent caveat is placed immediately after.

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 mutation tool, the description covers the main safety distinction and the confirm requirement, while the schema handles parameter details. It does not describe return values, but no output schema exists and this is a standard deletion operation, so the gap is minor.

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 all parameters. The description restates the force/confirm relationship but adds no new meaning about id or site_id beyond what the schema provides.

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?

Description states the specific verb 'Delete' and resource 'a comment', leaving no ambiguity about the target. It is easily distinguishable from sibling tools like get_comment, update_comment, and moderate_comments because those name different actions.

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 guidance is given about when to use this tool versus alternatives such as moderate_comments or update_comment. The intended usage is only implied by the resource name, not explicitly explained.

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: discloses that content goes to trash and stays recoverable from wp-admin by default, that permanence requires force AND confirm together, and exactly what is destroyed ('the row is removed from the database along with its meta'). Fully consistent with destructiveHint: true and readOnlyHint: false — no 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?

Three tight sentences, purpose front-loaded in the first, with each sentence carrying distinct information: scope, default trash behavior, and the permanent-deletion path. No filler or repetition of schema text.

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?

Strong coverage for a 5-parameter tool: purpose, safety default, permanence requirement, and destruction scope are all disclosed. Minor gaps: no indication of what the response reports (trashed vs permanently deleted) given there is no output schema, and 'any type' leaves some ambiguity against the type-specific delete siblings.

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 adds value by synthesizing the force/confirm interaction and spelling out the consequence of setting force: true (irreversible row + meta deletion), enriching what the bare parameter docs 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 and resource ('Delete content of any type') in the first sentence. The 'any type' phrasing differentiates it from the type-specific delete siblings (delete_media, delete_comment, delete_term, delete_plugin), and the trash-versus-permanent detail further clarifies what the operation does.

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 through 'any type' and the permanent-deletion gate, but never explicitly says when to use this tool over siblings like delete_media, delete_comment, or delete_term, nor states any exclusions. An agent must infer that this is the generic content-delete 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 communicate destructive intent, and the description adds exactly what is destroyed ('a draft theme and its files') and what is not ('the live site'). The sandbox-vs-live distinction is meaningful behavioral context beyond the structured hints.

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 no filler. The action and scope are front-loaded, and 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?

For a simple destructive tool with complete schema coverage and no output schema, the description plus schema fully explains what is removed, what is preserved, and what confirmation is required. Nothing needed 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 the schema fully documents all three parameters. The description adds no parameter-level details beyond 'and its files', but that is acceptable given the high baseline 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 description opens with a specific verb ('Discard') and a specific resource ('a draft theme and its files'), then clarifies scope by stating the live site is unaffected. This clearly distinguishes it from file-level tools like delete_theme_file and from publish_draft_theme.

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 makes clear this tool is for discarding an unpublished sandbox theme, which gives an agent solid context for when to use it. It does not name alternative tools explicitly or provide exclusions, but the draft/sandbox framing is enough to route selection correctly.

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 mark the operation as destructive, and the description usefully narrows what is destroyed: only the registration, not the underlying stored values. It also adds that re-registration is possible. It does not mention the confirm gating behavior hinted at by the schema, but the description still adds meaningful behavioral context beyond the 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?

Two tight sentences with no filler. The core action is front-loaded, and the second sentence efficiently conveys the non-destructive outcome and the recovery option.

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 tool is simple, and the annotations plus schema cover safety and parameter meaning. The description does not clarify the confirm parameter, which is marked 'Required.' with default false but is not in the schema's required list; this ambiguity could lead an agent to call the tool without the confirmation needed to actually delete.

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 structured schema already documents group_key, site_id, and confirm. The description adds no parameter-level detail beyond the schema, 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?

The description names a specific verb and resource: 'Remove a registered field group.' It also clarifies that the action targets the registration rather than the data itself, which distinguishes it from related field-group operations such as register_fields and list_field_groups.

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 clear context: use this tool when you want to unregister a field group without losing its stored values, and the group can be re-registered to restore it. It implies the recovery path but does not explicitly name the alternative tool or state when not to use it.

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 mark destructiveHint true and readOnlyHint false, but the description adds crucial non-obvious consequences: attachments bypass the trash, files are permanently removed from disk, and references break. This goes beyond the structured metadata and directly prevents an agent from treating this as a reversible delete.

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: purpose, irreversible behavior/requirement, and side-effect warning. No filler, and the most safety-critical statement is front-loaded after the purpose.

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 delete operation, the description covers what is deleted, what the caller must provide, what happens to the file, and downstream consequences. Combined with full schema parameter docs and destructive annotations, nothing essential is missing for correct invocation.

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 confirm already documented as required and irreversible, id as attachment ID, and site_id with usage details. The description repeats the confirm requirement, which reinforces it, but does not add meaning beyond the schema for the 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 phrase 'Delete a media item' states a specific verb and resource, and the WordPress attachment detail makes the target unambiguous among delete_* siblings. Even without naming alternatives, an agent cannot confuse this with delete_content, delete_plugin, or delete_user.

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 explicitly instructs callers to set confirm: true and warns why, which is a concrete usage rule. It does not name alternatives or exclusions, but the media-specific scope makes the appropriate context clear.

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 signal destructiveHint, but the description adds behavior beyond them: it cascades to all menu items and explains the theme-location fallback. This gives the agent a concrete picture of side effects that annotations alone do not provide.

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, each carrying distinct value: what is deleted, what side effect occurs, and what confirmation is required. No filler, and the core operation 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 tool with 3 parameters and no output schema, the description covers the key operational facts: cascade deletion, theme fallback, and confirm requirement. It does not explain return behavior, but that is a minor gap for such a straightforward operation.

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 id, confirm, and site_id. The description restates the confirm requirement but adds no new semantic meaning beyond the schema, keeping this at the baseline for fully covered 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?

States a specific verb and resource ('Delete a navigation menu') and clarifies the cascade ('and all of its items'), distinguishing it from sibling delete_menu_item. The resource is unambiguous and the sentence is action-focused.

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 conveys the key usage requirement ('Requires confirm: true') and implies it is for whole-menu deletion, but it never explicitly says when to prefer this over alternatives like update_menu or delete_menu_item. No exclusions or alternative-routing guidance is provided.

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, which already mark the tool destructive and non-idempotent, the description reveals a crucial side effect: children are re-parented to the top level instead of being deleted. This is exactly the kind of non-obvious behavior an agent needs to know before invoking the 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?

Two sentences, no filler. The primary action is stated first, and the important behavioral caveat follows immediately. Every word 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?

For a simple two-parameter destructive tool with annotations covering the safety profile, the description is complete. It covers the action, the target, and the most important side effect; the optional site_id is fully explained in the schema.

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 id and site_id already documented. The tool description adds no parameter-specific meaning, but it does not need to since the schema carries the full burden.

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 ('Remove'), a specific resource ('one item from a navigation menu'), and immediately clarifies the key distinction from deleting the entire menu. The child re-parenting detail also makes the tool's 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?

The description gives clear context: use this when you want to remove a single menu item rather than the whole menu. It does not explicitly name alternatives like delete_menu, but the 'one item' phrasing establishes the intended use without exclusions.

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 annotations already mark this as destructive, but the description adds valuable specifics: files are removed permanently, many plugins also drop database tables, and confirm: true is required. This goes well beyond the annotation surface and gives the agent a realistic understanding of consequences.

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 compact and front-loaded: it states the action first, then the prerequisite, then the irreversible consequences, then the required flag. Every sentence earns its place with no redundancy or 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 destructive delete operation with no output schema, the description is fully adequate. It covers what gets deleted, prerequisites, irreversible effects, and the required confirmation flag. The annotations supply idempotency and destructive hints, and the schema covers parameter details, so nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful emphasis on the confirm parameter ('Requires confirm: true'), which is critical for invoking this destructive operation correctly. It also clarifies the plugin must be inactive, reinforcing the prerequisite tied to the plugin parameter.

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 uses a specific verb and resource ('Delete an installed plugin') and clearly differentiates this from sibling tools like activate_plugin, deactivate_plugin, and install_plugin. The scope is unambiguous and immediately tells the agent what operation this tool performs.

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 states the key prerequisite: 'The plugin must be inactive first.' This gives strong contextual guidance for when this tool is appropriate and implies that deactivation should happen before deletion. However, it does not explicitly name alternative tools like deactivate_plugin for cases where deletion is not intended.

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 says 'Delete one of your saved playbooks', a destructive action, but the annotations set destructiveHint=false. This is an annotation contradiction, and per the rubric the score must be 1 even though the bundled/override nuance is useful.

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 core action front-loaded, followed by a useful caveat. The second sentence is slightly awkward but earns its place by explaining the override 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?

For a one-parameter delete tool with full schema coverage, the essentials are present. However, with no output schema and minimal annotations, the description does not disclose whether deletion is permanent, what happens if the name does not exist, or what the response will be.

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 already explains the name parameter. The description reinforces 'saved' vs 'bundled' but does not add meaningful parameter syntax, values, or edge-case behavior beyond the schema, 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?

Description states a specific verb ('Delete') and a specific resource ('one of your saved playbooks'), and adds a distinguishing constraint: bundled playbooks cannot be deleted, only saved ones. This clearly separates it from generic delete tools among the 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 gives a partial when-not: bundled playbooks cannot be deleted. It does not name an alternative tool or specify when an agent should prefer this tool over another delete or skill-management tool, so routing guidance is mostly implied by the name and title.

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 destructiveHint=true by disclosing that terms have no trash, deletion is immediate and permanent, the tool reports what will be affected and requires confirm:true, and that content assignments are orphaned rather than deleted, with fallback to the default category. No contradiction with 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?

Three sentences, starting with purpose, then the critical safety warning about permanent deletion, and finally the content side-effect. Every sentence adds meaningful information with no 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?

Covers purpose, side-effects on content, and the confirmation requirement—sufficient for safe invocation. Does not describe the response shape beyond 'reports what will be affected,' but with no output schema that is a minor 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?

The input schema already covers all four parameters with descriptions, so the description adds little parameter-level detail. It reinforces that confirm:true is required and explains the reason, which provides some context beyond the schema's 'required' label, but no additional format or valid-value guidance is given.

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 action, object, and scope: 'Delete a term from any taxonomy.' Differentiates from sibling delete_* tools (delete_content, delete_media) by specifying the resource type, and from update_term by stating deletion rather than modification.

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?

Describes the finality of the operation and that confirm is required, but does not explicitly identify alternatives or conditions for choosing this tool over siblings. The context makes the use case clear, yet no when-not guidance or alternative routing is provided.

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 destructiveHint annotation, the description adds valuable behavioral detail: it refuses to operate on live active themes without explicit permission, and it warns that deleting required templates like index.php or style.css breaks the theme. This helps an agent anticipate important consequences before invoking the 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?

Three tight sentences with no filler: the first states the operation, the second states the safety guardrail, and the third states the key risk. All information is front-loaded and 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?

For a destructive tool with no output schema, the description covers the core action, the safety constraint, and the most important risk. While it doesn't describe response behavior or explicitly say 'permanent,' the destructiveHint annotation, high schema coverage, and confirm parameter description make the tool well-specified overall.

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 every parameter is already documented in the schema. The description does not add parameter-specific semantics beyond broad behavioral context, so the baseline of 3 is appropriate because the schema carries the weight.

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 action ('Delete'), a specific resource ('a file from a theme draft'), and distinguishes itself from live-theme operations by noting that live active themes are refused unless explicitly allowed. This clearly separates it from sibling tools like read_theme_file, write_theme_file, and edit_theme_file.

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 clear context: use it on draft themes, and it will not touch a live active theme unless allow_live_theme is explicitly set. It does not explicitly name sibling alternatives, but the draft-vs-live guidance is sufficient for an agent to select this tool over related theme-file tools in most cases.

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 mark destructiveHint: true, but the description adds meaningful context beyond that: deletion is permanent because there is no trash, confirm must be true, and content must be either reassigned or deleted. This gives the agent important behavioral expectations beyond the structured 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?

The description is two concise sentences with no filler, and the most important information—permanence and mandatory confirm—is front-loaded. Every sentence contributes directly to correct invocation.

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 4-parameter tool with no output schema, the description covers the critical behavioral context: permanence, confirmation requirement, and content disposition. It could additionally note that id is required, but the schema already covers that, so nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter is already documented structurally. The description reinforces the semantics of confirm and reassign_to, but does not add new parameter-level information beyond what the schema provides.

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 the specific action and resource: 'Delete a user', and immediately clarifies the key semantic that WordPress has no trash for users, so deletion is permanent. This clearly distinguishes it from sibling tools like update_user or create_user.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit conditions for use: deletion requires confirm: true and the agent must decide what happens to the user's content, with reassignment strongly preferred. It doesn't explicitly name alternatives or say when not to use it, but the required workflow is clearly specified.

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 mark the tool as destructive and non-idempotent, but the description goes further by explaining the nuanced behavior: the widget is moved to the inactive area and its settings survive unless force is true. This is meaningful behavioral context beyond what annotations or the schema alone provide.

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 two sentences with no wasted words. It front-loads the core action and then immediately explains the most important behavioral nuance, making it easy for an agent to parse quickly.

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 three-parameter delete tool with no output schema, the description covers the essential behavior and the key force parameter. It could mention what happens to a widget currently placed in a sidebar, but the inactive-widgets explanation provides enough context for correct invocation.

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 description adds some semantic value by explaining the real-world consequence of force: true versus false, especially that settings survive in the inactive area. It does not compensate for id or site_id, but those are already well documented in 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?

The description starts with 'Remove a widget,' a specific verb and resource that clearly identifies the tool's action. It also distinguishes itself from sibling delete_* tools by naming 'widget' and from update_widget by the remove semantics. The force behavior adds further clarity without ambiguity.

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 explains the default soft-delete behavior versus the force: true permanent delete, giving agents a decision rule for the force parameter. It does not explicitly discuss when to use this tool instead of update_widget or other alternatives, but the core usage context is clear.

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 and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it explains that the diff includes JSON-path entries, that palette entries are matched by slug, and that it also lists templates/parts with source 'custom'. It also discloses the 'silently wins' override behavior, which is a non-obvious consequence. It doesn't mention pagination or output format, but the output schema is absent and the description gives enough behavioral detail for a read-only inspection 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?

The description is two sentences, front-loaded with the core purpose and then the use-case guidance. Every clause earns its place: the slug-matching detail, the custom-source template list, and the 'silently wins' warning are all high-value. No fluff or repetition 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?

For a read-only diff tool with no output schema, the description covers what the tool does, what it returns (diff entries plus templates/parts), and when to use it. It doesn't describe the exact output structure or how to interpret a diff entry, but the tool's purpose is clear enough for an agent to invoke it and interpret results. The absence of an output schema raises the burden slightly, but the description is strong enough to earn a 4.

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 adds context for include_unchanged by explaining the 'pin the value' consequence, which is not in the schema. It doesn't add much for site_id or max_entries, but the schema covers them well, so the baseline 3 is exceeded by the added semantic value for include_unchanged.

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 ('Show'), a precise resource ('diff of the user's global-styles customisations against the theme's own theme.json values'), and the matching mechanism ('palette entries are matched by slug'). It also distinguishes itself from related theme tools by focusing on Site Editor overrides and custom templates, which is unique among the sibling 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?

The description explicitly says when to use it: 'before editing theme.json' and 'before shipping a theme update', and explains why (a user override silently wins over file changes). It also implies when not to use it (when you don't need to inspect overrides), and the sibling list contains no other diff tool, so the guidance is clear.

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 and destructiveHint=false, so the description need not repeat safety. It adds context about the underlying API and the rationale for using abilities, which goes beyond the annotations. However, it does not disclose behavior like pagination or output structure, but given the read-only nature and annotations, this is acceptable.

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 no fluff. The first sentence front-loads the primary function; the second provides valuable context about why abilities are preferable, though it's slightly tangential to a listing tool. Still, it earns its place by aiding decision-making. Appropriately sized.

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 list operation with optional search and site_id, the description conveys the purpose and the broader ecosystem. It does not explicitly describe the return format (a list of abilities) but that is implied. Given the output schema is absent, this is sufficient. It could mention pagination or that details are available via get_ability_info, but that is not strictly necessary.

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 search and site_id have clear descriptions. The tool description does not add any parameter-specific details beyond what the schema provides, so it sits at the baseline for high schema coverage. No extra guidance on parameter usage is given.

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 clearly states the verb (list) and resource (abilities) with a specific API (WordPress Abilities API). It names example plugins (WPForms, AIOSEO, SeedProd) and distinguishes this from sibling tools like discover_content_types or discover_taxonomies by focusing on abilities. The purpose is unambiguous.

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 broader value of abilities (safer than direct table writes) but does not explicitly say when to use this tool versus alternatives like get_ability_info or run_ability. It implies listing is a discovery step but lacks direct guidance on when to choose this tool over siblings. No exclusions or conditions 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 convey readOnly and non-destructive behavior. The description adds non-obvious context: a type missing from this list has show_in_rest => false and is unreachable over REST. This is exactly the kind of behavioral insight that goes beyond 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?

Two sentences with no filler. The first sentence front-loads the purpose and output fields; the second delivers usage guidance. Every clause contributes 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 simple read-only discovery tool, this is complete: the returned fields are enumerated, the parameters are fully documented in the schema, annotations cover the safety profile, and the usage context is explicit. No critical information an agent needs 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 parameters (site_id and include_counts) thoroughly. The tool description does not need to restate them, and it adds no additional parameter-level meaning, so the baseline of 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 uses a specific verb ('List') and identifies the exact resource ('every content type registered on the site') with concrete examples (post, page, custom post type). It also enumerates what is returned, making it easy to distinguish from sibling tools like discover_taxonomies or list_content.

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 an explicit trigger: 'Call this before working with an unfamiliar site.' It also explains the consequence of a type being absent, which is strong practical guidance. It does not name alternatives or explicitly say when not to use it, 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description is consistent with them (a list operation). Beyond annotations, it adds that results reflect live site registration including plugin additions, and that route shapes vary between plugin versions — useful open-world context consistent with openWorldHint=true. No contradiction with 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?

Two sentences, both earning their place: the first states the core function, the second delivers usage guidance with a rationale. Information is front-loaded with purpose before context, with no filler or repetition of schema/annotation 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?

For a read-only discovery tool, the description covers purpose, when to use it, and the basic return content (namespaces and routes). Annotations cover the safety profile and open-world nature, and the schema documents all parameters. The minimal return description suffices for the stated use case of feeding rest_api.

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 all three parameters (search, site_id, namespace) already documented in the schema. The description adds no parameter-specific semantics beyond what the schema provides, 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?

The description states a specific verb + resource: it lists the REST namespaces and routes the site actually registers, including plugin-added ones. It distinguishes itself from siblings like rest_api by scoping to actually-registered routes rather than theoretical ones, making its purpose unambiguous.

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?

Explicit guidance is provided: 'Use this before rest_api so you call routes that exist' — naming the alternative tool directly and giving the condition plus rationale (route shapes vary between plugin versions, guessing wastes calls). There is no ambiguity about when to invoke 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=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral detail by disclosing that taxonomies with show_in_rest=>false are omitted and unreachable, which is beyond the annotation hints. This transparency about limitations enhances the agent's understanding.

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 two sentences with zero fluff. The first sentence front-loads the core purpose and output, and the second adds a concise, high-value caveat. Every word earns its place, and the structure is immediately 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?

For a read-only discovery tool with no required parameters and no output schema, the description covers the essential facts: what is returned, the REST base, post types, hierarchical flag, and the important exclusion. It does not mention pagination or limits, but for a tool with this simplicity and given the annotations (openWorldHint), the missing details are minor. The description is complete enough for an agent to 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?

Schema description coverage is 100%, and both parameters (site_id and for_type) already have detailed descriptions in the schema. The description does not add any parameter-specific information, but it doesn't need to because the schema fully documents them. The baseline of 3 applies when the schema carries the load.

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 ('List'), a precise resource ('every taxonomy on the site'), and enumerates the exact information returned (REST base, post types, hierarchical flag). It also adds a critical caveat about taxonomies not exposed over REST, distinguishing the tool's scope from a general taxonomy listing.

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 makes clear what the tool returns and includes a practical note about unreachable taxonomies, but it does not explicitly mention when to choose this over related tools like discover_content_types or list_terms. The usage context is implied rather than stated, and no alternatives or exclusions 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?

The description reveals that this is an alias with legacy status, which is useful context beyond the annotations, but it does not describe side effects, permissions, or what fields actually get modified. Since readOnlyHint=false, destructiveHint=false, and idempotentHint=false already signal a non-read, non-destructive mutation, a mid score is appropriate.

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 two short sentences with no filler: it states the alias relationship, the backward-compatibility rationale, and the preference for update_media. Every sentence 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?

For a deprecated alias, the description is largely complete because it directs the agent to update_media for canonical behavior, and the input schema documents all parameters. It does not describe return values, but the alias framing makes that omission minor.

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 fully documents all seven parameters and their meanings. The description adds no parameter-level information, 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?

The title and description make clear this tool edits a media item, and the description explicitly frames it as a legacy alias for update_media. This distinguishes it from update_media and other media tools, though it relies on the referenced tool to fully define the 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 description gives explicit routing guidance: this is a legacy alias for update_media, kept only for backward compatibility, and update_media should be preferred. This is a clear when-to-use versus when-not-to-use statement with a named alternative.

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 annotations already signal a non-read-only, non-idempotent mutation. The description adds useful behavioral context beyond that: edits are surgical, safer than a full write, and a no-match edit fails loudly. This is meaningful and does not contradict the 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?

Three tight sentences: one states what it does, one gives the key comparison with the sibling alternative, and one discloses an important failure behavior. There is no fluff and the most important distinguishing information 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?

The description covers the essential context for safe use: targeted edits, comparison to write_theme_file, and loud failure on no match. The schema fills in the remaining operational details like path, theme selection, and live-theme protection. Some minor context such as drafts or ordering is handled by the schema and sibling tools, not a critical 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?

The input schema has 100% description coverage for all parameters, so the schema carries the semantic weight. The tool description adds general context about targeted find/replace and failure behavior, but it does not need to add per-parameter meaning since the schema already documents find, replace, all, regex, required, theme, site_id, and allow_live_theme in 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?

The description states a specific verb and resource: 'Make targeted find/replace edits inside a theme file'. It also distinguishes itself from write_theme_file by emphasizing targeted edits and leaving the rest untouched, so an agent can immediately tell this from 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?

It explicitly names write_theme_file as the alternative and gives the deciding condition: 'Safer than write_theme_file for changing one function or block of markup'. This gives clear when-to-use guidance rather than leaving it 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?

The description goes far beyond the sparse annotations (readOnlyHint: false, destructiveHint: false). It discloses the two-phase mutation protocol (preview + confirm_token required even with allow_mutation: true), the 'stacked statements are always refused' rule, the enforced row limit on safe statements, and the side effects of bypassing hooks: caches not invalidated and plugin logic skipped. No contradiction — destructiveHint: false is consistent with the default-deny-plus-confirmation design.

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 (~90 words) with zero redundancy: what the tool does, how safe statements execute, the mutation safety protocol, and the routing caveat all earn their place. The description is front-loaded with the core purpose and flows logically from behavior to risk, with no repeated 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?

Operationally complete for an agent: execution model, row limit, confirmation flow, stacked-statement refusal, and side effects are all covered. The only gap is the return shape of query results and the preview response, which matters because no output schema exists — though the confirm_token parameter description ('Token returned by the preview') partially bridges the preview format question.

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 all five parameters, including the interplay between allow_mutation and confirm_token. The description adds only framing — 'enforced row limit' echoes max_rows and 'stacked statements are always refused' constrains query — but no significant new semantics beyond the schema's own parameter descriptions. 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: 'Run a SQL query against the WordPress database through the companion plugin.' The scope is unambiguous and the closing sentence explicitly frames raw SQL as a last resort beyond the REST API and WP-CLI, which maps to siblings rest_api and run_wp_cli — so an agent can tell this tool apart without opening schemas.

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?

'Reach for this only when the REST API and WP-CLI cannot get at the data' is an explicit when-condition that names the alternatives and implies the when-not: do not use it when standard APIs suffice. It also explains why ('raw SQL bypasses WordPress hooks, so caches are not invalidated and plugin logic does not run'), giving the agent a decision rule rather than a vague preference.

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 flag readOnlyHint:false and openWorldHint:true, but the description adds significant behavioral context: it can optionally mutate in the same call, update is off by default making it safe for pure lookup, and it discloses the detection order (explicit ?p=, search index, rewrite base, slug sweep). This goes well beyond what the annotations convey and helps the agent predict side effects.

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 compact, front-loads the core purpose and usage trigger, and every sentence contributes: purpose, example, when-to-use, and detection order. No filler or repetition of schema contents.

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 complex tool with 23 parameters and nested objects, the description provides the necessary mental model — URL resolution, optional update behavior, and the update flag's safety default. It doesn't describe return values or failure modes, but with no output schema and rich parameter docs, what's missing is minor.

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 each of the 23 parameters is already documented in the schema; the description adds no parameter-level detail beyond the url resolution logic and the update flag's default-off behavior. This matches the baseline of 3 where the schema carries the heavy lifting.

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 ('Resolve any WordPress front-end URL to the content behind it') and a clear resource, and distinguishes itself from siblings by the URL-resolution mechanism and optional update capability. The example with /documentation/getting-started/ and the explicit 'This is the tool to reach for when a human hands you a link' makes its purpose unmistakable and differentiates it from slug-based tools like get_content_by_slug.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a clear when-to-use signal ('when a human hands you a link') and explains the detection order, which helps agents understand what kinds of URLs are valid inputs. However, it stops short of explicitly naming alternatives or stating when not to use it (e.g., 'if you already have a slug, use get_content_by_slug instead'), so it lacks full exclusion 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?

The description adds meaningful behavioral detail beyond the annotations: sites are checked in parallel, each site is isolated so one failure never breaks the report, and results are sorted worst-first with headline issues. It also confirms the read-only nature of the operation without contradicting the 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?

The description is front-loaded with the core purpose and packed with useful, specific information in just two sentences. The checklist of checks is organized efficiently, and every clause contributes meaning without repetition or 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?

Even without an output schema, the description tells an agent what the report covers, how failures are handled, and how results are ordered. It could be more explicit about the exact response shape, but for selecting and invoking the tool the description is sufficiently 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 description coverage is 100%, so the input schema already documents all five parameters. The description loosely reinforces some parameters, such as 'chosen subset' for site_ids and 'checked in parallel' for concurrency, but it does not add substantial new parameter-level meaning beyond what the schema provides.

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 function: generating one aggregate report across all configured WordPress sites or a chosen subset. It enumerates the exact checks performed and distinguishes itself from single-site tools like test_site or get_site by its fleet-wide, parallel scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear context by positioning the tool as 'the starting point for agency maintenance rounds' and by clarifying it can run on every site or a chosen subset. It does not explicitly name alternatives or when-not-to-use, but the intended use case is clear enough.

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 and destructiveHint=false, so the description does not need to repeat those. The description adds value by specifying that the tool returns input/output schemas and destructive status, which are behavioral traits beyond the read-only nature. This complements the annotations, and there is no 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 description is a single sentence with no wasted words. It front-loads the primary benefit ('full definition'), then lists the key returned details, and ends with crucial naming guidance. 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?

Given the tool's simplicity (2 params, 1 required, no output schema), the description is adequate. It explains the purpose, the main use case (calling correctly), and the namespacing requirement. It could mention that the output schema is not provided here, but the description already says it returns schemas, so an agent knows to look at the result. Overall, sufficient for correct invocation.

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 explains both parameters. The description adds nuance by noting ability names are namespaced with an example ('my-plugin/get-site-info'), which reinforces the schema's pattern and helps agents format the parameter correctly. This is a small but meaningful addition 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?

The description clearly states the tool's purpose: 'Get the full definition of one ability, including its input and output schemas and whether it is destructive.' It specifies the resource (an ability) and the exact information it returns. While it doesn't explicitly distinguish itself from siblings, the unusual 'ability' concept makes it unique enough, and it references 'discover_abilities' for context, aiding differentiation.

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 that the tool is the prerequisite for calling abilities correctly: 'so you can call it correctly the first time.' It also implies it should be used after discovering abilities. However, it does not explicitly state when NOT to use it or name alternatives, but given the unique purpose, this is acceptable.

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 and destructiveHint=false. The description adds meaningful context: the log is append-only and local, and specifies which actions are recorded, going beyond what annotations convey. No contradiction with 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?

Two efficient sentences with no filler. The first sentence front-loads the resource, scope, and output fields; the second adds a practical use case without repeating schema or annotation information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.