ars-nova-wordpress-mcp

Official

by ArsNovaSingers

Overview Schema Related Servers Score Discussions

TypeScript

Local

Server Quality Checklist

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

Latest release: v0.2.0
Disambiguation3/5
Several tools have overlapping boundaries (e.g., wp_get_site_info vs wp_get_settings, wp_get_sidebars vs wp_get_widgets, tickera_list_ticket_types vs wc_list_products, wp_search_content vs wp_list_posts with search). Descriptions help clarify but ambiguity remains in selection.
Naming Consistency4/5
Naming largely follows a consistent verb_noun pattern with clear prefixes (wp_, wc_, tickera_). Minor outliers like wp_ops_status, tickera_status, and ans_rest_call break the pattern slightly but are still recognizable.
Tool Count1/5
With 89 tools, this server far exceeds reasonable scope. Even for a comprehensive WordPress/WooCommerce/Tickera management server, the sheer number overwhelms agents and creates excessive selection overhead.
Completeness2/5
Significant gaps exist: no delete for categories/tags, no update/delete for redirects or widgets, no theme activation/deletion, and WooCommerce orders are list-only. These missing lifecycle operations will cause agent failures in common workflows.
Average 4.3/5 across 89 of 89 tools scored. Lowest: 3.7/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 2 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
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

Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the behavioral trait 'Only the fields you pass are changed', which goes beyond the annotations. This clarifies that it performs a partial update, which is important for an idempotent mutation tool. With annotations covering the safety profile (not read-only, not destructive, idempotent), the description provides meaningful additional context about how the update behaves.
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 focused sentence that states the core purpose and key behavior. Every word is meaningful, and it is appropriately front-loaded with the action and resource. There is no redundancy or unnecessary detail.
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?
Given the tool has 11 parameters, no output schema, and no explanations of return values or error behavior, the description is sparse. It covers the primary purpose and partial-update semantics but omits details about what the response looks like, permission requirements, or how missing/invalid fields are handled. The description is insufficient for an agent to fully understand the tool's behavior without additional inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low at 36%, and the description does not compensate by explaining the individual fields. It only mentions the general concept of 'fields you pass', but does not list or describe any of the updatable parameters. This leaves several params (e.g., sku, virtual, stock_quantity) without any semantic explanation beyond their types.
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 'Update' and the resource 'existing WooCommerce product by ID', which distinguishes it from create/list tools. The phrase 'by ID' specifies the scope, and mentioning 'existing product' differentiates it from wc_create_product. This is specific 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 implies the tool is for modifying an existing product, but it does not explicitly state when to use it over alternatives or when not to use it. For example, there is no mention that wc_create_product should be used for new products. The context is clear but lacks explicit exclusions or alternative guidance.
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 readOnlyHint annotation already indicates a safe read operation. The description adds a useful detail about including ticket-type products, but it does not disclose other behavioral aspects such as response format specifics, pagination, or error handling. This is consistent with the high-score calibration example where annotations cover safety and the description adds modest 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 a single, clear sentence that conveys the essential purpose and key additional detail (ticket-type products) without any filler or 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 simple read-only operation with only two parameters (one required) and no nested objects, the description is mostly complete. It mentions the inclusion of ticket-type products, but could further clarify the return value format. Since there is no output schema, a slightly more explicit return description would have made it fully 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 schema descriptions cover 100% of the parameters, including the event_id as a tc_events post ID and the response_format enum. The description does not add additional parameter semantics beyond what the schema already provides, so it matches the baseline 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 clearly states the verb 'Get', the specific resource ('one Tickera event by ID'), and additional scope ('including its ticket-type products'). It distinguishes from sibling tools like tickera_list_events (which lists events) and tickera_create_event (which creates events).
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 context is implied: this tool is for fetching a single event by its ID, while tickera_list_events is for retrieving multiple events. However, there is no explicit when-to-use or when-not-to-use guidance, nor any mention of alternatives, so the guidance relies on the purpose statement.
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?
The readOnlyHint annotation already covers safety, and the description adds no additional behavioral context beyond the title. There is no mention of pagination, default tax class inclusion, or output details; the description merely restates the title, providing minimal value 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 a single concise sentence that is easy to scan and front-loaded with the action ('List') and resource ('tax classes'). No unnecessary information is present.
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 one optional parameter and no output schema, the description is mostly sufficient. However, it could have added a bit more context about what tax classes are included (e.g., standard vs custom) to reduce ambiguity, so a 4 rather than a 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?
The only parameter, response_format, is fully described in the schema with an enum and a default value, achieving 100% schema description coverage. Therefore, the baseline of 3 applies even though the description does not mention the 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 uses the specific verb 'List' with a clear resource 'available tax classes,' which clearly distinguishes it from sibling tools like wc_list_products and wc_list_orders. It is concise 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the tool for tax classes, providing enough context for selection. However, it does not explicitly state when to use this tool over alternatives or mention any exclusions, so it stops short of full 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?
The description adds meaningful behavior beyond the annotations: it explains the default behavior (trash) and the force option (permanent deletion). It also points to the return shape via 'see wp_delete_post for shape'. This enriches the safety profile already indicated by destructiveHint=true and readOnlyHint=false, giving the agent operational detail.
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 tightly structured with a one-sentence summary, a labeled Args list, and a Returns line. It is concise, avoids redundancy, and every sentence 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 deletion tool with a moderate complexity (3 parameters, 1 required), the description covers the critical aspects: what it deletes, how to control trash vs permanent, and where to find the return shape. It does not provide a detailed return format, but the reference to wp_delete_post and the presence of an output schema for that sibling reduces the need. Minor gaps include error handling and idempotency, but these are not essential.
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 descriptions that match the description text exactly. The description adds no new meaning beyond the schema—it essentially repeats the schema's parameter descriptions, 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.
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 a page') and the target resource ('a page'). It differentiates from sibling tools like wp_delete_post by naming 'page' specifically, though it does not explicitly contrast itself against alternative deletion tools.
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 tool when you need to delete a page. It does not provide explicit guidance on when to choose this over alternatives like wp_delete_post, nor does it mention any preconditions or exclusions. The mention of 'see wp_delete_post for shape' hints at a relationship but doesn't clarify selection criteria.
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?
Beyond annotations, the description adds an authorization requirement ('Requires admin') and return value ('Returns the new menu ID'). However, it does not disclose potential side effects of theme location assignment, such as overriding existing location assignments, which could be relevant given openWorldHint=true.
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 opening sentence is concise and front-loaded with the core behavior. The Args list is somewhat redundant with the schema, adding minor waste, but overall the description remains brief 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?
For a simple creation tool, the description covers the purpose, parameters, return value, and auth requirement. The lack of output schema is compensated by the explicit return ID. However, the undisclosed side effects of location assignment leave a minor gap in 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 input schema already provides descriptions and examples for all three parameters, so the Args section in the description adds no new meaning. It merely repeats the schema information, thus offering marginal 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 clearly states it creates an empty navigation menu and optionally assigns theme locations, distinguishing it from related tools like wp_update_menu and wp_create_menu_item. The verb 'Create' and resource 'navigation menu' are specific, and the scope ('empty') adds clarity.
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 use for initial menu creation, but it does not explicitly mention alternative tools or exclusions. Sibling tools like wp_create_menu_item or wp_update_menu are not referenced, so the guidance relies on implicit 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 already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds useful behavioral context beyond annotations, notably that 'tags do not have hierarchy on most sites; this is usually ignored' for the parent parameter, and that results include post counts. This helps the agent set expectations.
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 well-structured with a clear one-line purpose, a compact Args list, and a Returns line. It is somewhat redundant with the input schema (all 8 parameters are repeated), but it remains easy to scan and lacks 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?
Given 8 parameters and no output schema, the description covers all parameters and states the return type as 'Paginated envelope of WPTermItem objects.' It could explain the response fields or pagination details further, but the combination of schema, annotations, and parameter caveats makes the tool reasonably 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.
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 meaning beyond the schema with the parent parameter caveat ('usually ignored'), which is not present in the schema. It also documents defaults and enums concisely, reinforcing schema semantics without replacing 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 begins with 'List post tags with post counts,' which uses a specific verb and resource, clearly distinguishing it from related tools like wp_list_posts or wp_list_categories. The purpose is unambiguous and directly tied to the tool name.
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. It does not mention conditions like 'use wp_list_categories for categories' or any exclusions, leaving the agent to infer usage solely from the tool name.
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 provide idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds value by disclosing the 'Requires admin' permission and specifically noting that locations 'replaces existing' assignments—important behavioral detail not fully captured 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loads the core purpose in one sentence. The Args block is efficient, but it partially duplicates the schema and could be trimmed. Still, every sentence earns its place, including the admin requirement.
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 4-parameter tool with no output schema, the description covers the purpose, parameters, permission requirement, and the replacement behavior of locations. It lacks explicit side effects beyond the parameters, but given the idempotent and non-destructive hints, this is acceptable.
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 schema already documents each parameter. The description repeats the parameter list but adds the nuance that 'name' and 'locations' are optional and clarifies that locations replaces existing assignments, which is useful but not a major addition 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 tool's function: 'Rename a menu and/or change its theme-location assignments.' It uses a specific verb and resource, and distinguishes from sibling tools like wp_update_menu_item (menu items) and wp_create_menu/delete_menu.
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 rename a menu or change locations) but does not explicitly contrast it with alternatives or edge cases. It mentions 'Requires admin' as a prerequisite, but lacks direct '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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the destructive and non-read-only nature. The description adds implementation detail ('Writes via WP REST's meta sub-object using Yoast's underlying postmeta keys') and a verification note. However, it does not clarify whether omitted fields are left unchanged or reset, leaving ambiguity about partial updates.
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 well-structured with sections for Args, Returns, and Note, but the Args section duplicates the schema. It could be more concise without losing key information. Still, it is organized 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?
For a complex tool with 12 parameters, the description covers return value, verification steps, and Yoast-specific limitations. However, the gap regarding partial vs. full update behavior prevents a perfect score, as agents may incorrectly assume that all fields are overwritten when only some are provided.
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 parameter semantics are already fully documented. The description's Args section mostly restates the schema without adding new meaning. The only marginal addition is the 'undefined = leave Yoast's default' clarification for noindex, which is already present in 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's function: updating Yoast SEO meta on a post or page, with a specific list of fields (title, description, canonical, noindex, focus keyword, OG, Twitter). It distinguishes itself from siblings by explicitly mentioning Yoast and noting that RankMath/AIOSEO are not supported.
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 a clear exclusion ('This is for Yoast specifically. RankMath / AIOSEO sites need different keys') and suggests verifying with wp_get_seo_meta. It does not explicitly mention when to use this tool over wp_update_post or wp_set_page_meta, but the Yoast-specific context implies a clear use case.
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 destructive and idempotent behavior. The description adds specific context by noting that roles replace existing roles and referencing demotion, which clarifies the destructive nature. 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 well-structured with a clear purpose, an Args list, and a Returns line. It is concise and front-loaded, though the Args list duplicates schema content; still every section serves a 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 tool with 10 parameters and no output schema, the description conveys the key use, the destructive role replacement behavior, and the return value. It is reasonably complete given the annotations and schema, though it omits explicit alternatives and edge cases.
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 fully. The description's Args section largely repeats schema info, though it adds examples for roles and emphasizes required id. This is marginal added value 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 tool updates an existing user's name, email, roles, or profile fields, with a specific verb and resource. It also distinguishes from siblings like wp_delete_user or wp_get_user by listing the updatable fields and giving a common use case (demoting an admin).
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 common use case (demoting an admin) but does not explicitly mention when to avoid this tool or alternatives such as wp_bulk_update_users for batch updates. Usage guidance is implied rather than stated with exclusions.
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?
With readOnlyHint=true, the safety profile is already clear. The description adds value by stating what fields are returned and that all events are listed, which gives a sense of scope beyond the annotation. However, it does not mention potential pagination or result limits, so not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that communicates the core purpose and key fields without any fluff 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?
For a simple list tool with no output schema, the description covers the essential return information. It could mention pagination or filtering constraints, but 'all events' conveys scope sufficiently for most use cases.
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% for the single response_format parameter, which includes a clear enum and description. The tool description does not need to repeat this, and it correctly focuses on the tool's purpose.
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 all Tickera events (tc_events)' and specifies the resource and included fields (date, location, status, linked ticket-type products). This distinguishes it from siblings like tickera_get_event (single event) and tickera_create_event (creation).
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 as a list-all operation, but it does not explicitly mention when to prefer this over tickera_get_event or tickera_list_ticket_types. No exclusions or alternative tool names are provided, leaving the decision somewhat 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 mark this as a mutating, non-idempotent operation. The description adds one useful behavioral fact (Tickera bridge mapping availability) and a claim that it 'supports simple products with price, description, categories, and images.' However, the latter is vague and could imply that only simple products are supported, which contradicts the schema's enum of product types. There is no mention of auth requirements, error behavior, or result contents.
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 and immediately front-loads the core purpose. The first sentence is direct, the second provides a specific use-case. The final sentence about 'simple products' is somewhat redundant with the schema but not wordy. Overall it is compact and scannable, though the last sentence could be trimmed.
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 14 parameters and no output schema, the description should explain return behavior or at least confirm what happens on success—it does neither. It does provide key context about Tickera mapping and product capabilities, but the missing result information and ambiguity about non-simple product types leave the tool only partially contextualized. The schema fills many gaps, but the description alone is not fully 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 coverage is 100% (all 14 parameters have descriptions), so the baseline is 3. The description adds extra meaning to the 'type' parameter with the Tickera guidance and groups key parameters (price, description, categories, images), which helps the agent understand typical usage. This lifts it above 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 opens with a clear, specific verb and resource: 'Create a new WooCommerce product.' This directly distinguishes it from siblings like wc_update_product and wc_list_products by the action 'create'. It also adds a domain-specific note about Tickera ticket products, which further clarifies its role.
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 guideline: 'For Tickera ticket products, set type='simple' and the product will be available for Tickera bridge mapping.' This tells the agent when and how to use the tool for a specific scenario. It doesn't explicitly exclude alternatives (e.g., 'use wc_update_product for existing products'), but the word 'create' implies the distinction well 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 declare readOnlyHint=true, and the description adds valuable context by specifying the returned fields (order ID, status, total, customer info, line items). This goes beyond the annotation and helps the agent anticipate the output structure without contradicting the read-only hint.
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 includes the most important return details. Every sentence earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description appropriately lists the key return fields. Pagination and format defaults are covered by the input schema, so not repeating them is acceptable. It is sufficiently complete for a straightforward list 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 50%, with status and response_format described. The description reinforces the status filter and implies the response format, but does not explain page or per_page semantics. It adds partial value but does not fully compensate for the undocumented 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 a specific action ('List WooCommerce orders') with a distinct resource that differentiates it from sibling tools like wc_list_products or wp_list_posts. The optional status filter is mentioned, adding precision 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 implies usage by listing orders and mentioning an optional status filter, but it does not explicitly state when to prefer this tool over alternatives or provide exclusions. Context is clear, yet no direct guidance is given for choosing this among related 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?
The description enriches the annotations by explicitly stating 'Defaults to status="draft" for safety' and explaining that 'set status="publish" to publish immediately.' It also discloses slug auto-generation and scheduling behavior. These are meaningful behavioral traits beyond the basic write indication from readOnlyHint=false and destructiveHint=false. The return format is also stated, adding further transparency.
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 clearly structured with 'Args' and 'Returns' sections, front-loading the core purpose and safety default. It is somewhat lengthy and partially duplicates the schema, but every sentence adds contextual value for an agent, and the formatting aids quick scanning.
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 11 parameters, no output schema, and minimal annotations, the description is remarkably complete. It covers all parameters, defaults, scheduling, return value (WPContentItem with id, slug, status, link, etc.), and safety defaults. This provides an agent with everything needed to invoke 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?
With 100% schema description coverage, the schema already fully documents all parameters. The description repeats the args but adds no new meaning beyond the schema (e.g., slug auto-generation is already in the schema). It meets the baseline but does not elevate 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 opens with 'Create a new blog post' – a specific verb+resource statement that clearly distinguishes from siblings like wp_create_page, wp_update_post, and wp_delete_post. It reinforces the scope with detailed parameter guidance and a return value description, leaving 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers clear context on how to use the tool (e.g., defaults to draft for safety, set status='publish' to publish, set status='future' for scheduling), but it does not explicitly mention when to use this tool over alternatives like wp_create_page or wp_update_post. No when-not or alternative guidance is provided, so it falls short of 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?
Annotations indicate a non-read-only, non-destructive, non-idempotent action. The description adds some behavioral context (slug auto-generation, response_format selection) but does not disclose potential side effects, error handling, or duplicate tag handling. With annotations present, the description provides adequate but not rich behavioral detail.
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 well-structured: a one-line purpose, a clean Args list, and a Returns section. Every sentence is functional and there is no 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?
For a simple create operation with full schema and annotations, the description is largely complete. It explains all parameters and the return type. However, it lacks guidance on edge cases or alternative usage scenarios, and does not elaborate on the WPTermItem structure, but that is not critical for such a straightforward 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 coverage is 100%, so the baseline is 3. The description repeats parameter information already in the schema without adding significant new semantics, though it does clarify that 'name' is required and slug defaults to name if omitted.
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 'Create a new post tag' with a specific verb and resource, clearly distinguishing from sibling tools like wp_update_tag and wp_create_category. It is unambiguous and directly reflects the tool name and title.
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: use when creating a new post tag. It provides context about the action, but does not explicitly compare with alternatives (e.g., wp_update_tag for modifying existing tags). The purpose is clear enough that a user can infer 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?
The annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description does not need to restate these. It adds value by disclosing the response format control (markdown vs json) and listing the metadata fields (dimensions, file size, MIME type, alt text, caption, source URL), which provides concrete behavioral insight beyond annotation hints.
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 compact and well-structured: a single-purpose first sentence, followed by clearly labeled Args and Returns sections. Every line is informative, with no filler. The front-loaded main clause ensures immediate comprehension.
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 get-by-id tool with no output schema, the description sufficiently explains the return value (a WPMediaItem with specific fields). It does not cover error cases like non-existent IDs, but the tool is low-complexity and the annotations plus parameter descriptions fill most gaps. Slight lack of edge-case context keeps it from a 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%, so the baseline is 3. The description's 'Args' section repeats what the schema already documents (id as number, response_format as enum with default). It does not introduce additional meaning or clarify syntax beyond the schema, so no bonus is earned.
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 'Fetch a single media item by ID', which is a specific verb+resource pairing that clearly distinguishes it from sibling tools like wp_list_media (listing all media) and wp_upload_media (creating/uploading). It also enumerates the exact metadata returned, 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 implies usage (when you need a specific media item's metadata), but it does not explicitly contrast with alternatives or state when not to use it. No mention of wp_list_media for queries or wp_get_post for non-media content. The 'by ID' phrasing gives context but lacks explicit usage boundaries.
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?
Beyond the annotations (readOnlyHint, idempotentHint), the description adds valuable behavioral details: it requires the activate_plugins capability, returns 403 otherwise, and clarifies that active plugins are flagged with status='active'. This goes beyond the baseline.
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 well-organized with sections for purpose, auth note, args, and returns. It is thorough without being overly verbose, though the return shape listing could be considered slightly detailed for such a simple tool.
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 the lack of an output schema, the description compensates by specifying the exact return object shape. It also covers auth requirements, parameter defaults, and error behavior (403), making it highly complete for a list tool of this 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 already fully describes all three parameters with types, enums, defaults, and descriptions. The description essentially repeats the schema, adding no new semantic meaning, 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 tool lists installed plugins with version, status, and metadata, using a specific verb and resource. It also distinguishes from sibling write/update tools by emphasizing the read-only nature and the status flag.
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 some usage context via the admin capability requirement and default response format, but it does not explicitly state when to use this tool versus alternatives like wp_get_* or wp_update_plugin. The guidance is mostly 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=false, idempotentHint=true, and destructiveHint=false, covering mutation and safety behavior. The description adds operational detail about the plugin basename format, but it does not disclose potential side effects such as plugin activation/deactivation hooks. 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 long, front-loaded with the primary action, and includes a concrete example. Every sentence earns its place with no 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's simplicity, the schema's thorough parameter descriptions, and the annotations covering safety, the description is complete enough. It provides the critical plugin basename mapping and references the source. It could optionally mention that the plugin must be installed, but this is already implied.
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 three parameters with descriptions, so the baseline is 3. The description adds a cross-reference to wp_list_plugins for the plugin basename, which is useful but does not significantly enhance parameter understanding 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 ('activate or deactivate') on a specific resource ('an installed plugin') using a specific verb and object. It is distinct from sibling tools like wp_update_plugin or wp_delete_plugin, which handle other plugin operations.
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—when you need to toggle a plugin's active status. It also gives a valuable cross-reference to wp_list_plugins for obtaining the correct plugin basename. However, it does not explicitly mention when not to use it (e.g., for installation or updates).
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 readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the agent knows it's a potentially destructive but idempotent write. The description adds the scope of updatable fields and notes the return type, but does not disclose edge cases like parent self-reference or consequences for child categories. This is acceptable given annotation coverage, but not rich 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 compact and well-structured: a one-sentence purpose, a clear 'Args' list, and a 'Returns' line. Every element serves a purpose, with no redundant fluff or excessive 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 has 6 parameters, no output schema, and clear annotations, the description adequately covers essential context: what can be updated, required id, optional fields, output format options, and the return type. It does not go into error scenarios or edge cases, but for an update tool of this scope, 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 has 100% description coverage, meaning each parameter is already well-documented in the schema. The description's 'Args' section repeats schema info (types, optionality, response_format default) without adding new meaning. Baseline 3 is appropriate because 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 explicitly states 'Update an existing category's name, slug, description, or parent,' which clearly identifies the action (update) and the resource (category), and lists the specific mutable fields. This distinguishes it from sibling tools like wp_create_category or wp_update_tag.
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 use for existing categories by saying 'existing category,' which provides context for when to use it (updating, not creating). However, it does not explicitly name alternatives or state when-not-to-use, so it lacks full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, and the description's "List" aligns with that. The description adds little beyond the annotations, only restating the optional event_id filter that is also in the schema. No contradictions, but no additional behavior (e.g., pagination, limits) is 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?
The description is a single, front-loaded sentence that communicates the core purpose without any unnecessary words. It earns its place and no more.
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 and a read-only annotation, the description is complete. The schema covers all parameters, and no output schema is needed. The description adequately explains what the tool does and the optional filter, making it self-sufficient in the given 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%, and both parameters (event_id, response_format) are fully documented in the schema. The description adds no extra meaning beyond what the schema already 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 uses a specific verb ("List") and resource ("ticket-type products"), clearly distinguishing it from sibling tools such as tickera_create_ticket_type (create) and tickera_list_events (list events). It also notes an optional event_id filter, adding precision.
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: this tool lists ticket types, optionally filtered by event. It implies use when you need ticket-type products and not events, but it does not explicitly mention alternatives or exclusions. However, the context is sufficient for straightforward selection.
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 readOnlyHint annotation already establishes this as a safe read operation. The description adds the content scope (what data is included) but doesn't disclose additional behavioral traits like response format details, potential sensitive data, or permissions beyond what is implied.
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 wasted words. The first sentence front-loads the purpose and contents, the second gives usage guidance. Every clause contributes 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?
For a simple read-only status tool with one optional parameter and no output schema, the description fully captures what the tool does and why to use it. It lists all relevant data categories, making the behavior clear enough without needing to explain return values.
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 the single parameter response_format fully described in the schema. The tool description adds no additional parameter 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?
The description uses a specific verb+resource ('Get WooCommerce system status') and enumerates the included categories (environment info, database, active plugins, theme, settings, pages). This clearly differentiates it from siblings like wc_get_settings or wp_get_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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'Use for health checks,' providing clear context for when to invoke the tool. However, it doesn't mention alternatives or exclusions, such as wc_get_settings for settings-only needs.
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 is consistent with the readOnlyHint annotation and adds useful behavioral detail by specifying the exact return fields (product ID, name, type, status, price, SKU, stock info). This goes beyond the annotation, which only indicates read-only, by informing the agent what to expect in the response. 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?
The description is two short sentences, front-loaded with the main action and immediately followed by the return value list. Every word earns its place; no fluff or redundancy.
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 rich schema and readOnlyHint annotation, the description is complete. It states what the tool does, what filters are available, and what it returns. No output schema exists, but the return fields are explicitly listed, filling that gap. The tool is straightforward and has no complex side effects or prerequisites.
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 already described in the input schema. The description only generalizes them as 'optional filters' without adding syntax, format, or additional meaning beyond the schema. Baseline 3 is appropriate since 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 uses a specific verb and resource: 'List WooCommerce products'. This clearly distinguishes it from sibling tools like wc_list_orders or wp_list_posts, and the mention of 'optional filters' further defines its scope. The purpose is 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states that filters are optional but provides no explicit guidance on when to use this tool versus alternatives such as wc_get_system_status or wc_list_payment_gateways. It implies usage for product listing but lacks context or exclusions. This is adequate but not explicitly helpful for tool selection.
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 idempotentHint=true and destructiveHint=false. The description adds value by providing example value types (e.g., 'yes/no' for woocommerce_calc_taxes) and common setting groups, but does not disclose additional behavior 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 opens with the core instruction and a quick example, then provides a well-organized list of common settings. It is longer than minimal, but the list is practical and 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 update tool with only 3 required parameters and a response_format enum, the description covers the essential usage context and common inputs. It does not explain return values, but no output schema exists and the tool's behavior is straightforward.
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 baseline is 3. The description goes further by listing concrete setting IDs grouped by category, giving the agent real values to use for 'setting_id' and 'group' beyond the schema examples.
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 ('Update'), specific resource ('single WooCommerce setting'), and distinct scope ('by group and setting ID'). The example and common settings list differentiate it from siblings like wc_get_settings and wc_update_product.
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?
Implied usage is clear: this is for updating WooCommerce settings, not reading them (wc_get_settings) or updating products. However, it does not explicitly state when not to use it or name 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 the critical dry_run=true default and lists required/optional CSV columns, adding behavioral context beyond the annotations. It does not contradict the annotations, which already indicate a non-read-only operation.
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 with the core purpose. The first paragraph states what the tool does and the column requirements; the second gives a clear use case. No redundant or filler content.
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 description covers the essential input format and dry-run behavior, making the tool usable. However, because there is no output schema, it should clarify what the tool returns (e.g., created post IDs or a summary) and error handling, which are missing. This is a notable gap for a bulk write 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?
The schema already provides descriptions for csv_path and response_format (50% coverage). The description echoes the CSV column information and adds the dry_run default, but it does not explain stop_on_error beyond the parameter name. It adds modest value 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 opens with 'Create many posts from a CSV,' which precisely states the action, resource, and input method. It distinguishes this bulk operation from single-post tools like wp_create_post and the use case adds further clarity.
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 a clear use case ('import a content calendar') and notes the dry_run default, which guides safe usage. However, it does not explicitly contrast with alternatives (e.g., wp_create_post) or state exclusions, 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 indicate readOnlyHint=false, destructiveHint=false, so the safety profile is covered. The description adds value by disclosing that a new resource is created and that the created WPTermItem is returned, along with the auto-generation behavior for slug. 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 concise and well-structured with a one-sentence purpose followed by a clean Args list and a Returns statement. Every element contributes information, with no redundant or verbose phrasing.
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 the tool's moderate complexity (5 parameters), full schema coverage, and annotations, the description is sufficient. It states the action, lists all parameters, and explains the return type. No output schema exists, but the Returns line covers that 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 schema describes all 5 parameters with 100% coverage, and the description's Args list largely duplicates the schema's descriptions. It adds no meaningful new meaning beyond the schema, such as example values or format 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 states 'Create a new post category' with a clear verb and resource, distinguishing it from siblings like wp_update_category (update) and wp_list_categories (list). The resource type is specific ('post category'), eliminating 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 verb 'create' implies use for new categories, but the description does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. No alternative tools are named, so guidance is only implied, not provided.
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 mutating, non-destructive operation. The description adds the key safety behavior that it 'Defaults to status='draft'', and explicitly mentions the response_format option. It also notes the return type as WPContentItem, giving some behavioral insight 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 concise and well-structured, starting with the purpose, then a bulleted arg list, and a Returns line. There is no redundant fluff; the reference to wp_create_post avoids repeating full parameter definitions.
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 no output schema, the description only states 'Returns: The created WPContentItem,' which lacks detail about the returned object's fields. Also, it doesn't address potential errors, permissions, or edge cases like invalid parent IDs. It's adequate for a simple create operation but has clear gaps.
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 groups shared params under 'same as wp_create_post' and explicitly explains parent and menu_order, but this largely duplicates schema information. It adds marginal value via the sibling reference, but not enough to exceed 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 'Create a new static page,' specifying a verb and resource. It distinguishes from siblings like wp_create_post (which handles other post types) and wp_update_page/wp_delete_page. The default status='draft' adds clarity.
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 context that this tool creates static pages, and the args reference wp_create_post for shared semantics. However, it doesn't explicitly state when to prefer this over wp_create_post or other alternatives, though the page-specific purpose is 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 indicate a mutation (readOnlyHint=false) and non-destructive behavior. The description adds useful context beyond annotations: it requires the Redirection plugin to be active, requires admin rights, and mentions the SEO effect ('search authority transfers'). 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 well structured: a concise one-sentence purpose, usage guidance, prerequisites, and a clear Args list. It is slightly long due to the full parameter enumeration, but the readability is high and each section 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 7 parameters, no output schema, and annotations that don't cover all behavioral aspects, the description covers the use case, prerequisites, parameter semantics, and return value ('Returns: the created redirect'). It doesn't describe error scenarios or duplicate handling, but for a creation tool this is reasonably 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 the baseline is 3. The text's Args list largely restates the schema descriptions (e.g., source, target, code defaults), adding only minor value such as example paths and the semantic note about SEO authority. It does not meaningfully augment the schema's parameter explanations.
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 'Create a 301 (or 302/307/308) redirect in the Redirection plugin,' a specific verb and resource that clearly states the tool's action. It distinguishes itself from the sibling wp_list_redirects by emphasizing creation, and the title 'Create a Redirect' 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?
Explicitly states when to use: 'Use after any slug change or page re-parenting so the old URL keeps working and search authority transfers.' It also lists prerequisites ('Requires the Redirection plugin to be active and admin rights'), but does not mention explicit alternatives or when not to use, which keeps it from 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, idempotentHint, and destructiveHint, reducing the burden. The description adds meaningful behavior beyond annotations: it discloses that the content is 'rendered to plain text — HTML stripped' and that the return expands content_preview, which gives the agent additional expectations about the operation's side effects and output format.
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 well-structured with clear sections ('Args' and 'Returns') and front-loads the core purpose in the first sentence. While it repeats some schema parameter details, it avoids fluff and each section earns its place, keeping the overall size reasonable 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 single-page fetch tool with no output schema, the description adequately explains the return type (WPContentItem) and the expansion of content_preview, and covers the response_format options. It lacks information about error cases or prerequisites, but the combination of annotations, full schema coverage, and description is sufficient for 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?
The schema provides complete descriptions for all three parameters (100% coverage), so the baseline is 3. The description enhances semantics by explicitly stating that 'id' and 'slug' are mutually exclusive and that at least one must be provided, which clarifies the relationship beyond the schema's 'Either id OR slug is required'.
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 'Fetch a single page by ID or slug', using a specific verb and resource that clearly identifies the tool's action. It distinguishes itself from siblings like wp_get_post (which targets posts) and wp_list_pages (which lists multiple pages) by emphasizing 'single page' and 'by ID or slug'.
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 some context by stating 'Fetch a single page by ID or slug' and requiring at least one of id or slug, which implies when to use it. However, it does not explicitly name alternative tools or state exclusions, such as when to use wp_get_post or wp_list_pages instead, leaving the guidance 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful context beyond that, such as returning a paginated envelope of WPTermItem objects with a specific shape, and confirms the response includes hierarchy and post counts. 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?
The description is well-organized with an Args section and Returns section. Every sentence adds value, and it's appropriately sized for 8 parameters. It leads with a clear one-sentence summary, making it easy to parse.
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?
Despite having no output schema, the description explicitly documents the return envelope and item shape. It covers all parameters, defaults, and edge cases like using parent=0 for top-level. This is complete for a read-only list 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 coverage is 100% and each parameter already has a meaningful description. The description repeats these details in a clear format, adding minimal new information beyond what's in the schema, so it meets the baseline 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 it lists post categories with hierarchy and post counts, using a specific verb and resource. It distinguishes itself from sibling tools like wp_list_tags and wp_list_posts by explicitly saying 'post categories' and mentioning hierarchy.
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 through its clear explanation of what the tool does and its parameters, but it doesn't explicitly state when to use it versus alternatives like wp_list_tags or wp_list_posts. No exclusions or alternatives are mentioned.
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, idempotentHint, and non-destructive behavior. The description adds meaningful context beyond annotations by disclosing the response_format options (markdown/json), pagination defaults, and the exact object shape returned (id, date, slug, title, etc.). This gives the agent a clear picture of behavior without needing to guess.
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 well-structured with a clear one-line purpose followed by a bulleted Args list and a Returns section. It is efficient and front-loaded. However, it duplicates much of what the schema already states, making it slightly redundant for a description, though not verbose.
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 8-parameter, read-only tool with no output schema, the description is quite complete: it enumerates all filters, pagination controls, output formats, and the full return object shape. It also clarifies edge cases like parent=0 for unattached media. This compensates for the lack of an output schema, though it doesn't address error cases or rate limits.
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's 'Args' section largely restates the schema parameters (e.g., 'limit' page size 1-100 default 20, 'parent' 0 for unattached). While it adds a note about response_format output readability, this is also present in the schema. The description does not materially add meaning 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 opens with 'List items in the WP media library with filtering and pagination', which clearly states the verb (list), resource (WP media library), and capabilities (filtering and pagination). It distinguishes this from sibling tools like wp_list_posts and wp_list_pages by specifying 'media library'.
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 communicates that this is for listing media items with filtering/pagination, which implies appropriate use cases. However, it does not explicitly exclude alternatives or name when to prefer this over wp_get_media_item or other media queries. The context is clear, but no explicit when-not-to-use guidance is given.
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, idempotentHint=true, and destructiveHint=false. The description adds useful context beyond annotations: the plugin prerequisite, admin rights requirement, and the return structure ({ count, total, items }). 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?
The description is compact and well-structured: a brief intro, an Args list, and a Returns section. Every sentence provides necessary information with no 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?
Given no output schema, the description fully compensates by specifying the return structure. It also covers prerequisites, parameter usage, and pagination context, making it complete for a read-only listing 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 coverage is 100%, with each parameter already having a description. The description repeats parameter details without adding new meaning, 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?
States 'List the 301/302 redirects managed by the Redirection plugin' with a specific verb (List) and resource (redirects), clearly distinguishing it from sibling tools like wp_create_redirect. The scope 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a clear prerequisite ('Requires the plugin to be active and admin rights') but does not explicitly state when to use this tool versus alternatives. There is no mention of wp_create_redirect or other redirect-related tools, so 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 declare this is a write/destructive operation. The description adds valuable context: it requires admin, POSTs to core REST, and returns the updated meta object. It also discloses the REST-registration limitation, going 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with a purpose paragraph, an Args list, and a Returns line. It is concise but the Args list duplicates schema information, making it slightly redundant. Still, it earns its place overall.
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 key aspects: what it does, permissions (admin), the REST mechanism, the meta-key registration constraint, and the return value. It does not discuss error handling for invalid keys, but this is a minor gap given the annotations and schema richness.
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. The description's Args list largely repeats the schema, though it reinforces the meta example. It does not add new meaning, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Write post meta on a page/post', a specific verb and resource, and gives a concrete Kadence example. This clearly distinguishes it from siblings like wp_update_post (which updates post content) and wp_get_post (which reads).
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 the tool writes meta directly via REST and notes the constraint that only REST-registered meta keys can be written, which implies when this specialized tool is appropriate. However, it does not explicitly mention alternatives or when not to use it, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal destructiveness and idempotency, and the description adds valuable semantics such as passing an empty string to clear alt_text, post=0 to unattach, and the return value. There is no contradiction with annotations, and the added edge-case behavior improves transparency beyond the flags.
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 compact and front-loaded with the purpose, then a concise arg list and return note. It avoids unnecessary fluff, though the arg list partially duplicates the schema, making it slightly less lean than ideal.
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 7 parameters and no output schema, the description covers key operational details (clearing alt_text, unattaching, response_format) and states the return value. It lacks error handling or workflow guidance, but annotations and parameter details make it sufficiently complete for 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% and all parameters have descriptions, so the baseline is 3. The description repeats parameter meanings but adds minor emphasis (required id, grouping of optional fields) without introducing new semantic information.
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 'Update metadata on an existing media item' and enumerates specific fields (title, alt text, caption, description, attachment target), distinguishing it from sibling tools like wp_upload_media, wp_delete_media, and wp_get_media_item. The common-use note further reinforces 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear context with 'Most common use: backfilling alt_text on images that don't have it,' which implies when to use. However, it does not explicitly mention alternatives (e.g., wp_bulk_update_media_alt_text for bulk updates) or state when not to use, so it stops short of full exclusion 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?
The description goes beyond the annotations (all false) by revealing a significant side effect: 'Creates a WooCommerce product and wires it to the event via the Bridge meta, so it sells through the normal Woo cart/Stripe checkout.' It also discloses the required prerequisite of an existing event. This is valuable behavioral context that annotations do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/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 adds essential side-effect and prerequisite context without any redundancy 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 10 parameters and no output schema, the description covers the core context: purpose, side effect, and prerequisite. The main gap is that it does not describe what the response returns (e.g., the created ticket type ID or object), which is left unspecified.
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. The description adds no parameter-specific semantics beyond the schema; it merely gives examples of tier names in the purpose sentence, which does not meaningfully enhance parameter understanding.
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: 'Create a ticket tier for an event' with concrete examples. It clearly distinguishes from sibling tools by explaining it creates a WooCommerce product wired via Bridge meta, which separates it from tickera_create_event and wc_create_product.
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 says 'Requires an existing event_id (from tickera_create_event or tickera_list_events)', giving a clear prerequisite and pointing to the relevant sibling tools. It does not explicitly state when not to use the tool or name alternatives, but the context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint: true, so the agent already knows it's a safe read operation. The description adds valuable behavioral context by specifying exactly what is checked (plugin active, dependencies present) and what it returns (default ticket-template ID). This goes beyond the minimal safety annotation and provides actionable expectations.
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 action, and every sentence earns its place. No filler or redundant content, making it easy to parse quickly.
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 simplicity (1 optional param, read-only, no output schema), the description fully covers purpose, usage timing, and return value. It lacks explicit details on what happens when dependencies are missing, but that is not critical for tool selection. Overall, it is complete enough for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, response_format, is fully described in the schema with enum, default, and description, giving 100% schema coverage. The description does not need to add further parameter semantics, and it correctly focuses on the tool's core behavior. Baseline 3 is appropriate as no additional parameter meaning is necessary.
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 function: 'Check that the Ars Nova Tickera Bridge plugin is active and that WooCommerce, Tickera, and the Bridge for WooCommerce are all present. Returns the default ticket-template ID.' It uses a specific verb ('Check') and names the resource and return value, distinguishing it from sibling tools like tickera_create_event and wp_ops_status.
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 says 'Call this before creating events/tickets,' giving a clear when-to-use directive. It does not mention alternatives or when-not to use, but the context is sufficiently clear for an agent to select this tool appropriately among the Tickera-related siblings.
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?
With readOnlyHint=true already provided by annotations, the description adds value by specifying that the output includes both shipping zones and their methods, which is not evident from the tool name alone. It also suggests a practical use case (verifying shipping is disabled). 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 extremely concise: two short sentences that immediately state the function and provide the primary use case. Every word earns its place, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 a single optional parameter and no output schema, the description covers the key aspects: what is returned (zones and methods) and when to use it. It could theoretically detail output formatting, but the parameter description covers that, and the scope is minimal.
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 the single parameter (response_format), which is fully documented with an enum and default. The description does not add any information about parameters, but it doesn't need to because the schema is self-explanatory. 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's purpose: 'List shipping zones and their methods.' This uses a specific verb ('list') and a specific resource ('shipping zones'), and goes beyond the title by mentioning methods, which distinguishes it from other list tools in the sibling set (e.g., wc_list_products, wc_list_orders).
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 to verify shipping is disabled or check what zones exist.' This tells the user when to invoke the tool. It does not explicitly name alternatives or state when not to use, but given the simplicity and lack of overlapping sibling tools, this 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 idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds valuable context beyond annotations: the Stripe test mode key limitation and the specific scope of updatable fields. 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?
The description is two sentences: the first states the purpose, the second adds usage and a specific caveat. It is front-loaded, concise, and free of 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 simple settings update tool with fully documented parameters, the description covers primary use cases and an important limitation. It doesn't mention response_format or return values, but no output schema exists and the tool is straightforward.
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 title, description, and enabled, but adds no additional parameter-level detail 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 updates a payment gateway's settings, specifying actions like enable/disable and changing title/description. This distinguishes it from generic tools like wc_update_setting and aligns with the sibling wc_list_payment_gateways.
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 explicit usage for enabling/disabling and changing title/description, and adds an important exclusion: Stripe test mode keys are handled manually, not via this tool. It doesn't explicitly name sibling alternatives for listing gateways, but the guidance is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive and idempotent behavior. The description adds the crucial safety detail that dry_run defaults to true, which mitigates the destructive hint. It also mentions the CSV columns, though it does not fully disclose behavior like error handling or whether existing values are overwritten. Overall, it adds meaningful context 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, front-loaded with the primary purpose, and each sentence adds value. The optional columns are listed efficiently, and the use case is a concrete example without unnecessary prose.
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 bulk operation tool with four parameters, the description covers the essential invocation details: CSV path, required/optional columns, and dry-run default. It lacks explicit behavior on stop_on_error and what happens with invalid rows, but the core usage is clear. The provided use case adds context that helps the agent understand when to apply 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 50% (csv_path and response_format have descriptions). The description reinforces csv_path column requirements and highlights the dry_run default, which is not in the schema. However, stop_on_error is left undocumented in both schema and description, and the description does not fully compensate for the missing 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 ('Backfill') and explicitly states the resource ('media items') and method ('from a CSV'). It also lists the optional fields (caption/description/title), which differentiates it from sibling tools like wp_update_media (single update) and wp_bulk_update_posts (bulk posts).
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 bulk backfilling media alt text from a CSV and even gives a concrete use case. However, it does not explicitly state when to use this tool instead of alternatives (e.g., wp_update_media for single items), so it lacks explicit exclusions or alternative comparisons.
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 mutating action (readOnlyHint=false). The description adds the admin requirement and explains the two linking modes (page_id vs url). It does not detail side effects or return behavior, but with annotations present, the added context is sufficient.
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 front-loaded with the core purpose, followed by a concise list of arguments. Every sentence earns its place, and there is no redundant fluff. It is easy to scan and understand quickly.
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 operation with 7 params and no output schema, the description covers the essential context: purpose, permissions, and argument semantics. It does not describe the response content, but the response_format parameter hints at output options. Minor gap, but overall 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?
Schema description coverage is 100%, so the schema already documents every parameter. The description repeats the same information (e.g., parent: 0 = top level) without adding new meaning or clarifying relationships beyond what the schema states.
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 'Add a single item to a menu,' which clearly identifies the verb (add), resource (menu item), and scope (single item). It also distinguishes itself from sibling tools like wp_create_menu (creates a menu) and wp_update_menu_item (updates an existing item).
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: link via page_id or url, nest via parent, and requires admin. It implies it's for creation, not updating, but does not explicitly name alternatives or exclusions. Since the tool name and context make the creation intent obvious, this is clear but missing explicit alternative 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=false and destructiveHint=false. The description adds 'Requires admin' and explains the return value (the created widget with its new id), plus the block-based nature. It does not reveal unexpected side effects, but for a non-destructive create this is solid.
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 plus a compact Args list. It front-loads the purpose and keeps every element useful — no fluff or 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 simple create tool with no output schema, it covers purpose, a use case, auth requirement, and return value. The only gap is not listing response_format in the Args summary, but the schema covers it, so completeness remains high.
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 is 3. The description repeats sidebar and content meanings from the schema, adding only a pointer to wp_get_sidebars for IDs. It omits response_format from the Args list, but the schema 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 opens with 'Create a block-based widget in a sidebar/widget area' — a specific verb, resource, and type. It clearly distinguishes from siblings like wp_update_widget and wp_get_widgets by specifying the creation action.
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 states 'Use for populating Kadence footer columns,' giving a concrete use case. It also notes 'Requires admin,' which is a relevant prerequisite. It does not explicitly contrast with alternatives, but 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?
Beyond annotations (destructiveHint=true), the description adds that the deletion is permanent, includes 'all its items', and is a 'force delete'. It also states the admin requirement, giving valuable behavioral context without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the most critical information (permanent deletion, admin requirement). The Args list is clearly formatted and every sentence contributes to understanding the tool's purpose and constraints.
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 100% schema coverage and strong annotations, the description is sufficiently complete for a simple delete tool. It covers irreversibility, admin requirement, and the fact that all menu items are affected. Minor omissions (e.g., exact return behavior) are acceptable given the response_format parameter and lack of output 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%, so the baseline is 3. The description's Args section repeats the schema's parameter details (menu_id, response_format) without adding additional semantic meaning 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 specific action: "Permanently delete a navigation menu and all its items (force delete)." It names the resource (navigation menu) and the scope (all items), distinguishing it from sibling tools like wp_delete_menu_item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 usage: requires admin and is irreversible via the API. It doesn't explicitly name alternatives, but these operational caveats effectively guide when to use it, meeting the bar for 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, but the description adds 'force delete' and 'Permanently remove', clarifying the nature of the deletion beyond a generic destroy. It also discloses the admin permission requirement. 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 extremely concise, with a clear front-loaded purpose, followed by a compact list of args. Every sentence adds value, and there is no fluff or 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?
Given a simple delete operation with no output schema and good annotations, the description covers essential aspects: scope, permanence, permission requirement, and parameters. It lacks details like return success indication or error handling, but these are not critical for this type of 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 coverage is 100%, and the description simply restates the parameter names and descriptions already present in the schema. It adds no extra meaning beyond what the structured fields already provide, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Permanently remove a single menu item (force delete)', specifying the verb (remove), resource (menu item), and scope (single). It distinguishes from sibling tools like wp_delete_menu, which deletes a whole menu, by explicitly limiting to a single item.
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 a clear context for use ('Requires admin') and indicates the operation is a permanent force delete. However, it does not explicitly mention when NOT to use this tool or name alternative tools, 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 readOnly, idempotent, and non-destructive behavior. The description adds the admin capability requirement and specifies the return type (RawWpSettings object), providing useful 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 compact and front-loaded with the primary purpose. The note and Args/Returns sections are clearly structured with no unnecessary filler, making it 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 low-complexity read tool, the description covers the essential aspects: what it fetches, auth requirement, and return type. Pointing to wp_get_site_info for the field list is a helpful reference, though a bit indirect. It is complete enough for an agent to use effectively.
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 single parameter response_format is fully described in the input schema (markdown/json with human-readable vs machine-readable). The description repeats the default value but does not add significant new meaning 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 tool 'Fetch WP general settings' and enumerates specific settings like title, tagline, admin email, timezone, etc. This specific verb+resource combination distinguishes it from sibling tools such as wc_get_settings (WooCommerce) and wp_update_settings (mutator).
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 indicates a clear prerequisite (admin manage_options capability) and provides context on what settings are included. It does not explicitly mention when not to use it or point to alternatives, but the scope 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 declare read-only and idempotent behavior, and the description adds the critical 'Requires admin' requirement and the return shape. These details go beyond the structured hints and provide useful operational 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 extremely concise: two sentences and a return type line. Every element adds value, and it is well-structured with a clear breakdown of the response.
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 one optional parameter, the description covers the essential aspects: what it lists, how it identifies items, the endpoint, auth requirements, and the return structure. It could mention pagination or error handling, but these are unlikely for a read-only core endpoint.
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 coverage is 100% and the single parameter (response_format) is fully described with an enum and default. The description does not need to add further parameter details, so it meets the baseline without extra 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 clearly states the tool lists all registered widget areas/sidebars with their IDs and widgets, which is specific and distinguishes it from sibling tools like wp_get_widgets. It also names the core REST endpoint for additional precision.
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: it lists all sidebars and notes that admin access is required. It does not explicitly mention alternatives, but the scope is unambiguous and the tool's purpose is obvious from the description and title.
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 read-only and non-destructive behavior. The description adds useful context beyond that, such as the dependency on the Ars Nova Bridge plugin and the return shape (active theme slug/name and theme_mods map). No behavioral surprises are hidden.
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 well-organized with an intro, dependency note, args list, and returns line. It is slightly verbose in repeating parameter details that are already in the schema, but every section serves a purpose and contributes to understanding.
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 two parameters and no output schema, the description fully covers what the tool does, the necessary plugin dependency, and what to expect in the response. 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?
The input schema already provides 100% coverage for both parameters, including their optionality and defaults. The description repeats this information without adding any additional semantic nuance, so it meets the baseline for schema-covered parameters 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 provides a specific verb and resource ('Read the active theme's theme_mods') and elaborates with concrete examples (header layout, logo, colors, fonts). It clearly distinguishes itself from sibling tools like wp_get_settings and wp_get_sidebars by focusing on theme_mods and noting the companion plugin dependency.
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 clearly states when this tool is needed ('Core REST does not expose these') and gives a usage prerequisite (the Ars Nova Bridge plugin must be active). However, it does not explicitly name alternative tools or exclusion scenarios, so it falls short of a perfect 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 read-only/idempotent safe behavior. The description adds meaningful behavioral context: the 'edit' context requires admin and returns roles/capabilities, and the response_format parameter controls markdown vs. JSON output. This goes beyond what the schema provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the purpose, followed by a structured Args/Returns layout. Every sentence earns its place with no redundancy 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 simple get-by-id tool, it covers all parameters, enum options, and the return type (WPUserItem). It does not mention error behavior for missing IDs, but given the annotations and simple scope, this is not a critical 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%, so all parameters are already well-documented. The description repeats param details and adds a note about 'edit' requiring admin, but this is already in the schema, so the value added beyond structured data is minimal.
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 'Fetch a single user by ID' with a specific verb and resource. The 'single user' scope distinguishes it from sibling tools like wp_list_users (list), wp_update_user (update), and wp_delete_user (delete).
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 context for when to use the tool (when you have a user ID) and includes a usage note for the 'edit' context requiring admin. However, it does not explicitly mention alternatives like wp_list_users for listing users, though this is implied by the sibling set.
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, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds the permission requirement (admin edit_theme_options) and details the return structure. This is useful context beyond the annotations, though it does not discuss pagination or edge cases. No contradictions found.
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 tight and front-loaded: it states the purpose in one sentence, then lists parameters and return format. Every line earns its place, and there is no fluff. The structure (description, args, returns) is easy to scan.
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 one parameter and no output schema, the description covers the return format, required permissions, and the scope ('all'). It does not mention potential errors, but that is not critical for a read-only list operation. The information provided 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully describes the single parameter 'response_format' with its enum values, default, and a clear description. The tool description repeats this information in the Args section without adding new semantic meaning. Since schema coverage is 100%, 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 starts with a specific verb and resource: 'List all WordPress navigation menus with their IDs, slugs, and assigned theme locations.' This clearly distinguishes it from sibling tools like wp_list_menu_items, which targets menu items rather than menus. The scope ('all') and output fields are explicitly stated.
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: it is for listing all navigation menus, and it notes the required admin capability ('edit_theme_options'). It does not explicitly compare with alternatives like wp_list_menu_items, but the purpose and name make the intended use obvious. No exclusions are mentioned, but none are necessary for a simple list operation.
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, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds behavioral context beyond that: it explains page hierarchy and menu_order ordering, mentions statuses such as draft/private/trash can be listed, and references the return envelope shape via wp_list_posts. 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 well-organized: a lead sentence with purpose and site scope, a brief paragraph differentiating pages from posts, a scannable Args list, and a Returns note. Every sentence contributes meaning, and the structure makes it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, page-vs-post semantics, all parameters, and return format via a reference to the wp_list_posts envelope. However, since there is no output schema, the return envelope shape is only partially specified by reference; it does not detail field names or pagination behavior, leaving a small completeness 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 already documents all 8 parameters with descriptions, defaults, and enums. The description's Args section simply re-states this information without adding new semantic value. The 'Use 0 for top-level pages' note duplicates the existing parameter description, so it offers no additional insight.
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 function: 'List static pages on arsnovasingers.org.' It provides a specific verb+resource+scope and distinguishes pages from posts by noting hierarchy, menu_order ordering, and evergreen content examples (About, Concerts, Education, Contact). This differentiates it from sibling tools like wp_list_posts.
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 contrasts pages with posts ('they are hierarchical, ordered by menu_order rather than date, and used for evergreen content'), which guides when to use this tool over wp_list_posts. However, it does not explicitly name alternatives or state when not to use this tool, so it stops short of full exclusion 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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds context about the scope of results (built-in + custom) and the return shape (an object keyed by slug with specific fields), which goes beyond the annotations. No contradictions found.
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 well-structured and reasonably concise. It front-loads the purpose, then provides organized Args and Returns sections. It is a bit longer than the minimal two-sentence ideal, but every sentence serves a purpose and adds useful information.
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 no output schema, the description is complete. It covers the purpose, usage context, parameters, and the return structure in detail. Annotations handle safety, and the schema covers parameter details, so 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%, and the schema already documents both parameters with their enums and defaults. The description repeats the args but adds no new meaning beyond what the schema provides. Baseline 3 is appropriate since 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 clearly states the tool's function with a specific verb ('List') and resource ('all registered post types'). It explicitly notes the scope (built-in + custom) and distinguishes it from siblings like wp_list_posts by clarifying it operates on post types, not posts. The mention of discovering Stagehand/plugin-added types adds concrete context.
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 a clear use case ('Useful for discovering custom post types...') but does not explicitly name alternatives or state when not to use the tool. It implies the tool is for listing post types rather than posts or other entities, but lacks direct sibling differentiation.
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, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond that: the 'edit' context requires admin and returns roles/capabilities, and the response is a paginated envelope with a defined shape. This enriches the agent's understanding 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 well-structured: a one-sentence purpose, a bulleted args list, and a returns section. Every line earns its place, and the most important information (what it lists, the admin requirement for context='edit') is front-loaded. It is long due to the number of parameters, but not verbose or redundant.
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?
Even though there is no output schema, the description provides the returned object shape, which is essential for an agent to understand the result. It also covers pagination, filters, enums, defaults, and the admin requirement. Lacking only explicit error scenarios or rate limits, but for a read-only list tool with robust annotations, this 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?
Schema coverage is 100%, and each parameter's description in the schema is already very informative. The tool description largely repeats the schema (e.g., limit, search, orderby) with only a slight simplification—notably, it says 'requires admin' where the schema more precisely says 'requires list_users capability'. The description adds minimal new meaning beyond the schema, 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 opens with 'List users on the WP site', a clear verb+resource statement. It distinguishes this from sibling tools like wp_get_user (single user) and wp_list_posts, and further clarifies that context='edit' reveals roles/capabilities. This is specific 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context for the 'edit' context ('requires admin') and explains pagination/filtering parameters. However, it does not explicitly mention when this tool should be preferred over alternatives like wp_get_user or how it differs from other list tools. It provides good context but no explicit exclusions or alternative comparisons.
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 destructive and non-read-only behavior. The description adds meaningful behavioral context: partial update semantics, content_path overriding content, and the output format default. 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 concise and well-structured, with a front-loaded purpose statement, clear Args list, and Returns line. Every sentence adds information without redundancy or 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 destructive update tool with 13 parameters, the description covers partial update behavior, the content_path use case, and the return type. It lacks details on error conditions or authorization, but annotations and schema provide sufficient safety context. Overall complete for typical usage.
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 baseline is 3. The description adds value by explicitly noting id is required and all other fields optional, and by explaining content_path overrides content. This exceeds the baseline by providing cross-referential clarity.
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 'Update an existing page' with a specific verb and resource, distinguishing it from create operations. The reference to wp_create_page for field shape further clarifies the tool's scope. No ambiguity with sibling tools like wp_update_post.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for updating existing pages with partial field updates ('Only the fields you pass will change'), but does not explicitly state when to use this tool versus alternatives like wp_update_post or wp_delete_page. The cross-reference to wp_create_page is helpful but not a full alternatives discussion.
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 destructive (destructiveHint=true) and not read-only. The description adds non-obvious behavioral context: partial/merging updates rather than full replacement, and the content_path override behavior. This goes beyond annotation-only 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?
The description is compact and front-loaded with the core purpose, followed by a clearly organized args list and a returns line. Every sentence and bullet carries useful information with zero 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?
For a 13-parameter tool with no output schema, the description provides a solid overview, explicit merge behavior, parameter categorization, and return type. It doesn't detail error cases, but annotations cover destructive/idempotent hints and the schema fully documents parameters, making it 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 the baseline is 3. The description adds a valuable cross-reference to wp_create_post ('same shape as wp_create_post') and clarifies that content_path overrides content, enriching context 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?
The description clearly states 'Update an existing post' with a specific verb and resource, distinguishing it from sibling update tools like wp_update_page, wp_update_widget, and wp_update_media. It also implicitly contrasts with wp_create_post by requiring an existing post ID.
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 partial update semantics ('Only the fields you pass will change; omitted fields preserve their current values') and requires an id, which implies use on an existing post. However, it does not explicitly mention alternatives such as wp_bulk_update_posts or provide when-not-to-use guidance, so usage direction 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 destructive and idempotent behavior, and the description adds context by detailing the updateable fields and the return type ('updated WPTermItem'). It does not contradict annotations and provides useful behavioral detail beyond what annotations state.
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 compact, front-loaded with the main purpose, and uses a clear list for arguments and return value. Every sentence earns its place with no 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?
For a simple update tool with 5 parameters and no output schema, the description provides the essential context: what is updated, the required ID, and the return type. It could mention usage alternatives, but that gap is minor and covered under usage guidelines.
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 each parameter. The description mostly repeats this information, adding only marginal value by explicitly marking optionality and the response_format default. This meets the baseline 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 clearly states the verb ('Update') and the resource ('an existing tag'), specifying the exact fields that can be modified (name, slug, description). This distinguishes it from sibling tools like wp_create_tag (creation) or wp_update_category (different taxonomy).
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 the tool is used when updating an existing tag and lists the editable fields, providing clear context. However, it does not explicitly mention when to avoid it or point to alternatives like wp_create_tag, so it lacks explicit exclusions.
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 signal destructive behavior (destructiveHint=true). The description adds valuable context beyond annotations by specifying the admin requirement, the deactivation mechanism via sidebar value, and the underlying REST PUT endpoint, giving the agent a clearer operational model.
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 compact, front-loaded with the primary action, and every sentence adds useful information: update/move capability, deactivation hint, endpoint, and permission requirement. 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?
For a mutation tool with a comprehensive schema and annotations, the description provides sufficient context: purpose, auth prerequisite, deactivation behavior, and endpoint. It does not describe return values, but no output schema exists and the update semantics are clear enough for 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%, with each parameter (id, content, sidebar, response_format) already documented in the schema. The description largely repeats the sidebar deactivation hint already present in the schema, so it adds little parameter-level meaning beyond what structured data 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?
Description clearly states 'Update a widget's content and/or move it to another sidebar,' using a specific verb and resource. It distinguishes itself from related tools like wp_get_widgets or wp_create_widget by focusing on updating/moving an existing widget, including the deactivation usage.
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: to update content and/or move a widget, with explicit instruction to use 'wp_inactive_widgets' to deactivate. Also states the admin requirement. It does not explicitly name sibling alternatives, but the operation is unambiguous.
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, so the agent knows this is a non-destructive read operation. The description adds the context that templates are used on PDF/printed tickets and how the selected ID feeds into tickera_create_ticket_type, but doesn't disclose additional behavioral traits like return structure, pagination, or required capabilities. Since annotations cover the safety profile, this is adequate but not rich, so a score of 3 is warranted.
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 action, and every sentence earns its place by either defining the resource or linking to its usage context. 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?
Given the simplicity of a one-parameter, read-only list tool with a 100% schema coverage and readOnlyHint annotation, the description is complete. It states what the tool returns (templates), clarifies the formatting option via schema, and provides the exact use case, so an agent has sufficient information to select and invoke 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 only parameter response_format is 100% covered by the schema with a clear description ('Output format: markdown for human-readable, json for machine-readable'). The tool description adds no additional meaning about the parameter, 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?
Description clearly states the tool 'List Tickera ticket templates' – a specific verb (List) + resource (ticket templates). It adds the context of PDF/printed tickets and explains the purpose of selecting a ticket_template ID for tickera_create_ticket_type, which distinguishes it from other Tickera list tools like tickera_list_ticket_types.
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?
Description explicitly instructs to use the tool to 'pick a ticket_template ID for tickera_create_ticket_type' and notes the fallback behavior ('if omitted there, the plugin uses the default template'). This provides clear when-to-use context and references the related creation tool, even though it doesn't name alternative listing 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, so the read-only nature is covered. The description adds value by disclosing the exact fields returned (gateway ID, title, description, enabled state, method title) and the scope ('all registered'). It also suggests a practical use case (checking Stripe test mode), which goes beyond annotation 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?
The description is three sentences, each purposeful: the first states the action, the second enumerates returned fields, and the third gives a real-world usage example. It is front-loaded with the primary verb and has no filler or redundancy.
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 listing tool with a well-defined schema and readOnlyHint annotation, the description covers all essential aspects: what it lists, what data it returns, and when to use it. No output schema exists, but the description explicitly enumerates return fields, making the tool's behavior fully understood.
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% (single parameter `response_format` with enum values and clear descriptions). The tool description does not reference the parameter, but that's fine because the schema already fully explains 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's action ('List all registered payment gateways') and the resource (payment gateways). It also lists the exact output fields (ID, title, description, enabled state, method title), making its purpose specific and distinguishable from siblings like wc_update_payment_gateway and wc_get_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 provides a direct use case: 'Use this to check if Stripe is enabled and in test mode.' This gives clear context for when to invoke the tool. It doesn't explicitly mention alternatives or when not to use it, but for a read-only listing tool, the use case 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?
Beyond the annotations (read-only, idempotent, non-destructive), the description adds useful behavioral info: the core REST endpoint, the requirement for admin privileges, and the specific fields returned. This goes beyond the schema and 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 concise, front-loaded sentences. The first sentence states the main action and key details; the second adds technical context and a prerequisite. No wasted words.
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 one optional parameter and no output schema, the description provides sufficient context: what it lists, what fields are returned, the endpoint, and auth need. It is complete for its 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 single parameter (response_format) is fully covered by the schema with an enum and default. The description does not discuss parameters but is not required to, as the schema does the heavy lifting. 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 it lists all widget instances across sidebars with specific details (IDs, sidebar assignment, rendered/raw content), distinguishing it from sibling tools like wp_create_widget or wp_update_widget. It also identifies the underlying REST endpoint.
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 sets clear context: it is for reading widget instances and notes an admin requirement. It doesn't explicitly mention alternatives or exclusions, but the read-only verb and the 'list all' scope make usage obvious.
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, idempotentHint=true, destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context by specifying the order of items and nesting via parent IDs, and it describes the return structure. This goes beyond the annotations, so 4 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 compact and well-structured: a one-sentence purpose, a practical pointer for menu_id, and concise Args/Returns blocks. Every sentence adds value, and the front-loaded core purpose is immediately clear.
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 two well-documented parameters, safety annotations, and an explicit return shape, the description is complete. It even tells the user where to find the input ID. No output schema exists, but the Returns section covers what the agent will receive, so no gaps remain.
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 parameters, providing complete meaning for menu_id and response_format. The description's Args section simply restates the schema without adding extra semantics. The Returns block is helpful but does not enhance parameter understanding, so baseline 3 fits.
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+resource: 'List the items in a navigation menu, in order, including nesting (parent IDs).' It clearly distinguishes from sibling wp_list_menus by referring to 'menu_id from wp_list_menus', making the tool's 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on obtaining the required menu_id ('Use the menu_id from wp_list_menus'), which is practical. It does not discuss when to prefer this over alternatives, but the read-only list purpose is self-evident and the tool's role in the menu management workflow is 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?
Although annotations already mark destructiveHint=true, the description goes further by explaining that theme_mods control 'header/layout/colors' and that removing a key 'resets it to the theme default'. It also recommends backup steps, adding practical risk awareness beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded, starting with the core purpose, then prerequisites, a caution, and a compact Args list. Every sentence contributes useful information without padding or redundancy.
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 the tool's mutation and destructive potential, the description covers prerequisites, admin requirement, destructive effects, recommended pre-read/backup steps, parameter meanings, and return value. Since there is no output schema, the 'Returns' line adequately communicates the response shape. This is a complete operational picture.
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 100% description coverage, so the baseline is 3. The description's Args section largely restates the schema, though it does clarify that 'mods' is a key:value object and 'remove' resets keys to defaults. No substantial new parameter meaning is added 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 a specific verb and resource: 'Set and/or remove the active theme's theme_mods', distinguishing it from the read-only sibling wp_get_theme_mods. It also specifies the domain (Kadence/Customizer) and a required plugin, 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 description provides clear usage context by noting the required companion plugin, admin privileges, and a 'CAUTION' to always read current values with wp_get_theme_mods and back them up before bulk changes. It does not explicitly enumerate when-not-to-use alternatives, but it gives a strong paired-workflow hint.
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 file is read from the MCP host machine, sent as multipart/form-data, and that WordPress MIME-sniffs the file. It also notes the host must have read access and recommends alt_text for SEO. These go beyond the annotation flags (readOnlyHint=false, destructiveHint=false) and provide useful operational 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 well-structured with a clear opening sentence, an Args section, a Returns section, and useful Notes. Every sentence adds value: the opening states the action, the Args list is compact, and the Notes cover access, SEO, and MIME rejection—all without 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?
Although there is no output schema, the description specifies the return type (WPMediaItem with id, source_url, dimensions) and covers potential rejection due to MIME restrictions. Combined with 100% parameter schema coverage and practical notes on permissions and alt text, the description gives an agent a complete understanding of what the tool does and what to expect.
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 schema already documents all seven parameters. The description largely repeats the parameter list and defaults (title defaults to filename, post 0 = unattached), which are also in the schema. It adds minimal new semantic detail 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 uses a specific verb ('Upload'), identifies the resource ('WP media library'), and clarifies it creates a new attachment. This distinguishes it clearly from sibling tools like wp_update_media, wp_delete_media, and wp_list_media.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: to upload a local file as a new media item. It does not explicitly name alternatives or provide exclusion criteria, but the notes give practical context (file access, MIME restrictions, alt-text recommendation) that helps an agent decide. No explicit 'when not to use' is present, but the context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description complements the readOnlyHint annotation by explicitly stating it returns all setting IDs and their current values, and clarifies the 'checkout' => 'payments' alias. This adds useful behavioral context beyond the annotation without contradicting 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 two concise sentences, front-loaded with the primary purpose, and every word adds value. It lists groups and return behavior without redundancy or wasted space.
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 adequately covers the purpose, returns (all IDs and values), and valid group inputs, which is sufficient for this simple read-only tool. It does not address edge cases like empty results, but the output format is simple and the scope is well-defined.
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 schema already describes both parameters. The description adds value by enumerating the valid group values and noting the 'checkout' alias, which aids in selecting the correct 'group' parameter. It does not add new info for 'response_format' but schema covers 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 ('Read') and resource ('WooCommerce settings group'), lists the available groups, and distinguishes itself from sibling tools like wc_update_setting by focusing on read-only retrieval. It clearly conveys 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 for when to use the tool (reading a settings group) and enumerates the groups it can access, effectively implying what it covers. However, it does not explicitly mention alternatives or when-not-to-use, though sibling tool names (e.g., wc_update_setting) make the distinction obvious.
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 a destructive, write operation. The description adds valuable behavior: empty cells are skipped, defaults to dry_run=true, and explains parameters like stop_on_error. This context 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 compact yet thorough, with a clear intro, an args list, and a relevant use case. Every sentence adds value, and the structure is 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?
Despite no output schema, the description covers the input format, key behaviors, and output format options. It is complete for a bulk update tool but omits details about error reporting beyond stop_on_error and what the response contains.
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 baseline is 3. The description adds meaningful context about the CSV format (required id, optional columns, empty-cell skipping) that clarifies parameter behavior beyond individual schema descriptions, especially the combined effect of csv_path and dry_run.
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 updates many posts from a CSV, listing the specific fields and required column. It distinguishes itself from sibling bulk operations by targeting posts specifically and using CSV input, with a concrete use case.
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 a clear use case (backfill categories on 45 'Uncategorized' posts) and conveys the tool is for bulk CSV-based updates. It does not explicitly exclude alternatives like single-post updates or term-only bulk assignment, so it falls short of full alternative 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?
While annotations already declare destructiveHint=true and readOnlyHint=false, the description adds critical context by stating 'Defaults to dry_run=true', which tempers the destructive signal. This is valuable behavioral disclosure beyond the annotations, though it does not detail what happens when dry_run is disabled or mention permissions/rollback.
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 well-structured, with a short opening sentence, a succinct list of columns, and a relevant use case. Every sentence adds value, and there is no redundant 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?
Given the tool's complexity (4 params, no output schema) and the presence of annotations, the description is largely complete. It covers the core action, CSV requirements, dry-run default, and a use case. It omits details on stop_on_error and response_format, but those are inferable from their names. Minor gaps prevent a perfect score.
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 50%, with only csv_path and response_format described. The description compensates by explaining the required 'id' column, the optional columns, and the roles format. It also clarifies the dry_run default, which is explicitly present in the schema but reinforced here, adding helpful context.
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 updates many users from a CSV, specifying the resource (users) and the method (bulk update from CSV). This distinguishes it from sibling tools like wp_update_user (single user update) and wp_bulk_update_posts (bulk post 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?
The description provides a concrete use case ('demote stale admins identified in the website audit'), making the intended context clear. However, it does not explicitly mention when not to use this tool or compare it to alternatives like wp_update_user for single-user updates.
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 mark this as destructive and non-idempotent, but the description adds valuable context: automatic deactivation before deletion, irreversibility ('This cannot be undone'), and the safety guard on production refusing execution without confirm_production=true. This goes beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with front-loaded action, a concise parameter clarification, and a critical warning. Each sentence earns its place, and there is no repetition of schema or annotation 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 destructive tool, the description covers the essential behavioral aspects: the action, the parameter format, the production guard, and irreversibility. No output schema is present, but the return value isn't critical for a delete operation. It could mention required permissions or what success looks like, but overall it's 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% with clear descriptions for all three parameters. The description adds minimal parameter-level meaning beyond what the schema already provides, such as reiterating the plugin basename format. It does not elaborate on response_format or confirm_production beyond the schema, 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 uses a specific verb phrase 'Deactivate (if needed) and permanently delete' with a clear resource 'an installed plugin from the site'. It distinguishes itself from sibling tools like wp_set_plugin_status (activation/deactivation) and wp_update_plugin by emphasizing permanent deletion.
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 when to use this tool: for permanent removal, with an explicit step to deactivate if needed. It also introduces the production safety flag confirm_production=true, which is a contextual usage condition. However, it doesn't explicitly name alternative tools for deactivation-only workflows, so it misses a direct comparison.
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 destructiveHint annotation, the description discloses that content is transferred to the reassign user, that WP REST does not support trashing, and that deletion is permanent. It also specifies the return format, providing valuable behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for overview, arguments, and return value. It is front-loaded with the purpose and remains compact, though the argument list is somewhat redundant with the schema.
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?
Since there is no output schema, the description provides the return shape ({ deleted: true, previous: <full user object> }) and explains the critical reassign behavior. It covers all essential aspects for correct invocation, making it complete for a mutation 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 schema already provides 100% coverage for all 3 parameters with detailed descriptions, including the required reassign behavior. The description repeats this information without adding new semantics, 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 'Permanently delete a user' with a specific verb and resource. It distinguishes this from sibling delete tools by noting WP REST does not support trashing, making this the definitive user deletion tool.
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 that a reassign target is required and that deletion is always permanent, indicating when this tool should be used (when permanent removal is intended). However, it does not explicitly mention alternatives or when not to use it, though such cases may be rare.
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, idempotentHint, and non-destructive. The description adds valuable behavior: HTML is stripped, content_preview is expanded to up to 500 characters, and the JSON response includes the raw body. There is slight ambiguity between 'full content of the post' and the 500-character preview limit, preventing a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a front-loaded one-sentence purpose, a clear constraint line, compact Args, and Returns sections. There is no filler; every sentence 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?
With no output schema, the description adequately describes the return shape (WPContentItem, content_preview expansion, raw body in JSON). It covers required input constraints and output behavior. It does not address error cases, but for a simple read-only tool with strong annotations, this is not a major gap. The full-content phrasing could be clearer.
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%, providing baseline 3. The description adds mutual exclusivity between id and slug, and explains response_format implications ('markdown' vs 'json' returning raw body) beyond the schema's simple enum. This extra context justifies a 4.
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: 'Fetch a single blog post by ID or slug.' This clearly distinguishes it from sibling tools like wp_list_posts (listing) and wp_get_page (pages). It also notes the output is HTML-stripped plain text, which further separates it from raw-content retrieval 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 clearly states the use case: fetching one post by id or slug, and requires at least one identifier. However, it does not explicitly name alternatives such as wp_get_page or wp_get_raw_content, nor does it state when not to use this tool, 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, idempotentHint, and destructiveHint false. The description adds valuable context: it specifies the REST context=edit, the admin permission requirement, and the exact return structure. This goes beyond 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 well-structured and front-loaded with the core purpose and usage in the first three sentences. The Args section is redundant with the schema but still concise and readable. No wasted sentences beyond the duplication.
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?
Despite no output schema, the description fully specifies the return object and its fields. It covers the raw source distinction, the write-back workflow, and the admin requirement, making it complete for a read-only single-item tool with full schema coverage and annotations.
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. The description's Args section restates parameter info without adding new meaning beyond the schema. Since the schema already explains defaults, enums, and formats, the description adds no significant 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 clearly states the tool reads a page/post's RAW Gutenberg block markup, using a specific verb ('Read') and resource ('page/post RAW block markup'), and explicitly distinguishes it from sibling tools wp_get_page/wp_get_post by noting they strip away the raw source.
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: 'Use to inspect and transform page content, then write it back with wp_update_page.' It also contrasts with alternatives (wp_get_page/wp_get_post) and mentions the admin requirement, giving clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral detail: auto-detection of the active SEO plugin, normalization across plugins, and the presence of a 'raw' blob for unnormalized data. It also documents the response_format 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 well-structured with clear sections for Args and Returns. It is slightly longer than needed because it repeats schema details, but every sentence serves a purpose and it remains readable. The response shape is provided, which is valuable given no output schema.
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 compensates by specifying the full WPSeoMetaResult shape. It covers required parameters, mutual exclusivity, plugin auto-detection, and normalization. The tool complexity is moderate, and the description addresses all key aspects for correct invocation and interpretation.
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 repeats parameter information already present in the schema (e.g., id/slug exclusivity, content_type required, response_format default). It adds no new semantic meaning 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 starts with a specific verb ('Get'), identifies the resource ('SEO meta') and its scope ('for a single post or page'), and enumerates fields (title, description, canonical, OG/Twitter, focus keyword). It clearly distinguishes from sibling write tool 'wp_update_seo_meta' by emphasizing read-only 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 explicitly states the requirement that either 'id' or 'slug' must be provided, and that content_type is required. It implies usage (reading SEO metadata) but stops short of naming alternatives or when-not-to-use. This is clear context without explicit 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?
The description adds valuable context beyond the annotations: it explains the tool combines public /wp-json with admin-only /wp/v2/settings, and notes that settings fields are omitted gracefully without manage_options capability. This enriches the agent's understanding of auth-dependent behavior and output variability, going beyond the readOnly/idempotent hints.
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 well-structured with a clear opening statement, then sections for args and returns. The return shape is detailed (necessary because no output schema exists), and the text avoids waste while remaining informative. Slightly verbose due to the full JSON shape, but justified.
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 fully specifies the WPSiteInfo return shape. It also covers auth caveats and graceful degradation for missing settings fields. Given the tool's simplicity (1 optional param), the description is complete for an agent to select and invoke 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 single parameter (response_format) is fully described in the schema (enum, default, and explanation). The description's 'Args' section merely restates the schema without adding new semantics, so baseline 3 applies per schema coverage of 100%.
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 function: 'Get high-level info about the WordPress site' and enumerates specific data points (name, tagline, admin email, REST API namespaces, supported authentication, general WP settings). This distinguishes it from sibling tools like wp_get_settings or wc_get_settings, providing a specific verb+resource+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 gives clear context on what the tool is for ('high-level info about the WordPress site') but does not explicitly mention when to prefer it over alternatives or list exclusions. It implicitly differentiates from other 'get' tools by focusing on site-wide metadata, which is adequate for this simple read-only tool.
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 readOnlyHint annotation, the description adds important behavioral details: pagination envelope fields (has_more, next_offset), default ordering, status filter capabilities, and the trimmed post shape. It does not contradict annotations and enriches the agent's understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a purpose sentence, parameter list, and return format. It is reasonably comprehensive for a 10-parameter tool, but it duplicates schema details, which adds length without significant new 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 the tool's complexity (10 parameters, no output schema), the description provides a complete return envelope shape, default behaviors, and capability notes. This is sufficient for an agent to invoke the tool correctly without ambiguity.
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 with descriptions. The description's Args section largely restates this information, adding little new meaning. The only extra note about edit_posts capability is already present in the schema's status description, so no meaningful semantic gain.
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: 'List blog posts on arsnovasingers.org' with filtering, pagination, and sorting. This clearly distinguishes it from siblings like wp_list_pages (pages) and wp_get_post (single post).
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 by specifying default behavior (20 per page, newest-first) and a capability requirement for status='any'. However, it does not explicitly name alternative tools or state when NOT to use this tool, so it lacks explicit 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?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral context: sandboxing to wp-content/themes, directory vs. file behavior, 500 KB cap, and plugin/admin requirements. This goes well beyond the annotations and provides clear expectations without any 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?
The description is compact and front-loaded with the core action, followed by behavior, use case, and prerequisites. The 'Args' section is somewhat redundant with the schema's parameter descriptions, but it's brief and does not detract from clarity.
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 2 parameters, rich annotations, and no output schema, the description is complete: it explains sandboxing, output behavior (file vs directory), size cap, authentication prerequisites, and a specific use case. An agent has enough context to invoke 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?
Schema description coverage is 100%, so the baseline is 3. The description repeats path semantics and gives an example, but adds no new information about response_format beyond the schema. For path, the description's 'Omit to list themes' and 'relative to wp-content/themes' largely mirror 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 'Read theme source on the server (sandboxed to wp-content/themes)' with a specific verb and resource. It distinguishes itself from siblings like wp_list_themes by detailing path-based directory/file behavior and a 500 KB cap, making the tool's unique capability obvious.
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 a concrete use case ('Use to discover Kadence footer-builder option keys') and necessary prerequisites ('Requires Bridge plugin active + admin'). However, it doesn't explicitly mention when not to use it or compare it to alternatives such as wp_list_themes for simple theme listing.
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 read-only, idempotent, and non-destructive behavior. The description adds substantial behavioral context: it names the exact endpoint, explains pagination with offset and limit, and fully specifies the return envelope including has_more and next_offset. This goes well beyond the annotations and gives the agent a precise model of the tool's output and behavior.
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 well-structured: a clear lead sentence, a bulleted arg list, and a JSON return shape. It is longer than strictly necessary because the arg list repeats schema content, but every part has a purpose—especially the return shape, since no output schema exists. The structure is front-loaded with the most important information.
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, 5-parameter tool with no output schema, the description is complete. It covers the endpoint, parameter constraints, pagination behavior, and the full return envelope with field types. It also differentiates the tool from sibling wp_list_posts. There are no significant gaps that would leave an agent uncertain about how to invoke or interpret the 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 input schema already covers 100% of parameters with descriptions, constraints, and defaults. The description's arg list largely restates the schema, but it adds useful framing like 'page size' and 'pagination offset' and clarifies that type='any' searches both posts and pages. This is the baseline 3 because 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: 'Cross-content keyword search across posts and pages'. It also names the underlying WP endpoint and explicitly distinguishes itself from wp_list_posts by highlighting its lighter-weight nature and the specific fields returned. This makes the tool's purpose and scope 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 provides a clear comparative guideline: 'Lighter-weight than wp_list_posts(search=...) because it returns just (id, title, url, type, subtype) per match.' This tells the agent when this tool is preferable over an obvious alternative. It stops short of listing exhaustively when not to use it, but the guidance is direct 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 only provide readOnly=false, idempotent=false, destructive=false. The description adds valuable context: 'overwrite forced on', 'Keeps the plugin's activation state', and the production refusal unless confirm_production=true. These go beyond the generic hints and are not contradictory.
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. Each sentence earns its place: core action, source selection, behavior details. No redundancy 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 7 params and no output schema, it covers the main mechanics, source selection, activation state, and production guard. Minor gaps: doesn't explicitly state that a source is required, and no mention of return behavior beyond the response_format parameter. Still largely 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 coverage is 100%, so baseline is 3. The description adds meaning by clarifying that only ONE source should be picked among slug, url, zip_b64, zip_path (not enforced in schema), explaining zip_path is read by the connector, and detailing confirm_production's role. This exceeds 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 tool 'Update / replace an already-installed plugin in place' with specific verbs and resource. It distinguishes from install/delete/status by noting 'already-installed' and lists source options, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It says 'already-installed plugin' implying not for new installs, and explains the production guard requiring confirm_production=true. However, it does not explicitly name alternatives like wp_install_plugin for new installs, so usage context is clear but lacks direct 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?
The description goes beyond the annotations by disclosing that deletion is always permanent, that force=false triggers a validation error, and by specifying the return shape. This adds valuable behavioral context that annotations alone do not provide, and it aligns with the destructiveHint=true 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 well-structured with a clear opening sentence, a concise Args section, and a Returns section. It is appropriately sized for a tool with three parameters and avoids unnecessary verbosity, front-loading the most critical information (permanence) first.
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 the tool's simplicity and the absence of an output schema, the description is complete: it covers the action, the permanence constraint, parameter behavior, and the return value. The agent has all essential information to invoke the tool correctly and understand its consequences.
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 is 3. The description repeats the parameter details already present in the schema (id, force, response_format) and does not add new semantic meaning beyond what the schema provides. The additional note about force triggering an error is already in the schema description.
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 'Permanently delete a media item' with a specific verb and resource, and distinguishes itself from siblings by emphasizing the permanent nature of deletion (no trash support). This makes the tool's purpose unambiguous and unique among related media 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 for when to use the tool (permanent deletion of media) and includes an important caveat that WP REST does not support trashing media. However, it does not explicitly name alternative tools or exclusions, though the warning about permanence implicitly guides usage.
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 readOnly/idempotent/non-destructive, so the bar is lower. The description adds valuable context: the prerequisite plugin, the exact REST endpoint, and the return shape. 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 well-organized, front-loaded with the core purpose, followed by usage, args, and returns. Every section contributes, and there is no redundant filler beyond the acceptable inline parameter reference.
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 compensates by explaining the return structure. It also covers the required plugin, endpoint, usage context, and all parameter defaults/enums, making it complete for a read-only 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 coverage is 100% (all three params have descriptions). The description's Args section essentially mirrors the schema without adding new meaning. It does not clarify behavior 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 states it reads fields from an ACF Options page, using a specific verb and resource. It also distinguishes this from page-specific content by noting it's for global site content, setting it apart from sibling tools like wp_get_post.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear usage context: 'Use this for Stagehand's global site content... that aren't stored on a specific page.' It does not explicitly name alternative tools or state when not to use it, but the contrast with page-specific content implies the distinction.
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=true, destructiveHint=false), the description adds critical behavioral context: the admin capability requirement, the 403 response for non-admins, the active theme flag, and child theme detection logic. It also details the return object's shape. This goes well 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?
The description is well-structured, starting with the core purpose, followed by a brief behavioral note, then clearly formatted args and returns. Every sentence provides necessary information, with no fluff or redundancy. It is front-loaded and easy 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 list tool with two optional parameters, the description is fully complete. It covers the return shape, auth requirements, and behavioral nuances, while the schema handles parameter definitions. No significant information is missing given the tool's low 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 input schema already provides 100% coverage with detailed descriptions, enums, and defaults for both parameters. The description repeats this information without adding new semantics. 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 opens with 'List installed themes,' which is a specific verb+resource that clearly states the tool's function. It distinguishes itself from sibling tools like wp_list_plugins or wp_list_posts by focusing on themes, and adds useful distinguishing details like active theme flagging and child theme detection.
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 list installed themes, with notes about active status and child theme detection. It also warns about the admin capability requirement. However, it doesn't explicitly mention alternatives or when not to use it, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set readOnlyHint=true. The description adds meaningful context about what the tool checks and returns (production flag, DISALLOW_FILE_MODS, install capability, allowed zip hosts). It doesn't document failure states, but the read-only hint eliminates concern about side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states purpose, the second lists returns and gives usage guidance. Every sentence adds value with no padding.
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 status tool with no output schema, the description covers what it verifies, what data it returns, and when to invoke it. Combined with the schema's full coverage of the optional parameter, the description is sufficient for an agent to decide when and how to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the only parameter response_format is fully documented in the schema with enum, default, and description. The tool description adds no additional parameter information, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's purpose: checking whether the Ars Nova Ops plugin is active, and lists the exact data it returns (production site status, file modification allowance, user install capability, zip host allowlist). This distinguishes it from related tools like wp_install_plugin and wp_get_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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly instructs to 'Call before installing/updating plugins', giving a decisive usage guideline. While it doesn't name alternative tools, this precondition makes the intended workflow unambiguous.
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 read-only and idempotent annotations, the description discloses important behavioral nuances: it skips non-image media, offsets are into the media library rather than the missing list, and the missing_alt_count is scoped to the current scan window only. This adds significant value and prevents misinterpretation.
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 well-structured with clear sections for Args and Returns, using bullets and a code block for readability. It is a bit long but every sentence contributes essential information, avoiding 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?
Despite having no output schema, the description provides a full return shape, explains pagination flow, and covers scoping behavior. Combined with rich annotations, this gives the agent everything needed to use the tool 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 descriptions are already comprehensive (100% coverage), but the description adds crucial semantics: it explicitly clarifies that 'offset' paginates through the media library, not the result set, and explains the relationship between scan_limit and limit. This goes beyond the schema's generic wording.
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 function: 'Scan the media library and report which IMAGE items are missing alt text.' It uses a specific verb ('Scan') and resource ('media library'), and explicitly restricts to images, distinguishing it from sibling media tools like wp_list_media.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear guidance on when to use the tool (to audit missing alt text) and how to paginate large libraries by starting at offset 0 and following next_offset. It does not explicitly name alternatives or exclusions, but the context is obvious enough to infer appropriate usage.
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 key behavioral traits beyond annotations: it replaces existing terms, auto-creates missing tags, defaults to dry_run=true, and requires specific CSV columns. This aligns with destructiveHint=true and readOnlyHint=false, adding valuable specifics 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?
Two short paragraphs with front-loaded purpose and safety warnings. Every sentence adds value: purpose, required columns, dry-run default, replacement behavior, and merge guidance. No 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?
The description covers the tool's purpose, input format, safety defaults, and merge strategy, which is sufficient for a moderately complex CSV-based bulk operation. It does not describe error handling, but the stop_on_error parameter implies this and no output schema exists to explain returns.
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 description adds semantics for term_names (replace vs merge) and dry_run default, which the schema does not fully explain. Schema covers csv_path, response_format, and auto_create_missing, but stop_on_error is not clarified. This partially compensates for the 60% schema description 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 opens with 'Assign categories or tags to many posts using term NAMES (not IDs)', which is a specific verb + resource + method. It clearly differentiates this bulk taxonomy tool from sibling tools like wp_bulk_update_posts or singular create/update category/tag 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 states the tool is for bulk assignment from a CSV and explicitly warns that it REPLACES existing terms, advising to include existing terms if merging is desired. This provides clear usage context, though it does not name specific alternative tools for exclusion.
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 this as read-only, idempotent, and non-destructive, and the description adds valuable context: the source is the connector's target site, the plugin must be active, notes include specific fields, and results are sorted open-first then priority. This goes 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with a clear purpose, usage context, arg list, and return summary. It is slightly redundant with the schema's arg descriptions, but every sentence is purposeful and the structure is easy 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?
Even without an output schema, the description explains what the return contains (fields like page URL/title, priority, status, author, timestamp, linked element) and the ordering. It also covers multi-site usage, making it 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage with descriptions for all three parameters, including enums and defaults. The description restates the args without adding new details 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 clearly states the tool lists in-context notes/change-tasks captured on the front end via a specific plugin, distinguishing it from sibling tools like wp_list_posts and wp_list_pages. It names the resource and the action ('List') with sufficient specificity.
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?
Guidance is explicit: use it to sync notes into project tracker/wiki or review outstanding notes, and run on both DEV and LIVE connectors to get the full picture. It also mentions the prerequisite that the companion plugin must be active, which helps the agent decide when to invoke.
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 that omitted fields are untouched, repeater fields are replaced wholesale, and it identifies the exact REST endpoint. These details go beyond the annotations, which only indicate readOnly=false, destructive=false, and idempotent=true, and there is no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but well-structured, with a clear purpose sentence, behavior notes, and an Args summary. Every section earns its place, though the Args list partially duplicates schema content.
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 covers prerequisites, partial-update behavior, repeater handling, parameters, and the return value (since no output schema exists). It is complete enough for an agent to use the tool correctly in most cases.
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 three parameters thoroughly (100% coverage), so the baseline is 3. However, the description adds the important 'full replacement for repeaters' nuance in its Args section, adding a bit more meaning than the schema alone.
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: 'Write one or more fields to an ACF Options page.' It clearly distinguishes from the sibling read tool wp_get_acf_options by framing this as a write operation and even references that read tool for prerequisite 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?
It explicitly says incremental edits are safe and instructs to 'Read first with wp_get_acf_options' for repeaters, naming the alternative. It also gives a prerequisite about the ACF to REST API plugin, but does not provide an explicit 'when not to use' beyond the repeater caveat.
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?
Adds meaningful behavior beyond annotations: requires admin permissions (manage_options), partial update semantics ('Only the fields you pass are changed'), a limitation (cannot set blog_public via REST), and return value ('Returns the updated settings object'). 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 well-structured with a summary, usage example, caveat, Args list, and return statement. It is slightly repetitive with the schema's parameter list, but every sentence contributes useful context and the layout aids scanning.
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 update tool with 8 optional parameters, the description covers permissions, scope, partial update behavior, limitations, and return format. This is complete given the schema already fully documents parameters and annotations provide safety hints.
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 8 parameters with descriptions, so baseline is 3. The description adds an example usage for static homepage and notes that page_on_front/page_for_posts are used only with show_on_front='page', but the Args list repeats schema info without adding much new 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 clearly identifies the tool as updating core WP general settings, listing specific fields (title, tagline, posts-per-page, front/blog page assignment). It distinguishes from siblings like wp_get_settings (read) and wc_update_setting (WooCommerce) by scope and verb.
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?
Provides explicit usage context with the static homepage example, and states when to avoid it (cannot toggle blog_public, recommends WP Admin or a plugin instead). This gives clear when-to-use and when-not-to-use guidance, though it doesn't name sibling alternatives directly.
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?
With no annotations, the description carries the full burden of behavioral disclosure. It reveals that the tool returns the site URL and environment label, and its 'SAFETY CHECK' framing implies a read-only, non-destructive operation. While it doesn't explicitly state 'read-only,' the context is sufficient and adds value beyond the raw name.
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 exceptionally concise, using a warning symbol, a clear imperative, and a terse explanation of return values. Every sentence earns its place, and the critical safety instruction 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?
Given the tool's simplicity (no parameters) and the absence of an output schema, the description is complete. It explains the purpose, usage, and return values (site URL and environment label), covering all essential context an agent needs to invoke the tool 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?
The tool has zero parameters, so the description need not explain parameter semantics. The schema already provides full coverage (vacuously), and the description does not introduce any confusing parameter-related information, earning the baseline score for no-parameter tools.
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+resource ('Check WordPress Environment') and clearly states it returns the site URL and environment label. It distinguishes itself from sibling write/update/delete tools by being a safety check, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to call this tool before any write, update, or delete operation, and strongly emphasizes 'Never skip this on write operations.' This provides clear, actionable guidance on when to use the tool, even without naming 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 annotations (destructiveHint=true), the description discloses the default trash behavior, 30-day recoverability, and the effect of force=true. It also outlines the exact return payload for both modes, offering rich behavioral context. This exceeds what the annotations provide and fully clarifies the tool's side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear 'Args' and 'Returns' sections. Every sentence serves a purpose: the first explains the core behavior, the Args bullet list specifies inputs, and the Returns section clarifies outcomes. No fluff or redundancy; it is concise yet highly 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?
With three parameters, all explained, and no output schema, the description fully compensates by detailing return values for both force modes. It covers edge cases (trash vs. permanent deletion) and output format options. The description is complete for an agent to invoke the tool correctly without additional context.
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 parameters are already documented. The description adds value by explicitly linking each argument to its behavioral impact, especially in the 'Returns' section showing how force=false returns a trashed post object and force=true returns a deleted flag and previous object. This goes beyond the schema's static definitions.
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 'Delete a post', using a specific verb and resource. It further distinguishes by explaining the trash vs. permanent deletion behavior, which clearly separates it from sibling tools like wp_delete_page or wp_delete_media. The title and description align perfectly with the tool's functionality.
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 when to use the tool (deleting posts) and explains the force option for permanent deletion. However, it does not explicitly contrast with alternative tools (e.g., wp_delete_page) or state when not to use it. The context is clear but lacks explicit exclusion 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?
Discloses important behaviors beyond the annotations: requiring exactly one source, the semantics of activate, and refusal on production without confirm_production. It does not mention potential side effects of overwriting existing plugin files, but since destructiveHint=false, this is not a direct contradiction and the provided detail is substantive.
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 action, and every phrase adds value: source options, update alternative, activation flag, and production safety condition. No wasted 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?
Given the complexity of 8 parameters with four mutually exclusive source options, the description covers the essential selection logic, activation behavior, update fallback, and production guard. It does not explain return values, but no output schema exists and the description is sufficient for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema provides 100% coverage with parameter descriptions, but the tool description adds critical meaning by explaining the relationship among source parameters ('Pick ONE source') and clarifying how overwrite relates to updates. This goes beyond what the schema alone conveys.
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 'Install a plugin on the target WordPress site,' using a specific verb and resource. It also differentiates from the sibling tool wp_update_plugin by explicitly naming it as the preferred tool for updates.
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?
Provides explicit when-to-use guidance: 'For updating an already-installed plugin, use wp_update_plugin instead (or pass overwrite=true here).' It also explains the production guard, making it clear when confirm_production is required and mentioning source selection constraints.
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 mark destructiveHint=true and readOnlyHint=false, and the description reinforces this with 'Remove' and 'strips/writes' while adding important safety guarantees (only first+cover blocks removed, others unaffected). It also discloses server-side processing, scalability, and the per-id return shape, going 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?
The description is compact and well-structured: a single-purpose intro, a safety note, a server-side scaling note, a clean Args list, and a Returns line. Every sentence carries useful information with no redundancy 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?
Despite no output schema, the description spells out the exact per-id return fields. It covers prerequisites (admin), side effects (destructive but scoped), behavior on pages without a leading cover, and the dry_run option, making the tool's behavior fully understandable.
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 comments; the description's Args section mostly paraphrases the schema without adding new parameter semantics. The dry_run and response_format entries repeat defaults/enums already in the schema. Return shape is mentioned but that's not parameter-specific, 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 clearly states the action: 'Remove the embedded leading core/cover hero block from one or more pages' with a specific resource (core/cover hero block). It also explains the intended effect (theme's page-title bar takes over) and differentiates this from generic post/page editing tools among siblings.
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 states when it is safe to use: only removes a block that is both the first block and a core/cover, and pages without a leading cover are left unchanged. It also notes the admin requirement, mentions dry_run for previewing, and clarifies server-side processing for scaling. This gives an agent clear criteria for selecting 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 annotations, the description discloses partial-update semantics ('Only the fields you pass are changed'), permission requirements ('Requires admin'), and the return value ('Returns: the updated menu item'). It also contrasts with the destructive effects of rebuilding, providing rich behavioral context that aligns with the idempotent and non-destructive hints.
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 opens with a clear purpose sentence, follows with a concise paragraph explaining when to use the tool, and lists parameters compactly (combining multiple fields into one line). Every sentence adds value without redundancy, making it well-structured and appropriately sized.
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 11 parameters and no output schema, the description still covers all essential context: purpose, usage guidance, permissions, partial update behavior, parameter list, and return value. It compensates for the missing output schema by explicitly stating what is returned, making it complete enough 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 has 100% coverage with detailed descriptions for all 11 parameters. The description's Args block largely mirrors schema descriptions (e.g., mutual exclusivity, 0 = top level, item_id source) without adding new meaning. Since schema coverage is high, 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 uses the specific verb 'Update' with the resource 'a single existing menu item' and narrows scope with 'IN PLACE', listing exact operations (rename, repoint, re-nest, reorder). It also distinguishes itself from the sibling tool wp_build_menu by warning against rebuilding, 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?
The description explicitly states when to use this tool over an alternative: 'Prefer this over wp_build_menu for small edits.' It explains why rebuilding is problematic (regenerates EVERY item ID, breaks references, leaves orphaned rows) and adds a prerequisite ('Requires admin'). This is a clear, actionable usage guideline.
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), the description adds essential context: it is 'RESTRICTED BY DESIGN' to owned namespaces, it hits the configured site (environment safety), and it gives concrete examples of destructive actions like 'DEL tickera/event/{id} — trash (?force=1 to delete)'. Returns are specified as JSON verbatim.
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 front-loaded with a clear purpose and structured into sections (purpose, restrictions, safety, route catalog, Args, Returns). While it is long, the route catalog is highly useful for a generic tool, but the 'Args:' section partially duplicates the schema, making it slightly less concise than ideal.
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 REST-calling tool with no output schema and many possible endpoints, the description covers the essentials: what it can call, what it cannot, environment safety, parameter usage, and return format ('Returns: the endpoint's JSON response verbatim'). It also mentions calling wp_check_environment for safety, making it complete for the intended use case.
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 detailed per-parameter descriptions and examples, so the baseline is 3. The description adds value by listing concrete routes (e.g., 'tickera/introspect') and their purposes, which clarifies how to construct route, query, and body even though the schema already provides analogous examples.
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 function: 'Call any route in one of the Ars Nova plugins' own REST namespaces.' It uses a specific verb (call), the resource (routes in owned namespaces), and explicitly differentiates from sibling tools by noting it's for capabilities with no dedicated tool yet.
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 when-to-use guidance ('Use this for capabilities that have no dedicated tool yet'), explicit exclusions ('It cannot call wp/v2, wc/v3 or third-party plugin routes — those have their own purpose-built tools'), and a direct prerequisite ('Call wp_check_environment first if you are unsure whether you are on DEV or LIVE').
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 only indicate non-readonly, non-idempotent, non-destructive. The description adds critical behavioral context: defaults to 'draft' status so nothing goes public, and date parsing/storage format ('Y-m-d H:i'). These are useful side effects not derivable from annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with the core purpose, then practical usage details and a workflow pointer. Every sentence earns its place with no redundancy.
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?
Despite 7 parameters and no output schema, the description covers the essential context: what the tool does, the default status behavior, date format handling, and the follow-up action. Combined with the fully described schema, this is 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining the date format behavior ('stored as Tickera's 'Y-m-d H:i'') and reinforcing the default for status. This clarifies the most complex parameter beyond the schema's example.
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: 'Create a Tickera event (tc_events)'. It also clarifies the scope ('Use for one performance/show date'), which distinguishes it from sibling tools like tickera_list_events and tickera_get_event.
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?
Provides explicit usage context: 'Use for one performance/show date', implicitly excluding multi-date scenarios. Also gives a clear next step: 'After creating the event, add ticket tiers with tickera_create_ticket_type', guiding the agent on the workflow.
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, the description discloses that it creates a NEW menu and explicitly does not merge, which is critical for understanding side effects. It also explains item linking semantics and return values, providing full behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with introduction, args, example, and return note. Every sentence adds value—no filler or repetition of schema details. Despite length, it remains efficient and information-dense.
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 the tool's complexity and lack of output schema, the description fully covers return format, behavior around creating vs merging, replacement guidance, and parameter relationships. Nothing important is left unexplained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds substantial meaning beyond the schema: it explains how items map to submenus, ordering follows array order, and the example clarifies page_id vs url vs neither. This enriches the schema's already high coverage with practical usage 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?
Description clearly states a specific action: creating an entire navigation menu with nested submenus, ordering, and theme-location assignment. It distinguishes itself from sibling tools like wp_create_menu or wp_create_menu_item by emphasizing whole-menu construction from a single spec.
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 it is ideal for rebuilding primary navigation by command and even advises using wp_list_menus / wp_delete_menu first when replacing. This gives clear when-to-use and alternative guidance.
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:

[![ars-nova-wordpress-mcp MCP server](https://glama.ai/mcp/servers/ArsNovaSingers/ars-nova-wordpress-mcp/badges/card.svg)](https://glama.ai/mcp/servers/ArsNovaSingers/ars-nova-wordpress-mcp)

Score Badge

Copy to your README.md:

[![ars-nova-wordpress-mcp MCP server](https://glama.ai/mcp/servers/ArsNovaSingers/ars-nova-wordpress-mcp/badges/score.svg)](https://glama.ai/mcp/servers/ArsNovaSingers/ars-nova-wordpress-mcp)

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/ArsNovaSingers/ars-nova-wordpress-mcp'

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