AlphaBridge MCP for WordPress

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

With annotations flagging destructiveHint=true and readOnlyHint=false, the description explains the destructive mechanism precisely: each call replaces the previously issued link, which then stops working even if an addition with it has started. It also discloses the 10-site cap, that no link is returned at the cap, and the ten-minute validity window — none of which the annotations 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 core action is front-loaded and the important constraint — the 10-site cap and refusal behaviour — arrives early. The text is a bit baggy, repeating "adds one site" three times and packing the link-invalidation race condition into a single dense closing sentence.

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

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

For a no-argument tool with no output schema, the description covers everything an agent needs: what it returns, the failure condition, the link lifetime, and how a subsequent call invalidates the previous link. Nothing essential is left to 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?

There are zero parameters, so the baseline is 4. The description explicitly confirms "Takes no arguments" and then enumerates the JSON fields returned (add_site_url, note, connected-site labels, site_limit), which preempts questions an agent might otherwise have about what to supply.

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

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

The opening sentence names a specific verb and artifact: it returns a one-time link that adds one more site to this connection. It also clarifies what it does not do (no site is added until the link is used), which keeps it clearly separate from connect_status and the wp_* mutation 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?

"Suited to connecting a further site; the sites already connected stay as they are" gives clear context for when to call it. It also states the hard precondition of at most 10 sites, at which point the call is refused. It never names an alternative tool or an explicit avoiding case, so it falls 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 beyond the annotations: explains the tool reads AlphaBridge Connect's own record without contacting any site, that each call mints a fresh ten-minute disconnect link, that the previous link is invalidated, that confirming the old link voids the new one, and that the connection only ends after browser confirmation. Those are the kind of irreversible, stateful mechanics an agent cannot infer from the destructiveHint alone.

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

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

The core purpose comes first, followed by the return shape, then usage, then the link lifecycle. The single dense run-on listing all returned fields is heavy, but every clause carries operational meaning and 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?

There is no output schema, so the description documents the JSON answer field by field (label, address, CMS/version, plugin edition, scope, status/last_error/last_ok_at, linked_since, taken_out, disconnect_url). It also covers the destructive path end to end, so nothing an agent needs before calling 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?

Zero parameters, so the baseline is 4. The description states 'Takes no arguments' explicitly, which matches the empty schema and closes any doubt.

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: reports reachable sites and returns a one-time link that ends the connection. The disconnect side effect is named up front, which distinguishes it from connect_add_site and from all the wp_* per-site tools in the sibling list.

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 two use cases: checking which sites are connected and why one fails, and ending the connection with every site in it. It does not name a sibling as an alternative or state when not to use it, which keeps it below a 5.

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

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

Annotations only flag destructive/non-idempotent; the description goes far beyond by disclosing the full rollback protocol: pre/post test requests against four targets, automatic deactivation (without deactivation routine) on a new fatal error or lost endpoint response, error answers naming file and line with files left untouched, and pre-existing fatals keeping the activation with a warning. It also scopes what is NOT checked (other admin screens, cron, AJAX, other users) and notes that activation-routine DB writes persist — unusually complete behavioral context for a destructive mutation.

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

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

Front-loaded correctly: purpose, identifier format, and sibling routing come first, with caveats after. It is long and sentences are dense (the fastcgi_finish_request/exit-in-shutdown clause is niche), but nearly every sentence carries decision-relevant information, so the length is largely justified 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?

For a destructive, non-idempotent, no-output-schema tool, the description covers permissions, concurrency, rollback, error-answer content, warnings, and known blind spots. There is no output schema, and the description compensates by describing what the answer/error will contain, leaving no significant gap for correct invocation.

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

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

Schema coverage is 100% and the schema already gives the folder/main-file format with examples, so the description is not required to carry this. It still adds a small amount by tying the value to wp_list_plugins as the source of truth, telling the agent where to obtain a valid identifier rather than guessing.

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 ("Activate an installed plugin on this site") and immediately pins the identifier format to the same one wp_list_plugins returns. It explicitly distinguishes itself from wp_install_plugin and wp_network_activate_plugin, so an agent can pick the right tool 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?

Names both competing siblings and the condition that selects each: installing goes to wp_install_plugin, multisite network activation goes to wp_network_activate_plugin. It also states prerequisites ("Needs activate_plugins") and a runtime constraint (only one activation/update/deploy at a time, a second is refused), which is exactly the guidance an agent needs before calling.

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 destructive/non-idempotent annotations, it discloses the undo snapshot and its "undo" token, the pre/post smoke tests across home page, MCP endpoint, admin-post.php and dashboard, automatic rollback with file/line error reporting, the pre-existing-fatal-error and "not checked" edge cases, and a concurrency lock. That is a genuinely uncommon level of disclosure for a mutating 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 critical facts (what it does, what it refuses, that it rolls back) are front-loaded, so it is well ordered. But it is a single dense paragraph of semicolon-chained clauses, and some caveats (background work in WP-Cron, the not-checked list) could be trimmed or split for readability without losing the contract.

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 tells the agent what comes back: the "undo" token, its null case, and that errors name the offending file and line. It also scopes what is explicitly not verified (other admin screens, cron, AJAX), so an agent knows the limits of the guarantee it is given.

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 `theme` parameter is already documented with the folder/slug convention and the child-theme caveat. The description repeats that naming rule and adds the useful pointer that wp_list_themes is how you discover valid values, but it contributes little beyond the schema — 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 ("Switch the active theme to an installed theme") and immediately distinguishes itself from the sibling that installs (wp_install_theme) and the one that lists (wp_list_themes). An agent can tell exactly what this does and what it does not do 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?

The install-vs-activate split plus the slug-naming pointer to wp_list_themes gives clear selection context, and the description enumerates the conditions under which activation is refused (broken child theme, network restriction, unmet PHP/WP requirement). It lacks only an explicit "use wp_update_theme instead when..." routing for the adjacent update/deploy operations, so it lands just below the top.

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

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

Goes well beyond the annotations: discloses that no undo point is recorded (critical given wp_undo exists), that duplicates are created on repeat calls, that disallowed URL schemes (javascript:, data:) are refused, and that edit_theme_options is required. These are exactly the failure modes an agent could not infer from destructiveHint/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?

A single front-loaded paragraph that leads with the action and its two modes before consequences and caveats. It is dense and slightly run-on, and the closing AlphaBridge forwarding sentence is scoping context rather than tool behavior, but nothing 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?

A six-parameter mutation tool with no output schema, and the description compensates by naming the return shape ("added and item_id") plus permissions, duplication behavior, and undo absence. An agent has everything needed to call it correctly and anticipate 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?

Schema coverage is 100% and every one of the six parameters is already documented in the schema. The description reinforces the object_id/url precedence but adds no syntax, default, or format detail the schema does not already carry, so the baseline 3 applies.

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

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

