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

Beyond the annotations, the description discloses authorization requirements, test-request behavior, rollback on fatal errors or endpoint failure, warning behavior when the site cannot reach itself, concurrency refusal, and the fact that a failed activation is deactivated without running its deactivation routine. It also clearly states what is not checked, such as cron, AJAX, and other wp-admin screens.

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 purpose, naming convention, and alternatives before moving into behavior. It is dense and long, but the length is largely justified by the destructive activation checks, rollback rules, and edge cases; it could still be more structured than one monolithic paragraph.

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 activation tool with one parameter, no output schema, and rich annotations, the description covers authorization, test behavior, rollback semantics, warning messages, concurrency, and explicitly excluded checks. An agent has enough context to invoke it and understand the main failure modes.

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 has 100% description coverage for the single plugin parameter, including the same akismet/akismet.php example and wp_list_plugins reference. The description reinforces the required file format and ties it to an installed plugin, but it does not add substantially new parameter semantics 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 verb and resource: activate an installed plugin on this site, named by its file as wp_list_plugins lists it. It explicitly distinguishes installation via wp_install_plugin and network-wide activation via Network Admin, so an agent can separate it from nearby 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?

It gives the use case directly: activate an installed plugin on this site, using the file identifier that wp_list_plugins returns. It also names alternatives and prerequisites: installing belongs to wp_install_plugin, network-wide activation is handled under Network Admin, and the caller needs activate_plugins.

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?

Far exceeds the annotations: it discloses refusal conditions (broken child theme, network restriction, unmet PHP/WP requirement), the undo snapshot and its "undo" token (null when unavailable), the pre/post test-request set and what happens when a security plugin blocks login, automatic rollback on fatal error/endpoint failure, pre-existing fatals kept with a warning, the "not checked" fallback when the site can't reach itself, and the one-at-a-time lock. Nothing here contradicts readOnlyHint=false / destructiveHint=true / idempotentHint=false — it substantiates 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?

Front-loaded with purpose and naming, then progressive detail on refusals, testing and rollback — the ordering is sound and each block carries real information. It runs long and a few ideas repeat (the failed-check rollback is stated twice, and the undo point is revisited), which costs a point against a tighter version.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With one fully documented parameter, no output schema, and destructive/mutating semantics, the description carries the needed weight: it explains the return payload ("undo" token, null case), failure modes, and rollback guarantees. An agent has everything required to decide, call, and interpret the result.

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

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

Schema description coverage is 100% and the description's naming guidance ("named by its directory as wp_list_themes lists it", the "collection/theme" example, child-theme-by-own-folder) largely restates the schema property description. The wp_list_themes cross-reference is a mild convenience but adds no format or validation detail beyond the schema, 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?

Opens with a specific verb+resource ("Switch the active theme to an installed theme") and immediately differentiates siblings by naming wp_install_theme for installation and wp_list_themes for the naming convention. An agent can tell exactly which of the many theme/plugin tools to call without opening a schema.

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

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

Explicitly routes the agent: install-then-activate is spelled out via the wp_install_theme cross-reference, and the closing "Not checked" paragraph draws the boundary of what this tool does not verify (other wp-admin screens, cron, AJAX, per-page/per-user code). It also states the concurrency exclusion — a second activation is refused and changes nothing.

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

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

Goes well past the annotations: append-at-end positioning, non-deduplication on repeated calls, rejection of javascript:/data: schemes, required capabilities (edit_theme_options plus assign_term, which a site can withhold per menu), and the absence of an undo point. The duplicate-add and no-undo disclosures corroborate idempotentHint=false and destructiveHint=true rather than 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?

Five compact sentences, front-loaded with verb, resource, and placement, then behavior, then constraints, then permissions and recovery. No filler and no restatement of the title.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 6 params and no output schema, the description covers the return shape ("Returns added and item_id"), the failure mode for bad URLs, capability requirements, and the recovery tool. Nothing an agent needs to call this mutation correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by framing the object_id-vs-url precedence as a mode choice rather than a per-field note, which is the main semantic decision when calling this tool. It does not add syntax or format detail (e.g. parent/item_id lookup) beyond the schema.

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

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

States a specific verb and resource ("Add a published item to a navigation menu") plus position ("at the end"), then immediately disambiguates the two operating modes: content link via object_id vs custom link via url. An agent can tell this apart from wp_create_menu and wp_delete_menu_item without opening any schema.

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

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

