wpxmcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.0.0
Disambiguation4/5
Tools are largely distinct, with clear descriptions for overlapping use cases (e.g., get_content vs get_content_summary vs get_content_by_slug vs find_content_by_url). A few explicit aliases (create_plugin/install_plugin, edit_media/update_media) are labeled as such, but the sheer number of tools may still cause some selection confusion despite clear descriptions.
Naming Consistency5/5
All tool names follow a consistent verb_noun snake_case pattern (e.g., list_comments, create_term, update_theme_file, delete_menu). Even compound names like assign_terms_to_content and get_global_styles maintain the convention. The aliases also conform to the pattern, so there is no stylistic inconsistency.
Tool Count1/5
At 117 tools, this is an extreme count far beyond the calibration's 50+ threshold. While the tools cover a broad WordPress management domain, many could be consolidated (e.g., get_content and get_content_summary could be one tool with a parameter). The volume is overwhelming and likely to confuse agents, making it inappropriate for efficient use.
Completeness5/5
The toolset is remarkably comprehensive, covering content lifecycle, taxonomies, media, users, comments, plugins, themes (including draft workflows), menus, widgets, templates, global styles, blocks, revisions, meta, options, SQL, WP-CLI, abilities, snippets, fields, audits, bulk operations, and an escape-hatch REST API tool. There are no obvious dead ends; even edge cases like unregistered meta have dedicated tools.
Average 4.1/5 across 117 of 117 tools scored. Lowest: 2.8/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 9 commits in the last 12 weeks
- Last stable release on August 23, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description contradicts the annotations: it states 'Delete one of your saved playbooks' implying destructive behavior, while annotations declare destructiveHint=false. This is a clear contradiction. The added context about bundled playbooks is useful but cannot offset the inconsistency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, with the purpose front-loaded. The second sentence adds essential nuance about bundled playbooks. No wasted words, though it could be slightly more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with one parameter and no output schema, it covers the primary action and a key caveat. However, the contradiction with annotations and lack of error handling or result information make it incomplete. A 3 is fair given the simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the single parameter 'name' with a description, and the tool description adds little beyond that, only clarifying that it refers to a saved skill. With 100% schema coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete) and the resource (saved playbooks). It adds a relevant nuance about bundled playbooks, which distinguishes it from generic delete tools, though it does not explicitly separate it from sibling delete_* tools. The verb+resource is specific enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It does not mention any sibling tools or conditions that would select this over others (e.g., delete_content, delete_term). The caveat about bundled playbooks is a constraint, not a usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=false, destructiveHint=false) already indicate this is a write operation that is not read-only. The description only restates 'Install a plugin' and adds the alias fact, which is naming information, not behavioral context. It does not disclose side effects (e.g., filesystem changes, activation behavior), permissions needed, or what happens on failure. With no additional behavioral disclosure beyond the basic action, the score is low.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action. The second sentence clarifies the alias relationship, which is useful for disambiguation but not redundant. It is concise and well-structured, though the alias note could be considered slightly extraneous if the sibling tool already covers that context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write operation with no output schema and only 3 parameters, the description is thin. It does not explain what happens after installation (e.g., default activation status, return value, or errors), nor does it mention how the alias differs functionally from install_plugin (it does not differ). The status parameter defaults to 'inactive' implying installation without activation, but that is not conveyed in the description. An agent would need to infer behavior from the schema and annotations, making this incomplete for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and all three parameters (slug, status, site_id) already have descriptive text in the schema. The description does not add any extra meaning or constraints beyond what the schema provides. Since the schema is complete, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action and resource: 'Install a plugin from the WordPress.org repository.' It also distinguishes itself from the sibling install_plugin by explicitly noting it is an alias, so an agent understands they perform the same operation. This resolves any ambiguity about the misleading title 'Create a plugin'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description identifies install_plugin as a clearer name but provides no explicit guidance on when to choose this tool over install_plugin or when not to use it. It does not state preferred usage, conditions, or alternatives beyond noting the alias relationship. The instruction is implicitly that either works, but no direct selection criteria are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, indicating a non-destructive modification. The description adds the fields that can be changed (label, target, nesting, position), which is useful context, but it does not disclose side effects, reversibility, or any prerequisite conditions beyond that. Given the annotation coverage, a score of 3 reflects the partial added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action and key scoping fields. It has no redundant detail and effectively communicates the core purpose without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 10 parameters, no output schema, and annotations covering safety, the description is adequate but minimal. It does not mention return behavior, but that is not required without an output schema. It omits context about the WordPress menu system or any operational notes, relying heavily on the schema. The description is sufficient for a basic call but leaves room for richer guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with each of the 10 parameters individually documented. The description's phrase 'label, target, nesting or position' loosely maps to parameters like title, url, parent, and menu_order, but it adds little beyond what the schema already provides. Since the schema carries the semantic load, this is a baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Change') and resource ('a menu item'), and enumerates the changeable aspects: label, target, nesting, or position. This clearly conveys the tool's function and differentiates it from siblings like add_menu_item, delete_menu_item, and reorder_menu_items, though it does not explicitly name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention add_menu_item for creating, delete_menu_item for removing, or reorder_menu_items for ordering, nor any conditions that would make one more appropriate. The agent must infer usage context from the name and parameters alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish that this is a non-idempotent, non-read-only mutation (readOnlyHint=false, destructiveHint=false). The description adds the two behavioral outcomes (rename, location change) but omits any side effects like the fact that locations are fully replaced (which is stated in the parameter description) or the effect on auto_add and description fields. It does not contradict the annotations; it just adds a modest amount of behavioral context beyond what they encode.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence that front-loads the two most salient actions. There is no filler, redundancy, or unnecessary detail. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description under-specifies the tool's capabilities: it only mentions renaming and changing locations, while the schema shows the tool can also update auto_add and description. An agent might incorrectly conclude these fields are not settable via this tool. Additionally, it does not mention that locations replaces current assignments (though that is in the param schema). For a tool with 6 parameters and no output schema, the description alone is insufficient for complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% — every parameter (id, name, site_id, auto_add, locations, description) has a description. The tool description itself maps 'rename' to the name parameter and 'theme locations' to the locations parameter, but it does not mention auto_add or description as updatable fields. Since the schema already carries full meaning, the description adds marginal value; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Rename a menu or change which theme locations it fills' states specific verbs (rename, change) and the resource (menu), and specifically calls out two concrete actions that distinguish it from siblings like update_menu_item or delete_menu. The purpose is unambiguous and immediately scopes the tool to altering an existing menu's identity or placement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus related tools such as create_menu, delete_menu, or update_menu_item. It does not state prerequisites (e.g., the menu must already exist), nor does it contrast with alternatives. An agent receives no explicit selection cues beyond the tool's name and vague action verbs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a mutation (readOnlyHint=false, destructiveHint=false). The description adds valuable behavioral context: the default 'replace' mode and the side effect of auto-creating unknown term names. It also explains the effect of each mode. However, it doesn't disclose potential impacts like whether 'remove' could delete terms globally or affect other content, though 'detach' implies only association removal. This is adequate given annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences that front-load the core action and purpose, then explain the key behavioral nuance (auto-creation and modes). No filler or repetition. It earns a 4 for being compact and well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-param tool with 3 required and no output schema, the description covers the essential behavior: assigning terms, handling names vs IDs, and the three modes. It doesn't explain the site_id selection logic (but that's in the schema) or type parameter, and it doesn't discuss return value, but that's not required without an output schema. Overall, an agent can call this tool correctly with this description and schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema already describes all parameters including the 'unknown names are created' behavior for terms and default modes. The description repeats this and clarifies the default replace behavior, but adds little beyond what the schema provides. Since coverage is high, baseline 3 is appropriate; the description doesn't add unique semantic value for parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Assign taxonomy terms') and the resource ('to any content item'). It distinguishes itself from related tools like create_term or list_terms by focusing on assigning terms to existing content, and the added detail about auto-creating unknown names further clarifies its scope. However, it doesn't explicitly name a sibling to differentiate from, so it's not a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on when to use this tool (to assign terms to content) and explains the three modes (replace, add, remove) which guide the agent in choosing the right behavior. It doesn't explicitly mention alternatives like get_content_terms for reading terms, but the purpose is clear enough that an agent likely won't confuse it with other tools. Missing explicit 'when-not-to-use' guidance prevents a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already provide readOnlyHint=true and destructiveHint=false, so the description need not restate that it is read-only. The description adds no additional behavioral context beyond what the schema and annotations convey, such as return format or pagination defaults. It does not contradict the annotations and provides a baseline level of transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose ('List items in the media library') and then lists the key capabilities. There is zero wasted wording, and it is easy to scan. This is exemplary conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a read-only list operation with a fully described schema and safety annotations, the description is mostly complete. It omits explicit return format and does not differentiate from siblings, but those are minor gaps because the purpose is clear and the schema covers all parameter behavior. It is adequate for an agent to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 13 parameters have schema descriptions with 100% coverage, so the baseline is 3. The description does mention 'search, type filtering, date filtering and pagination', which groups some parameters, but it does not add any meaning beyond what the schema already states for each parameter. No additional semantic value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List'), the resource ('items in the media library'), and key capabilities (search, type filtering, date filtering, pagination). It is immediately distinguishable from sibling tools like list_content (content library) and get_media (single item), so an agent can tell what it does without inspecting the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description does not mention get_media for single-item retrieval or list_content for posts, nor does it state any contexts where this tool is preferred. The only context is implied by the name and purpose, but no explicit usage direction is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the autoloaded-options/bloat observation, which is a mild diagnostic hint. No contradiction with annotations. It doesn't disclose return format or pagination, which is a minor gap given the annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose. The second sentence about autoloaded options adds real diagnostic context rather than fluff, but it is slightly ornamental and not strictly load-bearing for calling the tool correctly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Reasonably complete for a read-only tool with zero required parameters and 100% schema coverage. The description explains what the tool is for and when it matters (configuration reads, bloat diagnosis). No output schema and simple return semantics make further detail unnecessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters (limit, names, search, site_id) are already well documented in the schema. The description adds little parameter-level value beyond the word 'browsing' implying the search/limit interplay. Per baseline, 3 is appropriate when the schema carries the load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource: 'Read values from the WordPress options table by name.' It names the exact storage location (options table) and the access mechanism (by name), and the 'where plugins and themes keep their configuration' clause distinguishes it from get_site_settings and get_theme_mods. An agent can distinguish it from the set_option sibling 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides useful context for when to use it — reading plugin/theme configuration and spotting database bloat via autoloaded options. However, it never names alternatives or states when NOT to use it (e.g., no mention that set_option is the write counterpart, or that get_site_settings handles non-option settings). Context is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true (indicating a remote call). The description adds the 'secrets redacted' behavior and specifics of what the WordPress install reports, which is useful context beyond the annotations. It doesn't contradict the annotations, but it doesn't delve into rate limits or potential delays from the remote query either.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One effective sentence that front-loads the key purpose ('full configuration for one site') and then appends the supplementary info. No wasted words, though it could be broken into clearer parts. It's concise and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description carries the burden of explaining return values. It lists the specific pieces of information returned (secrets redacted, name, description, timezone, WordPress version, permalink shape, capabilities). Combined with the schema-provided parameter behavior, this is sufficient for an agent to know what to expect. Minor gap: it doesn't mention that the response might be large or structured in any particular way.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameters site_id and include_remote are fully described in the schema. The description does not add new meaning about parameters, but it inherently ties to site_id by saying 'one site'. With full schema coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get') and resource ('full configuration for one site'), with explicit details on what is included (secrets redacted, WordPress install info such as name, timezone, version). It clearly distinguishes itself from sibling tools like get_site_settings or site_info by covering the broad config plus remote site info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (it gets configuration and site-reported info) but does not explicitly mention alternatives or when not to use it. No exclusions are given. The context is clear, but an agent might still wonder how this differs from get_site_settings or site_info.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No contradiction: 'List' matches readOnlyHint=true and destructiveHint=false. However, the description adds only a use-case rationale ('recover a previous version if an edit went wrong'), not new behavioral detail such as pagination, ordering, or revision content shape — which the annotations already largely cover for safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single focused sentence with the action front-loaded ('List the stored revisions of a piece of content') and the purpose appended. No wasted words, appropriately sized for a simple read operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete enough for a read-only list tool: annotations carry the safety profile, the schema documents parameters, and the description covers purpose and typical use. The only gap is that it doesn't hint at what a revision record contains (given no output schema), but that's a minor shortfall for a listing operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters are documented in the schema at 100% coverage (id, type, site_id, per_page with defaults and bounds), so the description need not add parameter detail. It contributes nothing beyond the schema, which is fine given the coverage; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('List') and resource ('stored revisions of a piece of content'), followed by the rationale (see what changed, recover from a bad edit). The verb clearly separates it from siblings like restore_revision (which restores) and get_content (current state).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it — inspecting change history or deciding on recovery after a bad edit — but never explicitly contrasts it with the restore_revision sibling (which is the actual recovery action) or states when not to use it. The 'recover a previous version' phrasing hints at a follow-up without clarifying this tool only lists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a meaningful side effect: 'Changing a slug changes the term archive URL.' This goes beyond the annotations, which only indicate it is a mutation (readOnlyHint: false) and not idempotent. However, it does not clarify whether the update is partial (PATCH-like) or full replacement, nor does it mention any other consequences of updating fields like parent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no redundant words. The core action and field list are front-loaded, and the notable side effect is added without bloat. It is efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters and no output schema, the description covers the core purpose but leaves out important context such as usage guidance, whether it is a partial update, and how to handle the default taxonomy. The schema covers parameter details, but the description does not fully equip an agent to decide when and how to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters have descriptions in the input schema (100% coverage), so the schema already explains each field. The description only lists the fields without adding semantic detail, such as how 'meta' interacts with 'show_in_rest' or the behavior of 'parent' when set. It adds minimal value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Update'), the resource ('a term'), and enumerates the updatable fields ('name, slug, description, parent or meta') and scope ('in any taxonomy'). This clearly distinguishes it from get_term, create_term, and delete_term.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for modifying an existing term via the required 'id' parameter, but it does not explicitly state when to use this tool over alternatives (e.g., instead of deleting and recreating a term), nor does it mention prerequisites or exclusions. It only says 'in any taxonomy' without guidance on when this is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a meaningful side effect beyond the annotations: 'promoting to administrator grants full site control.' This adds real behavioral context about privilege escalation that annotations do not convey. It does not contradict readOnlyHint=false or destructiveHint=false. The password session-invalidation effect lives in the schema, not the description, but the description's added role warning earns a strong score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no waste. The first states the action and fields; the second flags the security-relevant consequence. The role warning, while peripheral to the mechanics, earns its place because it is high-stakes behavior an agent must weigh before invoking. Well front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 14-parameter tool with a nested object and no output schema, the description covers the core purpose and the most consequential behavior (role escalation). Since schema coverage is 100%, the description need not enumerate every param. The one gap is how the update is applied (replace vs merge) for fields like roles — 'Replace the user's roles' is in the schema, not the description, but the description remains sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description maps to key params (profile, email, password, roles) but adds no syntax or format detail beyond the schema. The role escalation note touches on the 'roles' param semantics, but the schema already documents each field, so the description adds marginal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb+resource ('Update a user') and enumerates the mutable fields: 'profile, email, password or roles'. It is distinct from the sibling set (get_user/create_user/delete_user) — 'update' unambiguously targets an existing user — though the differentiation relies on conventional naming rather than an explicit contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied but not stated. The description does not explicitly say 'use this to modify an existing user, use create_user for a new one', nor does it list when not to use it. The role-change warning hints at caution, but no when/when-not alternatives are named. Adequate but leaves routing to convention.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds valuable detail: 'Terms have no trash — deletion is immediate and permanent', the confirm:true requirement, and the side effect that content assignments are removed but content is not deleted, with fallback to default category. This enriches the agent's understanding beyond the annotation flags.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the core action, followed by essential caveats. There is no redundant phrasing; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive delete with 4 parameters and no output schema, the description covers the critical behavioral aspects: permanence, confirm requirement, and content-assignment consequences. It does not specify return format or error handling, but those are less critical given the explicit caveats. Overall, it provides sufficient context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter described, so the baseline is 3. The description reinforces that confirm must be true ('requires confirm: true') but does not add new meaning to site_id or taxonomy beyond the schema. It adds minimal extra semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Delete a term from any taxonomy' with a specific verb and resource, and the scope 'any taxonomy' clearly distinguishes it from get_term, create_term, update_term, and list_terms. It is unambiguous what the tool does and how it differs from term-related siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives (e.g., update_term for modifications) or when it should not be used (e.g., when only a soft removal is needed). The purpose is implied by the name, but no conditional or exclusionary context is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the deprecation/legacy status, which is genuinely useful context beyond the annotations. It discloses that the tool is an alias, implying identical behavior to update_media. It doesn't add mutation semantics, but annotations already carry readOnlyHint=false and destructiveHint=false, so the burden is partially lifted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with zero waste. The critical deprecation signal ('Legacy alias') is front-loaded, and the routing guidance follows immediately. Ideal brevity for a deprecated alias.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a deprecated alias, the description is essentially complete: it identifies the tool, declares its deprecation, and routes to the preferred alternative. The fully-documented schema covers parameter usage. Nothing an agent needs to decide whether to call it is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 7 parameters. The description adds nothing about parameters or how they map to the underlying media update, which is acceptable given the schema carries the weight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states this is a legacy alias for update_media, which clearly identifies it as a media-edit operation and distinguishes it from the preferred sibling. However, it relies on the reader knowing what update_media does rather than stating the edit behavior itself; the title partially fills that gap.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Prefer update_media' gives explicit routing guidance to use the sibling instead. It doesn't describe any scenario where this alias would actually be invoked (backward-compatibility callers), but the deprecation instruction is clear enough for an agent to avoid it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the data returned (full text, author, moderation status) but does not disclose additional behavioral traits such as error handling, required permissions, or rate limits. The annotation coverage makes this acceptable, though the description adds little beyond it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly written sentence that leads with the primary action and immediately specifies the returned fields. There is zero redundancy or filler, making it highly efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with no output schema, the description adequately conveys what the tool does and what it returns. The annotations cover the read-only and non-destructive behavior. The only omission is error behavior when the ID does not exist, but this is a minor gap for a get-by-id operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both id and site_id, with the site_id parameter already having a detailed explanation of its optionality and default behavior. The description only says 'by ID', which adds no new meaning beyond the schema. The baseline of 3 applies when the schema fully documents parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Fetch'), a resource ('one comment by ID'), and enumerates the returned fields (full text, author details, moderation status). This clearly distinguishes it from comment mutation tools like create_comment or update_comment, and from other entity getters like get_term or get_user.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for fetching a single comment by ID, but it does not explicitly mention alternatives such as list_comments for enumeration or moderate_comments for moderation workflows. No when/ when-not conditions or exclusions are provided, leaving the selection logic implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint: true and destructiveHint: false, so the description's 'Read' aligns with that. It adds conceptual value by explaining what global styles are, which goes beyond the annotations, but it does not disclose behavioral details like potential errors for non-block themes or the exact structure of the returned data. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero wasted words. The core purpose is front-loaded ('Read a block theme's global styles'), and the elaboration in the second sentence is informative yet compact. Ideal length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one optional parameter and no output schema, the description explains what the tool returns conceptually (design tokens and their origin). It does not mention error cases or output format, but these are not critical for basic invocation. The description is complete enough for an agent to know when and why to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents the single optional parameter site_id with its description, achieving 100% coverage. The tool description adds no additional meaning about this parameter, so it relies on the schema, which is sufficient. No need to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read' and the resource 'a block theme's global styles', and elaborates with specific contents (palette, typography, spacing, per-block styling) and where they come from (theme.json, Site Editor overrides). This is specific enough to distinguish from the sibling update_global_styles and get_theme, even without explicit comparison.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by indicating it reads global styles, but it does not explicitly state when to use this tool versus alternatives (e.g., 'use update_global_styles to modify' or 'use get_theme for theme-level info'). It gives context (block themes) but no exclusions or direct alternative references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the plugin-path identifier format but does not disclose behavior such as error responses or what happens for invalid paths. Since annotations carry the primary safety burden, a 3 is appropriate for the minimal extra context provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately states the action and resource, followed by concrete examples. Every word earns its place with no redundancy or filler, making it highly efficient for an agent to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only getter with only two parameters, high schema coverage, and annotations covering safety, the description provides all necessary context: the purpose, the identifier format, and the site scoping (via schema). No output schema exists, so no return details are required. The tool is fully specified for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters, so the schema already documents them. The description adds value by providing explicit example plugin paths ('woocommerce/woocommerce') that clarify the expected format beyond the schema's no-.php rule. This enriches the parameter understanding, justifying a score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves full details about an installed plugin, using a specific verb and resource. It distinguishes from sibling get_* tools by restricting to 'installed plugin' but does not explicitly contrast with get_plugin_info, which likely covers plugin repository metadata. A slight differentiation is present but not emphasized.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for installed plugins by giving file path examples, but it offers no explicit guidance on when to prefer this tool over alternatives like get_plugin_info or how it relates to list_plugins. No exclusions or sibling comparisons are given; the usage context is only inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is disclosed. The description adds the authentication requirement for non-'approve' statuses, which is a useful authorization nuance not covered by annotations. It does not elaborate on pagination or result volume, but given the annotation coverage, the added context is sufficient for a baseline 3.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The main filtering capability is stated first, then a focused note on moderation usage. Every word earns its place, and the structure is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list operation with 12 optional parameters, the description is adequately complete. It covers the primary use cases (filtering and moderation) and leaves parameter details to the fully documented schema. The absence of an output schema is acceptable for a list tool, and annotations handle the read-only safety profile. Nothing critical is missing for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 12 parameters are already documented with their own descriptions. The tool description reinforces the filter dimensions (post, status, author, date) but adds no new meaning beyond what the schema already provides. According to the rubric, high coverage yields a baseline 3, which is appropriate here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists comments and supports filtering by post, status, author, and date. It distinguishes itself from single-comment tools like get_comment by using 'list' and plural 'comments'. However, it does not explicitly differentiate itself from other list tools like list_content or from moderate_comments, so it is clear but not fully distinguished from all siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context on when to use the moderation-related status filters ('hold' and 'spam') and notes that these require authentication. This gives practical guidance on moderator workflows. It does not name alternatives or exclusions (e.g., 'use get_comment for a single comment'), so it falls short of an explicit when-to-use vs. when-not-to-use guide, but the context is present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only and destructive hints (readOnlyHint=false, destructiveHint=false), so the description carries a lighter burden. It adds the concepts of 'order' and 'nesting' which clarify the scope of the mutation. However, it does not explain side effects (e.g., what happens to items not listed, whether the operation is atomic, or how invalid parent/order values are handled). The description provides minimal additional behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that states the core function and a key benefit. It is front-loaded with the action and avoids redundancy. Every word contributes to understanding the purpose. No unnecessary details or filler, making it appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is incomplete for a mutation tool. It does not mention any return value or success indication. More critically, the tool operates on menu items but lacks a menu identifier parameter. There is no clarification on whether this reorders items within a specific menu or across all menus, nor whether it replaces the entire order or only affects the provided items. This ambiguity is significant and could lead to incorrect usage. The description does not address these gaps, so it is not complete enough for an agent to confidently invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The tool description does not add any parameter-level detail; it only refers to the overall action. The schema properties like menu_order ('Position; lower comes first') and parent ('Parent item ID, or 0 for top level') are adequately described, but the items array description ('The desired arrangement.') is vague. The description does not compensate for this vagueness, nor does it clarify the relationship between the items and the menu context. Thus, it stays at baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Set the order and nesting of several menu items at once'. It specifies the resource (menu items) and the operation (reorder/nest), and explicitly contrasts with 'updating them one by one', which distinguishes it from the sibling tool update_menu_item. This leaves no doubt about what the tool does and how it differs from alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when you need to set order and nesting for multiple items at once, as it is 'far less error-prone than updating them one by one'. This indirectly points to the alternative (likely update_menu_item for single items), but doesn't explicitly name it or state when not to use it. The guidance is clear enough for most cases but lacks an explicit conditional rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false (mutation) and idempotentHint=false (non-idempotent), so the behavioral baseline is known. The description adds the 'without re-uploading' nuance and lists fields, but does not disclose side effects such as whether unspecified fields are preserved or reset. This is adequate but not rich, given the annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence front-loaded with the action and resource, and it avoids repeating schema details. No wasted words; the key constraint (no re-upload) is included efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter mutation tool with full schema coverage and annotations covering the safety profile, the description covers the core purpose and a key constraint. However, the presence of edit_media introduces ambiguity about which tool to use, and the description does not resolve this, slightly reducing completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter is documented with a description. The tool description lists several fields (title, alt text, caption, description, attachment) but adds no new semantic meaning beyond the schema. Baseline 3 is appropriate when the schema carries the parameter documentation burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (update), resource (media item), and enumerates the fields (title, alt text, caption, description, attachment). It distinguishes from create by noting 'without re-uploading the file'. Although it doesn't address the edit_media sibling, the purpose is unambiguous and clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when updating existing media metadata without re-uploading, but it does not explicitly name alternatives or exclusion criteria. With an edit_media sibling present, there is no guidance on when to choose this tool over that one, leaving the agent to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry readOnlyHint=false, but the description adds real value: changes are global and take effect immediately for every visitor, with concrete ripple effects (homepage changes, date shifts), plus the Administrator-account requirement. No contradiction with annotations — the openWorldHint=true aligns with the described global reach.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences with no filler: core purpose front-loaded, followed by impact examples, then the auth requirement. Slightly condensed but every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 18-parameter mutation tool, the description plus 100%-coverage schema and readOnlyHint=false annotation cover the essential call context: what it does, why it matters, who may call it. Minor gaps remain (no mention of persistence to wp_options or return format), but the safety profile is already carried by annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 compensates by deepening meaning for the highest-impact parameters (show_on_front/page_on_front change the homepage; start_of_week/timezone shift displayed dates), which goes beyond their schema descriptions. The remaining 14 params are adequately covered by the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Update the site's core settings') and clarifies scope with concrete examples (homepage, timezone). It implicitly distinguishes itself from read-only siblings like get_site_settings by emphasizing 'global... for every visitor', though it never names an alternative explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context (global, immediate-effect settings) but no explicit when-to-use vs alternatives or exclusions. It doesn't distinguish itself from set_option, which could also mutate WP configuration, leaving the agent to infer boundaries between the two.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only indicate non-read-only and non-destructive. The description adds valuable behavioral detail: the change applies site-wide immediately, is persisted in the database, leaves the theme file untouched, and is reversible from the Site Editor. This goes beyond the structured fields and gives the agent a clear mental model of side effects and reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no redundant phrasing. The primary action is front-loaded, followed by the most important consequence (site-wide effect) and storage/reversibility details. Every sentence earns its place, and there is zero fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 6 parameters and no output schema, the description covers the key context: what it does, its scope, persistence, and reversibility. It does not mention the return value or error conditions, which could be useful, but these are often implicit for update operations. The description is sufficiently complete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all six parameters are already documented in the input schema. The description itself adds no parameter-specific guidance (e.g., expected formatting of 'content' or how 'kind' interacts). Per the rubric, a baseline of 3 is appropriate when the schema fully carries parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Update a block template or template part's markup') and a specific resource. It correctly distinguishes template from template_part, though it does not explicitly contrast with sibling tools like update_global_styles. The verb and object are unambiguous, so an agent can determine what the tool does without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: it notes the site-wide effect and that customization is stored in the database rather than the theme file, suggesting it is preferred over direct file edits. However, it never explicitly names an alternative or states when not to use it. The 'when to use this vs. something else' guidance 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No contradiction with annotations: readOnlyHint=false aligns with 'Change'/'move', and openWorldHint=true fits the open instance object. The description adds minor context by disclosing that relocation is possible, but it does not address side effects such as overwriting an existing instance (which is disclosed only inside the schema) or any return behavior. Basic mutation disclosure is present but not enriched.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single well-formed sentence that front-loads the core action (change settings) before the secondary capability (move). Zero filler, every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description is thin, the schema covers all parameters comprehensively, including the read-first warning that is the most important operational detail for this mutation. There is no output schema, and the description offers no return/error hints, but for a 5-param tool whose parameter semantics are fully documented, the package is adequate and little is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with all 5 parameters documented, including the critical 'read the widget first — replaces the instance wholesale' note on instance. The description adds little beyond mapping 'settings', 'sidebar', and 'position' to the corresponding parameters — modest value on top of an already thorough 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Change'/'move') with a clear resource ('a widget') and names three distinct capabilities: changing settings, relocating to a sidebar, or repositioning. This explicitly distinguishes it from sibling create_widget/delete_widget/list_widgets and any generic update tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied by the noun/verb pairing and sibling names (this is the widget-update variant among create/delete/list), but the description never states when to choose it over alternatives or when not to. No exclusions or alternative routing are given, so an agent infers applicability rather than being told.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint false) and openWorldHint true. The description adds significant behavioral context by enumerating the exact files generated (style.css, functions.php, header/footer, etc.), the Tailwind CDN setup, and the design token integration. It also clarifies the draft state, which is not explicit in annotations. This goes beyond just disclosing the operation's nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is about 100 words, structured with the core purpose in the first sentence and additional details in the second. It front-loads the action and rationale, then enumerates the deliverables. While the second sentence is lengthy, it packs essential information without redundancy. It is well-organized and avoids unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of scaffolding a full theme, the description covers all major outputs (files, tokens, Tailwind) and conveys the draft state. It does not describe the return value, but there is no output schema, and for a creation tool this is less critical. The prerequisites like site selection are handled in the schema. Overall, it provides enough information for an agent to understand what will be created and why.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with detailed descriptions for all parameters, so the description adds limited extra meaning. It does mention that design tokens are 'written into theme.css as CSS custom properties and reused across every template,' which gives additional context to the 'tokens' parameter beyond its schema type. However, this is minimal and the baseline for full schema coverage is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Scaffold a complete classic PHP theme styled with Tailwind, as a draft.' It specifies the resource (classic theme), the style (Tailwind), and the draft state, which distinguishes it from sibling tools like 'create_draft_theme' or 'install_theme'. The list of files and design token setup further clarifies the scope without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a rationale for using classic templates over block markup ('readable, diffable and predictable') but does not explicitly state when to use this tool versus alternatives. It does not mention any exclusions or direct comparisons to sibling tools like 'create_draft_theme'. Usage guidance is implied rather than explicit, leaving the agent to infer the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, so the write nature is expected. The description adds behavioral context by noting that validity depends on the theme and that the agent should read existing mods first. However, it does not disclose side effects, permissions, or whether overwriting an existing key has any consequence beyond setting the value. Since annotations cover the safety profile and the description adds the theme-dependency caveat, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose. The second sentence delivers essential guidance (read get_theme_mods first, theme-dependent validity) without redundancy. Every word earns its place; no filler or irrelevant detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 and minimal annotations, the description covers the essential pre-conditions (checking existing mods), value type semantics, and site selection. It does not describe return values, but that is not critical for a setter. The theme-dependency warning is sufficient to prevent naive misuse. Overall, it is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters are documented. The description adds valuable type guidance: 'Types matter: a logo expects an attachment ID, a color expects a hex string.' It also explains site_id behavior (automatic selection vs. default site, and reference to list_sites). This goes beyond the schema and aids correct invocation, earning a score above the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Write one Customizer setting (theme mod) for the active theme.' It distinguishes from related tools like set_option by specifying Customizer theme mods, and mentions get_theme_mods as a companion. The purpose is unambiguous and does not overlap with siblings like update_site_settings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on what to do before calling: 'read get_theme_mods first to see the keys it uses.' It also warns that validity depends on the theme, setting context for safe use. It does not name alternatives or say when not to use it, but the prerequisite and theme-dependence provide clear usage instruction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the agent knows this is a non-destructive, non-idempotent write. The description adds context about the item types and the use of parent/menu_order, which exceeds what annotations alone convey. However, it does not mention any side effects, permissions, or error conditions, and the schema covers most parameter behavior. The added context is moderate, not exceptional.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action and main variants. It avoids unnecessary details and every sentence earns its place, clearly explaining the tool's scope and its two key modifier parameters without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 14 parameters but only 2 required and comprehensive schema descriptions, the description provides enough high-level context to understand the tool's purpose and the main usage patterns. The absence of an output schema means return values need not be explained. It could mention that each call creates a new item (non-idempotent), but the idempotentHint=false annotation already conveys this. Overall, it is fairly complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all 14 parameters with detailed descriptions (100% coverage). The description adds a little connectivity between type, object, object_id, and the concept of nesting/positioning, but it largely restates information already in the schema. Given the high schema coverage, the description does not need to repeat parameter details, and this is a baseline 3 where the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: "Add an entry to a navigation menu." It clearly distinguishes from sibling tools like update_menu_item and delete_menu_item by stating the core action and the variety of targets (post, page, CPT, taxonomy, arbitrary URL). The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies usage for creating a new menu item, and it gives guidance on nesting and ordering via parent and menu_order. It does not explicitly mention when not to use it or compare it to update_menu_item, but the context of 'add' versus the existence of an update sibling is clear enough for an agent to infer the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the specific checks performed (alt text and unused media) and the reasoning behind them, which is useful behavioral context. However, it does not mention any operational behavior like pagination, limits, or output format, so it adds only modest value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states the exact scope, and the second offers a concise rationale. No wasted words, and the core functionality is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only audit tool with three optional parameters and no output schema, the description is reasonably complete. It explains what the tool checks and why it matters. While it does not describe the return format, the agent can infer it from the audit purpose and the well-documented parameters. Slightly more detail on output would make it perfect, but it is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter already has a descriptive comment (limit range, site_id selection logic, check_unused slow behavior). The tool description reinforces the purpose of check_unused by mentioning unused media, but it adds little beyond what the schema provides. Baseline 3 is appropriate given the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Audit') and resource ('media library'), and clearly lists the two distinct checks: images missing alt text and attachments not referenced by content. This distinguishes it from siblings like list_media (which only lists) and audit_content (which audits content, not media).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides strong contextual rationale for when the tool is valuable (accessibility and disk usage) and implicitly distinguishes it from listing or content audits. It does not explicitly name alternatives or say 'use this instead of X', but the purpose is clear enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, so the description adds value by explaining the trash-first behavior and the permanent deletion path (force:true AND confirm:true) plus the irreversible consequence (row and meta removed). It does not cover other potential side effects like revisions or hook triggers, but the core behavioral traits are well disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary action ('Delete content of any type') and then detailing the trash vs. permanent distinction. No filler, every clause adds information. Excellent structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description covers the essential behavioral side (trash, permanent deletion, irreversibility). It does not mention return values or error conditions, but for a destructive tool that is often acceptable. The parameters are fully documented in the schema, so the description is nearly sufficient for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explicitly stating the combination of force and confirm is required for permanent deletion and that this removes the row and meta. This clarifies the irreversibility, which is not directly in the schema descriptions, enhancing the parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Delete') and a clear resource ('content of any type'), which distinguishes it from sibling tools like delete_term, delete_media, and delete_user. The mention of trash and permanent deletion adds specificity about the behavior, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is a generic content deletion tool ('any type') but does not explicitly contrast it with specialized delete tools (e.g., delete_media, delete_term). It does not say 'use this for posts and pages; use delete_media for media', so an agent has to infer when to choose this over siblings. There is no when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false. The description goes further by explaining that deletion is permanent, bypasses the trash, requires confirm, and leaves broken images for referencing content – valuable context beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action, and every clause adds significant meaning. No waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description covers key behavioral consequences (permanent deletion, broken references) and the confirm requirement. It doesn't address errors or permissions, but given the tool's simplicity and annotation coverage, it is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description echoes the confirm requirement without adding new meaning for id or site_id. The description adds little beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Delete a media item' with a specific verb and resource, and adds crucial detail about attachments bypassing the trash and permanent deletion, distinguishing it from generic delete tools like delete_content or delete_comment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for media items but does not explicitly contrast with sibling delete tools or state when to use it instead of them. It provides behavioral context (permanent deletion, confirm requirement) but no direct guidance on selection among alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already include destructiveHint: true and readOnlyHint: false, establishing the safety profile. The description adds valuable behavioral context: it explicitly states that the menu AND all its items are deleted, and that the theme location falls back to default output. It also emphasizes the confirm requirement, which is a significant operational nuance. However, it does not mention any auth/role requirements or what happens on success/failure, which would be reasonable given the destructive nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff. The core action is front-loaded ('Delete a navigation menu and all of its items.'), and the behavioral consequence (theme location fallback) plus the critical requirement (confirm) follow immediately. Every word earns its place; there is no extraneous detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a deletion tool with three parameters and no output schema, the description covers the main consequences (cascade deletion, theme fallback) and the required confirm flag. It doesn't explicitly discuss return behavior or error handling, but those are often non-critical for delete operations. Given the annotations already carry the safety hints, the description is reasonably complete for an agent to decide whether and how to call it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage of all three parameters (id, confirm, site_id), including descriptions and the confirm's irreversibility warning. The description's only parameter-related mention is 'Requires confirm: true,' which is redundant with the schema's 'Required — menus and their items cannot be recovered.' Since the schema does the heavy lifting, the description adds little value beyond what's already structured.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action explicitly: 'Delete a navigation menu and all of its items.' This covers the verb, resource, and scope (menu + items). It also mentions the theme location fallback, which adds context. The sibling delete_menu_item exists, but this description clearly targets the whole menu, so it is distinguishable without further detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives such as delete_menu_item. It does mention 'Requires confirm: true,' which is an operational requirement, and the behavioral note about theme location fallback gives context. However, there is no explicit 'when to use / when not to use' statement, and no mention of alternative tools. The deletion intent is clear from the purpose, so some usage context is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals a nuanced behavioral trait: default soft-delete that preserves settings, and a force option for permanent deletion. This goes beyond the destructiveHint=true annotation by explaining the reversible default, adding valuable context without contradicting the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured sentence that is front-loaded with the primary action and then explains the optional branch. No wasted words; every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward delete operation with three parameters fully documented in the schema, the description covers the key behavioral distinction (soft vs. hard delete) and the rationale for the default. No output schema exists, so lack of return-value info is acceptable. It doesn't cover error cases or permissions, but those are not essential for calling the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so a baseline of 3 applies. The description adds useful context by explaining that the default (without force) moves the widget to inactive area so settings survive, which elaborates on the parameter behavior beyond the schema's 'Delete permanently instead of moving to inactive widgets.'
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Remove') and resource ('a widget'), and clarifies the two deletion modes (soft/hard) which distinguishes it from other delete tools (e.g., delete_content, delete_media). This is clear and non-tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is provided. The description doesn't mention alternatives or contexts where another tool would be preferred. While the title implies it's for widgets, it doesn't help the agent decide between this and similar delete tools beyond the resource type.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds a behavioral insight: taxonomies not listed are registered with show_in_rest => false and unreachable over REST, which helps agents understand the meaning of absence. It also describes the return fields (REST base, post types, hierarchical), which is output context rather than behavior, but still useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The primary action is stated first, followed by the return fields and a clarifying constraint. Every word is useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a listing tool with optional parameters and no output schema, the description adequately explains what the tool returns (REST base, applicable post types, hierarchical flag) and the meaning of absent taxonomies. It doesn't cover pagination or potential errors, but those are minor for a read-only discovery tool; the description is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions for site_id and for_type. The tool description adds no additional parameter semantics beyond what the schema provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and clearly defines the resource (every taxonomy on the site) with scope (categories, tags, custom taxonomies). It distinguishes from siblings like list_terms by focusing on taxonomy definitions rather than terms, and from discover_content_types. The added note about show_in_rest => false clarifies what is reachable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: use this to discover all taxonomies and their properties. However, it does not explicitly mention when to prefer this over alternatives like list_terms or discover_content_types, nor does it state situations where it should not be used. It provides no exclusions or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint true and destructiveHint false, covering the tool's own safety profile. The description adds value by revealing that the returned information includes input/output schemas and destructiveness status of the ability itself, which goes beyond annotations and directly informs the caller what to expect. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences deliver the purpose, what is returned, a usage rationale, and a concrete naming example. Every sentence earns its place, and the core purpose is front-loaded. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only retrieval tool with two well-documented parameters and safe annotations, the description provides all necessary details: what it returns, how to format the name, and the context for using it. Since the output schema is absent, the description's mention of schemas and destructiveness fills that gap. 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters well documented in the input schema. The description complements this by clarifying the namespaced format with an example ('my-plugin/get-site-info'), which reinforces the schema's instruction to use the fully qualified name from discover_abilities. This adds practical meaning beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: "Get the full definition of one ability." It specifies what is included (input/output schemas, destructiveness) and even gives an example of a namespaced ability name. However, it does not explicitly contrast itself with sibling tools like discover_abilities or run_ability, so it lacks sibling differentiation. This is clear but not fully distinguishing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool with "so you can call it correctly the first time," indicating it should be used before executing an ability. It also warns that ability names are namespaced, which helps prepare the caller. However, it does not explicitly state when not to use it or mention alternatives such as discover_abilities for listing, so usage guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: results are grouped by taxonomy and returned as full term objects, which goes beyond the schema. There is no contradiction with annotations, and the description enriches the operational understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise sentence that front-loads the verb and resource and packs the key distinctions (grouping, resolution) efficiently. Zero wasted words; the description is immediately scannable and informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a straightforward read operation with no output schema, and the description adequately explains the return format (grouped term objects). It does not mention pagination or limits, but for a single-content-item read, that is not critical. The description is complete enough for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters (type, site_id, content_id) have schema descriptions with 100% coverage, so the schema already carries the parameter semantics. The description does not add new parameter details beyond what the schema provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get'), resource ('taxonomy term assigned to one content item'), and adds distinctive details: grouping by taxonomy and resolving to full term objects rather than bare IDs. This clearly differentiates it from siblings like list_terms (listing all terms) and get_term (single term).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does but does not explicitly state when to use it versus alternatives or when not to use it. The phrase 'rather than bare IDs' hints at a scenario but does not name sibling tools or exclusions. No clear routing guidance is provided, so it's sufficient but not strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds context about returned fields (source URL, dimensions, etc.) but no behavioral traits like error handling or not-found behavior. With annotations handling the main behavioral expectations, the description adds minimal extra value, warranting a baseline score of 3.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action ('Fetch one media item by ID') and then lists the relevant payload fields. There is zero waste; every word adds informational value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only retrieval tool with only two parameters and no output schema, the description's enumeration of returned fields gives the agent a clear expectation. It omits possible edge-case behavior (e.g., 404 when the ID doesn't exist), but that is a minor gap for such a straightforward tool. The tool is well-specified for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (id, site_id) are adequately documented in the schema. The description only mentions 'by ID', which aligns with the id parameter but adds nothing beyond what the schema provides. Per the guidelines, baseline 3 is appropriate when the schema already explains parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Fetch' plus resource 'media item' and the selection criterion 'by ID', and enumerates the fields returned. It clearly distinguishes from sibling tools like list_media (plural) and update_media (modifying), leaving no ambiguity about its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is unambiguous: this is the tool to retrieve a single media item by ID. However, it does not explicitly state when not to use it or mention alternatives such as list_media for multiple items, though the name and singular phrasing imply the distinction. No explicit exclusions or alternatives are given, so it earns a 4, not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set readOnlyHint=true and destructiveHint=false, and the description does not contradict them. The description adds the context that the tool retrieves data from the WordPress.org repository, implying an external read operation, but doesn't disclose further behavior like rate limits or error handling. Given the annotation coverage, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main action and resource, and the second sentence provides the usage context. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only lookup with one required and one optional parameter, the description covers the purpose, usage, and the type of information returned. It doesn't explain error handling or output format, but given the simplicity and annotation coverage, it is sufficient. A more detailed description would not add significant value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, both parameters have meaningful descriptions. The tool description does not add extra parameter-level detail beyond mentioning the types of info returned, which relates to the response rather than inputs. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb 'Get' and resource 'one plugin from the WordPress.org repository', and lists the specific types of info (description, changelog, version history, ratings, compatibility). This distinguishes it from sibling tools like get_plugin, which likely targets installed plugins, and search_plugins, which searches multiple.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit use case: 'Use before installing or updating to see what changed.' This tells the agent when to invoke this tool, though it doesn't name alternative tools for other scenarios (e.g., get_plugin for installed plugin info). It's clear but could be more explicit about alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and destructiveHint=false, and the description's 'Read' aligns with that. It adds the valuable constraint that an Administrator account is required, which is not in annotations. It also lists the exact settings returned, giving behavioral context. It does not contradict any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that leads with the action ('Read'), enumerates the settings, and closes with the permission requirement. No filler, no repetition of the title or annotations. Every part carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one optional parameter and no output schema, the description is nearly complete. It states what is returned (the settings list) and the access requirement. It does not mention the response format or error behavior, but for a get-settings tool that returns a known set of fields, this is a minor omission. The existence of update_site_settings makes the read intent clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description for site_id is thorough, covering optionality, default behavior, and how to get valid ids. With 100% schema coverage, the baseline is 3. The tool description adds nothing about the parameter, but it doesn't need to since the schema fully documents it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads the site's core settings and enumerates the specific settings (title, tagline, timezone, etc.). This distinguishes it from the broader get_site and the write-oriented update_site_settings sibling without naming them explicitly but via content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives the tool's purpose and the administrative prerequisite, but it does not explicitly state when to use this instead of get_site or when not to use it. The only pointer is in the schema (run list_sites for ids), which is parameter guidance, not tool selection guidance. Context is clear but alternatives are not named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare `readOnlyHint=true` and `destructiveHint=false`, covering the safety profile. The description adds value by specifying the exact information returned (clone origin and last modified time), which is behavioral context beyond the structured annotations. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately states the action and resource, then details the output. No filler or redundant information is present. The structure front-loads the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list operation with one optional parameter and no output schema, the description provides sufficient context: it defines the scope (site), the object (drafts), and the included fields. It does not discuss pagination or ordering, but that is likely unnecessary for a low-complexity tool. The lack of an output schema is compensated by describing the output contents.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for the single parameter `site_id`, including its optionality and default behavior. The description adds no further meaning to the parameter, so the baseline of 3 is appropriate since the schema already handles parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'theme drafts', and specifies the returned data ('what each was cloned from and when it was last touched'). It reads as a distinct operation from the sibling `list_themes` which presumably lists active themes, so it differentiates well.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives like `list_themes` or `get_theme`. It implies usage for viewing draft themes, but offers no explicit guidance on when `list_themes` should be chosen instead. The context signals suggest a sibling grouping, but the description leaves the choice to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that it returns fields and placement info, which is content rather than behavior. It doesn't disclose any additional side effects or requirements (e.g., permissions), but since annotations carry the behavioral burden, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no redundancy. The primary purpose is front-loaded, and the usage hint is concise and actionable. Every word contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with a single optional parameter and no output schema, the description adequately communicates what results to expect (fields and placement) and why to use it. It doesn't mention pagination or limits, but these are not critical for such a simple list operation. The openWorldHint annotation suggests data may change, which is fine.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, site_id, is already fully described in the schema with 100% coverage, including optionality, default behavior, and a reference to list_sites for valid IDs. The tool description adds no further parameter details, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'List the editable field groups registered on the site' with the added detail of 'their fields and where each appears.' This distinguishes it from sibling tools like register_fields and delete_field_group, making the tool's scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence provides explicit guidance: 'Check here before registering a group so you extend an existing one rather than duplicating it.' This tells the agent exactly when to use this tool (before registration) and implies that register_fields is the alternative for creating new groups. It does not explicitly mention when not to use it, but the stated use case is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the Administrator account requirement, which is not present in the annotations, and explains that lower roles receive no data. It also specifies that the output includes activation status and version. This adds meaningful behavioral context beyond the readOnlyHint and destructiveHint annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no redundancy. The core function is front-loaded in the first sentence, and the second sentence adds the necessary permission context. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with three optional parameters and no output schema, the description covers the essential requirements: it states the scope ('every plugin'), the return fields (status and version), and a critical permission constraint. It lacks pagination details, but the description is sufficient for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all three parameters (search, status, site_id) fully described in the input schema. The description adds no additional parameter semantics or syntax details, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'List every plugin installed on the site with its activation status and version', which is a specific verb+resource with clear output details. It differentiates from sibling tools like search_plugins by emphasizing 'every' and from get_plugin by being a list operation. The admin requirement further clarifies the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly contrast with sibling tools such as search_plugins or get_plugin, nor does it state when to prefer this over alternatives. It implies usage for enumerating all plugins, and the admin requirement acts as a precondition, but there is no explicit directional guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds useful domain context about the nature of reusable blocks and their global effect when edited, which goes beyond the annotations. It does not describe return format or pagination, but given the annotated safety profile, this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no filler. It front-loads the core action and resource, then adds a clarifying note about the domain. Every word contributes to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with one optional parameter and no output schema, the description adequately covers what the tool does and the nature of the listed items. It does not mention return format or ordering, but these are not critical for a straightforward list tool, and the annotated safety profile covers side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for the single optional parameter site_id, including its behavior and fallback logic. The description adds no parameter-specific details, but since the schema is thorough, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the specific resource ('the site's reusable blocks / synced patterns'), and differentiates them from regular block types by explaining they are fragments reused across pages. It also adds a clarifying behavioral note that editing one changes all instances, which helps distinguish this from list_block_types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for retrieving reusable blocks but does not explicitly state when to choose this over similar tools like list_block_types or get_content. There is no mention of exclusions, alternatives, or typical use cases, so the guidance is adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that results include sizes and supports theme drafts, which is useful. It doesn't contradict annotations and provides modest extra context beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action and purpose. No wasted words, and it distinguishes scope clearly. It's appropriately sized for a simple listing tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with three optional parameters and no output schema. The description explains the output includes sizes and the purpose is to inspect structure before changes. While it doesn't detail the response format, the purpose is clear and the annotations cover safety. For its complexity, the description is complete enough for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all three parameters with descriptions (100% coverage). The description does not add new information about parameters; it mentions 'theme draft' but the schema already says 'Theme stylesheet or draft id'. Thus the description adds no value beyond the schema, so a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action (list), the object (theme or theme draft files), and the purpose (to see template structure before reading/editing). This clearly distinguishes from sibling tools like read_theme_file (read a single file) and list_themes (list themes themselves).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it: before reading or editing theme files, to get an overview. It doesn't explicitly name alternatives, but the context of 'before reading or editing' gives clear usage guidance. However, it doesn't mention when not to use it or alternatives like list_themes for listing themes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: the conditional return of email addresses and roles based on the list_users capability, which is not inferable from annotations and assists in setting expectations about the response.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose and scope, and adds the capability nuance without any fluff. Every sentence contributes to understanding the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a listing tool with 8 parameters all described in schema, the description gives a clear overview of capabilities and the key behavioral caveat. It does not detail the return format, but given the tool name and lack of output schema, this is acceptable. The description is sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is already documented in the schema. The description itself does not add further parameter details beyond what the schema provides, matching the baseline expectation for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'users', and enumerates the operations available (search, role filtering, ordering, pagination). It distinguishes itself from siblings like get_user (single user) and create_user by focusing on listing, making the tool's scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does but does not explicitly state when to use it over alternatives (e.g., when to use get_user instead). There is no mention of exclusion conditions or when not to use this tool, leaving the agent to infer usage from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=false, but the description adds valuable context: 'The current version is itself saved as a revision first, so this is reversible.' This explains the mechanism behind the non-destructive nature, giving agents confidence that the operation is safe and reversible. It goes beyond the basic annotation by explaining the 'how' and 'why'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no fluff. The primary purpose is front-loaded in the first sentence, and the second sentence provides essential behavioral context. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the key behavior (reversibility) and specifies the core action. It doesn't explicitly mention that the restored revision becomes the new current version or any success/failure conditions, but given the schema's parameter descriptions (which reference list_revisions for revision IDs) and the simple nature of the tool, the context is sufficiently complete for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters (id, type, site_id, revision_id) are already well-documented in the schema. The description adds no additional parameter-specific detail beyond what the schema provides, so the baseline score of 3 applies. The schema's descriptions are adequate and include references to list_revisions for revision_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: 'Restore a piece of content to an earlier revision.' It clearly identifies the verb (restore) and resource (content to a revision), distinguishing it from siblings like list_revisions (which lists revisions) and update_content (which edits content directly). The purpose is unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly mention when to use this tool versus alternatives like update_content or list_revisions. It implies usage for reverting to an earlier revision, but provides no explicit 'when to use' or 'when not to use' guidance. However, the purpose is self-evident enough that agents can infer the context without confusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry the safety profile (readOnlyHint=true, destructiveHint=false), and the description adds concretely what the tool checks and reports, plus that it verifies the optional companion plugin — useful behavioral context. However, it does not disclose side effects for a non-idempotent, openWorld tool: the outbound network call, latency, or any transient state it might leave. IdempotentHint=false with openWorldHint=true suggests an external side-effecting operation that the description leaves unexplained. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste. The first enumerates the tool's scope and outputs in compact clause form; the second delivers the usage directive. The core diagnostic message is front-loaded before the guidance, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool (zero required params, no output schema), the description thoroughly explains return semantics by listing exactly what will be reported. The only gap is that, given openWorldHint=true and idempotentHint=false, an agent might be warned about network latency or non-idempotency implications. Minor for a diagnostic tool whose output semantics are already well covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, site_id, has 100% schema description coverage that already explains the optional behavior, defaulting logic, and a pointer to list_sites for valid ids. The description adds no parameter-level detail beyond what the schema provides, so the baseline 3 is appropriate — schema does the heavy lifting and nothing is lost.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — 'Test connectivity and authentication against a site' — and enumerates exactly what it reports: REST reachability, credential authentication, user mapping, roles/capabilities, and companion-plugin presence. This distinguishes it sharply from diagnostic siblings like get_audit_log, run_ability, or audit_content; an agent can tell what it does without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use guidance: 'Run this first when anything is behaving strangely — it names the specific misconfiguration rather than a generic failure.' This positions it as the initial diagnostic step. It does not name explicit when-not-to-use conditions or alternatives that would supersede it, so it stops one step short of fully excluding sibling tools, though the schema's list_sites reference helps disambiguate parameter sourcing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only indicate it's not read-only, not destructive, and not idempotent. The description adds meaningful behavioral context by disclosing side effects: 'approve' publishes, 'spam' trains the filter, and 'trash' is recoverable. This goes beyond the bare annotation flags and helps an agent anticipate consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: the first states the purpose, the second details conditional behavior for status values. Every word earns its place, and the most important nuance is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully explains the core function and the nuanced status enum. With no output schema to address and a fully documented input schema, the description is nearly complete for an update tool, though it omits error-handling notes—which are typically out of scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is already documented. The description loosely references 'text, author details or moderation status' but adds no new semantic detail beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('update') and resource ('a comment'), and enumerates the updatable aspects (text, author details, moderation status). It also explains the effects of status values, clearly distinguishing it from get_comment, create_comment, and delete_comment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for modifying existing comments and elaborates on status behavior, but it never explicitly contrasts with alternatives like moderate_comments or states when not to use this tool. The context is clear but exclusions and alternative routing are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces 'Read-only' in plain terms. It adds value by specifying that the tool 'names the issues and the IDs' — a concrete output behavior beyond what annotations state — and by listing the exact problem categories it checks. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but well-structured: it front-loads the core purpose, lists concrete checks, and concludes with the read-only note and fix guidance. Every sentence contributes — the issue list is dense but informative, and the pointer to mutation tools is a helpful addition. Could be slightly tightened, but no waste exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only audit tool, the description adequately conveys what it does and what it returns (issue names and IDs). It lacks an output schema, but the description's statement that it 'names the issues and the IDs' suffices for an agent to understand the result. Parameter defaults and limits are covered by the schema, so nothing critical is missing. Slight omission: it does not mention whether output is a list or how pagination works, but given the 'sweep' metaphor and limit parameter, this is likely reasonable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with descriptive comments (e.g., 'Content type to audit', 'How many items to examine'), so the schema already documents semantics. The description does not add parameter-specific guidance, such as explaining the interplay between status and limit or the meaning of thin_content_words. Since schema coverage is complete, a score of 3 is appropriate — the description adds no extra value here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('sweep') and resource ('a content type'), then enumerates the exact checks performed (SEO titles, H1s, thin content, etc.), making the scope unmistakable. It also names the follow-up tools (bulk_update_content, update_content) and explicitly states it is read-only, distinguishing it from the mutation siblings in the list. Clear, specific, and differentiates adequately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly defines the usage scenario: use it to identify content issues, then apply fixes via bulk_update_content or update_content. It does not explicitly state when not to use it (e.g., for media, which has a separate audit_media tool), but the context is clear and the differentiation from mutation tools is explicit. This is sufficient guidance for an agent deciding to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool never publishes to a live site implicitly and creates drafts by default, which is a crucial behavioral trait beyond annotations. It also mentions taxonomy terms are created if missing, indicating a side effect. The annotations already indicate it's not read-only and not destructive, so this description adds value without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise paragraph that front-loads the action and then provides two key behavioral clarifications. Every sentence earns its place: purpose, draft default, and taxonomy behavior. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is complex with 20 parameters and no output schema. The description provides the essential rules (draft default, explicit publish, taxonomy term creation) but does not cover what happens if a custom post type is not registered, or whether the created object's ID is returned. Given the schema covers parameter details well, this is adequate but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 20 parameters have descriptions. The main description adds the default status of 'draft' which is not in the status parameter description, and reiterates the taxonomy term creation behavior which is already in the terms parameter description. It adds minimal but useful context, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'Create' and the resource 'content' (post, page, any custom post type). It clearly differentiates from siblings like update_content and delete_content by the action it performs. The additional detail about draft-by-default and taxonomy term auto-creation provides clarity on the tool's behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (to create any content type) and provides important context that content is created as a draft unless published explicitly. It does not explicitly mention alternatives like update_content for modifications or bulk_update_content, but the purpose is unambiguous. It implicitly suggests that for small changes, one should use `edits` (though that's in parameter description). This is clear usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the write nature is clear. The description adds valuable behavioral context beyond the annotations: it mentions that WordPress runs its normal image pipeline and generates thumbnail sizes, and stresses the alt_text requirement. It also clarifies the file_path semantics, which prevents a common mistake. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with the core action, and every sentence contributes value. It efficiently covers input sources, pipeline behavior, and a required field, with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 13 parameters and no output schema, the description omits information about the return value (e.g., whether it returns the created media object or ID), which is important for chaining calls (e.g., set_as_featured_for). It also doesn't mention error cases or prerequisites beyond file availability. While the input side is well covered, the lack of return-value disclosure leaves a gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for all 13 parameters, so the schema already carries the bulk of parameter meaning. The description adds a few extras (e.g., the local screenshot example for file_path, the accessibility importance of alt_text), but these are marginal. Baseline of 3 is appropriate since the description does not significantly improve parameter understanding over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Upload a file into the media library') and specifies three distinct input sources (file_path, url, base64_data) with clarifying examples. It distinguishes itself from sibling tools like update_media, delete_media, and list_media by focusing on creation, and even provides a concrete use case for local screenshots.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides practical usage guidance: it explains how to choose among the three input sources, clarifies that file_path is local to the server (not WordPress host), and mandates alt_text with a rationale. It does not explicitly mention alternative tools (e.g., search_stock_photos for finding stock photos), but the creation-focused context is obvious enough for an agent to know when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint, so the description doesn't need to repeat them. It adds useful context about the underlying WordPress Abilities API and the safety rationale, which is beyond minimal. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with zero waste. The primary purpose is front-loaded, followed by a relevant safety note that earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with two optional parameters, the description, combined with annotations and schema, is complete. An agent knows exactly what it returns conceptually and how to call it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (search and site_id) are already documented. The description adds no extra parameter-level information, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'List' + resource 'abilities' + context 'registered on the site through the WordPress Abilities API'. Differentiates from siblings like get_ability_info (which retrieves a specific ability) and run_ability (which executes one).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to enumerate abilities) but does not explicitly state when not to use it or which alternatives are preferable. The safety note about using plugin abilities is helpful but not tied to tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a mutation (readOnlyHint=false), and the description adds meaningful behavior: 'leaving the rest untouched' asserts a safety property, and 'an edit that matches nothing fails loudly' clarifies error handling. It doesn't cover ambiguous multiple matches, but the schema already documents the required/all flags. Overall it adds useful context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise—three sentences, each adding value: the first states the function, the second gives usage guidance, and the third describes a key behavior. It is front-loaded with the core purpose. No redundant text, but it could be slightly tightened without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 5 parameters and the nested edits array, the description covers the main usage scenario and distinguishes it from the write_theme_file sibling. It does not explain return values (no output schema), but annotations and schema handle parameter details. The mention of failure behavior and the safety comparison cover most operational context an agent needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter is already documented with clear descriptions in the schema. The description does not add extra meaning to the parameters themselves; it only provides a general context. With full schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs targeted find/replace edits inside a theme file while leaving the rest untouched. It explicitly distinguishes itself from write_theme_file by positioning itself as safer for single-function or block changes, so an agent immediately knows what it does and how it differs from its closest sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a clear usage signal: use this instead of write_theme_file when making focused changes. The phrase 'Safer than write_theme_file for changing one function or block of markup' gives a specific condition. It doesn't enumerate exclusions (e.g., when creating a new file or rewriting whole files), but the positive guidance is strong enough for most agents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds behavioral context by noting the log is 'append-only' and detailing the types of actions recorded, which goes beyond the annotations. It does not disclose auth requirements or rate limits, but given the annotation coverage, a modest score is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence that front-loads the purpose and includes a practical use case. Every phrase earns its place, with no redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description fills the gap by specifying the return fields (timestamp, site, tool, target, outcome) and the scope of actions logged. It also hints at pagination via the limit parameter, covered in the schema. An agent has everything needed to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters (limit, site_id, all_sites) are already documented in the schema. The description does not add any parameter-specific semantics beyond the schema; it focuses on the tool's output and purpose. Per the calibration, baseline 3 is correct when the schema carries the parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a precise verb ('Read') and a specific resource ('the append-only local audit log'), and enumerates the log's contents (writes, deletes, SQL, WP-CLI, theme publishes) with fields (timestamp, site, tool, target, outcome). This clearly distinguishes it from sibling tools like audit_content and audit_media, which target content/media rather than the system action log.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage context: 'Useful for answering "what did the AI actually change?"', which tells an agent when to reach for this tool. However, it does not name alternatives or state when not to use it. Since there are no closely competing siblings, this is adequate but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only safety profile is covered. The description adds behavioral context beyond that: it can search across all types at once and optionally restrict to specific types. It does not mention edge cases like not-found behavior, but for a read-only lookup the description meaningfully supplements the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero fluff. The action and scope are front-loaded, and the usage condition is stated immediately after. Every word adds value; no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is moderately simple with 4 parameters, but there is no output schema. The description does not describe the return value (e.g., whether it returns a single object or an array, or what happens if no match). Given no output schema, the description should hint at the result shape. That gap prevents a higher score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents every parameter, including the slug meaning and site_id defaults. The description adds no new parameter-specific detail beyond what the schema provides; the 'use when URL tail' line slightly reinforces slug semantics but does not elevate meaning. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'look up' and the resource 'content by slug', and explicitly distinguishes its cross-type behavior from type-specific lookups. The phrase 'across every content type at once, or within specific types' differentiates it from siblings like get_content, and the usage hint names the exact scenario (knowing URL tail but not post type).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit condition for use: 'when you know the URL tail but not which post type owns it.' It implies when not to use (when the type is known), and the ability to restrict by types adds usage context. However, it does not explicitly name alternative tools or say when to avoid this tool, so it is strong but not fully exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds a useful behavioral detail — that items are returned as an indented tree to make hierarchy obvious — which is not in the annotations. No contradictions exist; the idempotentHint=false is not contradicted by the description since it makes no claim about idempotency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One clean, front-loaded sentence states the action, the resource scope, and the output format. There is no filler or repetition; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with only two parameters (both schema-documented), the description covers the essential behavior and return format (tree rendering). No output schema exists, but the description implies the structure. Nothing critical is missing for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both `id` (with source hint 'The menu ID from list_menus') and `site_id` (with selection rules and reference to list_sites) are well documented. The tool description itself adds nothing about parameters or their formatting, so it does not extend beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Get), the resource (one navigation menu), and the distinctive behavior (rendered as an indented tree). This distinguishes it from list_menus (which lists menus) and other get_* tools like get_term or get_user, leaving no ambiguity about what the tool returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for retrieving a specific menu by ID, but it does not explicitly contrast it with list_menus for browsing or with other getters. There is no guidance on when not to use it or when an alternative would be better. The context is sufficient for a straightforward getter, but explicit routing would improve it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already assert readOnly=true and destructiveHint=false. The description adds the valuable behavioral detail that only server-rendered HTML is returned (JS-injected content absent), which goes beyond annotation coverage. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero fluff, front-loaded with the purpose and motivation. The caveat and optional modes are packed efficiently, though there is a slight repetition of 'HTML' but not a problem.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a read-only fetch tool: purpose, output type, and the crucial JS limitation are covered. Parameters like max_chars, site_id, and preview_token are documented in schema, so no critical gap for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 5 parameters with descriptions, so baseline is 3. The tool description adds a high-level summary of extraction modes but no new syntax or mechanics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States specific verb 'Fetch' and resource 'fully rendered HTML for any URL on the site', with a clear motivation to verify front-end changes. It contrasts with 'trusting the API's word', which distinguishes it from content APIs without naming them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context on when to use (verifying changes on the front end) and a key caveat about JavaScript-injected content. Does not explicitly name alternative tools or when-not situations, but the guidance is sufficient for a read-only fetch.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only and non-destructive. The description adds behavioral context by stating the output includes block markup, which is not in the annotations. This provides value beyond the structured fields, though it doesn't cover potential errors or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no redundant phrases. It front-loads the action and resource, and the clause about block markup is information-dense. Minor redundancy with the title ('Get') is negligible, but the description earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description partially explains the return value by mentioning block markup. It covers the essential purpose and parameters are fully documented. It lacks details on error conditions or structure of the returned object, but for a simple read operation with read-only annotations, the level is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all three parameters. The description adds no additional parameter meaning, so the baseline of 3 applies. It doesn't explain parameter interactions or provide examples beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves one block template or template part, including its block markup. It identifies the resource type and distinguishes from list_templates by emphasizing 'one' and the inclusion of markup, making its purpose explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for inspecting or editing layout, which hints at a read-then-edit workflow. However, it does not explicitly mention alternatives like list_templates or update_template, nor exclusion criteria. The guidance is clear enough for most agents but lacks explicit when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds behavioral context by enumerating the fields returned (description, parent, item count, term meta), which is useful beyond what annotations convey. It does not mention error behavior, but this is minor for a simple read.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One compact sentence that front-loads the action and includes all key details without wasted words. It is appropriately concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with all parameters documented and annotations covering safety, the description is complete. It specifies exactly what the agent can expect in the response (fields returned), and no critical information is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters (id, site_id, taxonomy) are already documented in the schema. The description does not add any extra meaning or constraints beyond what the schema provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Fetch one taxonomy term by ID') and lists the exact data returned (description, parent, item count, term meta). It clearly distinguishes from list_terms (which fetches many) and from get_content_terms (which fetches terms attached to content).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a term ID, but it does not explicitly mention when not to use it or name any alternative tools. No exclusions or routing guidance is provided, though the purpose is clear enough to infer basic usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and destructiveHint=false, and the description adds value beyond that by explaining that in block themes the tool may return no classic sidebars and that this is expected, not an error. It also clarifies that the output includes widgets placed in each area. These are behavioral details not present in the annotations, making the tool's behavior more predictable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no waste. The primary action is stated first, followed by a crucial edge-case note. Every word earns its place, and the structure is immediately scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with one optional parameter, the description covers what is returned (widget areas and their widgets), manages the common block-theme expectation, and is consistent with the safety annotations. There is no output schema, but the description sufficiently describes the result shape. 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, site_id, is fully documented in the schema (coverage 100%), including its optionality, default behavior, and reference to list_sites for valid ids. The tool description adds no additional meaning to the parameter, so it does not exceed the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List'), a clear resource ('the theme's widget areas (sidebars)'), and what it returns ('the widgets currently placed in each'). It also distinguishes itself from the sibling list_widgets by focusing on widget areas and their contents, and it preempts a common confusion (block themes have no classic sidebars). This is precise and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives contextual guidance by noting that block themes typically have no classic sidebars, which sets expectations. However, it does not explicitly state when to use this tool over the sibling list_widgets or any other tool, nor does it mention exclusions or alternatives. The usage context is implied but not made explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, and the description adds useful context: it explains that the tool runs validation, hooks, and cache invalidation, and that the HTTP method is auto-selected based on the ability's definition (GET for read-only, DELETE for destructive). This goes beyond the annotations and helps the agent understand side effects and method behavior. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a few sentences that front-load the core purpose and usage, then detail the method mapping. It is reasonably concise and does not repeat schema information verbatim, though it could be tightened by removing the explicit method mapping details that are already in the parameter schema. Still, it's well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description need not describe return values. It covers the required name, optional input, method selection, and site_id behavior, and points to get_ability_info for the input schema. It doesn't explicitly describe error behavior or what happens on invalid ability names, but for an execution tool this is acceptable. Overall, it provides enough context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all four parameters. The description adds some value for site_id by explaining the behavior with single vs. multiple sites and the default selection, and it instructs to check get_ability_info for input schema, which is helpful. However, these are moderate additions; the baseline of 3 is appropriate given the schema's completeness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Executes an ability registered through the WordPress Abilities API' with a specific verb and resource. It distinguishes itself from siblings like get_ability_info and discover_abilities by focusing on execution and by naming the sibling to check for schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear guidance on when to use this tool: 'This is the preferred way to write data a plugin owns', and contrasts it with raw SQL which bypasses validation. It also instructs the agent to check get_ability_info for the input schema first. However, it doesn't explicitly contrast with other write tools like update_content, but the plugin-owned scope is a clear differentiator.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate write behavior (readOnlyHint=false) and non-idempotency, so the description correctly does not repeat these. It adds valuable behavioral context: a wrong value can break the site, and reading first is recommended. This goes beyond the structured annotations and helps the agent understand risk. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the core action and then adds critical safety guidance. It is not verbose or redundant, and every phrase contributes value. The structure is efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write tool with four well-documented parameters and no output schema, the description covers the essential operational context: what the tool does, the risk involved, and the recommended pre-condition (reading before writing). It does not explain return values, but no output schema exists, so that is not a gap. The guidance about preferring plugin settings adds important decision-making context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters (name, value, site_id, autoload) with meaningful descriptions. The description does not add parameter-specific semantics beyond what the schema provides, which is acceptable given the high coverage. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('write') and resource ('the WordPress options table'), and adds context that options drive plugin/theme behavior. This distinguishes it from the read sibling get_options, though it doesn't explicitly contrast with other write tools like set_theme_mod or update_site_settings. The purpose is unambiguous and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: read the current value first with get_options, and prefer a plugin's own settings screen or ability when one exists. This tells the agent exactly when to use this tool and when not to, naming a concrete alternative. No inference is required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the description need not restate safety. It adds valuable context about how the block-based editor stores content in instance.content, which is beyond the schema's example. It does not contradict annotations and adds useful behavioral context for correct invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The purpose is stated first, followed by the most important usage detail (block widget markup). Every word earns its place; it is appropriately sized and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does not explain return values, but for a create action that is often implicit. It covers the required semantics well: how to specify the widget type and the block widget nuance. It does not mention potential errors or permissions, but given the schema covers all parameters and annotations cover safety, the description is complete enough for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and each parameter already has a descriptive definition, including instance examples for block and nav_menu. The description adds only a slight clarification about instance.content for block widgets, which is already covered by the schema's example. Baseline 3 is appropriate since the schema carries the semantic load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description leads with a specific verb and resource: 'Add a widget to a sidebar', which clearly identifies the action and target. It differentiates from siblings like update_widget and delete_widget by the action word 'Add'. It also provides concrete guidance on widget types, further clarifying scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly contrast with alternatives, but the purpose is unambiguous: it is the tool for creating a new widget. The mention of widget types and block-specific handling implies when to use it (when you need to add a widget with a given id_base). It lacks explicit 'use this instead of X' guidance, so it does not earn a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only indicate non-readOnly, non-destructive behavior. The description adds meaningful context: features stop working immediately and settings/data are normally retained. This goes beyond the annotations and gives the agent a clear picture of the tool's effect. It does not contradict any annotation, nor does it describe edge cases like deactivating an inactive plugin, but for a simple action it is good.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the core action. It conveys the immediate effect and the retention detail without any fluff. Every sentence earns its place, and there is no unnecessary repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating tool with only two well-documented parameters and no output schema, the description adequately covers what happens (deactivation, immediate effect, data retention). It could mention prerequisites (e.g., plugin must be active) but that is implied by 'active plugin'. Overall, it provides sufficient context for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides complete descriptions for both parameters (plugin and site_id), achieving 100% coverage. The tool description adds no new parameter-specific information, so it does not enhance what the schema already offers. This matches the baseline score for fully covered schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action ('deactivate an active plugin') and a clear resource. It distinguishes itself from sibling tools like activate_plugin and delete_plugin by focusing on deactivation, and the retention of settings/data implies the contrast with deletion. No ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when to use it (for an active plugin) and hints at the distinction from deletion by noting settings/data are retained. It does not explicitly name alternatives like activate_plugin or install_plugin, but the retention note is sufficient to guide a reasonable agent. It lacks an explicit 'when not to use' but is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the default trash behavior and recoverability, and specifies that force:true removes permanently and requires confirm:true. This goes well beyond the annotations' destructiveHint and readOnlyHint, giving the agent concrete safety context about the data impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with zero waste. The core action is front-loaded, followed immediately by the most important behavioral qualifier (trash vs. permanent). Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with 4 parameters (1 required) and no output schema, the description covers the key nuances of deletion and the confirm requirement. It lacks usage guidance and doesn't mention potential side effects like associated media, but the core behavior is well specified for an agent to call it safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 the 'recoverable' aspect and the explicit constraint that permanent deletion requires both force and confirm, which enriches the semantics beyond the schema's individual parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Delete a comment') and goes beyond a simple tautology by describing the trash vs. permanent deletion behavior. This clearly distinguishes it from other comment-related tools like moderate_comments or update_comment, which perform different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention moderate_comments or other comment-management tools, nor does it give any context about when deletion is appropriate. The description only states what the tool does, not when to choose it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, so the description adds value by specifying that the live site is unaffected and that files are removed. This goes beyond the annotation by clarifying the scope of destruction (only the sandbox copy). No contradiction; the description aligns 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no wasted words. The main action is front-loaded, and the clarifying detail about the live site immediately follows, making it efficient and easy for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description effectively conveys the essential context: destructive operation on draft themes only, with no impact on the live site. The confirmation requirement is covered in the schema, so the description doesn't need to repeat it. The tool is simple, and the description, combined with schema and annotations, is complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema descriptions for all 3 parameters are detailed and self-explanatory, providing 100% coverage. The description adds no additional parameter information, but that's acceptable given the schema's thoroughness. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the verb 'Discard' and the resource 'draft theme' with its files. It also differentiates from siblings like publish_draft_theme or delete_theme by explicitly stating the live site is unaffected, making the scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: this tool is for discarding draft themes without affecting the live site. While it doesn't explicitly name alternative tools like delete_theme, the clarification that live site is unaffected effectively tells the agent this is for sandbox copies only. This is a clear contextual cue, though not an explicit exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=false. The description adds valuable nuance beyond annotations: it explains that stored values are not lost and the group can be re-registered, effectively qualifying the destructive nature. This is important behavioral context that annotations alone do not provide, making the description a meaningful complement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero redundancy. The primary action is front-loaded, and the second sentence delivers a critical behavioral nuance. Every word earns its place, and the structure is clean and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (three parameters, one required, no output schema). The description covers the core purpose and the most important side effect (data retention, re-registration). It does not explicitly mention the confirm parameter's requirement, but that is fully documented in the schema, and the annotations already flag destructiveness. Thus, nothing essential is missing for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters (confirm, site_id, group_key) are fully documented in the schema. The description does not add any parameter-specific meaning beyond what the schema already provides. It sticks to the operation's semantics, so it matches the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Remove a registered field group') with a specific resource ('field group'). It adds useful context by explaining that stored values are left in place, distinguishing it from generic data-deletion tools. This clearly separates it from other delete_* siblings by naming the exact resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by noting the non-destructive nature of the removal (values preserved, re-registration possible), which helps an agent decide when to use it (e.g., to temporarily hide a group) versus other tools. However, it does not explicitly name alternatives or state conditions when not to use it, so it falls short of fully explicit routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, so the description correctly implies it can mutate via 'optionally update'. It adds useful behavioral details beyond annotations: the detection order (explicit ?p= id, search index, rewrite base, slug sweep) and the safe lookup mode when update=false (though this is described in the parameter, not the tool description). The description doesn't contradict annotations and provides meaningful context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is 2-3 sentences, each serving a distinct purpose: (1) core functionality with example, (2) primary use case, (3) internal detection logic. It is front-loaded with the main purpose and contains no fluff. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high complexity (23 parameters, nested objects), the description covers the core workflow well: URL resolution and optional update. It doesn't explicitly mention limitations (e.g., it only works on existing content, not creation), but the schema and annotations cover the broad scope. The description is sufficiently complete for an agent to start using it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline for this dimension is 3. The description adds context for the 'url' parameter (how detection works) but does not explain other parameters; they are fully described in the schema itself. The added URL resolution detail is useful but not extensive enough to raise the score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Resolve') and resource ('any WordPress front-end URL to the content behind it'), and explains the URL shape detection mechanism with an example (/documentation/getting-started/ -> documentation CPT). It clearly distinguishes from siblings like get_content_by_slug or get_content, since it handles URLs directly and can also update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states the primary use case: 'This is the tool to reach for when a human hands you a link.' This gives clear when-to-use context. It doesn't explicitly name alternatives or exclusions (e.g., for known IDs/slugs use other tools), but the description implies it is the go-to for URL→content resolution. Minor gap: no explicit 'when not to use'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral detail: it returns the raw stored body exactly as stored, and explains why (block editor stores markup with HTML comment delimiters). This goes beyond the annotations and helps the agent understand output semantics without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the core action and then provides the essential rationale. Every clause earns its place; there is no filler or redundancy. It is concise while still adding meaningful context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only fetch tool with a fully documented schema and strong annotations, the description is nearly complete. It covers the primary purpose, the editing context, and the raw-body nuance. It does not describe error conditions or return structure, but the schema and annotations compensate; no critical information for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so every parameter is already documented with clear meanings. The description adds marginal value by tying the raw body mention to the 'raw' parameter and reinforcing the editing use case, but it does not introduce new parameter semantics beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the exact action: fetch one item of any content type by ID, and highlights the raw content body. It clearly distinguishes from siblings like list_content (fetching multiple), get_content_by_slug (by slug), and find_content_by_url (by URL) by explicitly anchoring to ID-based retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a concrete usage context: 'what you must read before making targeted edits.' It implies this is the correct tool for content edits and that raw output is needed. However, it does not explicitly name alternatives or state when NOT to use it; the schema partially covers this by referencing find_content_by_url and get_content_by_slug, but the description itself lacks explicit exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate `readOnlyHint: true` and `destructiveHint: false`, so the safety profile is established. The description adds meaningful behavioral context beyond those annotations: it reveals that the tool can access unregistered keys (a visibility limitation of `get_content`) and that a companion plugin is required for that capability. This helps the agent understand functional boundaries and dependencies, which annotations do not cover. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action and resource, and every clause adds value. The contrast with `get_content` and the plugin requirement are both essential and concisely stated. No fluff or repetition; it is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with 4 parameters (one required) and no output schema, the description covers the key functional distinction (access to unregistered keys), the dependency (companion plugin), and the primary alternative (`get_content`). The lack of an output schema means return format isn't described, which is acceptable. Minor gaps: no mention of error handling (e.g., what happens if the plugin isn't installed) or performance considerations, but these are not critical for successful invocation. Overall, the description is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides detailed descriptions for all four parameters with 100% coverage, so the baseline is 3. The description does not add additional meaning about parameters—it doesn't explain how `keys` filters results, what `include_protected` does beyond the schema, or how `site_id` selection works. While the description's mention of 'unregistered keys' loosely relates to `include_protected`, the schema already covers that. Therefore the description adds minimal parameter value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read the custom fields') and the resource ('a content item'). It explicitly distinguishes itself from the sibling `get_content` by noting it can access keys not registered with `show_in_rest`, which is a precise differentiator. The added caveat about the companion plugin further clarifies the scope, making the purpose unambiguous and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when you need meta keys that are not visible through `get_content`. It names the alternative (`get_content`) and the condition (keys not registered with `show_in_rest`). However, it does not explicitly state exclusion cases (e.g., 'use get_content when you only need standard fields') nor mention write counterparts like `set_content_meta`. The guidance is clear but could be more explicit in routing between tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful context about the data returned (theme supports and block theme status), which goes beyond the schema and helps an agent understand what the tool reveals. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no fluff. It states the core purpose and key detail, earning every word.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with comprehensive schema and helpful annotations, the description is complete. It explains what the returned details include, which is sufficient for an agent to decide whether to call it. No output schema is needed here; the description covers the essential context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameters are well-documented. The description does not add parameter-specific meaning beyond what the schema already provides. Baseline 3 is appropriate since the schema handles parameter semantics fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Get details about one installed theme.' It also specifies the kind of details returned ('what it declares support for' and 'whether it is a block theme'), which differentiates it from sibling tools like list_themes (which lists) and activate_theme (which mutates). The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies usage for fetching a single theme's details, distinguishing it from operations like listing or activating themes. It does not explicitly name alternatives or exclusions, but the context is clear enough that an agent would know when to use this over list_themes or activate_theme. No misleading guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds contextual value by enumerating what theme mods typically contain (logo, colors, layout) and noting the classic theme relationship. While it doesn't describe return format or edge cases, the annotations lower the burden, and the description adds meaningful color beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The first sentence front-loads the primary action and resource; the second adds relevant context about classic themes. Every word contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only operation with one optional parameter and no required output schema, the description is adequate. It states what is returned (theme mods) and gives examples. It could mention possible absence of mods or return structure, but these are minor gaps for such a straightforward read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter (site_id) is fully described in the schema with its optionality and default behavior. The description adds no supplementary semantics about the parameter. With schema coverage at 100%, the baseline of 3 is appropriate; the description does not need to restate what the schema already documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Read the active theme's Customizer settings (theme mods)'. It lists concrete examples (logo, colors, layout options) and clarifies the scope ('anything else the theme registers there'). It also distinguishes from 'options', so an agent can tell this apart from other settings retrievers without needing to inspect siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear contextual guidance: it explains that classic themes keep configuration in theme mods rather than options, implying this tool is appropriate for classic theme settings. However, it does not explicitly name alternatives like get_global_styles or get_site_settings, nor state when not to use this tool. The 'rather than in options' hint is useful but falls short of direct comparison with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds value beyond annotations by noting that the response 'includes roles and a summary of notable capabilities when permitted', which hints at conditional content based on permissions. This is useful context not present in 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence that front-loads the action and resource, then adds the special 'me' case and the response content. There is no fluff or redundancy, and every phrase adds relevant detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch tool with full schema coverage and readOnly annotations, the description covers the key behavior: how to fetch, the 'me' special case, and what extra info is returned. It does not describe the response envelope (e.g., whether it returns a full user object), but given the simplicity and the absence of an output schema, this is not a significant gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents both parameters. The description adds no new parameter semantics beyond the schema's own description of 'id' and 'site_id'. It merely restates the 'by ID' concept, so it does not compensate or extend the schema's completeness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Fetch') and a specific resource ('one user'), and distinguishes the special 'me' case. It clearly differentiates from sibling tools like list_users, create_user, and update_user by focusing on a single-user retrieval with roles and capabilities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: use when you need a single user by ID or the authenticated user. It does not explicitly contrast with list_users or other alternatives, but the singular fetch nature is clear. A minor gap is the absence of an explicit 'use this instead of X' statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey non-read-only, open-world, non-idempotent, and non-destructive traits. The description adds the important disclosure that installation writes files to the server and requires filesystem write access. This extends beyond the annotations by explaining the concrete side effect and prerequisite. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, each earning its place. The first sentence conveys the primary action and the optional activation; the second covers the search-first guidance and the side-effect of file writes. It is front-loaded and free of filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 simple parameters and no output schema, the description is adequate. It tells the agent how to get the slug, what the action does, and the permission requirement. It does not describe error scenarios (e.g., plugin already installed, invalid slug) or the exact result of success, but these are not essential for basic invocation. A minor gap exists, but nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all three parameters (slug, site_id, activate). The description adds no new parameter semantics beyond the schema — it briefly mentions 'optionally activating it straight away' which is redundant with the schema's activate description. The schema already explains the slug and provides examples. Since the schema does the heavy lifting, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Install a plugin from the WordPress.org repository by its slug') with the option to activate. It distinguishes this from sibling tools like list_plugins or get_plugin by focusing on installation vs. reading. The verb and resource are precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to search first with search_plugins to get the right slug, which is a clear precondition. It also notes the requirement for filesystem write access. This gives the agent practical guidance on how to use the tool, though it doesn't explicitly state when not to use it or list alternative installation methods (e.g., installing from a local zip). Still, it's strong guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds behavioral context by stating the tool returns 'the exact block name and which attributes are valid,' which clarifies the output's purpose. It does not contradict annotations and provides useful, non-obvious detail about what the listing contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler. The first sentence states the core function, and the second provides a practical use case. The most important information (what it lists) is front-loaded. Every word earns its place, making it highly efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with three optional parameters, no output schema, and annotations covering safety, the description is almost complete. It explains the tool's purpose and gives a concrete use case. It doesn't mention, for example, whether results are paginated or how search filters work, but those are not essential given the schema documents them and the tool is read-only. A minor gap, hence 4 rather than 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — the schema fully documents all three parameters (search, site_id, namespace). The tool description adds no additional parameter semantics beyond what the schema already provides. With full schema coverage, baseline 3 is appropriate; the description does not need to repeat parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List'), resource ('block types registered on the site'), and outcome ('with their attributes'). It also distinguishes the tool's purpose by tying it to a concrete workflow ('Check here before generating block markup for an unfamiliar plugin's blocks'), which separates it from any sibling tool like discover_content_types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear when-to-use directive: 'Check here before generating block markup for an unfamiliar plugin's blocks.' This tells the agent the exact scenario where the tool is relevant. It does not explicitly name alternatives or when-not-to-use, but no sibling tool directly competes with block-type listing, so the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: it returns compact summaries by default to avoid flooding context, and that full_content is opt-in. This goes beyond what annotations alone provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundancy. The primary purpose is front-loaded, followed by a practical behavioral note. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 19-parameter listing tool, the description covers the key behavioral choice (summary vs full content) and relies on the schema for the rest. It doesn't explicitly distinguish from sibling listing tools, but given the schema richness and the openWorldHint annotation, this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with every parameter already described. The description adds value by explaining the trade-off between summary and full_content, providing usage nuance beyond the schema's simple 'Include the full content body of each item.' This is a helpful additional semantic.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists items of any content type (posts, pages, or CPTs) with filtering, search, ordering, and pagination. This distinguishes it from single-item tools like get_content or get_content_by_slug that retrieve one specific item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on when to use full_content ('only when you genuinely need bodies') and implies it's the standard listing tool. However, it does not explicitly name alternatives like get_content_summary or get_content, leaving the agent to infer which sibling to use for a single item.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds contextual behavior: it works across taxonomy types and supports search/ordering/hierarchy/pagination. It doesn't contradict annotations and adds useful context about scope beyond structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundant phrasing. The core scope is front-loaded ('List terms in any taxonomy') followed by key capabilities. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only listing tool with no output schema, the description covers the essential capabilities and taxonomy scope. It doesn't explain output format or edge cases like filtering by parent only applying to hierarchical taxonomies, but those are documented in the schema. The coverage is adequate for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all 11 parameters are documented in the input schema. The description mentions search, ordering, hierarchy filtering, and pagination, which maps to the parameters but doesn't add new semantics beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List terms in any taxonomy' with a specific verb and resource, and specifies it works for categories, tags, and custom taxonomies. This distinguishes it from related tools like get_term (single term) and content listing tools, even though it doesn't name them explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies this is the tool for enumerating terms across any taxonomy, and mentions search, ordering, hierarchy filtering, and pagination. It doesn't explicitly contrast with alternatives like get_term or list_content, but the scope is obvious given it's about terms. Slight gap in not stating when to prefer a more specific tool, but the context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the tool returns 'settings and rendered output', which is a valuable behavioral detail beyond the structured fields. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the action ('List widgets'), then the optional scope, then what is included. No wasted words; every phrase contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description must convey the return content, and it does by mentioning settings and rendered output. It does not mention pagination or ordering, but for a list tool this is a minor omission. Given the read-only annotations and straightforward parameters, the description is sufficiently complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: both `sidebar` and `site_id` have clear descriptions, so the schema carries the parameter semantics. The description mentions 'optionally within one sidebar', which aligns with the `sidebar` parameter but adds no new syntax or details. Baseline of 3 is appropriate because the description does not need to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('widgets'), and adds the scoping option ('within one sidebar') as well as what is included ('settings and rendered output'). It clearly distinguishes this read tool from create/update/delete widget 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly communicates intent ('List widgets') and the optional sidebar filter, which is the main usage decision. It does not explicitly name alternatives like create_widget/update_widget/delete_widget, but the read-only nature is evident from context and annotations. It could have explicitly stated 'use this for read, others for modify', but the tone and sibling names make it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses per-comment outcome reporting rather than whole-batch failure, a valuable behavioral detail not captured in the annotations. The annotations already indicate mutating (readOnly=false) and non-destructive actions, so the description adds the partial-success semantics. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the actions and add a key behavioral note. No redundant information; it's well-structured for quick consumption.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool with full schema coverage and no output schema, the description covers the core behavior and even hints at the result format (per-comment outcomes). It doesn't address edge cases like authentication or site selection nuances, but those are covered by the schema. Overall it's sufficient for an agent to decide and call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters have schema descriptions, so the schema fully documents them. The description does not add additional parameter-specific meaning beyond noting the batch nature (implied by 'several comments'). With 100% coverage, the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the exact actions (approve, hold, spam, trash) and the resource (comments) and explicitly says 'several comments in one call', which distinguishes it from single-comment tools like update_comment. The title 'Bulk moderate comments' reinforces this.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It positions the tool as 'the practical way to clear a moderation queue', giving a clear use case for batch operations. However, it does not explicitly mention when not to use it or name alternative tools like update_comment for single actions, leaving some inference required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, but the description adds valuable behavioral context: it writes to a specific path (~/.wpxmcp/skills), is loaded by load_skill, and overrides bundled skills with the same name. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: the first sentence defines the purpose with concrete examples, the second specifies storage and loading, and the third notes override behavior. Every sentence adds unique value with no repetition or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters and no output schema, the description covers the essential context: purpose, storage location, relationship to load_skill, and override behavior. It does not describe return values, but that is not required without an output schema, and the annotations already cover safety characteristics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema provides clear descriptions for all 5 parameters (including examples for name and keywords). The tool description itself does not add parameter-specific details beyond what the schema already captures, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool saves a playbook (skill) to persist conventions, with concrete examples of what those conventions could be. It distinguishes itself from siblings like load_skill and delete_skill by explicitly naming the storage location and the loading mechanism, leaving no ambiguity about the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: to persist a playbook for future sessions. It references load_skill as the counterpart that loads the saved skill, providing clear context. However, it does not explicitly state when not to use it or compare it to alternatives, though the purpose is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry the safety profile (readOnlyHint=true, destructiveHint=false) with no contradiction. The description adds genuine behavioral value beyond those hints: it reveals the tool uses WordPress's native search index and returns a type tag per hit, which informs the agent about both mechanism and output shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste: the first establishes the core purpose and behavioral trait, the second delivers the sibling-routing caveat. Every clause earns its place here.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only search tool this is complete: all six parameters are fully documented in the schema, annotations cover the safety profile, and the description provides the key output distinction ('what type each hit belongs to'). The lack of an output schema is partially compensated by that return-shape statement, though explicit pagination behavior is left implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline of 3 applies. The description implicitly differentiates the 'type'/'subtype' enum parameters by framing the tool as cross-type search, but it adds no parameter-level detail beyond what the schema already documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource — 'Search every searchable content type at once using WordPress's own search index' — and distinguishes itself from a sibling: 'Broader than list_content's per-type search.' An agent can tell this tool apart from list_content and the various search_* 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description names the alternative (list_content) and its differentiator (per-type vs. all-at-once search), giving a clear routing signal. It stops short of an explicit when-not-to-use statement, but the contrast is strong enough that the selection logic is nearly self-evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe/read-only nature is covered. The description adds value beyond annotations by disclosing the API key requirement (UNSPLASH_ACCESS_KEY or PEXELS_API_KEY) and the output shape (URLs and attribution). It does not mention rate limits, but given the annotations cover safety, this extra context is meaningful and earns a 4.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, all essential: the function and output, the downstream usage, and the prerequisite. The most important information (search scope and result type) is front-loaded. No redundancy or filler. The structure is efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has four parameters, two enums, and no output schema. The description compensates by stating the output includes candidate URLs and required attribution, and names the specific fields (download_url, attribution) to pass downstream. It does not explain edge cases like no results or error behavior, nor the exact result object structure, but for a search-and-return-list tool this is reasonably complete. It loses one point for omitting error/pagination context, but it covers the critical workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter (query, per_page, provider, orientation) is already well-documented with type, defaults, and enums. The description does not add any additional parameter-level guidance beyond what the schema provides. It introduces the non-parameter terms download_url and attribution, but those are output fields, not parameter clarifications. Per the baseline rule for full schema coverage, a score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches Unsplash or Pexels for royalty-free photos and returns candidate image URLs with attribution. The verb 'search' and specific resources are named, and the downstream workflow to create_media distinguishes it from sibling tools like list_media or search_site. It fully clarifies what the tool accomplishes and how it fits the media workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on when to use it: to find stock photos, and how to use results (pass download_url and attribution to create_media). It also states the prerequisite of API keys being set. It does not explicitly exclude scenarios (e.g., 'use list_media if you already have media'), but the workflow is clear and actionable. Minor gap but strong enough for a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as a write operation (readOnlyHint=false) and non-idempotent. The description adds valuable extras: it requires a companion plugin and explains that values persist as standard post meta even if the tooling is removed. This goes beyond the structured hints without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no filler. The core purpose and the unique differentiator (unregistered keys) are front-loaded, and the plugin requirement and storage persistence are stated efficiently. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 covers the plugin dependency and data persistence, complementing the annotations. It does not detail edge cases like error handling or the exact merge behavior for existing meta, but given the rich schema and annotations, these are minor omissions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters (id, meta, site_id) are already documented clearly, including the null-deletes-key behavior for meta. The description does not add further parameter-level meaning, matching the baseline expected when the schema carries the load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Write), the resource (custom fields/post meta on a content item), and a distinguishing detail: it handles keys not registered with show_in_rest, which core REST refuses to write. This differentiates it from sibling write tools like update_content and from the read-oriented get_content_meta.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies appropriate usage by highlighting a core REST limitation and the need for a companion plugin. It tells an agent when this tool is necessary (writing unregistered meta) but stops short of explicitly naming alternatives or stating when not to use it. The context is clear but not fully prescriptive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the destructive nature is covered. The description adds valuable behavior beyond annotations: it discloses that children are re-parented to the top level rather than deleted. This is a non-obvious side effect that agents need to know. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, no filler. The core action is front-loaded, and the critical child-re-parenting behavior is stated immediately after. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter tool with annotations covering the safety profile and full schema descriptions, the description is complete. It covers the key non-obvious behavior (child re-parenting) and needs no explanation of return values since there is no output schema. An agent has everything necessary to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both 'id' and 'site_id' having descriptions in the schema. The tool description adds no additional parameter-specific semantics beyond what the schema provides. According to the rubric, with high schema coverage, the baseline is 3, and no extra value is added here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Remove' and the resource 'one item from a navigation menu', distinguishing it from broader tools like delete_menu (which removes an entire menu). It also adds a unique behavioral detail (re-parenting of children) that further clarifies what the tool does. This is specific and not a restatement of the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use this tool (to delete a single menu item) but does not explicitly mention alternatives or when-not-to-use cases. However, the behavioral note about children being re-parented instead of deleted helps an agent decide if this is the right operation, especially compared to deleting the whole menu. There are no exclusions or alternative tools named, though the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only and non-destructive. The description adds meaningful behavioral context: the show_in_rest => false implication for absent types, which informs the agent about the tool's scope and limitations. It does not contradict the annotations (idempotentHint false is plausible for a listing that may reflect changing data, but the description doesn't claim idempotency). No conflicts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste. The primary action is front-loaded, followed by precise usage guidance. Every clause earns its place—no redundant phrases or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a listing tool with no output schema, the description fully explains what is returned and why this tool is essential for unfamiliar sites. It also covers the show_in_rest behavior and the optional include_counts parameter is already in the schema. An agent can call this correctly without additional information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (site_id, include_counts) are fully documented in the schema. The description does not add any parameter-specific details beyond the schema; it only mentions the include_counts cost indirectly via the parameter description. Per the rubric, a baseline of 3 applies when the schema carries the semantic weight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List'), a clear resource ('every content type registered on the site'), and enumerates the exact attributes returned (REST base, hierarchical status, taxonomies, supported fields). This distinguishes it from sibling tools like discover_taxonomies, which target a different resource. The purpose is unambiguous and detailed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit context for when to use it: 'Call this before working with an unfamiliar site.' It also explains the consequence of a type being absent (show_in_rest false and unreachable via REST), which is valuable guidance. However, it does not explicitly name alternatives like discover_taxonomies or state when *not* to use it, so it lacks formal exclusions/alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to repeat safety. It adds valuable behavioral specifics: the token expires, the URL is private, and it doesn't affect other viewers. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences carry full purpose, behavior, and usage guidance with zero filler. The core purpose is front-loaded, and every clause adds distinct information (tokenised, private, expiry, no-op for others).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with no output schema, the description fully explains what it returns (a URL), how it behaves (private, temporary), and when to use it (preview checks). No missing information that an agent needs to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptive parameter docs for path, theme, and site_id. The description adds general context (token expiry) but doesn't augment parameter meaning beyond what the schema provides, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (get a tokenised private URL) and the resource (preview URL for a draft theme), and explains its unique purpose: render the site without affecting others. It distinguishes itself from theme management siblings by focusing on preview, not activation or publishing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use it to check work before publishing, implying it's the pre-publication preview tool. It does not explicitly list alternatives or exclusions, but the 'before publishing' guidance effectively communicates when it's appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds the default-deny policy and notes that each entry indicates write capability, which is useful beyond the annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with zero redundancy. The main purpose is front-loaded and the default-deny behavior is stated efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional filter and no output schema, the description sufficiently explains the entries' content (write flag) and the policy, leaving no missing information an agent would need.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter (filter) is fully described in the schema (100% coverage) with an example. The description does not add additional meaning beyond what the schema provides, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (List) and resource (WP-CLI commands run_wp_cli will accept), and clearly distinguishes it from the sibling run_wp_cli tool by focusing on the allowlist. The title reinforces the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys that this lists commands that are allowed, implying it should be consulted before using run_wp_cli, but it does not explicitly state when not to use it or name alternatives. The default-deny policy gives clear context for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: it discloses the fallback behavior between the companion plugin and standard WordPress roles, which could affect output. This is valuable because the openWorldHint is true but the description clarifies a specific environmental dependency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The first sentence states the core action and purpose, and the second covers the fallback mechanics. Everything earns its place, and the most important purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with no required parameters, high schema coverage, and destructive/read-only annotations already provided, the description is complete. It explains the output scope (roles and capabilities), the fallback behavior, and the intended usage context. No other information 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter site_id is fully described in the schema (coverage 100%), including its optionality and behavior with multiple sites. The description adds no additional parameter-specific semantics (e.g., format or examples), so the baseline of 3 applies since the schema handles the explanatory burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific verb-resource pair ('List the roles registered on the site') and includes their capabilities. It also gives the practical purpose ('so you can pick the right role before creating or updating a user'), which distinguishes it from sibling tools like list_users or get_user by linking it to user creation/update workflows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly indicates when to use the tool: before creating or updating a user, which is a clear context. However, it does not explicitly contrast with alternative tools (e.g., list_users) or state when not to use it, but the guidance is strong enough to route the agent appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context by specifying exactly what information is returned (active status, block theme flag, versions, parents), which goes beyond the annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, tightly crafted sentence that leads with the core action ('List every theme') and then packs in the key output fields without wasted words. All essential information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only listing tool with two optional parameters whose schema is fully documented, the description is complete. It tells the agent what to expect in the result (active, block, versions, parents) and covers the operational scope, so nothing critical for invoking it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both parameters (status, site_id) are fully described in the schema. The tool description adds no further parameter guidance, so it does not enhance what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List'), a concrete resource ('every theme installed on the site'), and the key distinguishing fields (active status, block/FSE themes, versions, parents). This clearly differentiates it from sibling tools like get_theme (single theme) and activate_theme, without needing to inspect schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the tool is for enumerating all themes, giving the context of a list operation. However, it does not explicitly mention alternatives (e.g., 'use get_theme for a single theme') or exclusion criteria, 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows the tool is safe. The description adds valuable context beyond annotations: it reveals that the tool returns a focused guide, that it covers 'traps not obvious from the API', and specifically calls out page builders as a scenario where the playbook is critical. This enriches the behavioral understanding without contradicting any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but well structured. It front-loads the core purpose, then the usage directive, and then a specific, illustrative caveat about page builders. Every sentence adds value; there is no fluff. It could be slightly more compact, but it earns its length by providing critical operational guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with two well-documented optional parameters and no output schema, the description covers the essential information: what to provide, what to expect, and when to use it. It does not describe the return format, but that is not required given the annotations and the nature of the tool. The description is comprehensive enough for an agent to invoke it correctly in most expected scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides comprehensive descriptions for both 'name' and 'query' with examples, achieving 100% coverage. The description reinforces that 'query' is for describing the task and 'name' for loading a specific skill, but it does not add new semantic meaning beyond the schema. Therefore, per the rubric, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Load the playbook for the task at hand' with a specific verb (load) and resource (playbook). It goes on to explain what a playbook is and why it exists, making it distinct from all sibling tools. The purpose is unambiguous and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Call this FIRST when starting any substantive task' and instructs the agent to 'describe what you are about to do'. It also provides a concrete example (page builders) where using this tool is essential, effectively telling the agent when to invoke it. This is explicit and decisive usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate openWorldHint=true and destructiveHint=false, which the description aligns with. It adds valuable behavior details: fields are exposed to the REST API, data persists as post meta or options, and remains even if tooling is removed. This goes beyond annotations by explaining the persistence and API exposure, though it doesn't mention potential side effects like overwriting existing groups with the same key.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences that efficiently pack purpose, use case, and behavioral details. It front-loads the primary action and follows with a clear usage directive. While not minimal, every sentence adds value—no redundancies or filler. The length is appropriate for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the parameter count (8) and high schema coverage, the description covers the essential context: it explains what the tool does, when to use it, and key side effects. It doesn't explain every parameter in detail (schema does that) and omits details like how the 'position' parameter affects the meta box, but the overall behavior and intent are clear. For a registration tool with no output schema, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema: it explains the 'context' parameter (post_meta vs options) and the 'fields' array's display order, and clarifies that 'group_key' should be unique. It also lists the thirteen field types, which aids the agent in constructing valid field definitions. These additions justify a score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action (register custom fields), the resource (custom fields/meta boxes/settings pages), and the context (WordPress theme development). It distinguishes itself from sibling tools like set_content_meta or update_site_settings by focusing on registration of field definitions rather than setting values. The phrase 'Use this when building a theme...' reinforces the specific purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the intended use case: 'Use this when building a theme so the site stays editable by humans without touching code.' It implies that this tool is for initial setup, not for day-to-day value manipulation. While it doesn't name alternative tools for writing values, the message is clear that after registration, values are read/written via other tools. The context is strong enough to guide an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds valuable behavioral context: it calls an external service (WordPress.org) and discloses the specific return fields (slug, rating, install count, last-updated, compatibility). This helps the agent set expectations without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, with the core purpose front-loaded in the first sentence and the external-scope clarification in the second. Every sentence earns its place; there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is sufficient for a low-complexity search tool: it states the purpose, the external source, and the exact return fields. Combined with full param schema and safety annotations, nothing critical is missing for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (search, page, per_page) already having a clear description and defaults. The tool description adds no further parameter-level detail (e.g., case sensitivity, wildcard support), so it does not go beyond the schema. Baseline 3 is appropriate given full coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the verb 'Search' and the resource 'public WordPress.org plugin repository', and explicitly contrasts it with 'your site', distinguishing it from sibling tools like list_plugins and get_plugin. This gives an agent a clear, unambiguous sense of what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context—'queries WordPress.org, not your site'—which implies when to use this tool (when searching the external repository) versus site-local tools. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of full explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, but the description adds critical behavioral detail beyond that: 'Activation runs the plugin's code immediately' and highlights the risk of a fatal site error with incompatible versions. This goes well beyond the structured fields and gives the agent essential safety context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no filler. The primary action is front-loaded, and the critical warning follows immediately. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple activation tool with three fully documented parameters and no output schema, the description covers the essential risk (fatal errors) and the immediate execution behavior. It doesn't explain the success/failure response, but that is not necessary for correct invocations. This is complete enough for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter (plugin, site_id, network_wide) is already described in the schema. The description does not add any additional meaning to the parameters, so while it doesn't harm, it also provides no extra value. Baseline 3 is appropriate for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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.' Clear and unambiguous, and the description's mention of running the plugin's code further clarifies the action. It is distinguishable from sibling tools like deactivate_plugin and install_plugin without needing their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context for when activation is appropriate (installed plugins) but does not explicitly mention alternatives or when not to use it. The caution to test on staging addresses a key risk but is more of a warning than usage guidance. Still, the core condition ('installed plugin') is implied and the staging advice is valuable operational guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the description is not required to restate that. It adds valuable context beyond annotations: the immediate visual impact on the live site and the non-guarantee of widget/menu assignments carrying over. This is genuinely useful behavioral information that the schema and annotations do not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no filler. The primary purpose and immediate side effect are front-loaded, the required flag is called out early, and the alternative workflow is given in a single closing sentence. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-action tool with destructive implications, the description covers the essential operational facts: what it does, its safety requirement (confirm), and the alternative for iteration. Given the schema fully documents all three parameters and annotations cover the safety profile, nothing critical is missing. A small gap is that it doesn't mention what happens on failure (e.g., invalid stylesheet) but that is minor for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description mentions 'Requires confirm: true,' but the schema's confirm property already explains 'Required — this changes the live site's appearance for every visitor.' It adds no new meaning for site_id or stylesheet beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Switch the site's active theme,' a specific verb and resource that immediately conveys the core action. It goes on to state the consequence ('changes the entire front-end appearance immediately') and explicitly contrasts itself with the draft workflow, making it easy to tell apart from siblings like install_theme or publish_draft_theme.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states a hard prerequisite ('Requires confirm: true') and provides a clear when-not-to-use rule ('If you are iterating on a theme you are building, use the draft workflow and publish_draft_theme instead.'). This directly guides the agent toward the correct alternative in the relevant scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (readOnlyHint false, destructiveHint false), so the description carries the behavioral transparency burden. It adds key behavioral details: snippets are created disabled by default, PHP syntax is checked before save, and disabling can be done without touching code. It does not mention the confirm requirement for delete or side effects of update, but those are covered in the schema. The description discloses the most critical safety behaviors without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long and front-loads the core purpose and primary use case. It provides essential safety information (disabled by default, syntax check) without redundancy. Every sentence earns its place, and the structure is logical: first the why-to-use, then critical operational details. No fluff or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, multiple actions), the description covers the key context: why to use it, safety behaviors, and a hint about activation. It does not explicitly mention the confirm parameter for delete or the site_id fallback behavior, but these are fully documented in the schema. The description is complete enough for an agent to understand the tool's primary purpose and key operational constraints, though it could mention the delete confirmation requirement for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with descriptions, so the baseline is 3. The description does not add meaning beyond the schema; it mentions that snippets are created disabled and PHP syntax is checked, which relates to behavior rather than parameter semantics. The schema already explains the opening PHP tag omission and location preferences, so the description adds no extra parameter insight. It neither enhances nor degrades the schema's completeness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool manages code snippets by adding PHP, CSS, or JavaScript as managed entities instead of editing theme files. It explicitly names the action (Add) and the resource (snippet), and differentiates from the alternative approach of theme file editing. The purpose is unambiguous and the description distinguishes this tool from siblings like write_theme_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises using this tool over editing theme files, citing survival of theme updates and easy disabling. It also gives important usage context: new snippets are created disabled and must be activated in wp-admin, and PHP snippets are syntax-checked before saving. This provides clear when-to-use guidance and safety instructions, leaving no ambiguity about when to prefer this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, indicating a write operation. The description adds valuable behavioral context beyond that: the distinction between immediate publishing (with moderation capability) versus entering the moderation queue, and the permission requirement implied by 'requires moderation capability.' It also conveys that the operation is not idempotent (consistent with idempotentHint=false) by implying a new comment is created each time. This goes beyond the basic mutation signal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the primary purpose ('Post a comment on a content item') followed by the key nuance about status and moderation. Every sentence earns its place; there is no fluff or redundancy. The structure is logical and quickly scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with 10 parameters and no output schema, the description covers the core intent, moderation behavior, and a permission requirement. It does not explicitly state what the tool returns (e.g., the new comment ID) or describe error conditions, but such details may be considered implied for a creation operation. The schema covers parameter semantics and prerequisites like comment_status open in the 'post' field description, so the description is sufficient for basic invocation. A slight gap is the lack of return-value clarity, but overall it is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are documented in the schema. The description adds meaning beyond the schema for the 'status' parameter by explaining the practical effect: setting it to 'approve' publishes immediately, otherwise it enters the moderation queue. This is richer than the schema's 'Moderation status. Requires moderate_comments to set.' For other parameters, the description does not add extra semantics, but the full schema coverage makes that unnecessary. Overall, the description enhances at least one parameter's meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Post a comment on a content item, optionally as a threaded reply.' It specifies the resource (comment on content) and the optional threading behavior, and implicitly distinguishes from siblings like update_comment, delete_comment, and moderate_comments. The status handling adds further specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (to create a new comment on content, optionally threaded) and explains the moderation behavior. It gives a practical condition: setting status to 'approve' requires moderation capability, otherwise the comment enters the normal queue. However, it does not explicitly contrast with sibling tools like update_comment or moderate_comments, relying on the obvious 'create' purpose to imply usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=false and readOnlyHint=false. The description adds valuable context by explaining that the operation clones into an isolated draft, reinforcing safety and non-interference with the live site. It also mentions the backup behavior of the publishing step, which helps the agent understand the overall lifecycle. Not contradictory to annotations, and provides meaningful behavior beyond what the booleans convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no redundancy. It front-loads the core purpose, then explains the workflow context, and ends with a practical parameter tip. Every sentence earns its place, and the structure guides the agent from understanding to action efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, its position in the editing workflow, and the optional parameter behavior. While it does not describe the return value or response format, there is no output schema, so that gap is acceptable. For a tool with only three optional parameters and clear annotations, this is sufficiently complete for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters have detailed descriptions in the schema (100% coverage), so the baseline is 3. The description reiterates the from_theme default pattern ('Omit from_theme to clone the currently active theme'), which is already stated in the schema. It adds no new semantic detail to the parameters themselves, only reinforces the workflow. Thus it meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (clone) and resource (installed theme into an isolated draft copy). It clearly distinguishes this from sibling tools like publish_draft_theme and delete_draft_theme by focusing on the creation of an editable draft without affecting the live site. The purpose is unambiguous and immediately understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly prescribes when to use the tool: 'Every theme edit should go through a draft'. It outlines the full workflow (create draft → write files → preview → publish) and identifies publish_draft_theme as the follow-up action. It also gives a concrete tip about the from_theme parameter. This leaves no doubt about the tool's role versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the menu is created empty and that locations can be assigned, which are behavioral details beyond the annotations. It does not mention return values or potential side effects beyond location assignment, but annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) are not contradicted, and the workflow hint adds value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the main purpose, and includes the pointer to add_menu_item. Every phrase contributes to clarity, with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters and no output schema, but the description covers the essential workflow: creating an empty menu and then adding items. It does not explicitly state the return value (e.g., menu ID), but the mention of adding entries afterwards implies that an identifier is produced for later use. Overall, it is sufficiently complete for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes all 5 parameters with 100% coverage, so the description does not need to restate them. The mention of 'theme locations' mirrors the schema's 'locations' parameter, and the description adds no new parameter-specific guidance beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('empty navigation menu'), and explicitly says it optionally assigns to theme locations. It distinguishes itself from add_menu_item by noting that entries are added afterwards, making the tool's specific role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It directly instructs the user to use add_menu_item for adding entries, naming the appropriate next step. The phrase 'optionally assigning it to one or more theme locations' clarifies when locations are relevant, and the overall context implies that this tool is for creating new menus rather than updating or deleting them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=false and destructiveHint=false. The description adds behavioral context beyond that by stating the requirement for an Administrator account and the full-control implication of the 'administrator' role, which is not present in the annotations. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two crisp sentences: the first states the core purpose, the second delivers the role warning. No redundant content; every word earns its place and the critical caution is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 11 parameters, 3 required, and no output schema, the description covers the essential purpose and the most impactful behavioral warning (role implications). It omits return-value expectations and error handling, but given full schema coverage and clear purpose, it is reasonably complete for a creation operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by advising deliberate role selection and warning that 'administrator' grants full control, a nuance not captured in the schema's role description. This extra semantic guidance raises the score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Create'), a clear resource ('a WordPress user'), and adds an important scoping detail (requires Administrator account). It distinguishes from sibling tools like update_user and delete_user by specifying the creation action, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions a prerequisite (Administrator account) and warns about the consequences of the 'administrator' role, which guides when and how to use it. It does not explicitly contrast with alternatives like update_user, but the purpose is self-evident and the cautions provide practical usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral context beyond annotations: it includes plugin-added routes and notes that route shapes vary across plugin versions — information not present in the schema or annotations. However, it doesn't describe return format or pagination, which are minor for a discovery tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero redundancy. The core purpose is stated first, followed by actionable usage guidance with rationale. Every word earns its place; no filler or repetition of schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is sufficient for a read-only discovery tool with no output schema. It covers what the tool does, when to use it, and important caveats about plugin versions. Minor gap: return format is not mentioned, but for a list tool with no specific output schema, this is acceptable. It leverages annotations for safety context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for search, site_id, and namespace parameters, including default-site behavior. The tool description adds no extra parameter semantics, but since the schema fully documents them, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('List the REST namespaces and routes') and a specific resource (site-registered routes, including plugin-added ones). It clearly differentiates itself from the sibling rest_api by noting it lists actually registered routes, which prevents guessing. This is a precise, non-tautological purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to use this tool before rest_api to ensure called routes exist, and gives rationale ('route shapes vary between plugin versions and guessing wastes calls'). This provides clear when-to-use guidance and implicitly warns against guessing, making it easy for an agent to decide when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=true, destructiveHint=false) already cover safety; the description adds meaningful behavioral context: it returns a minimal summary without the body, and its purpose suggests it is lightweight and suitable for repeated use. This goes beyond the structured annotations and clarifies expected performance.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the return type, then the purpose, then input options. No fluff or redundancy; every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only summary tool with no output schema, the description lists all returned fields, which is sufficient for an agent to know what to expect. It doesn't mention error handling or edge cases (e.g., invalid ID), but given the simplicity and read-only nature, this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all four parameters, but the description adds crucial semantics by explaining the mutually exclusive id/url relationship and that type is only used with id. This clarifies how the parameters work together, exceeding what the schema alone provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states exactly what the tool does: returns a minimal summary of one item with a specific list of fields, explicitly excluding the body. It clearly distinguishes itself from siblings like get_content (which returns full content) and get_content_by_slug/find_content_by_url by focusing on the summary-only output and its audit/lookup purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a clear use case ('Built for audits and lookups over many items') and explains the input alternatives (id with type or URL). It doesn't explicitly name sibling tools or state when NOT to use it (e.g., if you need the body, use get_content), but the field list and 'without the body' make the intended use unmistakable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations (readOnlyHint=false, destructiveHint=false) cover the mutation safety profile, while the description adds the important behavioral nuance that installation is separate from activation. It also clarifies the source (WordPress.org), which is an external dependency. No contradiction with annotations; the description adds 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. The core action and scope are stated first, followed immediately by the critical exclusion (does not activate). Every word earns its place; it is efficiently front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two parameters, one required, and a straightforward install action, the description covers the essential behavior, source, and non-activation. It lacks explicit mention of consequences like overwriting an existing theme or network dependency, but given the low complexity and annotations covering safety, it is sufficiently complete for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters (slug and site_id) are well-documented in the schema. The description adds 'by slug' and 'from WordPress.org repository', which reinforces the slug parameter's meaning but adds little beyond the schema. With full schema coverage, baseline of 3 is appropriate; the description provides minimal extra value here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Install'), names the resource ('a theme'), and specifies the source ('from the WordPress.org repository by slug'). It explicitly distinguishes itself from activation ('Does not activate it') and names the intended follow-up tools (activate_theme, draft workflow), making it clear how this tool differs from siblings like activate_theme or install_plugin.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: it states that this tool installs but does not activate, and directs the agent to use activate_theme or the draft workflow afterwards. It also implies the appropriate use case (when a theme needs to be present but not active). This is clear, actionable guidance with named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds the behavioral detail that saved skills shadow bundled ones with the same name, which is beyond what annotations convey. It does not mention return format or pagination, but these are less critical for a zero-parameter list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff. The primary action is front-loaded, and the shadowing note is a valuable addition. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no parameters and no output schema, the description covers the core purpose and a key behavioral nuance. It does not describe the exact return format, which could be mildly helpful, but the absence of that detail is a minor gap given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so parameter semantics are trivially covered by the empty schema. The description adds no parameter-specific information because there is none needed. With 0 params, the baseline is 4, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List every available playbook') and the resource (playbooks/skills). It also distinguishes from other list tools by specifying it covers both bundled and saved playbooks, and adds the shadowing nuance. This makes it unambiguous and differentiates it from sibling list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this to see all available playbooks. It does not explicitly mention alternatives or when-not-to-use, but for a simple listing tool, the usage is self-apparent given the resource type. No exclusions or routing to siblings are needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only safety profile is known. The description adds valuable context: that classic themes yield an empty result and that template parts are included, which conditions agent expectations about output. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero fluff. The primary action is front-loaded, followed by the critical limitation and alternative. Every word contributes to understanding, making it highly efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with two optional parameters, the description covers what it does, when to use it, and a key edge case (classic themes). It lacks details about the return format (e.g., a list of names/objects), but no output schema is provided and the tool is straightforward, so this is a minor gap. Overall, an agent can correctly decide whether to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully describes both parameters (kind enum and site_id usage) with 100% coverage, so the description has little to add. It does not elaborate on parameter values beyond the schema, though the examples (front-page, single, archive) are illustrative rather than parameter definitions. This meets the baseline for fully documented parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists block theme templates or template parts, with specific examples. It distinguishes itself from related tools like get_template (which retrieves a single template) and list_theme_files (which handles theme files for classic themes). The verb 'list' and resource 'block theme's templates' are precise and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (block themes) and when not to (classic themes), and points to the alternative ('use the theme file tools instead'). This gives an agent clear routing guidance and prevents misuse on classic themes where the tool would return nothing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds valuable behavioral context: it discloses the fallback to core REST data when the companion plugin is absent and states it 'says which parts it could not see,' which is a transparency about limitations. This goes beyond the annotations and helps set expectations for partial results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. The first sentence front-loads the exact scope of the return value, and the second packs usage guidance plus behavioral nuance. Every clause earns its place, making it both concise and structurally sound.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Since there is no output schema, the description carries the burden of explaining the return. It lists the main data categories and the fallback behavior, giving an agent a good mental model of what to expect. It omits precise formatting or data types, but for a diagnostic aggregation tool this is adequate. The description is complete enough for correct invocation and interpretation at a high level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters clearly. The description does not add any extra meaning or usage nuance beyond the schema, such as how include_health interacts with the plugin or how parameters affect the output. It meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('get') and a comprehensive resource ('diagnostic picture'), enumerating concrete data points (WordPress/PHP versions, active theme/plugins, database size, health checks, updates, server config). It distinguishes itself from siblings like get_site or get_site_settings by framing itself as the full one-call diagnostic, which is immediately clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Start here when auditing a site or diagnosing a problem,' giving a clear trigger condition. It does not explicitly exclude alternatives or name siblings to use instead, but the 'start here' guidance implies this is the first step, leaving follow-up to more specific tools. This is clear context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses critical behaviors: it 'Refuses to write to a live active theme by default' unless allow_live_theme is set, and 'PHP is syntax-checked before it is saved, so a parse error is reported rather than fataling the site.' These are safety and error-handling traits not present in the schema or annotations, giving the agent essential operational knowledge.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, with the core action and overwrite semantics front-loaded in the first sentence. The second sentence packs two important safety behaviors (draft requirement and syntax check) without waste. Every clause serves a purpose, making it efficient and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a potentially destructive write operation, the description covers the key safety context: drafting is encouraged, live writes are guarded, and syntax errors are handled gracefully. The parameter schema handles the rest. It does not mention return values (no output schema) or permission requirements, but these are not explicitly needed given the schema and annotations. The description is sufficiently complete for correct invocation, with a slight omission of what happens on success, though output schema absence makes that less critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters are already documented. The description adds minimal parameter-specific insight beyond restating the overwrite semantics; for example, it reinforces the default draft behavior but does not explain syntax or format of path or content beyond the schema. Since the schema already explains the parameters, the description provides only marginal added value, aligning with the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Create or overwrite') and resource ('a theme file') with a clear scope ('replacing its entire contents'). It distinguishes from siblings like read_theme_file, edit_theme_file, and delete_theme_file by the overwrite action and the draft-workflow emphasis. The phrase 'Refuses to write to a live active theme by default' further defines its boundary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly advises working in a draft ('work in a draft (create_draft_theme) so the site stays untouched until you publish') and warns against live writes (via allow_live_theme). It names the sibling create_draft_theme and contrasts with the default refusal, but does not explicitly mention alternative write tools like edit_theme_file for partial changes. This gives strong context but lacks an explicit 'when not to use this' statement for partial edits.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, establishing a safe read operation. The description adds a useful behavioral nuance about block themes potentially not being covered, which is not encoded in annotations. It doesn't contradict annotations and provides context beyond the structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero fluff. The primary purpose is front-loaded, and the important alternative for block themes is placed second without unnecessary detail. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter and no output schema, the description is complete. It covers the purpose, the key alternative, and the schema covers the parameter. No critical information is missing for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameter site_id is fully described in the input schema. The description adds no extra meaning about parameters, which is acceptable given the schema handles it. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists navigation menus and their theme locations, using a specific verb and resource. It distinguishes itself from sibling tools like get_menu (singular) and create_menu by indicating the plural listing aspect and the additional theme-location information.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly notes that block (full-site-editing) themes may use navigation blocks instead, and directs the agent to list_content with type 'wp_navigation' as the alternative. This provides clear when-to-use and when-not-to-use guidance, surpassing simple context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint: true, readOnlyHint: false), the description discloses that the active theme is backed up first, making the change reversible, and stresses that this step is the one that alters the live site. It also requires confirm:true, adding important behavioral context about the confirmation gate. This fully surfaces the tool's side effects and safeguards.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences with no filler. The key verb and resource appear first, followed by the backup/reversibility note and the confirm requirement. Every sentence earns its place, and the structure is front-loaded for quick agent parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only three optional parameters and no output schema, the description covers all crucial operating context: the action, its reversibility, its impact on visitors, and the mandatory confirmation. It leaves no critical gaps that would prevent an agent from calling it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all three parameters with 100% coverage, including the confirm field's necessity and the theme default. The description only reinforces that confirm is required, which is redundant with the schema. Since the schema carries the full parameter semantics, the description adds no additional meaning, justifying the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the specific verb 'promote' targeting 'a draft theme to the live site', clearly stating the resource and action. It distinguishes itself from sibling tools like activate_theme or create_draft_theme by emphasizing that this is the only step that changes what visitors see, and that all prior steps are sandboxed. No ambiguity about the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives strong context on when to use the tool: when ready to make a draft theme live, and it implicitly contrasts with sandboxed steps beforehand. It also states the mandatory confirm:true requirement, which guides invocation. However, it does not explicitly name alternative tools or state 'when not to use', so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds context about the consequences of the sibling tools (file replacement and exact-match requirement), which is not in the annotations and helps the agent understand the implicit workflow. This adds value beyond the structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero fluff. The main purpose is front-loaded, and the workflow guidance is concise yet complete. Every word contributes to the agent's understanding. Excellent structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only file access tool with full schema coverage and strong annotations, the description covers the essential context: what it does, when to use it, and why it's necessary before editing. The absence of an output schema is acceptable because the tool returns raw file contents; no additional structure is needed. No critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters (path, theme, site_id, max_chars) are already documented in the input schema. The description itself does not add any parameter-level detail beyond what the schema provides. Since the schema is fully descriptive, a score of 3 is appropriate as the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Read') and the resource ('the contents of one theme file'), and explicitly differentiates from sibling tools by naming write_theme_file and edit_theme_file. This makes the tool's purpose unambiguous and distinguishes it from alternatives without needing to inspect schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Always read before editing' and explains the reasoning for both write_theme_file (replaces whole file) and edit_theme_file (needs exact text to match). This tells the agent exactly when to use this tool versus its siblings, and the rationale is concrete and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint:false, openWorldHint:true, destructiveHint:false) already signal that this is a non-read-only, open-world tool. The description adds value by naming plugin routes and warning about rest_no_route errors, but it does not explicitly state that write methods require a writable site (though this is covered in the schema's method parameter). Not contradicting annotations; adds useful context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The purpose is front-loaded, then usage guidance follows. Every word earns its place; the hint to use discover_rest_routes is both concise and actionable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an open-world catch-all tool, this description is highly complete: it describes scope (any endpoint, including plugin routes), gives a discovery workflow, explains the failure mode, and implicitly signals write capability via method hints (though that's in schema). It covers everything an agent needs to decide when and how to call it, given the rich schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 all six parameters. The description adds some semantic context for the route parameter (validity, discover_rest_routes), but does not elaborate on body/query/site_id beyond what the schema states. Baseline of 3 is appropriate since the description does not need to repeat schema details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Call') and resource ('any WordPress REST endpoint'), and explicitly frames it as the 'escape hatch' for what dedicated tools do not cover, naming plugin examples (WooCommerce, Yoast, ACF). This clearly distinguishes it from the many sibling tools that target specific resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use guidance: use this for anything the dedicated tools do not cover, and specifically instructs to 'Use discover_rest_routes first to find valid routes rather than guessing.' It also warns against inventing routes and explains the error behavior (rest_no_route), which sets the right expectations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (which only indicate readOnlyHint=false, openWorldHint=true, no idempotence, and destructiveHint=false), the description adds substantial behavioral detail: commands are emulated in PHP (no binary/SSH needed), only allowlisted commands run (everything else refused), writing commands need admin, and search-replace is dry-run first. This fully discloses the operational constraints and side effects, exceeding what annotations alone convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences with no filler. It leads with the core purpose, then adds essential operational details (emulation, allowlist, admin, dry run). Every sentence contributes unique information, and the structure is efficient and immediately informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a generic command-runner tool, the description covers all necessary context: what it does, how it works (emulated), authorization requirements (admin for writes), safety (dry-run for search-replace), and the allowlist mechanism with a reference to list_cli_commands. The lack of an output schema is mitigated by the format parameter, and no critical usage aspect appears missing. It is a complete and self-contained definition.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% — every parameter (command, format, site_id, confirm_token) has a descriptive text in the schema. The tool description does not add additional parameter-level insight beyond what the schema already states. It provides context about the command parameter's allowlist and admin requirements, but that is more behavioral than parameter-specific. Given the high schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Run a WP-CLI command against the site.' The verb is specific, the resource is clear (WordPress site via WP-CLI), and it distinguishes itself from the many dedicated sibling tools by positioning itself as a generic command runner. There is no ambiguity about what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides key usage guidance: commands must be allowlisted (pointing to list_cli_commands), writing commands require an Administrator account, and search-replace always dry-runs first. It does not explicitly state when to prefer a dedicated sibling tool over this one, but the instruction to check list_cli_commands effectively tells the agent to verify command availability. This is adequate context for selection, though a direct alternative-routing statement would earn a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark this as a write operation (readOnlyHint false) but say nothing about merge behavior or immediacy. The description adds crucial behavioral context: changes apply site-wide immediately, and partial settings replace the entire branch. This goes beyond the annotations and helps the agent predict side effects, though it doesn't cover authentication, rate limits, or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, front-loaded sentences: the first states the purpose, the second the immediate effect, and the third the critical usage caution. No fluff, every sentence earns its place, and the most important caveat is highlighted in a warning-like manner.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 optional parameters and nested open-world objects, the description covers the essential context: what is updated, the immediate site-wide impact, and the merge/replace caution. It guides the agent to read first, which is critical for safe usage. No output schema means return values need no explanation; 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the baseline is 3, but the description adds real semantic value for the `settings` parameter by explaining the merge behavior ('partial settings replaces that whole branch'). This clarifies a non-obvious aspect not present in the schema. The styles and site_id parameters are already well documented in the schema, so the description doesn't need to repeat them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'Update', the resource 'a block theme's global styles', and enumerates what that includes (palette, typography, spacing, per-block styling). This clearly distinguishes it from the sibling `get_global_styles` and other update tools, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises 'Read them first' and explains the merge semantics ('a partial settings object replaces that whole branch'), which guides when and how to use the tool safely. It also hints at the alternate `get_global_styles` by telling the user to read first, though it doesn't name the sibling or provide explicit exclusion conditions. The site_id parameter guidance in the schema also supports usage decisions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, etc.) by disclosing that the tool always previews first and requires a confirm_token to write anything, so no changes are applied without explicit confirmation. It also reveals that find/replace entries that don't match are skipped rather than aborting the batch. These are important behavioral traits not present in the schema or annotations, greatly aiding correct usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero fluff. The first sentence establishes the purpose and examples; the second immediately covers the critical preview/confirm behavior. All information is front-loaded and every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, nested filter/changes/content_edits objects) and the absence of an output schema, the description covers the essential workflow and a key nuance (skipping non-matching finds). The schema handles parameter details comprehensively. It doesn't describe the preview response structure, but that's a minor gap; the description is sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so every parameter is already documented. The description adds workflow-level context (the two-step preview/confirm flow) that clarifies the confirm_token's role beyond the schema's brief 'Token from the preview', and explains the skip-on-non-match behavior for content_edits. This enriches understanding but doesn't redefine individual parameter meanings, making a 4 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Apply'), a clear resource ('many items'), and enumerates concrete change examples (status, reassign author, add category, find/replace). It explicitly distinguishes from single-item tools by emphasizing 'many items at once', making the tool's niche unambiguous even without naming siblings like update_content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the preview-first, confirm-token workflow, which is a critical usage guideline that dictates the calling sequence. It implicitly contrasts with single-item update tools by targeting bulk edits, but it doesn't explicitly name alternatives or state when NOT to use it. The guidance is clear enough for an agent to follow the correct two-step invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds the non-obvious behavior that WordPress rejects duplicate names, and suggests a pre-check. This is valuable context beyond the annotations. However, it doesn't mention potential permissions or side effects, but the duplicate rejection and pre-check are sufficient credit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no fluff. The first states the purpose, and the second delivers the critical caveat and alternative in a front-loaded manner. Every word earns its place, and the structure is optimal for quick parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters (all well-documented) and no output schema, the description covers the core behavior and the most important edge case (duplicate names). It doesn't specify the success return format, but for a create operation this is often implied. The description is complete enough for an agent to call it correctly under typical conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with every parameter richly described (e.g., parent specified as hierarchical-only, meta limited to show_in_rest keys). The description adds a note about the name parameter's duplicate risk and suggests a workaround, which supplements the schema. This goes beyond the baseline 3 for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action 'Create a term in any taxonomy' with a clear verb, resource, and scope. It distinguishes itself from sibling tools like list_terms, update_term, and delete_term by focusing on creation. The wording is unambiguous and leaves no doubt about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly warns about the duplicate rejection behavior and advises using list_terms first when duplication is a concern. This gives both a clear when-to-use context (create a new term) and a when-not-to/alternative (check with list_terms before). This is exactly the kind of guidance an agent needs to select this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotation destructiveHint=true, the description adds critical behavioral details: files are removed permanently, many plugins drop database tables on uninstall, and confirm: true is mandatory. This goes beyond the schema's 'required' array, which only lists plugin as required, so it clarifies an essential safety control. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no wasted words. The core action is front-loaded, and the two additional sentences pack the essential preconditions and consequences. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive delete operation, the description covers the necessary prerequisites (inactive plugin), the required flag (confirm), and the irreversible consequences (permanent file removal and potential database drops). Given the schema fully documents param formats and the high annotation coverage, nothing an agent needs to safely call this tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers all parameters with descriptions at 100% coverage, so the baseline is 3. The description adds significant value by explicitly stating that confirm must be true, which is not listed as required in the schema's required array. This is a crucial semantic clarification that prevents an agent from assuming confirm is optional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states exactly what the tool does: 'Delete an installed plugin from the server.' The verb 'delete' plus the explicit resource 'plugin' makes the purpose unmistakable. It also distinguishes itself from other delete tools by naming the resource type, so an agent can immediately identify the target.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: the plugin must be inactive first, and confirm must be true. This implies a prerequisite (deactivation) and a hard requirement, which helps the agent execute correctly. It does not explicitly cite alternatives like deactivate_plugin, but the instruction 'must be inactive first' effectively signals that deactivation is a separate action, leaving only a minor gap in explicit when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations (readOnlyHint=false, destructiveHint=true) by specifying the exact refusal behavior on live themes, the requirement for explicit allowance, and the consequence of deleting required templates. This enriches the agent's understanding of side effects without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundant content. The primary purpose is stated first, followed by critical safety warnings. Every sentence contributes information that an agent needs to use the tool correctly—no fluff, and the structure is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with 5 parameters, the description covers the key behavioral caveats: live-theme refusal, the confirm requirement, and the danger of deleting core templates. It does not mention return values, but since no output schema is provided and the tool's purpose is clear, this is acceptable. The description is sufficient for an agent to invoke the tool safely and correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds context for theconfirm and allow_live_theme parameters by explaining when they are needed (e.g., to override the live-theme refusal) and the risk of breaking required templates. This adds semantic value beyond the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Delete a file from a theme draft'), identifies the resource (theme file), and implicitly distinguishes from sibling tools like write_theme_file and edit_theme_file by focusing on deletion. It also adds essential context about not touching live themes, making the scope clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear guidance on when to use this tool (on theme drafts) and warns against using it on live active themes unless explicitly allowed. It also notes the risk of deleting required templates. While it doesn't name alternative sibling tools explicitly, the guidance about draft vs. live is sufficient for an agent to decide. The mention of 'visit a draft instead' is implicit in 'Refuses to touch a live active theme unless explicitly allowed.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral detail that credentials are never returned, which is security-relevant and beyond the annotations. It also clarifies this list returns all sites ('every'), aligning with openWorldHint but adding specifics about the returned fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the core action and output description, followed by a targeted usage hint and a security caveat. No wasted words, every sentence provides distinct value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, a read-only annotation, and no output schema, the description fully covers what the agent needs: what is returned (id, URL, auth method, writable), the intended usage (start here when site_id unknown), and a critical security note (credentials never returned). Nothing is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters and a fully covered (empty) schema, the description has no parameter semantics to add. The baseline for 0 parameters is 4, and the description appropriately focuses on output and usage rather than inventing unnecessary parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (List) and the resource (every WordPress site configured on this MCP server), and specifies the output fields (id, URL, auth method, writable). It differentiates from sibling tools like get_site by emphasizing 'every' and the 'when you don't know site_id' hint, making it unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Start here when you do not know which site_id to use.' This directly tells the agent when to pick this tool, implying that when a site_id is known, get_site is the alternative. Clear usage context with no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses critical behavioral traits beyond the annotations: that edits apply in order, that a non-matching edit 'fails loudly rather than silently writing nothing,' that the 'required' flag defaults to true, and that content/edits are mutually exclusive. It also explains the scope of meta writes. These details materially shape an agent's expectations and are not provided by 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured paragraph. Each sentence earns its place: the opening states the core action, then the two modes are contrasted, followed by a concrete recommendation and a failure-behavior note. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 22 parameters and no output schema, the description effectively covers the most crucial aspects—update mechanisms, ordering, failure handling, and cautionary notes. It does not describe the expected response object, but for an update tool the implicit return of updated content is conventional and the schema covers parameter details. A small gap remains around concurrency or explicit success indicators, but overall it is comprehensive for practical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents all 22 parameters with high coverage, so the baseline is 3. The description adds meaningful semantic guidance for the key parameters—especially 'content' vs 'edits' and their behavioral implications—plus the tip to read content first due to HTML comments. However, it does not add new meaning for all parameters, so a 4 reflects the value added beyond schema, not a perfect treatment of each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a precise verb and resource: 'Update any content type by ID.' It immediately distinguishes the two update modes (content vs edits) and clearly differentiates from siblings like create_content, delete_content, and bulk_update_content by specifying both modes. This is unambiguous and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit guidance on when to use 'edits' vs 'content', recommending 'edits' for small changes (heading, price, one paragraph) as safer on long pages, and implies 'content' for wholesale replacement. It also warns about slug changes breaking links and notes the fallback for unregistered meta keys. This is clear, practical routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations by disclosing that WordPress has no trash for users, making deletion permanent and irreversible, requiring confirm: true, and explaining the content handling options (reassign vs delete). This adds significant behavioral context about consequences and prerequisites, enriching the annotation hints (destructiveHint=true) without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise—two sentences that directly state the purpose, permanence, confirm requirement, and content handling, with the most critical behavioral note front-loaded. There is no redundant information or fluff; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation with complex content handling, the description covers all essential aspects: irreversibility, confirm requirement, content reassignment vs deletion, and how site selection works. The absence of an output schema is acceptable as the description focuses on the action and its consequences, which is sufficient for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While the schema has 100% coverage, the description adds meaningful semantic context: confirm is emphasized as 'Required — user deletion cannot be undone' and reassign_to is clarified as 'User ID to inherit this user's posts' with guidance on omitting it only if content should be deleted. The site_id behavior is also explained, providing value beyond the bare schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Delete a user' and immediately clarifies the permanent nature and the confirm requirement, distinguishing it from user creation/updating. It explicitly states the resource (user) and the action (delete), making it unmistakable and clearly differentiated from siblings like update_user and create_user.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (when deleting a user is required) and what must be done: require confirm: true, and choose whether to reassign content or delete it. It also provides guidance on the site_id parameter (optional, default site behavior) and the need to run list_sites for valid ids, offering clear context for appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals critical behavioral details beyond the annotations: row limits are enforced, mutations are blocked by default, a preview and confirm_token are required, stacked statements are refused, and bypassing WordPress hooks means caches are not invalidated. This goes far beyond the sparse annotation hints and gives the agent a complete behavioral picture.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet information-dense, front-loading the purpose, then the safety mechanism, and finally the usage caveat. Every sentence adds necessary information with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with mutation safety and multiple parameters, the description covers all essential aspects: what it does, when to use it, safety gating, the two-step confirmation flow, and the consequences of using raw SQL. The agent has everything needed to call it correctly, even without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters have schema descriptions (100% coverage), so the baseline is 3. The description adds value by explaining the dependency between allow_mutation and confirm_token (preview flow) and noting that max_rows triggers an automatic LIMIT. This clarifies interactions not obvious from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs a SQL query against the WordPress database, specifies the immediate execution of read-type statements, and explicitly distinguishes it from the REST API and WP-CLI by stating it should be used only when those cannot access the data. This provides a precise verb+resource and sets it apart from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance: use this tool only when the REST API and WP-CLI are insufficient. It also explains the mutation safety flow, noting that mutations require allow_mutation and a confirm_token, which tells the agent when and how to use the tool safely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![wpxmcp MCP server](https://glama.ai/mcp/servers/alokemajumder/wpxmcp/badges/card.svg)](https://glama.ai/mcp/servers/alokemajumder/wpxmcp)

Score Badge

Copy to your README.md:

[![wpxmcp MCP server](https://glama.ai/mcp/servers/alokemajumder/wpxmcp/badges/score.svg)](https://glama.ai/mcp/servers/alokemajumder/wpxmcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/alokemajumder/wpxmcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server