Specific verb plus resource ("Add a published item to a navigation menu") with the two operating modes spelled out: a content link when object_id is given, otherwise a custom link to url. An agent can distinguish it from wp_create_menu (creates the menu itself) and wp_delete_menu_item (removes items) 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 names the removal counterpart (wp_delete_menu_item) and the capability prerequisite (edit_theme_options), and clarifies the object_id-vs-url selection rule. It does not explicitly state when to reach for wp_create_menu or wp_get_menu first, so it stops short of full when/when-not framing.

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 explains that settings pass the widget's own update() sanitisation and widget_update_callback filter, that HTML is filtered unless the account may post unfiltered HTML, that invalid input saves nothing, and that no undo point is recorded. The connection-scope note ('forwarded to the one site this connection reaches') also clarifies reach against openWorldHint.

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 and target, then moves to return shape, then behaviour, then the alternative tool and the undo caveat. Dense but every sentence carries information; the parenthetical id format and the AlphaBridge forwarding note are the only slightly incidental pieces.

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 (added, id, sidebar). With all four parameters documented at 100% coverage and the mutation risks (sanitisation, refusal, no undo) disclosed, 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 the baseline is 3; the description adds real meaning on top by specifying the returned id format ('<id_base>-<number>') and describing how the settings value is treated (sanitised through the widget's own update()), which the schema alone does not convey.

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

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

States a specific verb and resource ('Add a new widget of a registered type') plus the two scopes it can target (a sidebar or wp_inactive_widgets), and explicitly contrasts itself with wp_update_widget, so an agent can distinguish it from the sibling mutation 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?

Explicitly routes modifications to wp_update_widget and notes the refusal conditions for unknown types/sidebars, giving clear usage context. It stops short of a full when-not statement (e.g. bulk operations or checking existing widgets first via wp_get_widgets), so it is strong but not exhaustive.

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 names exactly what gets overwritten (settings, terms, pages), how menus merge (differing label/parent adds beside the old item and is noted), what is never touched (deletion, deactivation, deactivated structure not in the blueprint), which sections are advisory-only and reported blocked, that writes go through ordinary tools so their permissions and token scope apply, and that on_error 'stop' keeps writes already made. The 'never deletes' wording is reconciled with destructiveHint=true by the explicit overwrite list, so this is clarification rather than 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?

Purpose and the dry-run default are correctly front-loaded, and nearly every clause carries real information (unwritten_fields, not_written, notes). However it is delivered as one dense paragraph of semicolon-chained clauses that forces re-reading to separate refusals from outcomes, so structure costs it more than the length does.

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 9-parameter, nested-object, destructive tool with no output schema, the description covers the failure modes (refused rows, truncated sections, blocked sections, max_writes, on_error), the reporting keys an agent will see back (unwritten_fields, not_written, notes, unchanged), and the permission boundary. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by explaining consequences the schema does not, notably that settings always exist so a settings apply writes nothing without update_existing, and that max_writes exhaustion explains why a re-run still has work. It says nothing about session, expect_hash or allow_partial beyond what the schema already states, which caps it short of 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?

The first clause gives a specific verb and resource ('apply the applicable parts of a blueprint to this site') and immediately positions itself relative to a named sibling ('the write side of wp_blueprint_diff'). An agent can distinguish it from wp_blueprint_diff, wp_blueprint_export and the individual wp_create_*/wp_update_* tools without opening a schema.

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

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

It states the default mode (dry run without apply=true), when to escalate to writes (update_existing), and explicitly routes the read-only planning case to wp_blueprint_diff via the shared plan_hash. It also explains the repeat-run case ('writes only what earlier runs left undone') so an agent knows re-invocation is safe rather than duplicative.

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 supply readOnly/idempotent/non-destructive; the description goes well beyond them by enumerating the result vocabulary (create, update, unchanged, extra_on_target, advisory, blocked), stating there is no delete mode, that extra_on_target is never touched by apply, and that blocked sections occur when underlying tools are off or out of token scope. It also explains plan_hash staleness refusal and the multi-site forwarding caveat.

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, the target and the read-only guarantee in the first two clauses. It is long and clause-dense, but nearly every sentence carries operational information (result categories, no delete mode, hash staleness, token scope) rather than 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 carries the full burden of describing the return value and does so exhaustively, including the meaning of plan_hash and per-category results. Nothing an agent needs to interpret or safely chain the call is missing.

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

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

Schema description coverage is 100%, so the schema already documents session, sections, blueprint and allow_partial in detail. The description only adds provenance for blueprint ('from wp_blueprint_export on this or another site'), which is helpful but marginal against a fully documented schema; 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 ('Compare a blueprint ... against the CURRENT state of this site') plus the exact output intent ('return exactly what wp_blueprint_apply would do'). It also names its two siblings (wp_blueprint_export as the blueprint source, wp_blueprint_apply as the consumer), so an agent can place it in the workflow 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?

Establishes the use case (dry-run preview before applying) and a key operating condition: it works whether or not wp_blueprint_apply is available, and plan_hash is fed to apply as expect_hash. It does not state an explicit 'do not use this when…' exclusion, but the export → diff → apply routing is clear enough to act on.

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 state read-only/idempotent/non-destructive; the description adds substantive behavior an agent cannot get elsewhere: results return inline with nothing persisted, sections over max_items are truncated and flagged in a 'truncated' list, and downstream diff/apply refuse those sections. It also flags a real data-exposure trait — term descriptions and custom menu item URLs are free text and can carry internal host addresses into the document.

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 statement and the exclusions are front-loaded, and the paragraph stays on topic throughout. It is dense and long with capitalized emphasis, and the free-text caveat is buried mid-paragraph rather than surfaced near the top, which costs it a point.

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

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

With no output schema, the description carries the return-shape burden and does: inline JSON, per-section structure, a 'truncated' list, and the explicit note that the transport forwards to the single site the connection reaches. An agent has everything needed to call it and to interpret the response.

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 earns more by explaining the consequence of max_items (section truncation and the 'truncated' list) and by framing sections as the scope selector for the whole document. It adds no detail on post_types/taxonomies beyond the schema's own defaults.

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 ('Export the STRUCTURE ... as a portable JSON blueprint') and then enumerates exactly what is in scope. It explicitly excludes post content, widget settings, credentials and user data, which separates it cleanly from wp_export_content and the read-side getters like wp_get_site_settings.

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?

Clear context is given: this is a structural snapshot whose output feeds diff/apply, and truncated sections are rejected downstream unless allow_partial is set, which tells the agent to raise max_items rather than patch a partial blueprint. It stops short of explicitly naming wp_blueprint_diff / wp_blueprint_apply / wp_export_content as the alternatives, leaving that routing to inference.

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

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

Annotations cover safety (destructiveHint=true, readOnlyHint=false), and the description goes well beyond them: 500-id cap with over_limit accounting, duplicate ids collapsing to one, already-correct posts skipped, trash refused on sites without trash (where WordPress would hard-delete), media files becoming 'inherit', and the edit_others_posts requirement. It also documents the full result shape (updated/ids/stored_as/failed/forbidden/undo) including per-item error codes such as trash_refused and unverified.

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, but the body is a single dense semicolon-chained block that mixes inputs, edge cases, permissions and return values in one wall of text. The content largely earns its place given the tool's complexity, yet it would be far more scannable split into usage, edge cases, and returns.

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 documents the return payload in detail, including per-item error variants and the 100-item listing caps with omitted counters. For a destructive bulk mutation, permissions, idempotency-edge behavior, and undo token handling are all accounted for.

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 real meaning: the 500-id truncation behavior, duplicate collapsing, skipping of unknown ids, and the fact that a media file targeted at draft/pending/publish is stored as 'inherit'. It does not add format or type detail beyond that, so it lands 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?

States a specific verb (change status) and an explicit scope (many posts at once by id list, covering posts, pages, other post types and media), and lists the valid target statuses. It also distinguishes itself from the sibling that handles the single-post case: 'one post's status and other fields change with wp_update_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?

Signals the batch use case ('Suited to batches') and names the alternative for single posts (wp_update_post), plus it points to wp_undo for the returned undo token. The exclusion is embedded in a semicolon-separated clause rather than stated as an explicit when-not-to rule, but the routing information is present and usable.

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 destructiveHint and idempotentHint=false, but the description adds real substance: exactly which rows are removed (value and timeout), that site transients are spared, that a persistent object cache can leave stale option rows behind, and the manage_options requirement. That cache caveat is behavior an agent cannot infer from any structured field.

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 its scope, then caveats, then the sibling pointer. Every sentence carries information, though the trailing sentence about AlphaBridge forwarding is somewhat incidental and the cache caveat could be 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?

With no output schema, the description supplies the return contract ('deleted, the number of expired transients found and handed to WordPress for deletion'), plus permissions and the cache caveat. An agent has everything needed to call this and interpret the result 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. The baseline applies, and the description correctly describes only scope and return value rather than inventing arguments.

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 precisely defines the scope: only transients whose _transient_timeout_ row has passed, excluding site transients. It also distinguishes itself from the sibling wp_delete_transient by naming the single-name 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 condition for use is clear from the definition of 'expired', and it explicitly points to wp_delete_transient for the one-by-name case. It does not state exclusions like 'avoid running during peak load' or prerequisites beyond manage_options, so it falls short of a full 5.

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

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

Annotations already flag destructive=true, but the description adds materially: only cached copies are dropped and pages rebuild on next request, the site may answer slower briefly, manage_options is required, no undo point is recorded, and multisite behavior depends on a network capability. It also documents partial-failure semantics via page_cache_failed and page_cache_skipped.

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: what it flushes first, then the use case, then caveats and returns. A couple of clauses are packed (the multisite permission sentence), but nearly every sentence 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 return fields, permission requirements, multisite constraints, partial-failure cases, and the non-reversible nature of the operation. 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?

The tool takes zero parameters, so the baseline is 4. The description instead invests in return-value semantics (object_cache_flushed, opcache_reset, page_cache_purged, page_cache_failed, page_cache_skipped), which is useful since no output schema exists.

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 the exact resources: object cache, OPcache, and page cache of eleven named caching plugins. It explicitly contrasts with wp_cleanup_transients, so an agent can separate the two cache-related siblings 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 a concrete trigger ('making a change visible that a cache still serves in its old form') and routes transient cleanup to wp_cleanup_transients. It also bounds scope by warning that host/CDN caches are not reached. It stops short of a full when-not-to-use rule, 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 beyond the annotations by disclosing the uniqueness failure mode (duplicate names are refused by WordPress), the required capability, and the returned fields. Annotations already cover the mutation/safety profile; the remaining gap is that the error form (exception vs. structured error) is not described.

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 each sentence carries distinct information. The trailing AlphaBridge routing sentence is useful but slightly tangential to invocation and could be 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?

For a single-parameter creation tool with no output schema, the description supplies the return shape (created, menu_id), the failure mode, the needed capability, and the scope boundary. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100% and the schema already explains sanitisation and backslash handling, so the baseline is 3. The description adds real semantic value by stating the uniqueness constraint on the name field, which the schema does not mention.

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 ("Create an empty navigation menu") and immediately names the return values. The word "empty" plus the explicit hand-off to wp_add_menu_item distinguishes it cleanly from its menu siblings (wp_list_menus, wp_get_menu, wp_add_menu_item, wp_delete_menu_item).

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 follow-up work: items go through wp_add_menu_item, and theme-location assignment is declared out of scope for this tool. A precondition (edit_theme_options) is stated up front, so the agent knows what must be true before calling.

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, idempotentHint=false and openWorld, but the description adds real substance on top: repeated calls create duplicates, empty title/content/excerpt is refused (empty_content), page-builder meta requires unfiltered_html and is refused before any write, and publish/future need the publish right. That is capability, side-effect and failure-mode context the 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?

Purpose, side effects and alternatives are front-loaded in the opening sentences. The rest is dense semicolon-chained prose, but nearly every clause carries a real constraint (permissions, refused-before-write, meta key filters) rather than 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 an 11-parameter creation tool with no output schema, the description still names the return shape ({created: true, post} plus the wp_list_posts fields) and covers permissions, defaults and failure modes. An agent has enough to call it correctly on the first attempt.

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 parameter docs are already detailed (date formats, slug derivation, terms behavior, author capability). The description adds only marginal semantics beyond that, such as the draft default and status permission implications, so the baseline of 3 is appropriate.

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

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

Starts with a specific verb and resource ("Create a post, page or entry of a custom post type") and enumerates the settable fields. It also distinguishes itself from wp_update_post and wp_upload_media in the same breath, so an agent can separate creation from mutation or file upload without opening any schema.

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

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

Explicitly routes the agent: existing entries go to wp_update_post, files go to wp_upload_media. It also states the default state (saved as draft unless status says otherwise) and the permission conditions for publish, private and future, which is exactly the when/when-not guidance needed before calling.

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 (manage_categories for categories/tags), two concrete failure modes (nonexistent parent refused, duplicate name refused unless a distinct slug is given, scoped to same parent in hierarchical taxonomies), and the return payload. Slightly short of 5 only because it does not say whether a failed create is atomic/no-op or whether it is safe to retry 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?

Front-loaded with what is created and what is returned, then permissions, then failure modes, then the sibling pointer. Every sentence carries decision-relevant information; nothing is restated from 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 present, the description supplies the return shape ({created: true, term_id}), the permission requirement, the refusal conditions, and the single-site forwarding scope. That is everything an agent needs to invoke a 5-parameter create tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics on top: the 'parent' parameter must reference an existing term and only matters for hierarchical taxonomies, and name uniqueness is evaluated per-parent. That is behavior the schema's per-parameter text does not spell out.

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: 'Create a new term (category, tag or custom taxonomy term) in a taxonomy.' Explicitly distinguishes itself from wp_update_term ('Existing terms are changed with wp_update_term') and implicitly from wp_delete_term/wp_list_terms, so an agent can route 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?

Names the alternative tool (wp_update_term) and the condition that selects it, i.e. existing terms. Also states the connection scope ('the one site this connection reaches'), which tells the agent when this tool is applicable versus a network-level 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?

Although annotations already declare read-only/idempotent/non-destructive, the description adds genuinely non-structured context: the manage_options capability requirement, the exclusions (scheduled posts not counted, private media not counted), and the multisite/connection scoping. These are exactly the kinds of caveats 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?

Front-loaded with the verb and resource, then a dense enumeration that is largely information-bearing. It is on the long side and the trailing AlphaBridge forwarding sentence is peripheral, but no sentence 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, and the description compensates by itemizing every returned metric group, including which statuses are excluded. An agent can predict the response shape and decide whether this tool answers its question without any further documentation.

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

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

With zero parameters the baseline is 4, and the description confirms 'takes no arguments', removing any doubt about required inputs. There is no further parameter meaning to convey.

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

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

States a specific verb+resource ('Get content counts of this site') and then enumerates exactly what is counted: per-post-type statuses, users total and per role, comment statuses, and media counts. This is clearly distinguishable from listing siblings like wp_list_posts or wp_list_users, which return entries rather than aggregates.

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

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

Explicitly routes the agent to alternatives: 'The entries themselves are listed by wp_list_posts, wp_list_comments and wp_list_media.' It also gives scope rules (multisite: current site) and the precondition 'Needs manage_options', so an agent knows both when to use it and when not to.

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 table-locking risk during execution, that the call may be slow on large tables, that no dry run exists, that manage_options is required, and that the operation is scoped to a single site via AlphaBridge Connect. These are exactly the operational risks an agent needs before invoking a destructiveHint 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?

Front-loaded with the action and scope, then the return shape, then risk and prerequisites — a sensible ordering for an agent deciding whether to call. No filler sentences; every clause carries new information.

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

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

With no output schema, the description supplies the return shape (optimized count, tables list) and covers permissions, locking, duration and lack of dry run. Nothing material is missing for a parameterless destructive maintenance operation.

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

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

Zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The mention of the site's table prefix clarifies the implicit scope of an argument-less call.

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

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

Names the exact operation (OPTIMIZE TABLE), the exact target set (every table beginning with this site's prefix), and the outcome (reclaim unused space, defragment). This is clearly distinguishable from siblings like wp_db_tables (listing) or wp_db_schema (structure inspection).

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 goal that motivates a call ('to reclaim unused space and defragment') and tells the agent there is no dry run, which is decisive for a destructive tool. It does not, however, name alternatives (e.g., wp_db_tables to preview sizes) or a when-not-to-use condition.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds substantial context beyond them: the error-on-refusal behavior for views and foreign-site tables, the multisite super-admin nuance, the required capability, the 'write access on' precondition, and the forwarding scope. This is exactly the kind of extra behavioral disclosure 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 purpose and return shape, then constraints in descending order of importance. Dense but nearly every sentence carries information; the trailing AlphaBridge forwarding sentence is context rather than invocation guidance, a minor dilution.

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 read tool with full schema coverage and no output schema, nothing needed to call it correctly is missing: return shape is named inline, refusal cases are enumerated, and capability prerequisites are 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?

Schema coverage is 100% and the schema already explains prefix inclusion, example values, and character stripping, so the description adds little about the single parameter. Baseline 3 applies when the schema does the heavy lifting; the description only echoes 'as wp_db_tables lists it'.

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

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

States a specific verb (DESCRIBE) and resource (one database table), enumerates the exact returned columns (Field, Type, Null, Key, Default, Extra), and names wp_db_tables as the listing sibling. An agent can distinguish this from any other wp_db_* 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?

Clearly routes the agent: use wp_db_tables to discover table names, then this tool to inspect one. It also states exclusions (unknown tables, views, other sites' tables are refused) and prerequisites (manage_options, write access on). No explicit statement of when NOT to use it for other inspection tasks, but coverage 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 readOnly/idempotent annotations: discloses that views are excluded, that InnoDB row counts are estimates, that multisite non-super-admins see only the current site's tables, that manage_options is required, that it only runs with write access enabled, and that AlphaBridge forwards to one site.

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 return shape, then constraints, in one dense run-on sentence chain. Every clause carries information, but the packing into a single semicolon-laden sentence slightly hurts scannability.

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 compensates by naming the returned fields (name, rows, size, prefix) and covering limits (views excluded, multisite scoping, auth). 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?

The tool takes no parameters, so the baseline is 4. The description spends its space on return fields and constraints rather than parameter meaning, which is appropriate for a zero-argument call.

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

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

States a specific verb and resource ('List the base tables of this site's database') and enumerates exactly what each entry carries (name, row count estimate, size, prefix). It explicitly distinguishes itself from the sibling wp_db_schema, which returns columns rather than the table list.

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 the agent to wp_db_schema for column-level detail, establishing when to pick this tool versus that one. It lacks an explicit 'do not use for X' exclusion, but the division of labor is clear enough for correct selection.

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 destructive/not-idempotent/non-readonly, and the description adds information the annotations cannot: the response reports was_active, self-deactivation of the bridge is refused with the reason (it would end the connection or remove tools), and the call only reaches the single site this connection is bound to. That is exactly the context annotations lack.

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 identifier format, and every sentence carries real information. The parenthetical enumerating AlphaBridge's components is slightly heavy, and the closing sentence about Connect forwarding is one clause longer than needed, but there is no true 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 single-parameter mutation with no output schema, the description supplies everything needed: valid input source, the returned was_active field, the self-deactivation guard, and the reverse operation. Nothing an agent needs in order to call it 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; the description still adds value by telling the agent where to source the value (wp_list_plugins' file field) and that any other form is refused. It does not add further edge cases (case sensitivity, already-inactive plugins), so it stops short of 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 ("Deactivate a plugin") plus the exact identifier format it consumes, with a concrete example. It explicitly distinguishes itself from wp_activate_plugin ("the reverse") and from wp_delete_plugin by implication, so an agent can route correctly 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?

Gives the precondition for the argument (use the path as wp_list_plugins returns it), names the counterpart tool for the opposite action, and states a hard exclusion: AlphaBridge's own components are refused and must be deactivated in wp-admin. Both when-to-use and when-not-to-use are 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?

Goes well beyond destructiveHint=true: it discloses the two-stage delete model, that force also removes comment meta and promotes replies, that trashing a `note` cascades to reply notes, the required capability (moderate_comments), the return shape, and the not-found error. It even explains that a repeat call escalates to permanent deletion, which is precisely the non-idempotency the annotations hint at.

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 trash-versus-force distinction in the first clause, then layers exceptions, cascade behavior, permissions, and return value. Dense and mostly efficient, though the second sentence is long and could be 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 only two parameters, no output schema, and destructive annotations, this fills every remaining gap: destructive scope, cascade effects, permission requirement, response shape, error behavior, and the AlphaBridge single-site forwarding caveat. Nothing an agent needs to call it 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; the description earns above that by explaining the consequences of `force` (meta removal, reply promotion) and by enumerating the implicit-force conditions that override the flag entirely. It adds real decision-relevant meaning the schema's 'deletes for good' phrasing does not.

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

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

Names a specific verb and resource ('Delete one comment') and immediately distinguishes this from moderation or listing by naming wp_moderate_comment as the sibling for re-approving. An agent can separate it from wp_list_comments, wp_get_comment, and 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?

Explicitly states the default behavior (trash) versus `force=true` (permanent), and calls out the exception paths where a non-forced call still deletes permanently (already trashed, spam, trash disabled on the site). It also directs the agent to wp_moderate_comment for the restore case, so when-to-use and when-to-use-something-else 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?

Adds substantial context beyond the destructiveHint annotation: no trash, the physical file and derived image sizes are removed, featured-image assignments are cleared, embedding posts keep stale URLs, a delete-permission is required, and a file the server refuses to delete is left silently. That silent-failure caveat is exactly the kind of trait 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?

Front-loaded with the core action and its permanence before the caveats, and nearly every clause carries real information. It is on the dense side — several clauses are packed into long sentences — but nothing is filler.

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

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

With no output schema, the description correctly spells out the return value ({deleted: true, id}) and the not-found error path, and it covers side effects, permissions, and failure modes. An agent has everything needed to call it safely.

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 there is a single integer parameter already documented as 'Attachment id of the file to delete.' The description adds only the behavioral consequence of a nonexistent id (not-found error), not new meaning about the parameter itself, 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 ('Delete one file of the media library (attachment)') with explicit scope — a single attachment, permanently. It also names the sibling it is not ('Posts and pages are deleted with wp_delete_post'), so an agent can distinguish it from the ~100 other delete tools 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?

Clearly routes post/page deletion to wp_delete_post and implies this tool is only for media-library attachments. It does not explicitly distinguish itself from wp_delete_upload_file, which sits right next to it in the sibling list, so one exclusion 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?

Goes well beyond the annotations: it discloses that the operation is permanent (deleted, not trashed, no undo point), the required capability edit_theme_options, what happens to sub-items (retained as children, usually surfaced at top level), the return payload (deleted and item_id), and the error behavior for non-menu-item ids. The 'repeated call changes nothing' remark is about the refused retry rather than a claim of true idempotency, so it does not contradict 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?

The verb, resource and the key non-destructive-to-content caveat are front-loaded, and each following sentence carries a distinct fact (sub-item behavior, return value, error case, permission, permanence). No filler or restatement of the name.

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 destructive mutation with no output schema, everything an agent needs is present: the confirmation of permanence, the capability required, the side effect on child items, the refusal behavior, and the returned fields. Nothing material is left for the agent to infer.

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 item_id parameter and its wp_get_menu provenance are already documented. The description adds only behavioral meaning (an id that is not a menu item is refused) rather than new syntactic guidance, 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 ('Remove one item from a navigation menu by its item_id') and immediately bounds the scope with 'the linked post or page itself is not touched', which separates it from wp_delete_post and wp_delete_widget. An agent can pick this tool 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 'not touched' clause and the orphaned-sub-item note give clear situational context, and the invalid-id refusal tells the agent how repeats behave. It stops short of explicitly naming an alternative (e.g. edit the menu via wp_get_menu first), so it is clear context rather than 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 annotation, the description discloses extensive behavior: active snippets stop running, test requests probe the home page, MCP endpoint, admin-post.php, and dashboard, fatal errors restore the previous state, safe modes skip probes, undo points are recorded, and audit logging includes sha256 hashes. It also states multisite and DISALLOW_FILE_EDIT / DISALLOW_FILE_MODS restrictions.

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

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

The purpose and force behavior are front-loaded, but the description is extremely dense and runs long for a single delete operation, packing many clauses into long sentences. Most content is substantive, but the structure makes it harder to scan than necessary.

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

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

Given the destructive nature, probe behavior, undo recording, safe-mode interactions, and absence of an output schema, the description is remarkably complete. It covers rollback behavior, what the answer names on failure, safe-mode skipping, and site restrictions.

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 baseline is 3, but the description adds meaningful semantics beyond the schema: it explains that force true deletes for good, that allow_without_undo applies to snippets too large for an undo point, and that allow_without_probe applies where the previous state fails the same way. Provider detail is left to the schema enum.

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

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

The description states a specific verb and resource: 'Move a PHP snippet of Code Snippets or WPCode to the plugin's trash, or delete it for good with force: true.' It also distinguishes the tool from sibling listing tools by saying the id is the one wp_list_php_snippets lists.

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

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

The description gives clear conditions for force deletion and the allow_without_undo / allow_without_probe escapes, and it explains which snippet id source to use. It does not explicitly compare this tool to a sibling alternative or state when not to use it, but the intended 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?

Beyond the destructiveHint/idempotentHint annotations, it discloses that active plugins are deactivated first, that the uninstall routine may delete settings and data, that no undo point is recorded, the delete_plugins capability requirement, the DISALLOW_FILE_MODS refusal, and the self-protection refusal for AlphaBridge. This 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-loads the effect and identifier, then the permanence warning, then prerequisites and refusals — a sensible order. The AlphaBridge self-exclusion sentence is long and somewhat verbose, though it carries real safety value.

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

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

For a one-parameter destructive tool with no output schema, the description covers effect, side effects, permissions, refusals, alternatives, and names the return fields (deleted, plugin). Nothing needed to call it safely is missing.

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

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

Schema description coverage is 100%, so the single parameter's format and refusal of folder-name-only or unknown files are already documented in the schema. The description restates the same example and constraint rather than adding new meaning, so the baseline 3 applies.

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

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

States a specific verb (delete) and resource (installed plugin), plus the identifier format taken from wp_list_plugins. It explicitly contrasts with wp_deactivate_plugin, so an agent can distinguish it from siblings without opening any schema.

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

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

Gives explicit when-to-use (permanent removal), when-not (switch off without removing → wp_deactivate_plugin), and hard refusal conditions (DISALLOW_FILE_MODS, AlphaBridge's own plugin, handled in wp-admin instead). Nothing about selection 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?

Although annotations already mark this as destructive and non-idempotent, the description adds substantial context beyond them: trash behavior, comment hiding, restore path, refusal cases, permanent deletion side effects (revisions, comments, custom fields, term assignments), irreversibility, permission requirement, return shape, not-found behavior, and bridge forwarding. This is unusually complete 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 description is dense but front-loaded: it states the core action and default trash behavior first, then force deletion, side effects, permissions, and return behavior. Every sentence adds decision-relevant detail for a destructive operation, with no filler.

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

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

For a destructive two-parameter tool with no output schema, the description covers the critical gaps: default versus permanent behavior, irreversible effects, refusal conditions, permissions, return value, error behavior, and the relevant media alternative. It is complete enough for an agent to call safely and 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 schema already documents both parameters. The description adds operational meaning to force=true by explaining permanent deletion, side effects, and refusal behavior, and it explains that an unknown id returns a not-found error, which goes beyond the schema's basic descriptions.

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

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

The description uses the specific verb 'Delete' with the clear resource 'post, page or entry of any post type,' and explicitly distinguishes media deletion by pointing to wp_delete_media. An agent can distinguish it from nearby siblings such as wp_update_post and wp_delete_media from the text alone.

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

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

It gives explicit when-to-use behavior: default trash, permanent deletion only with force=true, restoration via wp_update_post, and refusal conditions for already-trashed entries, media files, or sites without trash. It also names the correct alternative tool for media files, making selection 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 mark the tool as destructive and non-idempotent, and the description goes substantially further: it explains there is no trash, posts lose the term, orphaned posts get the default category, child terms move to the parent, term meta is removed, default terms are protected, permission is required, and the return value is {deleted: true}.

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: the first clause states the action and irreversibility. Every subsequent clause adds concrete operational detail about side effects, constraints, permissions, or return value, with no filler.

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

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

For a destructive two-parameter tool with no output schema, the description covers the key missing context: permanence, side effects on posts and child terms, protected default terms, error conditions, required capability, and the exact return shape.

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 in the input schema. The description still adds useful semantic detail by stating that an unknown term_id returns an error and that the taxonomy's default term cannot be deleted, which clarifies parameter behavior 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 opens with a specific verb and resource: 'Delete a term from a taxonomy for good.' It makes the delete operation and its scope immediately clear, and the surrounding details distinguish it from update/create/list siblings without ambiguity.

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

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

The description implies when this tool applies (permanent term deletion) and states important exclusions, such as the default term not being deletable. However, it does not explicitly compare against alternatives like wp_update_term or explain when not to use deletion versus updating.

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: discloses the delete_themes capability requirement, DISALLOW_FILE_MODS refusal, permanence with no undo point, and the exact return fields (deleted, stylesheet). Also notes the request is forwarded to a single site via AlphaBridge Connect, which is non-obvious behavioral context.

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

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

Dense and front-loaded: the delete action comes first, then refusal rules, then side effects and return values. No sentence is filler despite covering several distinct facts.

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 names the returned fields and covers permissions, refusals, and irreversibility. The only thin spot is that permanent deletion scope (database rows vs. files) is implied by "folder and files" rather than spelled out.

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 defines stylesheet as the exact installed directory name with an example, so the description adds no parameter-level detail beyond it. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ("Delete an installed theme's folder and files") and makes the scope concrete, distinguishing it from wp_update_theme and wp_activate_theme by naming both 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?

Explicitly states what is refused (active theme, parent theme) and routes to the correct alternatives: wp_activate_theme for switching, wp_update_theme for a newer version without deletion.

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, the description discloses permission requirements (manage_options), return behavior including the false case when nothing is deleted, prefix filtering rules, and that the call is forwarded to one connected site. This adds substantial operational context for a destructive tool.

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

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

The definition is front-loaded with the core operation and then adds only relevant constraints, return behavior, permissions, alternatives, and forwarding context. Each sentence contributes useful information without redundancy.

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

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

Given a single-parameter tool with no output schema and annotations that already cover safety characteristics, the description is complete. It covers naming rules, permissions, return semantics, sibling alternatives, and connection behavior.

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

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

The schema already documents the single name parameter at 100% coverage, so the baseline is 3. The description adds meaningful detail beyond the schema by naming the allowlist filter and stating that the plugin's own ab_mcp transient state is never allowed, though it does not enumerate all allowed prefixes.

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: "Delete one transient by name." It clearly scopes the operation to a single named transient, distinguishing it from sibling tools such as wp_set_transient and wp_cleanup_transients.

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 contrasts this tool with wp_set_transient (sets one) and wp_cleanup_transients (removes expired ones), which tells the agent when this tool is the appropriate choice. The prefix allowlist and prohibition on the plugin's own ab_mcp state further constrain correct usage.

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

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

Annotations already declare destructive/non-idempotent, but the description goes well past them: it discloses the exact return payload, that the undo token can be null while the delete still succeeds, and the partial-effect trap that a media library entry is left dangling. It also names the auth requirement and the proxy/forwarding boundary — exactly the context 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?

Front-loaded with the action and location, then returns, then caveats, then the sibling alternative and deployment note. Every sentence carries a distinct fact (undo semantics, orphaned media entry, refusals, auth, proxy scope) 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?

No output schema exists, and the description compensates by enumerating the returned fields and the null-undo edge case. Combined with the auth and forwarding constraints, an agent has everything needed to call this 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% and the single `file` parameter already documents relative-path format, the wp_list_uploads reference shape, and the ".."/symlink refusals. The description adds no parameter-level detail beyond echoing the folder refusal, 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 with scope ("Delete one file from the uploads directory (wp-content/uploads)"), and explicitly distinguishes itself from the nearest sibling wp_delete_media. An agent can route between wp_list_uploads, wp_read_upload_file, wp_delete_upload_file and wp_delete_media from this description alone.

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

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

Gives explicit when-to-use-other guidance ("Attachments together with their files are deleted by wp_delete_media"), plus a prerequisite (Administrators only / manage_options) and named refusal cases (folders, AlphaBridge's own folders, ".." and symlinks). Nothing about selection 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?

Goes far beyond the destructiveHint annotation: discloses that deletion is permanent with no undo point, the multisite scoping (only removed from this site), the last-admin refusal, the admin role-strip/rollback sequence, partial-failure semantics (deleted-with-warning), and the ab_mcp_busy concurrency guard. This is exactly the contextual risk detail 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?

Front-loaded with the action and the reassign/no-reassign fork, and every sentence carries operational information. The dense parenthetical clauses and long single paragraph make it slightly harder to scan than it could be, but there is little true waste.

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

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

Despite no output schema, the description states the return contract ('Returns deleted and id'), covers permissions, failure modes, multisite scope, and the AlphaBridge forwarding boundary. Nothing material is missing for a destructive, non-idempotent, non-open-world 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, but the description adds real semantics: reassign_to must reference an existing user or the call is refused with nothing deleted, and omission/0 triggers the trash-or-delete cascade described above. The inheritance rules give an agent decision guidance the schema's field text only partly covers.

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 precise verb+resource ('Delete a user account') and immediately scopes it against siblings like wp_get_user and wp_update_user_meta by describing exactly what is removed versus reassigned. An agent can tell this is the destructive account-removal tool without reading further.

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 contrasts the two modes: 'With reassign_to... without it, WordPress deletes the user's links and entries of post types removed with their author.' It also states prerequisites (delete_users capability, right to delete this user, last administrator refused). No sibling alternatives are named, but the decision 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?

Beyond the destructiveHint/idempotentHint annotations, the description discloses that the option row is rewritten directly without the widget's own cleanup routines, that no undo point is recorded, and that the write is forwarded by AlphaBridge Connect to one site. These are non-obvious traits 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-loaded with the action and permanent/destructive consequence, then the alternative, then connection scope. Dense but every sentence carries information; the 'returns deleted and id' clause is slightly redundant with the id parameter narrative.

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 covers return fields, error case, permanence, cleanup bypass, the alternative tool, and the connection scoping. 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?

Schema coverage is 100% and the single id parameter is fully described there, so the description adds no format or syntax detail. It does add error semantics (id absent from sidebar and stored settings is reported not found), which is useful but doesn't extend parameter meaning itself. 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?

The description states a specific verb and resource (remove a widget instance from its sidebar, delete its settings) and distinguishes it from wp_update_widget and implicitly from wp_add_widget. An agent can select it from the sibling list without opening the schema.

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

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

It explicitly routes modification of existing widget settings to wp_update_widget, and the 'not found' clause tells the agent when the call will no-op. It doesn't state a concrete when-not-to-use case like 'use wp_add_widget to create', 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?

Far exceeds the annotation bar: it enumerates exactly what is copied (title with ' (Copy)', content, excerpt, parent, menu order, taxonomy terms, custom fields, featured image, builder layout), what is never copied (credential-like keys, edit lock, caches, protected keys, revision meta), the unfiltered_html capability requirement for builder markup, and the all-or-nothing builder key rule. The return shape is also described. Nothing here contradicts readOnlyHint=false / destructiveHint=false / idempotentHint=false — the copy-not-mutate semantics match those hints.

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

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

The action is front-loaded in the first clause and every sentence carries real information — nothing is filler. However, it is delivered as one long semicolon-chained sentence, which makes the dense capability and exclusion rules harder to scan than separated sentences 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?

For a write tool with no output schema, the description supplies the return value ({duplicated: true, new_id} plus copied/skipped keys and reasons), permission requirements, builder-specific edge cases, and the bridge/site scoping note. There is no gap an agent needs filled 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 coverage is 100% for the single `id` parameter, so the schema already carries the meaning. The description only restates it as 'an existing post or page' and adds no format or sourcing detail beyond that, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('Copy an existing post or page into a new draft') and immediately disambiguates from update/create siblings by noting 'the original stays unchanged and each call creates another copy.' An agent can tell this apart from wp_create_post and wp_update_post 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 gives a clear use case ('as a starting point for a new page') and states prerequisites ('Needs the right to read the original and to create entries of its type') plus exclusions (media files can't be duplicated, password-protected posts require edit rights). It stops short of naming sibling alternatives explicitly, so it lands at a strong 4.

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

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

Goes well beyond the annotations: it discloses that output lands in an uploads subfolder (ab-mcp-exports) under an unguessable name, that no URL is returned, that each call writes a new file, that Apache .htaccess protection may not apply on nginx, and that MCP file tools cannot reach the folder so deletion must happen over filesystem/SFTP. This is exactly the safety and retrieval context an agent needs, and it is consistent with readOnlyHint=false, idempotentHint=false and destructiveHint=false. It loses a point only because the explanation is dense enough that the operationally critical fact (file is not retrievable via MCP file tools) is buried mid-paragraph rather than flagged up front.

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 sibling alternative are front-loaded, and the sentence about no-match exports still yielding a WXR file prevents a common misread. However, the middle section stacks several long clauses and repeats the same protection idea twice (unguessable filename vs. unguessable name), which could be compressed.

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 naming the return fields (exported, file, path, upload_path, bytes, retrieve_with, a note) and explaining how to retrieve and delete the produced file. Combined with the capability requirement and error semantics, an agent has everything needed to call this correctly and act on 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 schema already documents status and post_type in comparable detail, so the description does not need to restate them. It adds no syntax or edge-case guidance for the two parameters (for example which post types accept a status filter beyond the schema note), so it sits at the baseline for a fully documented 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 (export content as a WordPress WXR file) and immediately scopes it against the sibling wp_blueprint_export, which handles structure/settings instead. An agent can distinguish 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?

Names the alternative tool and the axis that separates them (content export vs. site blueprint), states the required export capability, and clarifies that a zero-result export is still a success. The condition selecting the alternative is explicit rather than inferred.

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

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

Adds real context beyond the annotations: it is a soft flush, .htaccess is untouched, the permalink structure is preserved, manage_options is required, and the response is flushed=true. Slight gap: annotations flag destructiveHint=true while the prose emphasizes harmlessness, so an agent gets no explicit statement of what is overwritten (the rewrite_rules option).

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

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

Three compact sentences: operation first, symptom/use case second, side effects and auth third. Nothing is redundant and no clause is filler.

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

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

With no params and no output schema, the description covers the essentials: effect, non-effects, permission requirement, return value, and the bridge's single-site scope. Only the precise state change (rewriting the rewrite_rules option) is left implicit against a destructiveHint=true annotation.

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 also documents the return value (flushed=true), which compensates for the missing 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?

States a specific verb and resource: regenerate permalink/rewrite rules stored in the database. No sibling tool performs this operation, and the accompanying symptom (404s after a structural change) makes the purpose unambiguous.

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

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

Gives a clear triggering condition (posts, CPTs or taxonomies returning 404 after a structural change) and defines the boundary of the operation (soft flush only). It does not name an explicit alternative tool, but no sibling overlaps, so the guidance is nearly complete.

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 read-only annotations, it discloses that styling is omitted, unsafe elements are listed as locked without content, storage and layout_hash semantics, that post_content may be a non-displayed copy, and that an unknown id returns not-found. It also notes the edit capability requirement and that the tool is forwarded through AlphaBridge Connect.

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-loads the core purpose and output shape. It is long for a single paragraph and relies on semicolon-chained clauses, but the content is substantive 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?

No output schema exists, but the description thoroughly explains the returned outline, locked elements, storage metadata, write_via, and layout_hash. Combined with annotations and fully described parameters, it gives an agent enough to call the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents all four parameters. The description adds some meaning around id handling for revisions and around locked elements, but it does not elaborate on max_elements or max_field_chars beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: reading a page-builder layout as a compact outline, including builder, storage kind, data version, and ordered elements. It clearly differentiates this from a generic post read by focusing on builder structure, locked elements, storage, and write_via routing.

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 that pages without a builder are read as blocks and that write_via names tools which change the page with a visible effect. It also states the permission requirement, but it does not explicitly name wp_get_post or say when to prefer this over that sibling.

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

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

Annotations only declare read-only/idempotent; the description adds substantial behavioral context beyond them: the exact return field set, that author excludes email, the full status enumeration including the odd `false`/post-trashed case, RFC 3339 site-time dating, parent=0 semantics for top-level, and a not-found error for unknown ids.

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 dense factual payload (return contract, error, permission, alternative, bridge scope) in three sentences 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, yet the description fully specifies the return shape and edge-case status values, plus error behavior and permission needs — everything an agent needs to call it correctly on a single-site bridge.

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 comment_id parameter is already documented in the schema as 'Comment id, as wp_list_comments returns it.' The description adds no format or provenance detail beyond that, so the baseline 3 applies.

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

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

Specific verb+resource ('Get one comment by id') with explicit contrast to the sibling lister ('wp_list_comments lists several comments with filters'). An agent can distinguish single-fetch from list-fetch 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 list-style retrieval to wp_list_comments and states the permission requirement (moderate_comments). It gives clear context for use but does not spell out when-not-to-use cases (e.g., moderation or threaded retrieval, which wp_moderate_comment/wp_reply_comment cover).

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 readOnlyHint/idempotent annotations it discloses concrete behavior: hook arguments are excluded, count is the total but events is capped at 200, timestamps are UTC ISO 8601, and the call requires manage_options. It also notes the AlphaBridge forwarding scope, which matters for multi-site connections.

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?

It is a single dense paragraph, but the key facts (list, ordering, fields, cap, permission) are front-loaded and each clause carries content. Slightly over-packed with semicolons, which costs a point on readability rather than on waste.

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

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

With no output schema and no parameters, the description carries the burden well: it defines both output fields, the 200-item cap against the total count, the timezone/format, and the permission requirement. 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?

The tool takes zero parameters, so the baseline is 4. The description usefully spends its words instead on the response shape (count, per-event next_run and schedule, with false for single events), compensating for the absent 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?

States a specific verb and resource ('List the WP-Cron events scheduled on this site') plus ordering ('soonest first') and the exact fields returned per event. It is clearly distinguishable from the mutation siblings wp_schedule_cron and wp_unschedule_cron, which it names.

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 usage context ('Useful to check whether a job runs and when') and points to the tools that add and clear events, so an agent can route correctly. It stops short of stating when-not to use it (e.g. use wp_unschedule_cron to remove instead of reading), 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?

Goes well past the readOnlyHint annotation: it discloses the exact return keys (available, lines, log), that a missing file yields available=false with a message rather than an error, that the log may contain sensitive file paths and queries, and the WP_DEBUG_LOG prerequisite. It also explains the AlphaBridge Connect forwarding to a single reachable site, which matters for interpreting results.

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 resource and file path, then return shape, then failure behavior, then constraints. Roughly five dense sentences with no filler, though the multi-site forwarding note could be trimmed for a tool an agent will call for one purpose.

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

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

With no output schema, the description carries the return contract itself — available, lines, log — plus the non-error failure mode and the permissions/environment needed. That is everything an agent needs to call it and interpret either 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?

Schema coverage is 100% and the single parameter is fully documented there, including the 1–500 clamp and default of 100. The description adds one useful clarification by naming the returned 'lines' count as distinct from the input 'lines' parameter, but contributes no further syntax or format detail. Baseline 3 applies.

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

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

States a specific verb and resource — return the last lines of wp-content/debug.log — and explains what that file contains (PHP errors, warnings, notices when WP_DEBUG_LOG is on). No sibling tool reads a log file, and the description makes the scope boundary explicit, so an agent can distinguish it immediately.

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?

Frames the tool's purpose as 'diagnosing failures' and states the negative condition: a log written to another path is not read. It also gives the gating conditions (manage_options, write access on). There is no named alternative because no sibling serves as a substitute, so explicit when-not/alternative routing is largely moot here.

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 real behavior beyond them: the returned field set, the meaning of metadata, the empty-caption edge case for password-protected files read by a non-editor, the permission prerequisite, and the not-found failure mode. That is substantive disclosure an agent cannot get 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?

Purpose and return shape are front-loaded, and each sentence carries information. It is somewhat dense — the password-protected caption caveat and the AlphaBridge forwarding note add length — but all of them are useful rather than 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 takes on the burden of describing the return object and does so ('{id, title, mime, url, alt, caption, metadata}'), plus error and permission behavior. Nothing an agent needs to invoke this single-parameter read 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 single 'id' parameter is already documented as 'Attachment id, as wp_list_media returns it.' The description reinforces the origin of the id but adds no format or constraint detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Get one file of the media library (attachment) by id') and names the two sibling tools it must not be confused with (wp_get_post for posts/pages, wp_list_media for listings). An agent can select it without opening the schema.

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

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

Explicitly routes non-media ids away ('An id that is not a media file ... returns a not-found error: posts and pages are read by wp_get_post, and wp_list_media lists the media with their ids'). This gives both the when-to-use and the when-not-to-use plus the alternative, which is the top of the scale.

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 naming the required capability (edit_theme_options), the not-found error behavior for unknown menus, item ordering ('in menu order'), and the exact returned shape including parent semantics (0 at top level). Annotations already cover read-only/idempotent safety, so this added permission and error detail is substantive surplus context.

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

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

Five short sentences, front-loaded with what is returned, then shape, then permissions, then errors and discovery. Every sentence carries distinct operational 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?

No output schema exists, and the description compensates by enumerating the returned menu and item fields and their ordering. Combined with permission and error 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% and the schema already says the menu parameter accepts 'id, slug or name, as wp_list_menus returns them'. The description adds no format or resolution details beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Get one navigation menu with its items, in menu order') and distinguishes itself from the plural sibling wp_list_menus by returning a single menu plus its items. An agent can tell it apart from wp_list_menus without consulting 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?

Points to wp_list_menus as the way to discover valid menu identifiers and warns that an unknown menu yields a not-found error, which shapes correct invocation. It does not state explicit exclusions, but the single-vs-list split with the sibling is clear enough for correct 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 readOnly/idempotent/non-destructive, but the description goes well beyond them: it warns that raw code may contain API keys or other secrets, names the capability gates and blocked constants, clarifies single-site scope and the AlphaBridge forwarding, and enumerates the returned fields since no output schema exists. No contradictions with the read-only annotations.

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

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

Front-loaded with purpose and id source, then prerequisites and return fields; every sentence carries information. The single dense run-on sentence packing the return field list is slightly harder to scan than it needs to be.

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

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

With no output schema, the description supplies the return shape (list fields plus native_location, description, modified, code, declares) and defines 'declares', plus access restrictions and failure behavior. Nothing an agent needs 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 both parameters are fully documented, including the provider enum and the 'needed only when both are active' condition. The description restates the id provenance rather than adding syntax or format detail, so a baseline 3 is appropriate.

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

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

States a specific verb and resource ('Read one snippet of Code Snippets or WPCode with its code') and ties it to the sibling listing tool wp_list_php_snippets, which supplies the id. An agent can distinguish it from wp_list_php_snippets and wp_delete_php_snippet without reading the schema.

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

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

Explicitly names the source of the id (wp_list_php_snippets), says provider is needed only when both plugins are active, and states the preconditions: administrators only (manage_options and edit_plugins), not on multisite, blocked by DISALLOW_FILE_EDIT and DISALLOW_FILE_MODS. It also states that an unknown id is refused, so failure behavior is anticipated.

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 still adds substantive context: the manage_options gate on protected meta, the allowlist filter, the built_with/write_via disclosure, and the caveat that post_content may not reflect what the site renders. That is well beyond what the structured fields 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 core action and distinguished alternatives before the caveats, and every clause carries information. The field enumeration and permission details are packed into long, run-on sentences, which slightly hurts scannability.

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's field list is doing necessary work, and it also covers permissions, error cases, and the AlphaBridge connection scope. 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 documents defaults, so the baseline is 3; the description goes further by explaining why include_protected matters (allow-listed '_' keys such as _elementor_data) and that it requires manage_options. include_meta gets no equivalent treatment in the description, leaving one small gap.

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

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

States a specific verb and resource ('Get one post, page or other post-type entry by id') and enumerates the returned fields, so an agent knows exactly what comes back. It explicitly distinguishes itself from wp_get_post_meta and wp_get_builder_layout, which are the 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?

Names the alternatives and the condition that selects them ('One meta key alone comes from wp_get_post_meta, a page builder's own layout from wp_get_builder_layout'). It also states prerequisites (edit_posts, manage_options for include_protected) and failure modes (unknown id -> not-found, unreadable post -> refused).

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 readOnlyHint/idempotentHint annotations: it defines what 'public' excludes (underscore prefix, credential-like keys, non-editable keys), states the edit_posts requirement, names the not-found behavior for an unknown post id, and describes the manage_options gate plus the ab_mcp_pro_protected_meta_allowlist filter for protected keys. The 'read-only' claim is consistent with annotations.

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

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

Front-loaded with the core action and both modes before the permission caveats; every sentence earns its place. The heavy parenthetical packing makes it denser than it needs to be, but nothing 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 supplies the return shapes itself (id/key/value for a single key; id plus a key-to-value map for the listing), and it covers permissions, error cases, and the connection-scoping note. 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%, so the baseline is 3; the description adds genuine semantics on top — a missing key yields an empty value or the registered default, and include_protected only widens the full listing to allow-listed underscore keys and can also be bypassed by naming one such key directly. The credentials-like exclusion rule is only in the description, not 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 ('Get the meta of one post') and immediately enumerates both operating modes (single key vs. all public meta) with their return shapes. It also distinguishes itself from the sibling wp_get_post, which returns the same public meta bundled with the post, so an agent can choose 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?

Explicit conditions are given: omit key to list all public meta, set include_protected=true only when the account has manage_options, and use wp_get_post if you want the public meta alongside the post. What is missing is a forward pointer to wp_update_post_meta for writes, but the read-only framing 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 cover readOnly/idempotent/non-destructive, but the description adds two facts the annotations cannot: the edit_posts capability requirement and the fact that AlphaBridge Connect forwards the call to the single site this connection reaches. That scope note matters for interpreting results across connections. It does not discuss caching or whether results are filtered by user, which keeps it from 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?

Three compact sentences, front-loaded with the scope statement before the return shape and the auth requirement. 'Read-only; takes no arguments' mildly duplicates the annotations, but it is one clause and does not bloat the text.

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

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

There is no output schema, and the description compensates by naming the envelope (post_types) and each field's meaning, including that 'public' is WordPress' own public flag — exactly what an agent needs to filter results. Auth, scope, return shape, and the taxonomy alternative are all covered.

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 arguments, so the parameter bar is trivially met (baseline 4). The description spends its room on the return contract instead, which is more useful given the empty input 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 every post type registered on the site') and explicitly bounds scope to built-in, custom, and internal types like revision and nav_menu_item. It cleanly separates itself from the two nearest siblings, wp_list_posts (which lists posts) and wp_get_taxonomies.

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 actionable downstream use — 'name is the value the post tools take as type' — which tells the agent to call this before creating or filtering posts. It also routes taxonomies to wp_get_taxonomies. It stops short of stating any exclusion or precondition beyond the capability, so it is clear context rather than a full when/when-not rule set.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false. The description adds useful behavioral context beyond annotations: the manage_options requirement, no-argument nature, empty-value semantics for timezone and permalinks, and the AlphaBridge forwarding scope.

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 well-structured: returned fields first, edge-case semantics next, then permissions, operational traits, and the wp_site_info alternative. Every sentence adds information without repetition.

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

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

For a zero-parameter read-only settings tool with no output schema, the description is complete: it lists expected fields, explains ambiguous empty values, states the permission requirement, and routes agents to wp_site_info when they need adjacent data.

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 schema is not the limiting factor. The description correctly reinforces that the tool takes no arguments, though there are no parameter semantics to explain.

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

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

The description uses a specific verb-resource pair ("Get common site settings") and enumerates the returned fields, including title, URLs, email, timezone, language, posts per page, date format, and permalinks. It explicitly distinguishes itself from wp_site_info for versions, themes, and plugins.

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 required capability (manage_options), clarifies the tool is read-only and takes no arguments, and names wp_site_info as the alternative for versions/theme/plugin data. The forwarding note also clarifies the connection scope.

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. The description adds valuable behavior: needs edit_posts, non-public taxonomies appear only for accounts that may assign their terms, takes no arguments, and it's forwarded to one site. This is meaningful context beyond annotations, though return format detail is already partly covered.

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 return shape; dense but every sentence carries information. The trailing forwarding note and permission detail are slightly crammed into one block but still earn their place.

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

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

Complete for a zero-param list tool with no output schema: it documents the return structure, permission requirement, visibility rule for non-public taxonomies, and scope (single site via bridge). Nothing an agent needs to call it correctly is missing.

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

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

Zero parameters, so baseline is 4. The description reinforces this ('takes no arguments') and explains the return fields (name, label, objects) and how name maps to the taxonomy argument of term tools — useful semantic bridging.

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 taxonomies registered on the site', with built-in category and post_tag explicitly included. It clearly distinguishes itself from wp_list_terms (which lists terms) and wp_get_post_types (which lists post types).

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

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

Names the alternative tools and their roles: terms are listed by wp_list_terms, post types by wp_get_post_types, and this tool supplies the taxonomy value those tools consume. Effectively tells the agent when this tool is the right 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/openWorld=false, so safety is covered; the description goes further by disclosing the capability requirement for non-public taxonomies, the not-found error condition, and the meaning of the count and parent return fields. The AlphaBridge single-site forwarding note adds deployment scope that no structured field carries.

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

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

Front-loads the purpose and return shape, then packs prerequisites, error behavior, and sibling routing into short clauses with no filler. Every sentence is load-bearing, including the return-field glosses that substitute for the missing 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 no output schema, the description compensates by enumerating the returned fields and explaining count and parent, plus permissions, error behavior, alternatives, and connection scope. 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 both parameters are documented in the schema (term_id cross-references wp_list_terms output, taxonomy gives examples). The description only restates "by id and taxonomy" and adds that the term must belong to that taxonomy; baseline 3 is correct when the schema does the heavy lifting.

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

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

States a specific verb and resource ("Get one term by id and taxonomy") and immediately distinguishes itself from wp_list_terms and wp_get_term_meta by naming what those return. An agent can pick the right tool from the sibling list without opening any schema.

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

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

Gives explicit routing rules: name/slug lookups go to wp_list_terms (with the 'search' mode named), custom meta goes to wp_get_term_meta. It also states the prerequisite for non-public taxonomies and the not-found outcome, 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?

Goes well beyond the readOnlyHint annotation: discloses that underscore-prefixed, protected, and credential-like keys are withheld, that keys the account cannot edit are excluded from the all-keys listing, the exact return shapes including multi-value behavior, the required capability (assign terms, or edit term for a single key), not-found behavior, and the AlphaBridge forwarding scope.

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 scope are front-loaded, then permissions, return shapes, and error behavior follow in a logical order. The sentences are long and packed with clauses, which makes it dense, but almost nothing is redundant filler.

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

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

For a two-parameter read tool with no output schema, the description covers return shapes, permissions, error behavior, filtering rules, and alternative tooling. An agent has everything it needs to call this correctly.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema, which sets the baseline at 3. The description does add value by explaining what omitting the key returns and the permission difference between the all-keys and single-key modes, but it largely restates the schema's key 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 and resource ("Read custom meta of one term") and immediately scopes it to one key or all public keys. It is clearly separable from wp_get_term ("the term's own fields come from wp_get_term") and from wp_get_post_meta/wp_get_user_meta by naming the object type.

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

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

Explicitly routes the agent to wp_get_term for the term's own fields, which is the main ambiguity an agent would face. It does not name the write counterpart (wp_update_term_meta) or state when not to call it, so it falls short of a 5.

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

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

Beyond the readOnly/idempotent annotations, it discloses that no remote request is triggered, that data freshness is bounded by a roughly twice-daily scheduled check, that empty lists mean 'no update known at that check', and the required capability. That is exactly the context an agent needs before trusting the output.

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 and caching caveat, then the return shape, then the capability and forwarding note. Dense but every clause adds information; the AlphaBridge forwarding sentence is mildly off-topic for invocation decisions but still relevant scoping context.

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

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

No output schema exists, and the description compensates by enumerating the returned fields for core, plugins and themes plus the meaning of empty lists. Combined with the freshness caveat and permission requirement, an agent can call and interpret this safely.

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 and there is nothing further to disambiguate. The description instead spends that space on the return shape, which is appropriate.

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

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

States a specific verb and resource ('Report available core, plugin and theme updates') and immediately qualifies scope with 'as of WordPress's own last scheduled check'. Distinguishable at a glance from wp_update_core, wp_bulk_update_status and wp_list_plugins.

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?

Clearly frames this as a read-only, cached inspection step and states the 'Needs update_core' capability requirement. It doesn't explicitly say 'call this before wp_update_core/wp_install_plugin', so the alternative-selection guidance is implied rather than stated.

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

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

Annotations already cover read-only/idempotent safety, and the description adds real value beyond them: the required `list_users` capability, the not-found failure mode, the field set returned (including that `registered` is site time with UTC offset), and the single-site forwarding scope of the connection.

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 lookup keys, then return shape, then prerequisites and fallbacks — each sentence carries information. The telegraphic phrasing ('Needs list_users.') is efficient, though the final AlphaBridge forwarding sentence is slightly disconnected from the rest.

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

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

With no output schema, the description compensates by naming the returned fields and their formats. Combined with auth requirement, error behavior, and sibling routing, an agent has everything needed 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 already documents precedence for id/login/email, so the baseline is 3. The description adds genuinely new semantics not in the schema — that all three are optional yet at least one is effectively required, and that a miss is a not-found error rather than an empty result.

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 ('Get one user account') plus the three lookup keys, and enumerates the returned fields. It is clearly distinguishable from wp_list_users (search) and wp_get_user_meta (meta), both of which are named.

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: partial-name lookup goes to wp_list_users (search), user meta goes to wp_get_user_meta. It also states that supplying none of the three keys, or getting no match, yields a not-found error — a concrete when-not 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?

Goes well beyond the readOnly/idempotent annotations: it names the exact readable key set, the permission prerequisites (list_users plus edit rights on the user and each field, administrators in standard roles), and the not-found behavior for an unknown user_id. It also documents both return shapes, 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?

Front-loads purpose and the allowed key list, then permissions, error behavior, and return shapes in a compact single block. Slightly dense, and the trailing forwarding note is contextual rather than essential, but no sentence is filler.

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

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

With no output schema, the description supplies the return shapes, the constraint set, the authorization requirements, and the error case. There is nothing an agent needs in order to call this correctly that 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 real semantic value by enumerating the only legal values for 'key' and restating that omitting it reads all fields. The user_id hint ('authors' ids appear in wp_list_posts and wp_get_post') is carried by the schema, not the description.

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

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

States a specific verb and resource ('Get standard profile fields (user meta) of one user') and immediately bounds scope: one field or all of them, from a fixed key list. An agent can tell this apart from wp_get_user or wp_update_user_meta 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?

Gives clear when-to-use context and an explicit exclusion: only the enumerated non-sensitive keys are readable, any other key is refused with that list. It stops short of naming alternatives (e.g. wp_get_user for other user data), so it is clear but not fully 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 cover safety (readOnly, idempotent, non-destructive, closed-world), and the description adds substantive context beyond them: the required `edit_theme_options` permission, the credential redaction rule with `hidden_keys`, and the fact that results are forwarded by AlphaBridge Connect to a single site.

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 purpose, then the mode switch, then the return shape and edge cases in a tight run of sentences. Every clause (default scope, credential omission, permission, forwarding note) carries actionable 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?

With no output schema, the description supplies the return shape (`{id, id_base, number, name, sidebar, settings}`), the id format example, the hidden_keys behavior, and the permission prerequisite — everything an agent needs to call and interpret results 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 optional `sidebar` param is fully documented there, so the baseline is 3. The description adds meaning the schema does not: that omitting the param also returns inactive widgets, and that an empty `sidebar` value in results means the widget belongs to no area.

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 site's widgets with their settings") and immediately scopes the two modes: all areas including inactive by default, or one area when `sidebar` is given. It also distinguishes itself from the sibling `wp_list_sidebars` by noting that tool lists the areas themselves.

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 describes the default behavior versus the filtered behavior, and names the alternative tool (`wp_list_sidebars`) for obtaining area ids. An agent knows both when to use it and where to get the `sidebar` value it accepts.

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 destructive/openWorld/idempotent hints: no undo point is recorded, an existing folder causes no change and returns the installed version, part of the activation check may be rolled back in the same call while the install persists, and errors carry file and line. This is exactly the mutation/rollback context 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 is front-loaded and most clauses carry unique information, but it is a single run-on paragraph with tangled phrasing ('the answer, an error, names the error with file and line'; 'plus what the activation check reports'). Splitting prerequisites, returns and rollback into short sentences would make it far easier to parse.

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 fields (installed, plugin file, activated, version), the error shape, capability requirements, and the rollback contract. Nothing an agent needs to call 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 baseline is 3, but the description adds real meaning: the slug must be a WordPress.org directory slug, and activate requires a distinct capability whose absence yields installed=true with activated=false. That clarifies the consequence of each parameter beyond the schema's one-liners.

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 the WordPress.org directory by slug, optionally activating) and implicitly delineates itself from siblings by naming wp_update_plugin for upgrades. An agent can distinguish this from wp_install_theme, wp_activate_plugin and wp_update_plugin 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 prerequisites (install_plugins, and activate_plugins for activate), the environment exclusion (refused when DISALLOW_FILE_MODS is set), and the alternative for an already-installed plugin (wp_update_plugin). It even states the fallback outcome when activate_plugins is missing (installed but activated stays false).

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true; the description adds substantial context beyond them — no undo point is recorded, an existing theme folder is not overwritten and WordPress's error is surfaced instead, and the return shape (installed, stylesheet, version) is spelled out. These are exactly the side effects an agent needs to know before a destructive install.

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 scope lead the sentence; each following clause carries distinct, non-redundant information (return values, permission, refusal mode, no-undo, overwrite behavior, alternatives, routing). Dense but 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?

For a one-parameter destructive install with no output schema, the description covers preconditions, failure modes, side effects, return fields, and sibling routing — everything needed to invoke 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 itself documents slug format, lower-casing, and character stripping in more detail than the description. The description only restates 'by its slug', adding no semantics beyond the structured field, 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 (download and install a theme), the source (WordPress.org directory), the keyed selector (by slug), and a critical scope qualifier (the theme is not activated). This separates it cleanly from wp_activate_theme and the ZIP-install path without the agent needing to open 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?

Names explicit alternatives and the conditions that select them: ZIP sources go to wp_install_theme_zip, switching themes goes to wp_activate_theme. It also states preconditions (needs install_themes) and the refusal condition (DISALLOW_FILE_MODS), so an agent can decide before calling whether the tool will even succeed.

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 adds substantial context: the password value is never returned, last_used is null when unused, empty list semantics, the HTTPS/local-environment prerequisite with its error behavior, and required capability. This is well beyond what annotations provide.

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

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

Front-loaded with the core action and return shape; every clause earns its place. The single dense sentence packs many facts, making it slightly run-on, 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?

With no output schema, the description fully carries the return shape, edge cases (empty list, null last_used), permission requirements, and error conditions. 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 documents the not-found behavior for user_id, so the baseline is 3. The description adds meaningful semantics around the returned fields (uuid, name, created, last_used, ISO 8601, null handling), pushing 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?

States a specific verb (List) and resource (application passwords) scoped to one user, and implies the fields returned. It is clearly distinguished from wp_revoke_application_password and 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?

'Suited to reviewing which applications can sign in as that user' gives a clear usage context, and it names the prerequisite (list_users) and edit rights. It lacks an explicit 'when-not'/naming of the sibling revoke tool, so not quite 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 safety (readOnly, idempotent, non-destructive), and the description goes well beyond them: the required capability (moderate_comments), the exact return shape, that no total count is returned, and that a page past the end is empty. It also discloses date formatting and site-time semantics.

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 ordering, then return shape, then pagination caveats, then capability and sibling routing. Dense but every clause carries information; only the trailing forwarding sentence sits slightly apart from the operational content.

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

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

There is no output schema, so the description's inline return shape, pagination behavior, and empty-page semantics are exactly the context an agent needs. With annotations covering safety, nothing operationally important 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 all five parameters are already documented and the baseline is 3. The description adds little parameter detail, and its status vocabulary ('approved', 'unapproved') does not match the schema's accepted values ('approve', 'hold', 'all'), which could mislead an agent rather than clarify.

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, newest first') plus the three filters available. It explicitly distinguishes itself from the sibling wp_get_comment, so an agent can choose between list and single-fetch 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?

Names the alternative (wp_get_comment for one comment with its parent) and explains the default status scope, which effectively tells the agent that spam and trash are excluded unless requested. It stops short of explicit when-not guidance (e.g. use wp_search for cross-entity search), so not a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description still adds genuinely new facts: default ordering, relevance re-ordering when search is supplied, the 'inherit' status filter that excludes private files, per-account read scoping, empty-list-on-no-match, and the required upload_files capability. That is real behavioral disclosure beyond the structured fields.

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

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

Front-loaded with purpose and ordering, then return shape, then constraints — a sensible order for a scanning agent. It is dense but every clause carries information, though the trailing AlphaBridge Connect forwarding note is boilerplate and one sentence stacks several unrelated constraints (status filter, permissions, empty result) into a single run-on.

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

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

There is no output schema, and the description compensates by naming the returned item fields ({id, title, mime, url, date}) and pagination {total, total_pages}, plus empty-result behavior. Combined with the permission and filtering caveats, 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 the baseline would be 3, but the description adds semantics the schema does not carry — that supplying `search` switches result ordering from newest-first to relevance. That is a meaningful behavioral consequence of a parameter choice rather than a restatement.

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 ordering behavior (newest first, relevance on search) and return shape. It explicitly separates itself from wp_get_media, but leaves the boundary with the sibling wp_list_uploads (and wp_list_media vs file-on-disk listings) unaddressed, which is the one ambiguity an agent could stumble on.

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 alternative explicitly: 'wp_get_media returns one file with its sizes, alt text and caption,' which is a clear routing rule for single-file lookups. It also states the prerequisite capability (upload_files). It stops short of explicit when-not conditions, e.g. when a caller should reach for wp_list_uploads or wp_search instead.

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 annotations by disclosing the required capability (edit_theme_options), the exact return shape (a 'menus' collection with id, name, slug, count), and the connection scoping ('the one site this connection reaches'). Since annotations already declare read-only/idempotent, the auth and return-shape details are the value-add.

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

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

Three tight sentences with the action and returned fields front-loaded, followed by auth and routing context. Every clause carries information an agent needs; nothing is repeated from structured 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?

For a zero-parameter, read-only lister with no output schema, the description supplies the returned field names, the auth prerequisite, and the single-site scoping — everything needed to select and 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 tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The description correctly implies no filtering or selection options exist.

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 (navigation menus) with explicit scope ('all at once') and enumerates the returned fields (id, name, slug, count). It is unambiguously distinguishable from wp_get_menu, which is named as the tool for a single menu's items.

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?

Clearly routes the agent: use this to get all menus in one call, and use wp_get_menu for the items of one menu. It does not add explicit exclusions for adjacent write tools like wp_create_menu or wp_get_menu edge cases, so it falls just short of the full when/when-not bar.

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

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

Beyond the readOnly/idempotent annotations, it discloses real operational constraints: administrators only (manage_options and edit_plugins), not available on multisite, blocked by DISALLOW_FILE_EDIT and DISALLOW_FILE_MODS, and that calls are forwarded via AlphaBridge Connect to a single site. It also explains where snippets actually live (the plugin, not AlphaBridge), which shapes expectations about returned 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-loaded with the returned field list, then constraints, then the get_php_snippet pointer. Dense rather than padded, though the sentence about AlphaBridge keeping no snippets of its own is context rather than invocation guidance and could be trimmed.

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 compensates by enumerating return fields, and it covers auth, environment restrictions, and the fallback when no snippet plugin is active. 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 both parameters are enums with descriptions, so the schema already carries the semantics. The description's 'Only PHP snippets unless type is all' and the provider default restate what the schema says rather than adding new meaning such as ordering or filtering interactions. Baseline 3 is appropriate.

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

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

States a specific verb and resource (list snippets) and enumerates exactly which fields come back (provider, id, name, type, location, active, trashed, priority, sha256, last error). It also explicitly distinguishes itself from the sibling wp_get_php_snippet, which returns the code itself.

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

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

Clear routing: use this to enumerate snippets, use wp_get_php_snippet for the code, and the type/provider filters are explained. It also covers the degenerate case (neither plugin active) with a pointer to how to get one. It does not spell out exclusions like 'do not use this to check whether a snippet exists before deleting', 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 beyond the annotations by disclosing the 800-item cap and, importantly, that truncation is not signalled in the response — a caveat an agent would otherwise misread as a complete listing. It adds the capability requirement (edit_plugins), the site write-access precondition, and the AlphaBridge Connect forwarding scope, none of which appear in 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-loaded with purpose, then alternatives, then return shape, then failure modes and prerequisites — a sensible ordering with essentially no filler. It is a dense semicolon-chained block that borders on run-on, which slightly hurts scannability but nothing is expendable.

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 correctly carries the return shape: 'plugin and files', paths relative to the folder, sorted, capped at 800. Combined with the error conditions and permission requirements, 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 already supplies the derivation (the part before the slash in the wp_list_plugins path) plus an akismet example. The description adds no syntax, validation, or edge-case meaning 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?