Explicitly gives the selection rule between the object_id and url paths, warns that duplicate targets still create new items, and names wp_delete_menu_item as the removal path. It does not state the prerequisite that the menu must already exist (wp_create_menu / wp_list_menus is only implied by the menu param description), so it stops short of full when/when-not coverage.

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 by disclosing the sanitisation path (the widget's own update() plus widget_update_callback), the capability-dependent HTML filtering, the exact refusal conditions where "nothing is saved", and that no undo point is created. Annotations already flag destructive/non-idempotent, and the description reinforces rather than repeats 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?

Four tight sentences, front-loaded with the action and target, then behavior, then failure modes, then the undo caveat. No filler and no 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?

Although there is no output schema, the description names the return shape (added, id in "<id_base>-<number>" form, sidebar), covers rejection behavior, and states the atomics of the write. That is everything needed to call a mutation tool with four parameters 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 still adds real meaning by explaining what happens to the settings object (widget-specific sanitisation and filtering) and by clarifying that sidebar can be wp_inactive_widgets. It adds little about position 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?

Opens with a specific verb+resource+scope: "Add a new widget of a registered type to a sidebar, or to wp_inactive_widgets." It also names the sibling that handles the adjacent case (wp_update_widget for existing widgets), so an agent can route without opening either schema.

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

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

Explicitly says existing widgets are handled by wp_update_widget, which is a clean alternative-routing rule, and warns that no undo point is recorded. It doesn't tell the agent to check wp_list_sidebars/wp_get_widgets first, but the schema fields cover the sidebar-id source.

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 say only destructive/openWorld/not-idempotent; the description goes far beyond them by disclosing that trash is refused on sites without trash support because WordPress would delete permanently, that publishing makes posts public immediately, that media files collapse to 'inherit', and that edit_others_posts is required. It also documents retry semantics (duplicates count once, repeats are near no-ops except stored_as rewrites), the 60-second partial-completion behavior with 'remaining', and the undo token.

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 action and limits are front-loaded, but the body is two enormous multi-clause sentences that pack return-shape, edge cases and retry rules into an undifferentiated block. Every fact earns its place, yet the density hurts parseability and no structure (lists, separators) is used.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description carries the return contract itself and does so in full: updated, ids with stored_as, failed/forbidden with error codes and 100-item caps, omitted counts, undo token, and remaining. Combined with permission and time-limit disclosure, an agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100% and the schema already documents duplicates, the 500-id cap and the 'remaining' overflow, so the description largely restates the same facts. It adds a little beyond the schema (media files treated alike, statuses refused leave nothing changed), but not enough to exceed the baseline for fully documented 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 with scope: change the status of many posts at once by id list, across posts/pages/other post types/media, to publish, draft, pending, private or trash. It also names the single-post sibling (wp_update_post), so an agent can separate this from the per-post tool without opening either schema.

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

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

'Suited to batches; one post's status and other fields change with wp_update_post' routes the agent to the right alternative, and the 500-id cap plus 60-second cutoff tell it when to split work across calls. Exclusions are implied rather than crisply stated, which keeps it 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?

Goes well past the annotations: it discloses that deletion goes through WordPress, that a persistent object cache means only the cache entries are removed and option rows may linger, and that manage_options is required. It also explains the 'deleted' return value's meaning, which annotations cannot convey.

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

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

The scope constraint is front-loaded in the first sentence, followed by the negative scope, return value, cache caveat and permission requirement in descending order of importance. Every sentence carries distinct information with no restatement of the title.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description must describe the return value — it does. For a destructive, non-idempotent operation with zero parameters, it supplies scope, safety caveat, permission gate and return semantics, leaving nothing an agent needs before calling 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?

The tool takes zero parameters, so the baseline is 4; the description correctly implies there is nothing to configure. It does add meaning about the response shape ('deleted, the number of expired transients found') that the empty schema cannot express.

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 the expired transients') and then defines the exact criterion: every transient whose _transient_timeout_ row in the options table has passed. It also scopes negatively by naming what is not touched (unexpired and _site_transient_), which no sibling tool claims.

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 scope of the operation is clear, so an agent can infer this is a maintenance/cleanup tool, but it never states when to reach for it over neighbours like wp_clear_cache or wp_db_optimize. No explicit 'use this when' or exclusion guidance is 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?

Goes well beyond the annotations: declares the manage_options requirement, that no undo point is recorded, the multisite network-capability nuance with page_cache_skipped reporting, and the transient performance cost ('site can answer slower for a short while'). This is exactly the mutation-safety context annotations alone (destructiveHint=true) cannot convey.

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

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

Front-loaded with the action and the scope, then conditions, then return shape — a sensible order. The eleven-plugin enumeration is long but earns its place by bounding which caches are actually purged; minor trimming of that list would tighten it slightly.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

A no-parameter, high-impact mutation tool with no output schema is fully covered: what is flushed, what is skipped and why, the permission gate, the irreversibility, the return keys, and the performance side effect are all stated.

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?

Zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description compensates by documenting the output keys (object_cache_flushed, opcache_reset, page_cache_purged, page_cache_failed, page_cache_skipped) that the missing output schema would otherwise leave opaque.

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 (flush) and enumerates the exact resources affected: object cache, OPcache, and page caches of named plugins. It also explicitly distinguishes itself from the sibling wp_cleanup_transients, so an agent can choose between the two without opening a schema.

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

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

Gives the triggering condition ('making a change visible that a cache still serves in its old form') and names the alternative for transient cleanup (wp_cleanup_transients). It further bounds usage by noting that host/CDN caches are not reached, which tells the agent when this tool will not achieve the goal.

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, destructiveHint=false, idempotentHint=true, and openWorldHint=false, but the description adds substantial context beyond them: it states the tool changes nothing, keeps nothing, requires manage_options, takes no arguments, and performs self-requests from the site to itself. Crucially, it discloses a key limitation—external blocks like Cloudflare bot rules for AI crawlers are not seen—and notes that the result records this in a 'limits' field. This is rich behavioral disclosure that fully complements 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 then details the checks. Every sentence adds useful information (specific checks, behavioral constraints, return shape). It is dense and long, with some run-on clauses, but it avoids fluff and remains appropriately sized for a complex diagnostic 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?

There is no output schema, but the description compensates by explicitly describing the return structure: 'checks: [{id, status, title, finding, steps}], summary, checked_at, and limits.' It also covers auth requirements and operational limitations. Given the tool's complexity, this is a complete and self-contained definition.

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

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

The tool has zero parameters, so the baseline is 4. The description confirms 'takes no arguments,' which is consistent with the empty input schema. No additional parameter semantics are needed.

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: 'Check what stops an app from connecting to this site and how to fix it.' It enumerates the exact checks (HTTPS, permalinks, MCP endpoint behavior, Authorization header, well-known endpoints, firewall, Cloudflare, REST-restricting plugins), making the tool's scope unambiguous. It does not differentiate itself from the sibling diagnostics tool wp_site_health, which prevents a 5.

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

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

Usage is implied by the diagnostic framing ('Check what stops an app from connecting'), but there is no explicit guidance on when to choose this tool over alternatives such as wp_site_health or wp_get_error_log. No when-not conditions or sibling routing instructions are 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?

Goes well beyond the annotations: discloses the required capability (edit_theme_options), the WordPress duplicate-name rejection behaviour, and the return shape ('Returns created and menu_id') in the absence of an output schema. The annotations only say this is a non-idempotent, non-destructive write; the description supplies the operational context an agent needs.

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

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

Four short sentences, front-loaded with the action and return value, then boundaries, then the auth requirement. Every sentence carries distinct information; nothing is padded.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description fills the gap by naming the response fields, and it covers auth, error behaviour, and sibling boundaries for a single-parameter mutation tool. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% and already documents sanitisation, so the baseline is 3. The description adds a validity constraint not present in the schema — that a name already used by another menu is refused — which is meaningful for constructing a call, though it repeats nothing about backslash/HTML handling.

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 ('Create an empty navigation menu') and immediately disambiguates from siblings: item creation belongs to wp_add_menu_item, theme-location assignment is out of scope. An agent can distinguish this from wp_list_menus, wp_get_menu and wp_add_menu_item without opening a schema.

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

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

Explicitly names the alternative tool for adding items (wp_add_menu_item) and an exclusion (theme location assignment is not part of this tool). It leaves no ambiguity about when to call this versus its neighbours.

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

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

Adds substantial context beyond annotations: each call creates a new entry (consistent with idempotentHint=false), default draft status, publish/private/future require publish capability, a published entry is immediately visible on the site, empty title+content+excerpt is refused with empty_content, and the return shape {created, post} is given. None of this is derivable from the readOnly/openWorld/destructive hints 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?

Purpose and the non-idempotency warning are front-loaded, then permissions, failure mode, return value, and sibling routing follow in a logical order. It is a dense single paragraph, though, and the permission clauses are packed tightly enough to slow scanning.

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 what an agent needs for a zero-required-parameter mutation tool: default status, capability requirements, the refusal condition, immediate visibility of published content, non-idempotency, return payload, and which sibling to use instead. No output schema exists, and the description names the returned fields regardless.

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

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

Schema coverage is already 100%, so baseline is 3, but the description adds cross-parameter semantics the schema states only per-field: draft-unless-status-says-otherwise, and that invisible/refused combinations (e.g. builder meta needing unfiltered_html) fail before anything is written. It doesn't restate the date/status scheduling rule in detail, leaving that to the schema.

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

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

States a specific verb and resource (create a post, page or custom post type entry) and enumerates the fields it can set. It clearly separates itself from wp_update_post (existing entries) and wp_upload_media (files), so an agent can pick it without opening sibling 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?

Explicitly routes edge cases to alternatives: existing entries go to wp_update_post, files to wp_upload_media. It doesn't spell out a full 'when not to use' (e.g. bulk creation vs. duplicate), but the create-vs-update boundary is unambiguous.

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

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

Annotations already declare the non-read-only, non-destructive, non-idempotent profile, so the bar is lower, and the description still adds real value: the capability requirement, the exact refusal conditions (missing parent, duplicate name, with the hierarchical-parent nuance), and the response shape {created: true, term_id}. It doesn't state whether creation fires hooks or what happens on partial failure, keeping it off a 5.

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

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

Purpose and return value are front-loaded in the first sentence, and the rejection rules are packed into one dense sentence. A few clauses restate what the schema already documents (slug suffix behavior, parent id meaning), which is minor waste but not bloat.

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 5-parameter mutation with no output schema, the description covers the return shape, permission requirement, failure modes, and the alternative tool. An agent has everything needed to call it correctly and to predict the two ways it will fail.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds semantics the schema does not carry: the uniqueness rule on `name` (scoped to parent in hierarchical taxonomies) and the referential constraint on `parent`. Some of its phrasing (slug suffix, unknown taxonomy refused) duplicates the schema, so it is additive rather than transformative.

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

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

Opens with a specific verb+resource plus the resource's scope ("Create a new term (category, tag or custom taxonomy term) in a taxonomy"), and immediately states the return shape. It also names the sibling that handles the adjacent case, so an agent can distinguish it from wp_update_term without opening either schema.

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

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

Explicitly routes the alternative case: "Existing terms are changed with wp_update_term." It also gives the prerequisite (manage_categories for categories/tags) and the two conditions under which WordPress rejects the call, which is exactly the when-to-use context an agent needs before invoking.

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 give readOnlyHint=false and destructiveHint=false; the description goes far beyond by disclosing return fields (created, id, generated_password), the one-time visibility of the generated password, the role-escalation rules on multisite, the default subscriber role, and that no undo point is recorded. That last point is exactly the kind of missing-safety context the annotations cannot convey.

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

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

Purpose and return values are front-loaded and every clause carries information, but the permission chain is delivered as one long semicolon-and-parenthesis run that is harder to parse than it needs to be. Dense yet not padded.

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 six-parameter mutation tool with no output schema, the description covers the inputs' consequences, the returned fields, permission prerequisites, and the absence of an undo path (with wp_undo/wp_undo_list as siblings). Nothing an agent needs to call this 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 coverage is 100%, so baseline is 3, but the description adds semantics the schema cannot: the permission gate attached to role selection and the privilege rules governing which role may be assigned. It does not add format detail for username/email, but the added role rules are substantively useful.

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

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

Opens with a specific verb and resource ("Create a new user account with a role") and explicitly routes existing accounts to wp_update_user, so the agent can separate it from that sibling without reading either schema.

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

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

States when to use it, the alternative for the other case ("Existing accounts change with wp_update_user"), the required capability (create_users), and the extra capability needed to name a role (promote_users). It also covers the when-not edges: duplicate login/email refused, unknown role refused, multisite administrator restrictions.

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 annotations, it discloses the required capability ('Needs manage_options'), multisite scoping (current site), and meaningful counting exclusions (scheduled posts not counted, private files not counted). These are non-obvious traits an agent could not infer from readOnlyHint/idempotentHint alone.

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

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

Front-loaded with the core action, then the enumeration, then the permission/exclusion caveats and sibling routing. It is dense — a long single sentence with heavy parentheticals — but every clause carries information; minor tightening would help readability.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, and the description compensates by specifying the counted categories and their status breakdowns, including what is excluded. Combined with permission and scope notes, an agent has everything needed to call it correctly and interpret the result.

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

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

Zero parameters, so the baseline is 4; the description explicitly confirms 'takes no arguments,' which matches the empty schema. No additional meaning is needed or possible.

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 ('Get content counts of this site') and enumerates exactly what is counted: post statuses per post type, users total/per role, comment statuses, and media. It explicitly distinguishes itself from the list tools by noting 'The entries themselves are listed by wp_list_posts, wp_list_comments and wp_list_media.'

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 closing sentence routes the agent to the sibling tools when actual entries are needed, which is clear alternative guidance. It stops short of an explicit 'use this when you need an overview/dashboard summary' statement, so the positive selection criterion is only implied.

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

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

Annotations declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, and the description goes well beyond that by disclosing table locking depending on storage engine, long runtime on large tables, absence of a dry run, and the manage_options capability requirement. It also describes the return payload (optimized count and table names), which is absent from structured data.

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: what it does and on what scope, what it returns, then the risks and prerequisite. Risk and auth information is front-loaded before the agent commits, 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?

No output schema exists, but the description covers the return shape, the capability gate, the non-reversibility (no dry run), and the performance/locking hazard. For a zero-parameter destructive maintenance tool, an agent has everything needed to decide and to set expectations.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. The description correctly adds no parameter prose, keeping the focus on behavior.

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 the exact operation (OPTIMIZE TABLE), the exact scope (every table whose name starts with this site's table prefix), and the goal (reclaim space, defragment). An agent can immediately distinguish this from maintenance siblings like wp_cleanup_transients or wp_clear_cache without opening any schema.

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

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

Gives clear operating context — requires manage_options, no dry run, may be slow and may lock tables — which tells the agent when this is appropriate and what it costs. It stops short of explicitly naming alternatives (e.g., wp_cleanup_transients for lighter cleanup) or stating when not to run it, so it is strong context without 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?

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is partly covered. The description still adds real value beyond them: it discloses the returned was_active field, the hard refusal for AlphaBridge components, and the consequence that deactivating them would break the connection. It does not address what happens when the plugin is already inactive, a notable omission given idempotentHint=false.

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

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

Three short sentences, front-loaded with the operation and argument format, then return value, then the refusal exception. Every sentence carries information; the phrase 'The answer says in was_active' is slightly awkward but not wasteful.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With one parameter, no output schema, and annotations covering the safety profile, the description supplies what an agent needs: identifier provenance, the return field, the AlphaBridge refusal, and the reverse tool. The main missing piece is behavior on an already-inactive plugin, which matters because idempotentHint is false.

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 already documents the plugin parameter, so the baseline is 3. The description goes slightly further by naming wp_list_plugins as the authoritative source of the value and restating that anything else is refused, reinforcing the strict matching requirement.

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 (deactivate) and resource (plugin), and pins down the identifier format with a concrete example (akismet/akismet.php) sourced from wp_list_plugins. It explicitly names wp_activate_plugin as the reverse operation, so an agent can tell the two apart without opening either schema.

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

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

Covers use (deactivate an installed plugin), how to obtain the argument (via wp_list_plugins), when-not (AlphaBridge itself is refused, with the reason: it would end the connection or remove tools), and the alternative route (wp-admin under Plugins). The reverse sibling is named, giving a clean selection decision.

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, it discloses that deletion defaults to trash, force permanently deletes, removes meta, and moves replies up a level. It also explains that already-trashed/spam comments and sites with trash disabled are permanently deleted even without force, making repeat calls non-idempotent. Permissions and return/error behavior are also specified.

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

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

The core behavior is front-loaded: default trash versus force permanent deletion. Despite being dense, every sentence carries useful behavioral, edge-case, permission, or return-value information. There is no redundant restatement of the tool name or schema fields.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, but the description provides the return shape and unknown-comment error behavior. It covers destructive side effects, WordPress-specific trash/spam edge cases, note-reply cascading, permissions, and the alternative moderation tool. This is complete for a destructive delete tool.

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

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

Schema coverage is 100%, so the schema already defines both parameters, including force's default. The description adds meaningful semantics beyond the schema by explaining force's side effects: permanent removal, meta deletion, and reply promotion. It also notes that an unknown comment_id returns a not-found error.

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: delete one comment. It immediately distinguishes default trash behavior from permanent deletion with force=true, which an agent cannot infer from the name alone. Relevant sibling wp_moderate_comment is also named for the different restore/moderation action.

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 clearly explains when to use force versus default trash, including edge cases where a comment is already trashed, spam, or on a site with trash disabled. It also mentions wp_moderate_comment as the alternative for changing a trashed comment's status. It lacks an explicit 'use this instead of X when...' sentence for some sibling operations, but the practical guidance is strong.

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

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

Goes well beyond the destructiveHint annotation: it discloses that metadata and the file plus generated image sizes are removed, that undeletable files fail silently without an error, that featured-image references are cleared while embedded/linked URLs persist, and that a stale id returns not-found. That is exactly the kind of side-effect detail an agent needs before a destructive call.

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

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

A single dense paragraph that front-loads the destructive action and its consequence, then layers permissions, return shape, and the alternative tool. Every clause carries distinct information 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?

There is no output schema, but the description supplies the return shape ({deleted: true, id}) and the error case, plus the full deletion side-effect profile. Nothing an agent needs to invoke this destructive tool 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 coverage is 100%, so the single 'id' parameter is already documented in the schema and the description only echoes it. It does add one behavioral nuance — a nonexistent id yields a not-found error — but no syntax or format guidance beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Delete one file of the media library (attachment)') and explicitly scopes itself against the sibling wp_delete_post for posts/pages. The agent can distinguish it from wp_update_media or wp_delete_post without opening any schema.

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

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

Covers when to use it (deleting an attachment permanently) and points to wp_delete_post for a different resource, making the boundary explicit. It also flags the prerequisite ('Needs the right to delete that file') and that there is no trash, so the agent knows this is not a recoverable soft delete.

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 substantial behavior beyond the annotations: sub-items keep the removed item as parent and may surface at top level, the call returns deleted and item_id, invalid ids are refused, and permissions can be withheld per item. It also emphasizes permanence and lack of undo, which is critical for a destructive 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 core action is front-loaded, and each subsequent sentence adds distinct operational value: side effects on sub-items, return values, idempotent-ish refusal behavior, permissions, and permanence. There is 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 destructive tool with no output schema, the description is complete: it covers return values, permissions, permanence, side effects on child items, and behavior for invalid ids. An agent has enough information to call it correctly and understand the consequences.

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 item_id meaning is already documented in the schema. The description reinforces that it targets one menu item, but does not add format or lookup details beyond what the schema already 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 states a specific verb and resource: remove one item from a navigation menu by item_id. It also immediately clarifies that the linked post/page is untouched, which distinguishes this from wp_delete_post and makes the scope 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?

It gives clear when-to-use and when-not-to-use context: use it only for menu items, not for the linked content, and note that this is permanent rather than a trashable delete. It also explains what happens to sub-items and to repeated calls on non-menu-item ids.

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 what actually gets destroyed (the plugin's uninstall routine can remove settings and data), that an active plugin is deactivated first, that no undo point is recorded, and why self-deletion is blocked. It also explains the two-step confirm flow and correctly notes it guards against accidental calls without making the change reversible.

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

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

Front-loaded with the action, the identifier format and the permanence warning, which is the right order for a destructive tool. It is a single dense block, though, and the two-step confirm flow is explained in both the description and the schema, which is redundant weight in an already long paragraph.

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 with no output schema, the description covers everything an agent needs: identifier source, precondition capability, environment refusals, side effects of the uninstall routine, irreversibility, and the confirmation handshake. It even names the return keys (deleted, plugin).

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

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

Schema coverage is 100% and both parameters are already fully documented, including the example path, the folder-name refusal, and the 10-minute token validity. The description largely restates the path format and confirm flow, adding only the cross-reference to wp_list_plugins as the source of a valid value — correct baseline 3.

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

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

States a specific verb and resource (delete an installed plugin) plus the exact identifier format, with a concrete example path. It explicitly separates itself from wp_deactivate_plugin and points at wp_list_plugins as the source of the identifier, so an agent can pick it out of a 60+ sibling toolset without opening any schema.

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

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

Gives the alternative and the condition that selects it ("switching a plugin off without removing it is wp_deactivate_plugin"), states the prerequisite capability (delete_plugins), the environment blocker (refused when DISALLOW_FILE_MODS is set), and an explicit exclusion (AlphaBridge itself, with the reason and the wp-admin route instead). Nothing about when to use or avoid is left 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?

Despite annotations already declaring destructiveHint=true and idempotentHint=false, the description adds substantial behavioral detail: permanent deletion removes revisions, comments, custom fields, and term assignments, cannot be undone, and requires the right permission. It also explains trash behavior, comment hiding, refusal cases, and repeat-call safety, going well 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 front-loaded with the core delete/trash distinction and force behavior. It is dense and information-rich, but not bloated; most clauses carry useful edge-case or safety 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 destructive mutation with no output schema, the description is highly complete: it covers permissions, trash vs permanent behavior, irreversible side effects, refused cases, restore path, return shape, not-found error, and the media deletion alternative.

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 id and force. The description clarifies the practical consequence of force=true but largely repeats the schema's existing parameter meaning, so baseline 3 is appropriate.

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

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

The description states a specific verb+resource: delete a post, page, or entry of any post type. It explicitly distinguishes media deletion via wp_delete_media, so the agent can tell it apart from the sibling media tool without opening either schema.

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

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

It clearly explains the default trash behavior, when force=true is required, and which cases are refused without force. It also names wp_update_post as the restore path and wp_delete_media as the alternative for media files, giving explicit when/when-not/alternatives 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?

Goes well beyond the annotations by disclosing exact side effects: posts lose the term and fall back to the default category, child terms reparent to the deleted term's parent, and term meta is removed. It also names the required capabilities and the error conditions, which annotations alone (destructiveHint only) cannot convey.

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

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

Front-loaded with the destructive outcome and no-trash caveat, then side effects, then permissions, then return value — a sensible priority order. It is dense but nearly every clause carries distinct information; a slight tightening of the permission sentence would make it ideal.

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 2-parameter destructive tool with no output schema, it covers side effects, error cases, permission requirements, and even states the return shape ({deleted: true}). An agent has everything needed to call it safely and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value by constraining term_id semantically (unknown IDs error) and by explaining that taxonomy must be a real taxonomy whose default term is protected. It doesn't add format details beyond the schema's own examples.

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 term from a taxonomy") with an explicit scope qualifier ("for good; terms have no trash") that separates it from soft-delete siblings like wp_delete_post. An agent can distinguish it from wp_update_term/wp_trash-style operations without opening a schema.

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

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

Gives concrete when-not conditions: the taxonomy's default term is not deleted and an unknown term_id errors, plus that a site can withhold delete_term for individual terms. It doesn't explicitly reference sibling alternatives (e.g. wp_update_term, wp_list_terms) for reassigning rather than deleting terms, so it stops short of full routing guidance.

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

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

Beyond the destructiveHint=true annotation, the description discloses that the operation is permanent with no undo point, that a two-step preview/confirm token flow gates execution, and that the guard is anti-accident rather than a reversibility mechanism. It also names the return fields and the token's 10-minute validity constraint.

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

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

Front-loaded with the action and the refusals, then the side effects, then the confirmation mechanism. Dense but every sentence carries information; the only waste is mild duplication of the two-step token flow already spelled out in 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, irreversible mutation with no output schema, the description still covers permissions, environmental refusals, return values, reversibility, and the confirmation protocol. Nothing an agent needs in order to call this 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 coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it frames confirm_token as an accidental-call guard that 'does not make the change reversible', which prevents an agent from misreading the token as an undo. Everything else (stylesheet format, token expiry) is already in the schema, so it does not reach 5.

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

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

States a specific verb and resource with scope ('Delete an installed theme's folder and files'), and explicitly separates itself from wp_activate_theme and wp_update_theme by naming what those siblings do instead. An agent can distinguish this from every other theme tool without opening a schema.

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

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

Gives explicit when-not conditions ('active theme and its parent theme are refused') and routes to the correct alternative in each case: wp_activate_theme to switch, wp_update_theme to upgrade without deleting. Also names the precondition (delete_themes capability) and the DISALLOW_FILE_MODS refusal.

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 destructive=true and idempotent=false, but the description goes well beyond them: permanence with no undo point, multisite limiting deletion to the current site, temporary admin-role removal with restoration on failure, partial-failure semantics (deleted + warning), and a concurrency lock with the caveat that wp-admin changes are not covered. This is unusually rich for a destructive 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?

Front-loaded with the action and the reassign branch before edge cases, and nearly every clause carries operational information. It is a dense semicolon-chained paragraph, though, and the plugin-hook failure clause is hard to parse on first read.

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 supplies the return values ("deleted and id"), and it covers permissions, multisite scope, role-restoration rollback, partial failure, and concurrency. An agent has everything needed to call it correctly or decide not to.

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, and the description adds real meaning: it spells out exactly what happens to the deleted user's posts and links when reassign_to is omitted versus supplied, and notes that 0 is equivalent to omitted. Only the id format is left entirely to 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?

Opens with a specific verb and resource ("Delete a user account"), which cleanly separates it from the read/create/update siblings (wp_get_user, wp_create_user, wp_update_user, wp_list_users). The scope — full account removal, not just site membership — is stated explicitly.

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

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

Gives concrete conditions for the two branches: supply reassign_to to hand content to another user, omit it to let WordPress trash/delete the authored content. It also states refusal cases (missing delete_users capability, last administrator, ab_mcp_busy, invalid reassign target). No sibling alternative is named, but there is no competing delete-user 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?

Goes well beyond the annotations: it discloses that the widget option is rewritten directly, bypassing the widget's own cleanup routines — a side-effect an agent cannot infer from destructiveHint alone. It adds that no undo point is recorded (relevant given the wp_undo sibling), describes the return payload ('deleted and id'), and defines the not-found reporting 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?

Four tight sentences, front-loaded with the action and its scope, then side effects, return shape, permanence, and the sibling alternative. No sentence is redundant with the title or annotations.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description supplies the return shape and the not-found case; the mutation's irreversibility and cleanup bypass are stated. For a one-parameter destructive tool, an agent has everything needed to call it correctly and understand the consequences.

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 documents the id format with an example ('text-2'). The description adds no further parameter detail such as format validation or behavior for malformed ids, so it neither compensates for nor exceeds the schema 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?

States a specific verb+resource pair ('Remove a widget instance from its sidebar and delete its settings'), and immediately distinguishes the case from wp_update_widget, which handles changing settings of an existing widget. An agent can tell this apart from wp_add_widget and wp_update_widget without opening any schema.

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

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

The closing sentence explicitly routes the adjacent-but-different case ('settings of an existing widget change with wp_update_widget'), giving clear selection guidance. It also defines the not-found condition. There is no explicit 'do not use for X' exclusion beyond that one sibling, but the context is unambiguous.

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

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

Annotations only say this is a non-idempotent, non-destructive write; the description adds substantial context beyond that: which fields are copied, which are never copied (credentials, edit lock, former slugs, caches, other plugins' protected keys), capability gating (unfiltered_html for builder markup), builder key atomicity, Elementor id renewal, and password-protection rules. It also discloses the return shape, which no output schema provides.

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

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

The purpose is front-loaded correctly, but the body is a single dense run-on cramming taxonomy terms, builder behavior, capability gating, exclusions, and return shape into one sentence chain. The content mostly earns its place, but scanning it for the relevant clause is hard.

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 tool with no output schema, the description covers permissions, exactly what will and will not be carried over, edge cases (media, password-protected posts, revisions), and the return payload. An agent has everything needed to call it correctly and predict the outcome.

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 single `id` parameter is fully described in the schema (100% coverage), so the baseline is 3. The description adds only that the caller needs read rights on the original and the ability to create entries of its type, which is permission context rather than parameter meaning.

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

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

The description opens with a specific verb and resource: copy an existing post or page into a new draft, with the original unchanged. It distinguishes the operation from wp_create_post or wp_get_post by making clear it produces a new draft derived from an existing entry, not a fresh record or a read.

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

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

It states the intended scenario (a starting point for a new page) and the key behavioral premise that each call creates another copy while the original is untouched. It does not name siblings such as wp_create_post or say when not to use it, so there is no explicit alternative 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?

Goes well beyond the annotations by disclosing what is and isn't touched: .htaccess is not rewritten and the permalink structure in Settings stays as configured. It also names the return value (flushed=true) and the required capability (manage_options), which the annotations do not convey.

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

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

Two dense sentences: purpose and trigger first, then the soft-flush caveats, then return value and capability. No filler and nothing buried.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Although there is no output schema, the description supplies the response shape (flushed=true) plus the permission prerequisite and the mutation's limits. Everything an agent needs to decide to call it and interpret the result is 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?

The tool takes zero parameters, so the schema needs no elaboration and the description correctly spends no words on inputs. Baseline 4 applies; no parameter-level value could be added.

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 ('Regenerate the permalink (rewrite) rules stored in the database') and immediately scopes it as a soft flush. An agent can distinguish it from cache-clearing siblings like wp_clear_cache or wp_cleanup_transients based on the permalink/rewrite-rule focus.

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

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

Gives a concrete trigger condition: use when posts, custom post types, or taxonomies return 404 after a structural change. What's missing is explicit routing to alternatives (e.g., wp_cleanup_transients when stale transients, not permalinks, are the cause) — no sibling is named.

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

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

Annotations already cover read-only/idempotent, but the description adds substantial context beyond them: locked elements are listed without content, an edit capability on the post is required (revision ids resolve to their post), an unknown id yields a not-found error, and layout_hash changes when any stored copy changes. It also discloses that field texts are author-written site content returned as data, which is meaningful prompt-injection guidance.

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

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

Front-loaded with the core action and return shape, then layers permissions and storage semantics. It is densely packed with semicolon-chained clauses, which costs some readability but every sentence carries distinct information rather than 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?

With no output schema, the description fully carries the return contract: outline structure, element fields, locked-element handling, and the meaning of storage, write_via and layout_hash. Permissions and error behavior are also covered, leaving nothing an agent needs before calling it.

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

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

Schema description coverage is 100% and all four parameters are fully documented there (including ranges, defaults and truncation marking), so the description need not restate them. It adds nothing parameter-specific beyond the schema, which is the expected baseline when the schema already does the work.

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 — reading a builder-built page as a compact outline — and enumerates exactly what the outline contains (builder, storage kind, data version, elements with id/type/parent/depth/text/link/image fields). It also carves out what it is not: styling is excluded and locked elements omit content, which separates it from a raw post read like wp_get_post.

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

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

Gives clear context for use (pages with a builder, plus a fallback rule that builderless pages are read as blocks) and flags that post_content is often just a copy the page does not display, implicitly steering agents here rather than to wp_get_post. It stops short of naming sibling tools as alternatives or stating when not to use it beyond the locked-element exclusion.

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

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

Goes well past the readOnly/idempotent annotations: it discloses error behavior for unknown ids and the required capability. Crucially it surfaces a non-obvious edge case — status can be `false` for post-trashed comments, stored as a distinct value — which an agent could not infer from 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?

Front-loads the action, then the return contract, then the edge cases and the sibling redirect — a sensible ordering with no filler sentences. The return-shape portion is dense with semicolon-separated clauses, which costs a little readability.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the full burden of explaining return values and does so field by field, including formats and timezone. Permission requirement and not-found behavior round out what an agent needs to call this correctly.

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

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

Schema coverage is 100% and the property already says "Comment id, as wp_list_comments returns it," so the baseline is 3. The description's "by id" adds nothing the schema does not already carry about the parameter itself.

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

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

Opens with a specific verb and resource ("Get one comment by id") and immediately scopes it to a single record versus the many-record sibling. No ambiguity with wp_list_comments, wp_moderate_comment, or wp_reply_comment.

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

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

Explicitly routes listing/filtered lookups to wp_list_comments, which is the main plausible alternative. It also names the required capability (moderate_comments), which functions as a gate condition. It stops short of stating when-not-to-use (e.g. to read a comment while moderating), so not a full 5.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the truncation cap (events holds at most the first 200 while count is the full total), that hook arguments are excluded from output, and the required capability (manage_options). These are exactly the operational facts annotations cannot express.

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 packed sentences, front-loaded with the resource and ordering, then output shape, then the truncation/auth caveats. No filler and nothing important buried at the end.

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 zero parameters and no output schema, the description carries the return-value burden and does so fully: total count vs. returned list, per-event fields, truncation, and access requirement. An agent can call and interpret this tool without further information.

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

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

The tool takes no parameters, so the baseline is 4. The description instead spends its space documenting output field semantics (next_run ISO 8601 UTC, schedule false for single events), which is appropriate given there is no output 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?

Specific verb+resource ('List the WP-Cron events scheduled on this site') plus ordering semantics ('soonest first') and the exact shape of each returned entry. No sibling tool covers cron events, so the resource alone distinguishes it from wp_list_plugins or wp_site_health.

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

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

It states the practical use case ('check whether a job runs and when'), which gives an agent a clear reason to call it, but offers no explicit when-not guidance or named alternative for related diagnostics.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds material context beyond them: the return shape (available, lines, log), that a missing file yields available=false with a message rather than an error, the manage_options capability requirement, the dependence on write access being on, and a warning that the log may contain paths, queries and plugin-written data.

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

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

Front-loads what file is read and why, then layers the return contract, auth requirement and sensitivity caveat. Densest passage is one long paragraph, but each sentence carries distinct operational value, so it stays efficient rather than padded.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, and the description compensates by naming the three returned fields and the non-error failure mode. Auth, environment preconditions and content-sensitivity are all covered, leaving nothing an agent needs in order to call it correctly.

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

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

Schema coverage is 100%, and the schema already documents the 1–500 clamp and the default of 100, so baseline 3 applies. The description does not add syntax for the input; its mention of "lines (the count returned)" actually refers to the output field of the same name, and the name collision with the input parameter risks mild confusion.

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

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

States a specific verb and resource — returns the trailing lines of wp-content/debug.log — and explains what that file contains (PHP errors, warnings, notices when WP_DEBUG_LOG is on). No sibling in the list touches logs, and the description makes the diagnostic purpose unmistakable.

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

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

Gives a clear use case ("for diagnosing failures") and an explicit scope exclusion ("a log written to another path is not read"), which prevents a wrong attempt. It does not name an alternative tool, but no sibling covers this ground, so there is little to route against.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral context on top: the exact return shape, what attachment metadata contains, an edge case (caption empty for password-protected files on accounts without edit rights), and a permission requirement ('Needs the right to read the file'). The distinct not-found failure mode for non-media ids is also 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?

Four sentences, front-loaded with the action and return shape before the edge cases and sibling routing. Every clause carries actionable information; nothing is repeated from the schema or annotations.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, yet the description enumerates the return contract and explains the metadata sub-object, plus error and permission behavior. Nothing an agent needs in order to call this correctly is missing.

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

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

Only one parameter, and the schema already documents it at 100% coverage ('Attachment id, as wp_list_media returns it'), so baseline is 3. The description earns a bump by constraining the id's domain — it must reference an actual media attachment, otherwise a not-found error results.

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 ('Get one file of the media library (attachment) by id') and immediately enumerates the returned fields. It explicitly separates itself from siblings: posts/pages go to wp_get_post and collections go to wp_list_media.

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

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

Gives both the when-not ('An id that is not a media file ... posts and pages are read by wp_get_post') and the alternative for listing ('wp_list_media lists the media with their ids'). An agent can route correctly without opening any other schema.

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 read-only, idempotent, non-destructive behavior, and the description adds what they cannot: the required capability (edit_theme_options), the not-found error semantics for an unknown menu, and the exact shape of the returned payload including how parent=0 marks top level.

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, front-loaded with the core action, followed by return shape and then the capability/error constraints. No filler and nothing repeated verbatim from the annotations.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description takes on the job of describing the return value, and it does so field by field. Combined with the auth requirement, error case, and pointer to the listing sibling, an agent has everything needed to invoke it correctly on the first try.

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 states the parameter accepts an id, slug or name as returned by wp_list_menus. The description echoes that usage without adding format, resolution-order, or edge-case detail, 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 opens with a specific verb and resource ('Get one navigation menu with its items'), states the ordering scope ('in menu order'), and explicitly distinguishes itself from the sibling wp_list_menus, which lists rather than retrieves a single menu.

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

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

It names the alternative for discovery ('wp_list_menus lists the menus') and notes the failure mode for an unknown menu, which effectively tells the agent how to find a valid identifier before calling. It stops short of an explicit 'use this when / don't use this when' statement, but the 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?

Goes well past readOnlyHint/idempotentHint by disclosing capability requirements (edit_posts, right to read, extra rights for password-protected posts and revisions), the not-found error on unknown ids, and the built_with/note behavior when a page builder overrides post_content. That is exactly the behavioral context annotations can't express.

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

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

Front-loaded with the core purpose and tightly packed; the builder/revision/permission sentences each carry unique information. The density is high but no sentence is redundant.

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 compensates by enumerating returned fields (post fields, raw content, meta overview, term names, built_with/write_via) and covers permissions, revisions, and error behavior. An agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: the id may be a post id from wp_list_posts/wp_search or a revision_id from wp_list_revisions, which is a non-obvious overloaded 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?

States a specific verb and resource — fetch exactly one post/page/entry of any post type by id — and enumerates what is returned relative to a named sibling ("the fields of wp_list_posts plus..."). This cleanly separates it from wp_list_posts, wp_search, and the builder-layout tool.

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

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

Gives concrete routing rules: pass a revision_id to fetch a revision, and use wp_get_builder_layout when post_content is not the rendered page. It lacks an explicit "use wp_list_posts instead when you don't have an id" statement, so one minor exclusion is missing.

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 declare read-only, idempotent, non-destructive behavior, but the description adds critical context beyond them: underscore-prefixed, protected, and credential-like keys are unavailable, access is gated by edit capability, and an unknown post id returns a not-found error. It also describes return shapes for single-key and all-key reads.

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 front-loaded: purpose first, then access restrictions, return shapes, error behavior, safety, and alternatives. Every sentence adds operational value, and no space is wasted on restating the name or 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?

With no output schema, the description carries the return-value burden and does so by describing both {id, key, value} and {id, meta: {key: value}} responses. It also covers access restrictions, unknown-post errors, and alternatives, making it complete for a two-parameter read tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds useful semantic detail about the key parameter: only public keys are returned when key is omitted, protected and credential-like keys are excluded, and a key with several stored values may yield a list in the all-keys response.

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: reading custom fields (post meta) of one post. It clearly distinguishes scope by saying one key or all public keys, and later names wp_get_post, wp_get_builder_layout, and wp_seo_get as related alternatives.

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 alternatives and when to prefer them: wp_get_post returns the same keys with the post, page builder layouts go to wp_get_builder_layout, and SEO fields go to wp_seo_get. It also states that keys are available only where the account may edit the post and key.

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

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

Annotations already declare readOnlyHint/idempotentHint true and destructive false, so safety is covered; the description adds genuinely new context: the edit_posts capability requirement, that it takes no arguments, and that internal types are deliberately included rather than filtered. It also documents the returned shape (name/label/public).

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

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

Front-loaded with the purpose, then result shape, then capability requirement, then the sibling pointer — four tight sentences with no filler. Nothing repeats what annotations or the (empty) schema already state.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description supplies the return shape itself; with no parameters and full annotation coverage, the auth requirement, scope, and sibling routing are everything an agent needs to call this correctly.

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

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

Zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. 'takes no arguments' reinforces this explicitly.

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

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

States a specific verb and resource ('List every post type registered on the site') and pins down scope precisely — built-in, custom, and internal types like revision/nav_menu_item. It also disambiguates from the adjacent wp_get_taxonomies sibling in the same sentence block, so an agent can pick correctly without opening a schema.

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

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

'name is the value the post tools take as type' tells the agent exactly when this tool is the right prerequisite (before filtering/creating posts by type), and 'Taxonomies are listed by wp_get_taxonomies' routes away to the alternative. Lacks an explicit 'do not use for…' exclusion, but the guidance is otherwise 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 carry readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered. The description earns credit by adding what annotations cannot express: the manage_options capability requirement and the two semantic edge cases (timezone empty under fixed UTC offset, permalink empty for plain permalinks).

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 doing distinct work: field inventory first, then edge-case semantics, then permissions/sibling routing. Zero filler and the payload 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?

No output schema exists, and the description compensates well by enumerating the returned keys and flagging which can be empty. Minor gap: the return shape (single object vs array) and value formats (e.g., date format string) are not stated, but an agent has enough to call and interpret the result.

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

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

Zero parameters, so baseline is 4. The description only confirms 'takes no arguments', which matches the empty schema; nothing more is needed or added.

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

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

States a specific verb+resource ('Get common site settings') and then enumerates the exact fields returned (title, tagline, url, wp_url, admin email, timezone, language, posts per page, date format, permalink). The final sentence explicitly routes versions/theme/plugins to wp_site_info, so it is distinguishable from its closest sibling without opening either schema.

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

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

Gives the prerequisite ('Needs manage_options') and names the alternative for adjacent data ('Versions, theme and plugins are reported by wp_site_info'). It stops short of an explicit when-not-to-use rule (e.g., don't call this for update-status checks), but the routing 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 read-only, idempotent, non-open-world, so safety is covered; the description still adds real value beyond them — the edit_posts capability requirement and the visibility rule that non-public taxonomies appear only for accounts that may assign their terms. The one gap is pagination/filtering behavior, though with zero args and a fixed registry that is minimal.

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

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

Purpose is front-loaded in the first clause, and every sentence carries distinct information (return shape, taxonomy-name contract, permissions, empty parameter list). It is dense with semicolon-chained clauses, which slightly taxes scanning, but nothing is filler.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description takes on the return contract and does it — it names the fields (name, label, objects) and explains what each is used for. Combined with the auth caveat and sibling routing, an agent has everything needed to call it and use the result.

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

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

Zero parameters, so the baseline is 4. The description correctly confirms 'takes no arguments', which matches the empty schema and prevents an agent from fishing for filter options.

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

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

Opens with a specific verb+resource ('List the taxonomies registered on the site') and immediately scopes it ('built-in category and post_tag included'), which distinguishes it from wp_list_terms and wp_get_post_types named later. An agent knows exactly what this returns 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?

Routes explicitly to siblings: taxonomy names are what the term tools take, terms themselves come from wp_list_terms, and post types come from wp_get_post_types. That is clear situational context, but it never states an explicit 'call this before X' prerequisite or when-not-to-use beyond the sibling pointers.

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

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

Annotations already cover read-only, idempotent, non-destructive, so the bar is low, yet the description still adds what annotations cannot: the exact return shape, the meaning of 'count' and 'parent', the capability needed for non-public taxonomies, and the not-found failure mode.

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

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

Front-loaded with the action, then the return shape, then the routing hints — no wasted sentences. The enumerated return fields are dense but each earns its place since there is no output 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 two-required-param read tool with no output schema, the description supplies everything missing: return fields, field semantics, permission prerequisite, error behavior, and sibling routing. Nothing an agent needs to call it correctly is absent.

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

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

Schema description coverage is 100% and both parameters are documented there, including the cross-reference to wp_list_terms for obtaining the id. The description adds no format or edge-case detail about term_id/taxonomy beyond what the schema states, so baseline 3 applies.

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

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

States a specific verb and resource ('Get one term by id and taxonomy') and immediately distinguishes itself from wp_list_terms (name/slug search) and wp_get_term_meta (custom meta). An agent can pick it out of the crowded taxonomy sibling set 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?

Explicit routing: terms known only by name/slug go to wp_list_terms, meta goes to wp_get_term_meta, and the id+taxonomy pair is the entry condition here. It also names the alternative tool by name rather than gesturing vaguely at one.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: underscore-prefixed, WordPress-protected and credential-like keys are withheld, non-editable keys are filtered out in the no-key mode, and unknown term_id returns a not-found error. It also discloses the return shapes for both modes.

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

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

Front-loaded with purpose and mode, then permissions and return shapes; every sentence carries information. It is dense with parentheticals and semicolons, which makes it slightly harder to scan than a cleaner multi-sentence layout would be.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and only two parameters, the description supplies exactly what is otherwise missing: the two return shapes, permission requirements, key-filtering rules, and error behavior for a bad term_id. An agent can call this correctly without further inference.

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

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

Schema coverage is 100%, so both parameters are already documented, and the description largely restates the omit-key behavior the schema describes. The added meaning (first value returned when several are stored, list shape only in the all-keys mode) is useful but sits closer to return-value documentation than parameter semantics.

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

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

States a specific verb and resource ("Read custom meta of one term") plus the two modes: a single key or all public keys. It explicitly separates itself from wp_get_term ("the term's own fields come from wp_get_term") and from the post-meta sibling by scoping to 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?

Gives clear conditions: omit the key to read all public keys, pass a key for one value, and use wp_get_term for the term's own fields. Also states the permission gate (right to assign terms of the taxonomy; edit right for a single key). It stops short of naming when a caller should prefer post/user meta siblings, but for this domain the routing 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description still adds substantive behavior: results are cached rather than fetched, no remote request is made, and the cache refreshes roughly twice daily. It also discloses the capability requirement ('Needs update_core'), which annotations cannot express.

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 dense sentences, front-loaded with the verb and resource, then the caching caveat, then the return shape. Every sentence carries information an agent would otherwise have to guess.

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 supplies the exact return structure (core object, plugins and themes arrays with their field names) and explains that empty lists mean no known update rather than a failed check. Nothing needed to call this correctly or interpret its result is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description correctly spends no space on parameters and instead documents the return shape.

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 ('Report available core, plugin and theme updates') and immediately scopes it to WordPress's own last scheduled check, which separates it from sibling inventory tools like wp_list_plugins and wp_list_themes that list installed items rather than pending updates.

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 parenthetical 'read-only, cached data; triggers no remote request' plus 'WordPress repeats that check on its own, about twice a day' tells an agent exactly when this tool is appropriate and when its data is too stale to act on. It stops short of naming an alternative path for forcing a fresh check, so no explicit when-not routing is given.

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

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

Annotations already declare readOnly/idempotent/openWorld=false, and the description adds genuinely non-derivable behavior: required capability, the exact returned fields, that 'registered' is site time with UTC offset, and that no match or no identifier yields a not-found error rather than a default.

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 dense sentences with no filler: lookup keys first, return shape second, error/failure routing third. Every clause carries information an agent needs.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, yet the description enumerates the returned fields and timezone handling, covers the error path, and points to the two relevant sibling tools. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% and the schema already documents precedence, so the baseline applies; the description adds the consequence of supplying none of the three keys (not-found error), which the schema does not state. It does not add format details beyond that, so it sits just above 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?

Names a specific verb+resource (get one user account) and enumerates the three lookup keys, so it is immediately distinguishable from wp_list_users. The scope ('one user') is explicit, ruling out bulk retrieval.

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

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

Explicitly routes partial-name lookups to wp_list_users (search) and meta reads to wp_get_user_meta, both named as siblings. It also states the prerequisite capability ('Needs list_users'), giving when-to-use and when-not-to-use in three sentences.

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

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

Annotations declare read-only/idempotent, and the description adds real value beyond them: the fixed key allowlist, the exact refusal behavior for other keys, the permission model (list_users + edit rights, admin in standard roles), and the not-found error for an unknown user_id. Consistent with readOnlyHint; 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?

Front-loaded with purpose, then constraints, then return shape, then permissions. Dense and mostly waste-free, though the allowlist and permission sentences could be slightly tightened.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description compensates by describing both return shapes ({user_id, key, value} and {user_id, meta: {...}}). With the allowlist, permission model, and error behavior covered, an agent has everything needed to call it 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 baseline is 3, but the description adds meaning: it enumerates the valid values for `key` and states that omitting it returns all fields, which is only partly mirrored in the schema. It also notes where author ids come from, though that duplicates the schema text.

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 ('Get standard profile fields (user meta) of one user') and immediately clarifies the two modes: one field or all of them. Clearly distinct from siblings like wp_get_user (full profile) and wp_get_term_meta (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?

Explicitly defines the allowlist of readable keys and states that any other key is refused, plus the permission requirements and not-found behavior. It does not explicitly contrast against wp_get_user or wp_list_users, so the alternative-selection guidance is implicit rather than stated.

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

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

Goes well past the annotations: discloses the required capability (edit_theme_options), the exact return shape, that sidebar is empty for orphaned widgets, and — most importantly — that credential-like settings are redacted and reported in hidden_keys. That redaction behavior is non-obvious and would be surprising if undocumented.

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

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

Front-loaded with purpose and default scope, then the return shape, then the caveat, then the permission requirement. Dense and largely waste-free, though the return-shape enumeration reads as a run-on that could be a single compact line.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With one optional parameter, no output schema, and simple read-only annotations, the description covers everything an agent needs: default behavior, return fields, redaction semantics, and the required capability. Nothing material is left to guess.

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 value by stating the id format ("text-2"), that an empty sidebar means the widget belongs to no area, and what omission does. It stops short of saying whether an invalid area id errors or returns empty.

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

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

Specific verb and resource ("List the site's widgets with their settings") plus the returned field list {id, id_base, number, name, sidebar, settings}. It also distinguishes itself from the neighboring areas tool by naming wp_list_sidebars, so an agent can separate the two without opening either schema.

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

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

States the selection behavior precisely: omitted sidebar lists all areas including inactive widgets, providing sidebar narrows to one area, and points to wp_list_sidebars when the agent actually wants areas rather than widgets. The when-to-use condition and the alternative are both explicit.

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

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

Goes well beyond the destructiveHint/openWorldHint annotations: discloses that no undo point is recorded, that a failed activation health check is rolled back in the same call while the install persists, and that the error carries file and line. That is exactly the mutation-safety context an agent needs before calling 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?

Purpose and constraints are front-loaded and nearly every clause carries information. The final sentence is a dense run-on that packs rollback, error format, and persistence into one chain, costing some readability.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description still enumerates the return fields (installed, plugin file path, activated, version) and the activation-check report, plus error behavior and edge cases. Nothing material is missing for a 2-parameter destructive tool.

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

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

Schema coverage is 100%, so both parameters are already documented; the description still adds meaning by tying `activate` to the activate_plugins capability and to the post-activation health-check/rollback behavior. Only marginal gain over the schema, so not a 5.

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

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

States a specific verb + resource plus the source constraint ("from the WordPress.org directory by slug") and the optional activation, which implicitly separates it from wp_install_plugin_zip. An agent knows exactly what gets installed and from where 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?

Names the required capabilities (install_plugins, activate_plugins), the refusal condition (DISALLOW_FILE_MODS), and the correct alternative for the upgrade case (wp_update_plugin). It also defines the no-op case when the folder already exists, so the agent knows when this call accomplishes nothing.

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: it discloses 'no undo point is recorded', the two-step preview/confirm_token guard and its 10-minute validity, no-op behavior when the plugin folder already exists, and an activation rollback if the site gets worse, with the error naming file and line while the install persists. These are exactly the mutation-side risks the destructive/openWorld hints flag but do not explain.

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

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

Front-loaded with the core action and packed with information-dense clauses; every sentence carries real content. It is a single long block with several run-on constructions (source precedence, version handling, activation check, confirm flow all in one paragraph), which costs some readability.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, 5-parameter, no-output-schema mutation tool, the description covers return values ('installed, plugin, activated' plus activation check output), failure modes, idempotency behavior, and the confirm workflow, so an agent can invoke it correctly without further guessing.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds semantics the schema lacks: the precedence order among session/content/url, the default 30 MB limit shared across sources, and session's dependence on AlphaBridge MCP Pro being active.

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 (install a plugin from a ZIP archive) and immediately distinguishes itself from wp_install_plugin (directory plugins by slug) and wp_update_plugin (upgrading an already-installed plugin), while also implicitly separating it from wp_install_theme_zip by naming the resource '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?

Gives explicit source-selection rules ('A session given is used first, then content, then url'), routes directory installs to wp_install_plugin and upgrades to wp_update_plugin, and states prerequisites (install_plugins, activate_plugins) plus the DISALLOW_FILE_MODS refusal condition. Nothing about when to use it is left 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 annotations already flag this as destructive, non-idempotent, non-read-only, and open-world, and the description adds meaningful context beyond them: no undo point is recorded, existing folders are not replaced, the result is an error, and specific WordPress capabilities can block the call. It also describes return fields, which helps the agent understand the outcome.

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 front-loaded: it leads with the action and non-activation behavior, then covers return data, permissions, failure conditions, and alternatives. Every sentence provides actionable 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?

Although there is no output schema, the description lists the key return fields and explains constraints, failure behavior, and alternative tools. For a one-parameter mutation tool, this provides everything needed to call it correctly.

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

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

The schema already documents the slug format and normalization rules at 100% coverage. The description reinforces that the slug comes from WordPress.org and mentions the returned stylesheet, but it does not add substantial parameter semantics 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 verb and resource: download and install a theme from the WordPress.org directory by slug. It immediately clarifies that activation does not happen, and it distinguishes this from ZIP installation and theme activation by naming the relevant 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?

It explicitly names alternatives: use wp_install_theme_zip for ZIP themes and wp_activate_theme to switch themes. It also states prerequisites and refusal conditions, including install_themes and DISALLOW_FILE_MODS.

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?

Far beyond the annotations: it explains the two-step confirm_token preview gate, that a failed activation check is rolled back in the same call while the install persists, that no undo point is recorded for the install, that an existing folder short-circuits to a no-op naming the installed version, and the exact permission/constant gates. Annotations only say destructive and non-idempotent; the description carries the real 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 core (what it installs, from what sources, in what order) is front-loaded, and everything after earns its place given the tool's complexity. It is still a dense block — the activation-check and undo paragraphs could be tightened — but nothing is filler.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, yet the description names the returned fields (installed, stylesheet, activated) and the undo entry behavior, and covers the destructive semantics, permission gates and confirmation flow. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% and the schema descriptions already document the source precedence, the 30 MB cap and the 10-minute token validity, so the description mostly restates them. The consolidated precedence statement adds marginal value over the per-property text but no new semantics.

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

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

Opens with a specific verb+resource (install a theme from a ZIP archive) and immediately distinguishes itself from wp_install_theme, which handles WordPress.org slugs. An agent can route between the two without opening the 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?

Gives an explicit source-precedence rule (session first, then content, then url), names the sibling for directory slugs, and routes version bumps to wp_update_theme. It also states permission requirements and the DISALLOW_FILE_MODS refusal condition, so when-to-use and when-not are both covered.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description still adds substantive behavior: an empty list means no passwords, last_used is null when never used, dates are ISO 8601 UTC, the password itself is never returned, and an environment lacking application-password support produces a stated error. That is exactly the security- and failure-related context an agent needs for what is nominally a credentials-adjacent read.

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

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

Front-loaded with the verb, resource and return shape, and every clause carries information (permissions, environment requirement, empty-list meaning). It is a dense semicolon-chained sentence, which costs some readability but wastes nothing.

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 compensates by describing the returned object shape, date format, and null semantics. It also covers prerequisites, the environment precondition, and error behavior, leaving nothing an agent needs in order to call it correctly.

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

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

Schema coverage is 100% and the single user_id parameter is fully documented in the schema, including the not-found behavior, so the schema does the heavy lifting. The description's ISO 8601 and null-last_used notes describe the return payload rather than adding meaning to user_id, 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 gives a specific verb and resource — 'List the application passwords of one user' — plus the exact return shape, which makes the resource unambiguous against siblings like wp_list_users or wp_get_user_meta. It never names a sibling or states the boundary explicitly, so it falls just short of a 5.

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

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

'Suited to reviewing which applications can sign in as that user' gives a concrete use context, and the description adds real preconditions: needs list_users and the right to edit the target user (administrators in standard roles), plus HTTPS or a local environment. It does not compare against alternative tools or say when not to use it, so no explicit exclusion.

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

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

Annotations already cover read-only/idempotent/non-destructive, and the description adds genuinely new behavioral facts: pagination with per_page and page, that no total count is returned, that an out-of-range page returns empty, and the required capability moderate_comments. That is exactly the context annotations cannot carry.

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

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

Front-loaded with the verb and ordering, then filters, then return shape, then paging caveats, then permission and sibling pointer. Dense but every clause carries information; nothing is padding.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description supplies the return shape verbatim, the date format, the permission requirement, and the pagination edge case. For a paginated read tool, an agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100% and the schema documents every parameter's default and clamping. The description does add the domain vocabulary for status values ('approved', 'unapproved', 'spam', 'trash'), but this actually diverges from the schema's approve/hold tokens, so it neither supersedes nor cleanly extends the schema.

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

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

States a specific verb and resource ('List comments'), adds ordering ('newest first') and the filter dimensions (status, post, search text). This distinguishes it cleanly from wp_get_comment, which it names explicitly as the single-comment alternative.

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

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

The closing clause 'wp_get_comment returns one comment with its parent' gives an explicit alternative, and the filter enumeration implies when to use it. It stops short of stating exclusions, e.g. that this is not the tool for moderation or replies (which wp_moderate_comment handles), so it's clear but not fully bidirectional.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds real substance: the exact status filter applied, the capability requirement (upload_files), permission-scoped results, and the empty-result behavior. That is context an agent cannot derive from 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?

Four tight sentences, front-loaded with the purpose and ordering, then results, then filters, then the sibling pointer. Every clause carries information; nothing is redundant with the schema or annotations.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so spelling out the returned item shape ({id, title, mime, url, date}) and pagination fields ({total, total_pages}) is necessary and present. Combined with the filtering and permission notes, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100%, so baseline is 3; the description earns above that by linking 'search' to a change in sort order (relevance instead of newest first), which the schema does not state. The mime and pagination parameters are left entirely to the schema, keeping it from a 5.

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

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

States a specific verb and resource ('List files in the media library (attachments)') plus the ordering rule, which is exactly what distinguishes it from a generic list. It also names the sibling wp_get_media and what that one returns, so an agent can route without opening either schema.

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

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

Gives clear operating context: search switches ordering to relevance, only 'inherit'-status files are returned, private files are excluded, and the account needs upload_files. It routes to wp_get_media for single-file detail, though it frames that as a statement rather than an explicit 'use X when' rule, so it stops short of the top band.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closedWorld, so safety is covered structurally. The description adds genuinely new context: the required capability edit_theme_options, and the shape of the payload including the meaning of count as number of items.

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, zero filler. The positive statement of what is returned comes first, then the read-only/permission note, then the alternative — all front-loaded where the agent needs it.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return-shape burden and does so by naming the fields and the enclosing key. Permission requirement and the sibling alternative are both disclosed, leaving nothing an agent needs in order to call this correctly.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies the tool is unfiltered and returns everything at once.

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

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

Specific verb+resource ("List the navigation menus of this site") plus the exact returned fields (id, name, slug, count) and the wrapper key (menus). It is immediately distinguishable from the sibling wp_get_menu, which is named as the item-level counterpart.

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?

"all at once" signals there is no pagination or filtering, and the final sentence routes the agent to wp_get_menu when it actually wants the items inside a menu. There are no explicit exclusions or prerequisites for calling this over other list tools, but the relevant alternative is named with its trigger condition.

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

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

Annotations already declare a safe, idempotent read, and the description adds real context beyond them: the exact return shape (one entry per plugin with file, name, version, active), the multisite caveat that network-activated plugins show false, and the capability required. These are non-obvious behavioral details an agent would otherwise get wrong.

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

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

Front-loaded with the action and scope in the first sentence, with caveats and return fields following. Dense but every clause carries information; slightly run-on, packing returns, exclusions, and permissions into one block, but nothing is wasted.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description must explain the return value itself — and it does, enumerating file/name/version/active plus the meaning of 'active' on multisite. Combined with the capability requirement and the exclusion list, nothing an agent needs to call and interpret this correctly is missing.

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

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

The tool takes zero parameters, so the baseline applies. The description correctly spends no effort on parameters and instead documents the output fields, which is the right allocation.

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

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

Specific verb + resource ("List the installed plugins in wp-content/plugins") with an added scope qualifier ("all in one answer (no paging)"). It is clearly distinguishable from wp_get_update_status, which it names, and from unrelated siblings like wp_list_themes or wp_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?

Gives explicit exclusions (must-use plugins and drop-ins are not listed), routes the agent to the alternative for a related need ("Pending updates are reported by wp_get_update_status"), and states the prerequisite ("Requires activate_plugins"). An agent can decide when to call this versus the alternative without 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 cover readOnly/idempotent/non-destructive, and the description still adds real behavioral context: an edit_posts permission requirement, visibility scoping tied to the account, empty-list-on-no-match semantics, and the fact that content is deliberately excluded from results. These are facts an agent cannot obtain from the annotations or schema.

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

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

Front-loaded with purpose, then return shape, then constraints and sibling contrasts — no filler sentences. It is a dense single paragraph, and the inline result-field enumeration is long but earns its place given there is no output schema.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With ten optional parameters and no output schema, the description compensates by spelling out the returned item fields, the pagination envelope, the content exclusion, and the permission requirement. Nothing an agent needs to call this list tool correctly is missing.

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

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

Schema description coverage is 100%, so every one of the ten parameters is already documented in detail, including the built_with matching semantics and per_page clamping. The description only alludes to 'filters, sorting and pagination' generically and adds no parameter-level meaning beyond the schema, so baseline 3 applies.

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

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

Opens with a specific verb and resource plus the actual scope: 'List posts, pages or entries of any post type, with filters, sorting and pagination.' It then explicitly separates itself from wp_get_post (content retrieval) and wp_search (single keyword search, no paging), so an agent can distinguish it from all three nearest 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 names the alternatives (wp_get_post for content, wp_search for one-off keyword search without paging) and gives the condition that selects them, which is clear routing context. However it never states an explicit 'use this instead when…' rule for the list-vs-search decision, so the agent still has to infer the primary use case for a multi-filter listing.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the bar is lower; the description still adds real value with newest-first ordering, the empty-list conditions, and the 'right to edit the post' permission requirement. Missing only edge details like pagination or revision caps.

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 tight sentences, front-loaded with purpose and ordering, then return shape, then edge cases and prerequisites. No filler.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by specifying the return shape ({revision_id, date, author}), the RFC 3339/site-time format of date, that author is a user id, and the empty-result conditions. An agent has everything needed to call and interpret it.

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

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

Schema coverage is 100% and the single id parameter is fully documented in the schema; the description restates the same meaning without adding format or constraint detail. Baseline 3 applies.

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

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

States a specific verb and resource (list stored revisions of one post or page) plus scope and ordering (newest first). It also distinguishes itself from wp_get_post by explaining that revision content comes from that sibling.

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

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

Explicitly states the prerequisite (right to edit the post) and the follow-up path (use wp_get_post with a revision_id to get content). It does not cover when-not-to-use or contrast against wp_list_posts, so not a full 5.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world, so the description correctly doesn't restate them. Instead it adds genuinely new behavioral facts: the edit_theme_options capability requirement, the return entry order, and the notable edge case that block themes with no widget areas yield only the wp_inactive_widgets entry.

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 compact sentences, front-loaded with the return shape, then the edge case, then the capability requirement and the sibling pointer. Every sentence carries distinct information with no repetition of the name or annotations.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description fully compensates by describing the returned fields and the special wp_inactive_widgets entry. Combined with the permission note and the no-argument statement, an agent has everything needed to call and interpret it.

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

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

Zero parameters, so the baseline is 4. The description reinforces this with 'takes no arguments', matching the empty schema and leaving no ambiguity for the agent.

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

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

States a specific verb (list) and resource (widget areas/sidebars registered by the active theme) and immediately gives the return shape. It is clearly distinguished from the closest sibling wp_get_widgets, which is named for the contents of an area rather than the enumeration of areas.

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

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

Gives the prerequisite (needs edit_theme_options) and redirects to wp_get_widgets for widgets and their settings, which is clear routing context. It stops short of an explicit 'do not use this when...' exclusion, so a 4 rather than 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 cover read-only, idempotent, non-destructive, so the description's extra context is what matters: it discloses the hard pagination ceiling ('no further pages'), the permission requirement for non-public taxonomies, and the return field shape. Return format is fully explained for a tool with no output schema; only rate/error behavior is left implicit.

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 dense sentences, front-loaded with scope and ordering, then return shape, then the pagination/permission caveats, ending with the sibling pointer. Nearly every clause earns its place; the return-shape inline listing is slightly compressed but justified given there is no output 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?

Covers what the tool does, its ordering, its pagination boundary, permission prerequisites, the shape and meaning of returned fields, and the sibling that fetches a single term. Since no output schema exists, including the return structure here is exactly the right compensation.

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 taxonomy, search, per_page, and hide_empty are already documented; the description mostly repeats the per_page limit. It does add meaning for the returned 'count' and 'parent' fields, but those are output semantics rather than parameter semantics, so the baseline 3 holds.

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

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

States a specific verb and resource ('List the terms of one taxonomy'), names the taxonomy kinds, and specifies ordering. It also distinguishes itself from a named sibling ('wp_get_term returns one term with its description'), so an agent can route between them without opening either schema.

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

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

Gives clear usage context: one taxonomy per call, terms of a non-public taxonomy require the right to assign them, and only the first per_page matches come back. The wp_get_term pointer supplies an implicit alternative, but there is no explicit 'use this instead when…' exclusion (e.g., for enumerating across taxonomies).

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

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

Annotations already cover the read-only/idempotent safety profile, and the description goes well beyond them: no pagination, broken themes (folder without style.css) are silently omitted, and the subtle active-flag semantics where a parent of an active child theme reports false. That last detail is exactly the kind of non-obvious behavior an agent cannot infer from structured fields.

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

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

Front-loads the capability ('all in one answer') in the first clause and then packs return values into a single dense sentence. Every clause carries information, though the return-value sentence is lengthy enough that it would benefit from being split for scanability.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return-shape burden and does so fully: per-theme fields (slug, name, version, active), slug format for collection themes, exclusion of broken themes, and the capability gate. An agent has everything needed to call this and interpret the result.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. The description correctly spends no space restating an empty 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?

Opens with a specific verb+resource ('List the installed themes') and immediately distinguishes its scope with 'all in one answer (no paging)'. It is clearly separable from siblings such as wp_list_plugins and wp_get_update_status, which it explicitly hands off to.

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

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

Gives concrete selection context: use this for the full unpaged inventory, and use wp_get_update_status for pending theme updates. It also states the capability prerequisite (edit_theme_options). It stops short of explicit when-not-to-use framing, but the routing to the update-status sibling covers the main ambiguity.

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 a safe, idempotent read, but the description adds genuinely new behavior: pagination semantics, the capability required ('Needs list_users'), and the actual return payload (id, login, email, name = display name, roles) plus 'total' spanning all pages. It only stops short of stating default page size or ordering, so a 4 rather than a perfect 5.

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

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

Three tight sentences: purpose and scope first, return shape second, disambiguation third. No filler, and the most decision-relevant 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?

With no output schema, the description compensates by listing the returned fields and the 'total' count, and it discloses the required capability. Combined with a fully documented 4-parameter schema and read-only annotations, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100% and the schema already spells out page, role slugs, per_page clamping and the intricate search-term matching rules in more detail than the description does. The description only restates 'filtered by role or a search term' and 'one page at a time', so the baseline 3 for full schema coverage applies.

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

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

States a specific verb and resource ('List the user accounts of this site') plus the scope constraint ('one page at a time, optionally filtered by role or a search term'), and explicitly names wp_get_user and wp_get_user_meta as the tools for single-account and profile-field needs, so it is distinguishable from its user-related 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?

Gives explicit routing rules: this tool for enumerating accounts, wp_get_user for a single account with first/last name and registration date, wp_get_user_meta for profile fields. The alternative and the condition that selects each are named directly, leaving nothing 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?

Beyond the annotations, it discloses the return shape, caveat that the response does not confirm storage, required capabilities, public visibility and author notification effects, reversibility, EMPTY_TRASH_DAYS behavior, note-reply trashing behavior, and not-found errors. These are substantial behavioral details for a destructive mutation tool.

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

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

The core action and return shape are front-loaded, and the remaining sentences carry important caveats about permissions, public effects, trash irreversibility, and note descendants. It is dense and somewhat long, but most of the detail earns its place for a destructive 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?

For a destructive moderation tool with no output schema, the description covers side effects, permissions, reversibility, edge cases, error behavior, and alternatives. An agent has enough information to invoke it correctly and understand the consequences.

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 enum and comment_id are already documented. The description still adds useful semantics: what approve, hold, spam, and trash do, that hold means pending, and that an unknown comment_id returns not-found.

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: setting the moderation status of one comment, and enumerates the four supported statuses. It also distinguishes the tool from wp_delete_comment by saying outright deletion is handled there.

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 explains the effect of each status, names wp_get_comment for checking stored status, and routes outright deletion to wp_delete_comment. It also warns when approving makes the comment public and when trashing becomes permanent, which directly guides use.

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: states each call creates a new comment so repeats duplicate (matching idempotentHint=false), that the comment is saved approved and immediately visible, that no WordPress new-comment emails are sent, that the email is stored, and that HTML filtering applies. It also discloses two explicit non-checks (comments open, parent exists) and the return shape '{created: true, comment_id}'.

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

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

Dense but front-loaded: the create semantics and duplicate-call warning come first, then visibility/side effects, then limits and permissions, then sibling routing. Every sentence carries distinct information; nothing is padding.

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