mcp-server-woocommerce

Server Quality Checklist

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

Latest release: v1.2.0
Disambiguation5/5
Each tool corresponds to a specific WooCommerce REST API endpoint, targeting a distinct resource and action. CRUD operations are cleanly separated per resource (orders, products, coupons, etc.), with batch and system tools clearly distinct, leaving no ambiguous overlaps.
Naming Consistency4/5
Naming predominantly follows a consistent verb_noun pattern with list_, get_, create_, update_, and delete_ prefixes. Minor deviations such as add_shipping_zone_method, run_system_tool, cleanup_orphaned_media, and batch_update_* are understandable but break uniformity slightly.
Tool Count1/5
With 101 tools, this server is extremely oversized for an MCP interface. Even for WooCommerce's broad API, this volume is overwhelming and makes tool discovery and selection challenging, far exceeding the 50+ threshold considered an extreme mismatch.
Completeness3/5
The server covers most WooCommerce domains with full CRUD operations, but notable gaps exist: no update_attribute, no delete_customer, no update_tax_class, and no create operations for media or reviews. These omissions are significant given the server's comprehensive intent, though agents can work around some by using existing related tools.
Average 4/5 across 87 of 101 tools scored. Lowest: 3.1/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- Last stable release on March 12, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations declare destructiveHint=true, but the description adds no behavioral context beyond naming example tools. It doesn't describe side effects, what gets modified, or any operational details.
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 brief and front-loaded, with a clear verb and useful examples. The structure is acceptable, though it could be slightly more organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description doesn't explain return values or how to discover valid tool IDs. Given the destructive annotation, more context about impact would be helpful.
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 full descriptions for both parameters (id and fields) with examples, so the description adds minimal extra value. Baseline 3 applies due to high schema coverage.
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 ('Run a system maintenance tool') and lists common tool IDs, which distinguishes it from sibling tools like list_system_tools. However, it doesn't explicitly mention that this executes a specific maintenance operation, making it slightly generic.
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 examples but doesn't explicitly state when to use this tool vs list_system_tools or other tools. No alternative guidance is provided.
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 annotations already include 'destructiveHint: true,' so the description adds no further behavioral context. It does not mention irreversibility, the 'force' requirement, or any side effects, offering no value beyond what structured annotations already 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 a single, front-loaded sentence with no filler words. Every part is essential and directly conveys the operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a straightforward delete with full schema coverage and a destructive annotation. The description, while minimal, is sufficient given the structured data. It could mention the 'force' requirement, but the schema already handles that, so the overall context is complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema descriptions cover 100% of parameters (zone_id, instance_id, force, fields). The description adds no parameter-specific meaning, so the baseline score of 3 applies because the schema already documents each parameter clearly.
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 'Remove' with a clear resource 'a shipping method from a zone,' which precisely matches the tool name. It distinguishes this operation from siblings like 'delete_shipping_zone' and 'add_shipping_zone_method.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as using 'update_shipping_zone_method' or when a shipping method cannot be deleted. There are no exclusions, prerequisites, or contextual hints beyond the basic action.
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 safety is covered. The description adds insight into the report contents and breakdown type but does not clarify parameter interactions (e.g., how date_min and date_max relate to period, or default behavior when omitted). This is adequate but leaves some behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action and a concise list of returned data. Every word serves a purpose, 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?
For a read-only tool with no output schema, the description lists the key aggregate fields and indicates a breakdown by daily/weekly totals. The schema's rich field list compensates for the lack of an output schema. The main gap is not explaining how the parameters combine to produce the report, but overall it is sufficiently complete for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter description coverage, so the schema already explains each field. The description adds minor semantic context by mentioning daily/weekly totals breakdown, which aligns with the `totals_grouped_by` field, but it does not significantly augment the schema-provided meanings.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a sales report for a period, listing specific metrics it returns (total sales, orders, items, tax, shipping, refunds) and a daily/weekly breakdown. This differentiates it from sibling tools like get_order_totals or get_customer_totals by scope, though no explicit alternative is named.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus related alternatives such as get_order_totals or list_orders. The description implies it is for period-based reporting but does not state exclusions or preferences, leaving the AI to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the useful context that deletion is permanent, going beyond the destructiveHint annotation. However, it omits the nuance of the 'force' parameter, which in the schema states it must be true to permanently delete the note, making the behavior potentially misleading. It also does not describe any other side effects or response behavior.
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 consists of two short, front-loaded sentences that convey the operation and its irreversibility without any wasted words. Every word contributes to understanding.
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 gives the core action and permanence but lacks important context such as the force parameter's role in permanent deletion, potential prerequisites (e.g., needing a valid order_id and note id), and what happens on success or failure. With no output schema, return values are not explained, but the omission of the force condition is a significant gap for a destructive 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 description does not mention any parameters, but the input schema provides 100% coverage with descriptions for all four parameters (id, order_id, force, fields). According to the rubric, the baseline is 3 when schema coverage is high, and the description adds no extra parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Delete') and resource ('a note from an order'), which directly matches the tool name and distinguishes it from siblings like create_order_note and list_order_notes. The addition of 'permanently removes' further clarifies the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions. The only hint is the word 'permanently', which implies caution but does not explicitly say when to choose this over other note-related tools.
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 destructiveHint=true, so the description adds a bit by saying 'permanently delete' and linking force to permanence. However, it does not clarify the actual default (force=true per schema) or consequences of setting force=false, creating potential confusion about behavior 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?
Two short sentences, immediately front-loaded with the core action. No redundant words or filler, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with no output schema, the description covers the essential action. However, it misses clarification on the force default discrepancy (schema default true vs. description implying true is special) and does not mention what the response contains, even though a 'fields' parameter exists. The description is adequate but not 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?
Schema description coverage is 100%, so all parameters are already described. The description's 'Set force=true to permanently delete' merely repeats the schema's force description without adding new meaning. No additional parameter context is provided 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 'Delete a webhook' with a specific verb and resource. It distinguishes from sibling webhook tools (list/get/update) and other delete_* tools by naming the target resource. The mention of force=true adds relevant detail without obscuring the primary action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., update_webhook to disable, or soft delete). The only hint is the force parameter, but the description does not explain when it should be set or the default behavior. This leaves the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only include openWorldHint=false, which pertains to schema strictness, not behavioral traits. The description carries the full burden for safety and side effects, but it only says 'Create a tax rate' without disclosing potential consequences like duplicate handling, permission requirements, or whether creation is reversible. This is a significant transparency gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly written sentence that leads with the primary action and then covers the most salient parameters. There is no redundant phrasing or fluff; every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 11 parameters and no output schema, yet the description only mentions a subset of parameters and omits the required 'name' field entirely. It also doesn't clarify what the response will look like or any edge cases. While the schema is rich, the description itself is incomplete for guiding an agent toward a successful invocation, especially given the missing required parameter.
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 have individual descriptions. The tool description adds marginal value by grouping country/state/postcode as 'region' and giving an example for rate, but it doesn't go beyond what the schema already conveys. It also omits mention of the required 'name' parameter, which is present in the schema but not highlighted in the 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 immediately states 'Create a tax rate' with a clear verb and resource, and then enumerates the key configuration elements (country/state/postcode, rate, class). This distinguishes it from sibling tools like update_tax_rate, delete_tax_rate, and get_tax_rate.
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 tool's purpose as a creation operation is clear, and the description gives practical guidance on what fields to set. It doesn't explicitly say 'use this instead of update_tax_rate', but the context and naming make the usage context unambiguous. No exclusions or alternative mentions are provided, so it misses a top score.
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, so the agent knows it's a safe read operation. The description adds minor context (returns all currencies, includes codes/symbols) but does not disclose additional behavioral details like pagination, limits, or exact return format. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the action and resource. Every word adds value, with no wasted language 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 low-complexity list tool with one optional parameter and read-only annotation, the description adequately explains what it does and the default returned fields. While it doesn't specify the exact JSON return structure, the absence of an output schema and the simplicity of the tool make this sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: the single 'fields' parameter is fully described with its type, default value, and meaning. The description adds no additional parameter semantics, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and clearly identifies the resource as 'all currencies supported by WooCommerce' with details about what is returned (codes and symbols). This distinguishes it from sibling tools like list_countries or list_products, 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 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, nor does it mention any exclusions or alternative tools. Usage is only implied by the name and purpose, with no direct comparative context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only include openWorldHint:false, providing minimal safety context. The description does not disclose behavior such as idempotency, required permissions, or reversibility. For a create operation, there is no mention of what the response contains or potential side effects beyond creation, leaving the agent to infer behavior.
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 with no redundant text. The first sentence clearly states the primary action, and the second adds a helpful sequencing note. It is front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides a helpful next step (adding locations and methods) but is incomplete in other aspects. There is no output schema, and the description does not mention return values or error scenarios. Also, the mention of 'add locations' is ambiguous because no explicit 'add location' sibling tool exists, which might confuse an agent. Overall, it is adequate for a simple create but has 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 coverage is 100%, so all parameters have descriptions. The tool description does not add meaning beyond the schema; it only hints that locations and methods are separate, which is not directly about the parameters. Therefore, baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Create a new shipping zone' with a specific verb and resource. It also distinguishes itself from sibling update/delete/list tools by indicating creation as the action. The follow-up instruction about adding locations and methods further clarifies its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when creating a new shipping zone. It gives clear context that after creation, locations and methods must be added, which guides the workflow. However, it does not explicitly state alternatives (e.g., use update_shipping_zone for modifying existing zones) or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is clear. The description adds a useful tip about using the fields parameter to request only needed fields, but it does not disclose pagination behavior, return format, or other constraints. This is consistent with the read-only nature but adds limited extra 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 three short, focused sentences with no fluff. The first sentence states the core action, the second lists supported filters, and the third gives a pragmatic tip. It is well-structured and easy to parse, earning full marks for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the comprehensive input schema (100% parameter coverage) and read-only annotations, the description is sufficient for a list/filter tool. It does not explain pagination or default sorting, but those are captured in the schema. The absence of an output schema is acceptable, though a mention of pagination or default return fields would make it even more 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?
The input schema documents all 10 parameters, so the baseline is 3. The description adds value by explicitly mentioning the fields parameter as a way to request only needed fields and by highlighting the main filter dimensions (status, customer, date range, search term), which reinforces the semantics of key parameters and provides practical usage advice.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'searches and filters orders,' using a specific verb and resource. It lists key filter dimensions (status, customer, date range, search term), making its function distinct from sibling list tools like list_order_notes and list_products. However, it does not explicitly name alternatives, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied by the name and description: use this when you need to retrieve or filter orders. There is no explicit guidance about when not to use it or which sibling tool to choose instead, making the usage guidance only implicit rather than direct.
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 annotations only include openWorldHint: false, which provides minimal safety information. The description does not disclose any behavioral traits such as whether creation is idempotent, permissions required, uniqueness constraints, or what happens on duplicate names. The only added context is the assignment workflow via update_product, which is more about post-create usage than the create call itself. Thus the description carries the burden but fails to disclose expected mutation behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and every word serves a purpose. It explains the what, the why, and the follow-up action (assign via update_product) without any 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 create tool with only one required parameter and full schema coverage, the description provides sufficient contextual grounding: it names the resource, gives examples of use, and explains the relationship to products. It does not cover edge cases like duplicate names or required field constraints, but that is likely acceptable given the tool's simplicity and the schema's required field declaration.
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 example values for the shipping class name ('bulky', 'fragile') but does not attach them to a specific parameter or clarify the format of slug, fields, or description beyond the schema. Therefore it meets the baseline but adds little extra semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create a product shipping class,' which is a specific verb+resource statement. It also distinguishes this create tool from the sibling tools list_shipping_classes and delete_shipping_class by implying creation only, and provides an example use case ('bulky', 'fragile') to clarify the resource's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when this tool is useful: to create a shipping class that can later be assigned to products via update_product. It gives clear context and a concrete grouping use case. However, it does not explicitly state when not to use it or mention alternatives like updating existing classes, but the sibling creation vs management distinction is implicit.
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 description only covers the conceptual nature of tags, not behavioral traits like duplicate handling, slug generation defaults, or any side effects. Annotations only include openWorldHint=false, which does not disclose mutation or safety behavior, so the description carries the burden but fails to provide this 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 compact with two sentences, front-loading the core action and using an illustrative contrast. Every word earns its place without 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 creation tool with one required parameter, the description adequately explains the purpose and distinguishes tags from categories. Gaps exist around behavioral details like uniqueness or slug defaults, but these are partially mitigated by schema fields and the straightforward nature of 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?
Schema description coverage is 100%, so the schema already fully documents each parameter. The description adds context about tag semantics but does not provide additional per-parameter 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 uses a specific verb 'Create' with a clear resource 'product tag', and contrasts tags with categories to clarify they are flat labels without hierarchy. This distinguishes the tool from sibling tools like create_category and 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 explicitly illustrates usage with examples ('Bestseller', 'New Arrival') and contrasts with categories ('unlike categories, they have no hierarchy'), providing context on when to use tags instead of categories. However, it doesn't explicitly state exclusions or formal 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?
Adds 'permanent and cannot be undone' beyond the destructiveHint annotation, providing valuable irreversibility context. Does not detail effects on associated data, but annotations already signal destructiveness.
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, front-loaded sentences that state the action and a key consequence. No superfluous 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 the simple delete operation, complete schema, and destructive annotation, the description is largely sufficient. It omits mention of the force parameter requirement, but that is already in the schema. Overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are documented. The description adds no parameter-specific meaning beyond the schema, warranting the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb ('Delete') and resource ('tax rate'), making the tool's purpose unambiguous. It naturally distinguishes from siblings like get_tax_rate, update_tax_rate, and create_tax_rate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., update_tax_rate to modify). The permanence warning implies caution but does not state prerequisites or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 safe read. The description adds that the tool returns specific fields and allows field selection via the fields parameter, which is useful but does not disclose additional behavioral details such as error handling or response structure beyond what is stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff: the first states the core purpose and the second provides a practical tip. Every word earns its place, and the important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-id tool with complete schema and read-only annotations, the description sufficiently conveys what the tool does and what it returns. The lack of an explicit statement that a single object is returned is a minor gap, but the phrase 'full details of a product brand' adequately implies singular retrieval.
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 both id and fields. The description adds only a minor usage hint about requesting only needed fields, which slightly enhances but does not significantly extend the schema's meaning. Baseline of 3 is appropriate when 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 uses a specific verb ('Get') with a clear resource ('product brand') and specifies the kind of details returned (description, image, product count). This clearly distinguishes it from siblings like list_brands (plural) and other create/update/delete brand 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 for fetching a single brand's full details, and the fields tip suggests how to limit response size. However, it does not explicitly compare with alternative tools like list_brands or state when not to use it, leaving some ambiguity for an agent deciding between retrieval and listing.
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 safe read operation. The description adds that it shows total registered customers and their roles, which is useful output context, but it does not disclose other behavioral traits such as rate limits, data freshness, or performance characteristics. This is adequate but not rich 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 exactly two short sentences, delivering the core purpose without redundant words. It is front-loaded with the action ('Get') and easily skimmable, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one optional parameter and no output schema, the description adequately explains what the tool does and what it returns (total counts and roles). It does not mention the customizable 'fields' parameter, but the schema covers that, and the tool's simplicity means the description is sufficiently complete for an agent to select and 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?
The schema description covers 100% of the single 'fields' parameter with a clear explanation ('Comma-separated fields to return (default: slug,name,total)'). The tool description adds no additional parameter 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 uses the specific verb 'Get' with the resource 'customer counts' and a clear grouping dimension ('by WordPress role'). This distinguishes it from sibling tools like get_order_totals or list_customers, 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a clear use case (aggregate customer counts by role) but does not explicitly state when to use this tool over alternatives like get_customer or list_customers. It also lacks any exclusions or explicit 'when-to-use' guidance, so usage is only implicitly conveyed.
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 safety profile is known. The description adds the common IDs as useful context but doesn't disclose other behavioral aspects such as response format, variable returns based on the 'fields' parameter, or error handling. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with a list of common IDs, front-loaded with the main action and resource. It is concise with zero redundant prose, efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with two parameters and no output schema, the description is largely complete. It explains what the tool does and provides example ID values. Minor gap: it doesn't mention that the 'fields' parameter can customize the response, but the schema covers that. Overall adequate for tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters have meaningful descriptions. The tool description repeats the examples already present in the schema (e.g., cod, bacs, stripe, razorpay) without adding new parameter semantics beyond what is already structured.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get full details') and the resource ('payment gateway'), and specifies retrieval by ID. It also provides common IDs (bacs, cheque, cod, etc.) as examples, distinguishing it from sibling tools like list_payment_gateways and update_payment_gateway.
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 fetching a single gateway by ID but does not explicitly state when to use it over alternatives like list_payment_gateways or mention exclusions. No clear context for choosing this tool vs. its siblings is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, covering the safety profile. The description adds 'full details' but does not expand on return format or error behavior. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no wasted words. It front-loads the action and resource.
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 operation with readOnlyHint=true and schema describing the fields parameter, the description is sufficient. 'Full details' is a minor vague point but the schema provides the field list. Lack of output schema is acceptable here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with clear descriptions for both 'id' and 'fields'. The description's 'full details' does not add meaningful parameter semantics beyond what the schema documents, 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 clearly states a specific action (get), resource (tax rate), and scope (single by ID) with 'full details'. This distinguishes it from sibling list_tax_rates, which retrieves multiple tax rates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: 'by ID' indicates this tool is for when you have a specific tax rate ID and need its details. However, it does not explicitly mention alternatives like list_tax_rates or provide exclusions, so guidance is limited.
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 declare readOnlyHint:true, so the read-only nature is already known. The description adds an illustrative example and recommends using the fields param, but doesn't disclose behaviors like pagination, sorting, or response shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two clear sentences with front-loaded purpose and a concrete example. 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?
The tool is simple with complete schema coverage and read-only annotation. Description plus schema is sufficient for an agent to invoke it correctly; only minor missing context like pagination defaults (though present in 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 descriptions cover all 4 parameters at 100%, so baseline credit applies. The description adds a hint to use fields for efficiency, which is useful but not substantial 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?
Description explicitly says 'List values (terms) for a product attribute' with concrete examples ('500g', '1kg' for Weight). This is a specific verb+resource that clearly distinguishes from sibling tools like list_attributes and get_attribute.
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 clear use case (listing attribute terms) but does not explicitly compare to alternative tools or state when not to use it. The fields param tip is operational guidance rather than tool-selection 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 declare readOnlyHint=true, and the description aligns with that (search/filter). The description adds the scope of filtering but does not disclose pagination behavior or return format. 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 three short sentences, front-loaded with the purpose, and every sentence adds value (purpose, filter list, fields tip). 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?
For a 14-parameter list tool with full schema descriptions and readOnlyHint, the description is sufficient. It covers the core search/filter functionality and a key usage tip. It could mention pagination/sorting, but those are well-documented in the schema, so the description does not need to repeat them.
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 every parameter already documented. The description provides a useful summary of filterable fields and a tip on the 'fields' param, but it does not add any new semantic 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's action and resource: 'Search and filter the product catalog.' It also lists the filter dimensions, distinguishing it from sibling tools like get_product (single product) and list_categories (categories).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool (searching/filtering products), but it does not explicitly mention alternatives or when not to use it (e.g., for single product retrieval). Usage is implied rather than explicitly stated.
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 safe-read behavior is known. The description adds context about the purpose of shipping classes but does not disclose any additional behavioral traits such as pagination behavior, sorting, or what fields are returned by default. It does not contradict annotations, and the added conceptual information provides some value 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 two short sentences, front-loaded with the core action and resource. The second sentence adds useful conceptual context without redundancy. Every word earns its place, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with good annotations and complete parameter schema, the description sufficiently explains what the tool does and the concept of shipping classes. It does not explain return value details, but the absence of an output schema and the low complexity make additional explanation unnecessary. A slightly higher score would require more behavioral details like pagination or filtering nuances.
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 parameters (page, fields, per_page) have descriptions in the input schema. The description adds no additional parameter information beyond what the schema already provides, so it meets the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'List product shipping classes', a specific verb+resource pair that clearly states the tool's function. It distinguishes itself from sibling tools like list_shipping_zones by naming the resource explicitly and adds conceptual context (grouping products with similar shipping requirements).
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 listing shipping classes and explains what they are, but it does not explicitly state when to use this tool versus alternatives such as list_shipping_zones or create_shipping_class. No exclusions or alternative references are provided, making the guidance implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true already declared, the description need not restate safety. It adds the structural context of flat labels (no hierarchy), which is useful. However, it does not disclose return format, pagination behavior, or other operational details beyond what annotations and schema already 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 three short sentences: first identifies the tool's main purpose, second adds structural context, and third gives parameter usage tips. 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?
Given the tool's simplicity, the schema's thorough parameter documentation, and the annotations, the description is largely complete. It covers the key non-obvious context (flat labels) and parameter tips, though it does not describe the response structure since no output schema exists. This is a minor gap but acceptable 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 100%, so the schema fully documents each parameter. The description adds minor value by explaining hide_empty as 'skip unused tags' and suggesting fields for efficiency, but these are re-statements of the schema descriptions rather than significant new semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List product tags' with a specific verb and resource, and adds the distinguishing trait 'Tags are flat labels (no hierarchy)' which separates it from hierarchical category 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides parameter usage tips ('Use hide_empty to skip unused tags', 'Use fields param to request only needed fields') but does not explicitly state when to use this tool versus alternatives like list_categories or list_brands. Usage is implied by the name and purpose, but no exclusions or alternative recommendations are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the tool's non-destructive nature is covered. The description adds context about default tax classes and the grouping relationship, but does not disclose details like return formatting, pagination, or required permissions. This is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: the first states the action, the second adds valuable context about defaults and grouping. No redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with a single optional parameter, the description covers the core behavior and context. It omits details about return structure, but the schema and annotations handle most operational aspects, making it sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single 'fields' parameter, so the description does not need to explain it further. Since the schema already documents the parameter, the description adds no additional semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('list') and resource ('tax classes'), and the note that tax classes group tax rates distinguishes it from the sibling tool list_tax_rates.
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?
No explicit guidance on when to use this tool versus alternatives is provided. The context about tax classes grouping tax rates implies its purpose, but there are no exclusion statements naming list_tax_rates or other alternatives.
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 destructiveHint=true, and the description's mention of 'delete' is consistent with that. The description adds useful operational context (single request, efficiency) but does not disclose other behavioral aspects like partial success, validation rules, or whether operations can be mixed. This is acceptable given the annotation coverage, but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the tool's purpose and a concise efficiency note. Every word contributes meaning, with no redundancy or filler.
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 is adequate for a batch operation but leaves some gaps: it does not clarify whether the create, update, and delete operations can be combined in one call, nor does it mention what happens if some operations fail. With no output schema, a bit more detail about expected behavior would improve completeness. However, the required parameter is visible in the schema, and the core function is clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, and the description does not add additional meaning about the parameters beyond what is already in the schema. The baseline of 3 is appropriate since the schema carries the full burden, and the description does not elaborate on parameter use or relationships.
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: 'Batch create, update, or delete attribute terms in a single request.' It uses a specific verb and resource, and distinguishes itself from sibling tools like create_attribute_term and delete_attribute_term by emphasizing the batch capability.
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 usage context by stating it is 'More efficient than individual create/delete calls for multiple terms,' which implies when to use this batch tool over single-operation alternatives. It does not explicitly say when not to use it, but the guidance is clear enough for an agent to infer the appropriate scenario.
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?
With destructiveHint=true in annotations, the description's mention of 'delete' aligns but does not add deeper behavioral context. It describes the batch scope and variable product focus, but omits details like atomicity, partial failure handling, or what happens on errors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The key information is front-loaded, covering purpose and use case efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a moderately complex mutation tool with no output schema, the description covers purpose and use case but lacks information about return format, error handling, or whether operations are transactional. Given the schema and annotations, it is adequate but not 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 parameters are already well-documented. The description mentions create/update/delete actions which map to the params but adds no extra meaning or parameter-specific guidance 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?
Description clearly states 'Batch create, update, or delete variations' which is a specific verb+resource combination. It distinguishes itself from individual variation tools by emphasizing 'in a single request' and efficiency.
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 guidance by stating it is 'More efficient than individual calls for setting up a variable product.' This implies when to use it (batch operations) and contrasts with individual calls, but does not explicitly state exclusions or alternative tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only include openWorldHint: false, providing no safety or side-effect information. The description says 'Create a new order' but does not disclose whether totals are auto-calculated, whether payment is required, if customer creation is needed, or what happens on failure. For a mutating e-commerce tool, this lacks behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and 21 words, front-loaded with the core purpose. Every phrase adds value, and it avoids unnecessary verbiage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter tool with nested objects and no output schema, the description is minimal. The schema covers parameter definitions well, but the description does not mention return value, default status behavior, or how optional billing/shipping/customer fields interact with the order creation. It is adequate but leaves gaps.
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 all parameters described, so baseline is 3. The description adds genuine semantic value with 'Use variation_id for variable product variants,' clarifying when to use that parameter beyond its schema description. The rest of the parameter guidance is redundant with 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 a new order,' which is a specific verb and resource that clearly distinguishes from sibling tools like update_order, delete_order, and list_orders. It also notes required fields and variation handling, further clarifying the tool's 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 clear usage context by stating line_items are required and advising to use variation_id for variable product variants. It does not explicitly name alternatives or exclusions, but the context is sufficient for an agent to know when to choose this tool over update_order or delete_order.
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=true, so the read-only nature is covered. The description adds grouping-by-status detail but does not disclose the return format or clarify the odd 'fields' parameter, which is important given no output schema exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the verb and resource. Every word earns its place, and the use case is integrated without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, but without an output schema, the description should clarify the return shape (e.g., map vs array) and the meaning of the 'fields' parameter. The current description leaves these ambiguous, which could hinder correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. However, the description adds no extra context about the 'fields' parameter, and the schema's parameter description ('Comma-separated fields to return (default: slug,name,total)') seems generic and possibly mismatched for this tool.
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 order counts grouped by status' with example statuses. This specific verb+resource pairing distinguishes it from siblings like list_orders or get_sales_report.
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: 'Useful for a quick store health overview.' This gives context for when to use it, though it does not explicitly name alternatives or exclusions.
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, covering safety. The description adds the grouping behavior by status and the quick-overview intent, but does not disclose other behavioral traits like pagination, limits, or response format. With the lower bar due to annotations, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loading the core action and status groupings, with no wasted words. The second sentence efficiently adds the use-case context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter, no output schema, and strong annotations, the description is sufficient. It conveys the essential purpose, grouping dimensions, and the quick-overview use case. The parameter details are covered by the 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% for the single optional 'fields' parameter, with a description providing default and format. The tool description itself adds no extra parameter context, so 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 a specific verb and resource: 'Get product counts grouped by status', and enumerates the statuses (publish, draft, pending, private). This distinguishes it from sibling tools like get_product and list_products, and aligns with the pattern of other totals tools (get_order_totals, get_customer_totals).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied via 'Quick catalog size overview', suggesting it's for summaries rather than detailed product listings, but there is no explicit when-to-use or alternative guidance. No exclusions or alternatives are named, so it doesn't reach the level of explicit guidelines.
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, indicating a safe read operation. The description adds domain context ('Zones define geographic regions...') but does not disclose additional behavioral traits such as pagination, ordering, or return format, so it meets the baseline for annotation-covered tools.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the action, no redundant words or repetition. The second sentence provides useful domain context without bloat.
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 simple tool (one optional param, no output schema, read-only annotation), the description adequately conveys purpose and scope. It explicitly says 'all' zones, and the schema handles parameter details, making it complete for 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 covers 100% of parameters with a description for 'fields' (Comma-separated fields to return, default: id,name,order). The tool description does not add any parameter semantics beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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 the resource 'shipping zones', clearly distinguishing it from get_shipping_zone and other shipping-related tools. It also defines what zones are, which disambiguates the domain.
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 'List all shipping zones' but does not explicitly mention when to use this tool versus alternatives like get_shipping_zone or list_shipping_zone_methods. Usage is implied but no exclusions or alternatives are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description is consistent. The description adds a note about webhooks sending POST requests, which describes the domain, not the tool's behavior. It does not disclose pagination or filtering specifics beyond what the schema provides, but annotations cover safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the purpose. The second sentence about webhook behavior is extra but not excessive. It is concise and to the point, with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with four well-documented parameters, readOnlyHint annotation, and no output schema, the description plus schema provides sufficient context. It lacks an explicit statement about return format, but the name and schema imply a list of webhooks. Overall, it is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters (page, fields, status, per_page) are documented in the schema. The description adds no additional parameter semantics, but the baseline of 3 applies because the schema carries the full weight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' with the resource 'webhooks', clearly identifying the operation. It also briefly explains what webhooks are, adding domain context. This distinguishes it from get_webhook (single), create/update/delete webhooks, and other list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the use case clear: to list webhooks. It does not explicitly mention alternatives like get_webhook for a single webhook or exclude other operations, but the context implies it is the listing tool. No when-not-to-use guidance is provided, but this is a simple read operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish idempotency. The description adds the typical status flow (pending -> processing -> completed), which is useful but minimal. It doesn't disclose other behavioral aspects like whether updating billing/shipping triggers side effects, but the annotations cover the core safety trait.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no waste. The main function is front-loaded, and the additional sentence adds a common use case and helpful pointer.
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 is adequate for a standard update tool, but it doesn't explicitly mention updatable fields beyond status (billing, shipping, customer_note) or clarify the response 'fields' parameter. The schema covers this, but the description could be more complete given the nested objects and no 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 description coverage is 100%, so the parameters are well defined. The description adds a cross-reference for statuses but doesn't enrich beyond the schema. The 'fields' parameter's purpose as a response filter is only in the schema, not reinforced in the 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 the tool updates an order, distinguishing it from create/get/delete order tools. It also provides a specific common use case (changing status) which further clarifies its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates when to use it (for updates, especially status changes) and points to get_order_totals for valid statuses, providing an alternative for status lookup. However, it doesn't explicitly exclude creation/deletion, though this is obvious from the name and siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a key behavioral trait: this tool does not add values to the attribute, and a separate call is required. However, with only openWorldHint:false in annotations and no other safety or mutation hints, the description could have added more context about duplication behavior, permissions, or response format. It partially compensates for sparse annotations but doesn't fully disclose behavior.
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 exactly two sentences, front-loaded with the core action and enriched with a relevant example ('e.g. 500g, 1kg'). Every word earns its place—no filler, no repetition of schema details, and no tangential 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 creation tool with five parameters (most optional), the description provides enough workflow context to guide the agent: start here, then use create_attribute_term. It lacks output schema and doesn't mention return values, but the absence is mitigated by the simplicity of the tool and the clear next-step reference. The description is complete enough for correct invocation in most scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% description coverage for all five parameters, including examples and defaults. The description adds minimal parameter-specific meaning beyond the schema, except implicitly suggesting a 'Weight' attribute example. With schema coverage that high, 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 'Create a global product attribute,' which is a specific verb+resource pair that clearly identifies the tool's function. It distinguishes itself from siblings like 'create_attribute_term' by explicitly positioning the latter as the next step for adding values, making the scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by stating this tool creates the attribute itself and directs the user to 'create_attribute_term' for adding values. While it doesn't explicitly say when not to use this tool, the guidance establishes the correct workflow and unobtrusively signals that this is not for term creation.
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 are minimal (only openWorldHint: false), so the description carries the burden. It discloses that creation is separate from adding tax rates, which is useful behavioral context. However, it doesn't mention permissions, side effects, or response format, leaving some gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The first sentence states the core action; the second provides a crucial workflow step and a concrete example. Every word earns its place, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple (2 params, 1 required, no nested objects, no output schema). The description covers the essential purpose, gives a usage example, and notes the next step (adding tax rates). It does not explain return values, but for a create operation this is not critical given the 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?
Schema description coverage is 100% (both 'name' and 'fields' are described). The description adds no parameter-specific detail beyond the example 'GST 5%' which hints at the 'name' usage. Baseline 3 is appropriate as the schema already provides adequate parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a custom tax class' with a specific verb and resource. It distinguishes the tool from siblings like list_tax_classes and delete_tax_class by focusing on creation. The example and follow-up instruction 'After creating, add tax rates to it' further clarify its unique 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 provides clear context: it's for creating custom tax classes and implies a workflow where tax rates are added afterward. It doesn't explicitly name alternatives or when-not to use it, but the example ('GST 5%' for food items) gives practical 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?
With only openWorldHint=false in annotations and no readOnly/destructive hints, the description carries the transparency burden. It adds useful input constraints (topic format, valid resources and events) but does not disclose side effects like confirmation messages, idempotency, or required permissions beyond the schema. This is moderate disclosure, not rich behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—three sentences that front-load the core action ('Create a webhook') and then provide essential formatting details. No wasted words; every sentence contributes to understanding the tool's primary input 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?
The tool has 6 parameters, no output schema, and sparse annotations. The description covers the most critical input constraint (topic composition) and lists valid resources/events, but does not mention return values or potential validation errors. Given the schema already documents field meanings, the description is sufficiently complete for a create operation, though it could briefly state the response behavior.
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%, providing baseline 3. The description adds value by enumerating valid resources and events for the 'topic' parameter, which goes beyond the schema's example and clarifies the exact format expected. This compensates for the lack of an enum 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 uses the specific verb 'Create' with the resource 'webhook', clearly distinguishing it from sibling tools like update_webhook, delete_webhook, and list_webhooks. It also provides the topic format ('resource.event') with concrete examples, 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 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 (for creating a new webhook) but does not explicitly state exclusions or alternatives such as using update_webhook for existing webhooks. The topic format and resource/event lists provide context on valid inputs, but no direct guidance on choosing between create and other webhook operations.
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 annotation destructiveHint already signals that this is a destructive operation. Beyond that, the description discloses an important behavioral consequence: removing the term from all products using it. This adds meaningful context about the cascading effect, though it does not cover other aspects like permissions or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the main action and then the key side effect. No unnecessary words or filler, and it delivers clear information in minimal 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?
For a delete tool with destructive annotation and complete parameter schema, the description covers the core purpose and a critical side effect. It doesn't specify return values, but no output schema is provided and this is typical for deletion tools. It is adequately complete given the simplicity of the 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 coverage is 100%, with descriptions for all four parameters. The tool description itself does not add further parameter semantics, but the schema already provides clear meaning (e.g., 'Term ID', 'Parent attribute ID'). Baseline 3 is appropriate since the description does not compensate or enhance beyond 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?
Description states a specific verb ('Delete') and resource ('a value from a product attribute'), and further clarifies the scope ('Removes the term from all products using it'). This clearly distinguishes it from sibling tools like delete_attribute and delete_attribute_term.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to delete a term from an attribute) but does not explicitly compare it to alternatives like delete_attribute or provide exclusions. It relies on the tool's name and context for differentiation, which is adequate but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint=true, and the description adds useful behavioral context beyond that: it explicitly states that products are not deleted, only unassociated. This disclosure goes beyond the annotation without contradicting it, providing important safety-relevant information.
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 two short sentences that front-load the purpose and immediately add the key nuance. There is no redundant wording or unnecessary detail, 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 simple delete operation, the description is sufficiently complete: it states the primary action and the important side effect (products not deleted), while the schema covers parameter semantics. It could optionally mention the force parameter's soft-delete implication, but that is already handled by the 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?
The input schema provides descriptions for all three parameters (id, force, fields), achieving 100% coverage. The description adds no additional parameter-specific meaning beyond what the schema already explains, 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 ('Delete') and resource ('product brand'), and clearly distinguishes itself from other deletion tools by noting that products are not deleted, simply losing the brand association. This provides clear scope and prevents confusion with delete_product or delete_category.
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 (when you want to delete a brand but keep its products) by stating that products only lose the association, but it does not explicitly name alternatives or provide exclusions. It gives clear context but no direct comparison to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include destructiveHint: true, so the agent knows it's destructive. The description adds valuable context by disclosing what gets destroyed ('all methods and locations in the zone'), going beyond the annotation. It does not mention the force parameter requirement, but the schema covers that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, efficiently front-loaded with the primary action and a critical detail about cascading deletion. No unnecessary words 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?
The description covers the main effect and cascade behavior, which is adequate for a simple delete tool with annotations. It does not explain return values (no output schema) or the force parameter, but those are defined in the schema. For its complexity, it is complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with descriptions for id, force, and fields. The tool description does not add any additional parameter semantics beyond the schema; it only explains the effect of deletion, not the parameters themselves. 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 'Delete a shipping zone' with a specific verb and resource, distinguishing it from sibling tools like update_shipping_zone, get_shipping_zone, and delete_shipping_zone_method. The cascade effect ('removes all methods and locations') adds further specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage 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 delete a shipping zone) but does not explicitly say when not to use it or provide alternatives. There is no mention of using update_shipping_zone to disable instead, or any other usage context beyond the inherent purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, but the description adds valuable context beyond that: 'Does NOT affect products that had this tag; they simply lose the tag association.' This discloses a non-obvious side effect (no cascading deletion), which is helpful. It does not mention irreversibility, but the 'force' parameter in the schema covers permanent deletion.
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 one well-structured sentence with an explanatory clause. It is front-loaded with the action and contains 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?
For a simple delete tool with complete schema coverage and a destructiveHint annotation, the description provides the essential purpose and a key behavioral side effect. It doesn't mention return values, but no output schema exists and the schema covers the request parameters, making this sufficiently complete for a 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?
Schema description coverage is 100%, with all three parameters (id, force, fields) individually documented. The description adds no new parameter-level meaning, 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 begins with 'Delete a product tag,' a specific verb and resource that clearly distinguishes it from sibling tools like delete_category and delete_brand. It also clarifies the scope by specifying 'product tag.'
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 clearly implies the tool's use case (deleting a tag) but provides no explicit guidance on when to use it versus alternatives, such as updating a product to remove a tag association without deleting the tag. Context is clear but exclusions/alternatives are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already indicates a safe read operation. The description adds behavioral context that the response includes description and product count, and that the fields param can limit the response. This goes beyond the annotation and clarifies the return data scope.
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 resource. The first sentence states the core purpose, and the second sentence gives a single actionable hint. 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?
The description is sufficient for a simple read operation. It covers the tool's purpose and key return contents. The fields param's default list in schema provides additional response structure. It lacks an explicit statement that a single object is returned, but this is implied by 'a category' and the get_ naming convention.
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 baseline is 3. The description adds a tip to use the fields param to request only needed fields, but this is not a new semantic beyond what the schema's param description already states. No further parameter meaning is added.
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 'Get' and resource 'category', and clarifies scope with 'full details including description and product count'. It clearly distinguishes from sibling list_categories, which is a list operation, 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a single category's full details are needed, but it does not explicitly contrast with list_categories or state when to use this tool instead. It does provide guidance for the fields param, which is a useful usage hint, but lacks explicit alternative comparison.
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 known. The description adds useful context about the content returned (billing, shipping, order history stats), which goes beyond the schema's field list. 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?
Two sentences with no wasted words. The first sentence states the purpose, the second provides a practical usage tip. Well front-loaded and efficient.
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 get tool with full schema coverage, the description is adequate. It lists key return areas but not every default field; the schema compensates. No output schema, but the description gives enough context for an agent to 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?
Schema descriptions cover both parameters fully (id and fields). The description's mention of using the fields parameter to request only needed fields adds minor usage guidance but does not significantly extend semantic 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's function: 'Get full customer details including billing and shipping addresses, order history stats.' This is a specific verb+resource pattern that distinguishes it from sibling tools like get_order or get_product.
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 retrieving a customer's details, but does not explicitly contrast with list_customers or other alternatives. The 'fields param' hint is about parameter usage, not about when to choose this tool over others.
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, so the agent knows it's a safe read. The description adds context about richer return data and the fields parameter but does not disclose additional behavioral traits like error handling or rate limits. This is acceptable for a simple read-only tool, so a mid-range score is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, direct and front-loaded, with no filler. Every word earns its place: it states the resource, the scope, what extra fields are returned, and how to optimize.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward single-product retrieval with two parameters and no output schema, the description is sufficiently complete. It explains what the tool does, how it differs from list_products, and how to limit fields. Minor gaps like error responses are not critical for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both id and fields documented. The description adds no new semantic meaning beyond the schema; it merely reiterates that fields can be used to request only needed fields. Baseline of 3 applies since schema carries the parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get full details of a single product by ID.' It uses a specific verb (get) and resource (product) and distinguishes itself from list_products by noting it returns more fields, including description, tags, brands, and variations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool by contrasting it with list_products ('Returns more fields than list_products') and provides usage guidance for the fields parameter. It lacks explicit exclusions or when-not-to-use scenarios, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, covering safety. The description adds return-content context (email, verification status) but does not disclose error behavior, auth requirements, or rate limits. With annotations present, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is directly informative, front-loaded with the verb and resource. 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 simple get-by-ID tool with high schema coverage and readOnly annotation, the description sufficiently conveys purpose and key return elements. It doesn't detail error cases or full return structure, but the fields param default enumerates available fields, and no output schema exists to need explanation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (id and fields) are already documented. The description's mention of specific fields adds a bit of context, but doesn't fundamentally enhance parameter semantics 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?
Description clearly states the action (get full details), the resource (a product review), and the identifier (by ID). It also highlights key included fields (reviewer email, verification status), distinguishing it from list_product_reviews and mutation tools like update_product_review.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when needing full details for a specific review ID. It does not explicitly mention alternatives or when not to use, but the singular by-ID nature and sibling set make the context clear.
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 safe. The description adds little behavioral context beyond the group examples; it does not disclose return format or any edge cases, but the bar is lower due to annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action, and every sentence adds value. The group examples are useful and not wasteful.
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 low complexity, full schema coverage, and read-only annotations, the description is nearly complete. It could have mentioned that list_setting_groups provides additional groups not listed, but the provided examples and schema are sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both group_id and fields already documented. The description's examples are somewhat redundant with the schema, though they add a bit of context about what each group contains, so it meets the baseline without exceeding it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets all settings in a group, using a specific verb and resource. It distinguishes itself from siblings like update_setting and list_setting_groups by focusing on reading settings within a group.
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 common group examples and their contents, giving clear context on when to use this tool. However, it does not explicitly mention alternatives or when not to use it, such as pointing to list_setting_groups for discovering all groups.
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 include readOnlyHint=true, so the agent knows this is a safe read operation. The description adds no extra behavioral context beyond what annotations provide, which is acceptable for a simple get-by-ID tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences, with no fluff. It states the core action and provides a useful pointer for finding IDs, earning its place without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the schema covers all parameters, annotations indicate read-only safety, and the tool is a straightforward get-by-ID, the description is sufficiently complete. The 'fields' parameter is documented in the schema, and the pointer to list_shipping_zones fills the main usage 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% with both parameters (id and fields) clearly described with types and defaults. The description does not add parameter-level details, but the schema already handles this, 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 'Get a shipping zone by ID', which is a specific verb and resource. It also distinguishes from sibling tools by pointing to list_shipping_zones for ID discovery, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence 'Use list_shipping_zones to find zone IDs' provides explicit context for when to use the list tool versus this one. It implies this tool is for when you already have an ID, but does not give explicit exclusions or alternative conditions.
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 safety profile is established. The description adds that results are ranked by quantity sold and filterable, but does not disclose return format or pagination. It adds some context but not rich behavioral details.
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 followed by filtering options. 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?
For a simple read-only list tool with well-documented schema parameters, the description sufficiently explains what it does and its filtering capabilities. The absence of output schema is acceptable as the tool's return is implied by the resource type.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters are documented. The description mentions 'period or date range' which maps to the period/date_min/date_max parameters, but does not add extra 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 tool's function: retrieving top-selling products ranked by quantity sold. This distinguishes it from siblings like list_products or get_sales_report by specifying the ranking criterion and the focus on top sellers.
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 (filterable by period or date range) but does not explicitly mention alternatives or when not to use it. It implies usage for sales analysis but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already covers safety, so the description only adds 'global' scope and examples. It does not disclose additional behavioral traits such as pagination behavior or return format, but the annotation reduces the burden; no contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with a clear verb-first structure. It front-loads the primary purpose and then adds a sibling pointer and parameter tip without any filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, read-only list tool with fully documented parameters and annotations, the description is nearly complete. It covers what the tool lists, where to find related values, and how to optimize field selection; a return-shape note would be useful but is not essential for this task.
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 mentions using the fields param to request only needed fields, which slightly reinforces the schema but does not add substantive new parameter semantics beyond what the schema already documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action and resource: 'List global product attributes' with concrete examples. It differentiates from the sibling list_attribute_terms by directing users there for attribute values, so there is no confusion about 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?
It explicitly tells users to use list_attribute_terms for values and to use the fields parameter to limit requested fields. It does not explicitly state when not to use this tool, but for a straightforward read-only listing this guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description isn't required to state safety. It adds value by disclosing that the tool returns aggregate data (order count and total spent) and that the fields param can be used to request only needed fields. This provides behavioral context about return contents beyond the read-only annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long and front-loaded with the core action and resource. The first sentence states what the tool does; the second adds a useful usage tip about the fields parameter. Every sentence serves a purpose with no 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 7-parameter list tool with no output schema, the description covers the essential behavior: filtering and return of per-customer aggregates. It does not explain pagination or sorting, but those are documented in the schema. The return data is partially described, which is adequate given the schema's field listing.
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, so the baseline is 3. The description mentions filtering by name, email, or role, which maps to search and role parameters, but it adds no syntax or format details beyond what the schema already provides. It does slightly reinforce the purpose of fields but not substantially.
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 ('Search and filter') on a specific resource ('customers'), and distinguishes from siblings like list_products or get_customer by noting it returns order count and total spent per customer. It unambiguously identifies this as a list/search tool for customers.
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 searching/filtering customers but does not explicitly state when to use this vs get_customer, create_customer, or update_customer. The presence of sibling tools suggests a listing/search context, but there is no explicit 'when not to use' or alternative guidance beyond the implied purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the tool's safety profile is known. The description adds context about search and MIME filtering, which are useful but already present in the schema. It does not disclose additional behaviors like pagination limits or response format, but with the annotations covering the core safety, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and every word earns its place. It directly states the tool's purpose and key filtering capabilities without redundant phrasing.
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 (five optional parameters, no output schema), the description covers the core functionality. It mentions search, MIME filtering, and field selection, which are the main entry points. It could mention return structure or pagination, but the schema already handles parameter limits, and the tool name implies a list response. This is complete enough for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all five parameters thoroughly. The description adds a nudge to use the fields param for requesting only needed fields, which is helpful but not essential. With full schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and clearly identifies the resource ('WordPress media library items'). It distinguishes from sibling tools like list_products and list_orders by explicitly naming the media library, and the mention of search and MIME type filtering adds purposeful detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: whenever you need to list media items. It does not explicitly mention alternatives or when not to use, but the context is clear without confusing exclusions. The inclusion of search and MIME filtering signals typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, which indicates a safe read operation. The description adds context about the returned data (refund amounts, reasons, who processed them) and a behavior hint about requesting only needed fields. It does not introduce any destructive implications, and it is consistent with the read-only annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long and front-loaded with the primary purpose. Every sentence serves a purpose: the first states what the tool does, and the second gives a practical usage hint. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no output schema, the description covers the core return content (amounts, reasons, who processed them) and the ability to select specific fields. Pagination is documented in the schema, so the description does not need to repeat it. It is sufficiently complete 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all parameters, including order_id, page, per_page, and fields. The description adds a usage tip ('Use fields param to request only needed fields') but does not provide semantic meaning beyond what is already in the schema, such as the meaning of fields or pagination defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all refunds for an order' with a specific verb and resource, distinguishing it from sibling tools like list_orders, list_order_notes, create_order_refund, and delete_order_refund. The additional detail about showing amounts, reasons, and processors further clarifies its purpose.
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 refund details for an order but does not explicitly state when to use this vs. alternatives (e.g., create_order_refund or delete_order_refund). There is no when-not-to-use guidance or mention of alternative tools, only a parameter tip about the fields parameter.
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 description need not restate safety. It adds domain context (what methods are) but does not disclose behavioral details like return format, pagination, or the effect of the 'fields' parameter. This is acceptable given the simple read-only nature, but no extra behavioral traits are revealed 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?
Two short sentences with no filler. The first sentence states the purpose directly, and the second provides useful context. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with good annotations and full schema coverage, the description is adequate. It doesn't explain return structure, but the rules say output schema isn't required for that. It could mention the 'fields' parameter's purpose, but the schema covers it. Overall sufficient for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description complements the schema by explaining that methods define shipping options, but it does not add syntax or format details beyond what the schema already provides. The examples of method types are helpful but not parameter-specific.
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 ('shipping methods') with a clear scope ('for a zone'). It also provides examples (flat rate, free shipping, local pickup) that distinguish this tool from siblings like list_shipping_zones or add_shipping_zone_method.
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: whenever you need to see shipping methods for a specific zone. Although it doesn't explicitly state alternatives or exclusions, there is no sibling tool that performs a similar list operation, so the context is sufficient. A slightly more explicit 'use this to...' could push it to 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the description need not repeat. It adds useful context by naming example utilities (clear_transients, recount_terms) and categorizing them as maintenance tools, which helps the agent understand the scope without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the primary action. Examples are parenthetical and don't distract. Every word 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 read-only list operation with one optional parameter and no output schema, the description is sufficiently complete. It conveys the tool's purpose and examples, and the field parameter hints at the return format. Minor gap: it doesn't mention that results can be filtered/paginated, but that's not essential here.
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 the 'fields' parameter fully described (comma-separated fields with default). The description adds no extra parameter detail, but the schema does heavy lifting, 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 clearly states the tool lists available system tools with specific examples, distinguishing it from sibling tools like run_system_tool. The verb 'list' and resource 'system tools' are 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 usage as a discovery mechanism for maintenance utilities but does not explicitly state when to use it versus related tools like run_system_tool or get_system_status. There is no exclusion guidance, but the purpose is clear enough for basic 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 readOnlyHint=true, so the read-only nature is known. The description adds minor context about variation fields (price, SKU, stock) and suggests using the fields parameter to limit response size. It does not disclose pagination behavior or other limitations, but with annotations covering the safety profile, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences, front-loaded with the primary action. Every sentence adds value with no repetition or fluff, making it efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with readOnlyHint and a schema covering pagination, the description is sufficient. It hints at response contents (price, SKU, stock) and the fields parameter for customization. Since there is no output schema, this level of detail is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters are already documented. The description's mention of the fields param adds no new semantic information beyond what the schema provides. Baseline 3 is appropriate as the schema carries the weight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'List all variations for a variable product.' This clearly distinguishes it from siblings like get_variation (single variation) and list_products (products list). The additional context about each variation having its own price, SKU, and stock further clarifies the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states exactly when to use the tool: when you need variations of a variable product. It provides clear context but does not explicitly name alternative tools or state when not to use it, stopping short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond the annotations by explicitly noting that only included fields are changed, implying omitted fields remain untouched. This is valuable for a partial-update tool. The annotations (idempotentHint=true, openWorldHint=false) already convey safety, and the description does not contradict 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 a single, concise sentence that immediately communicates the tool's purpose and a key usage rule. Every word adds value, with no unnecessary detail or repetition of schema 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 the tool's complexity (7 parameters, one nested object) and rich schema descriptions, the description covers the core requirement of what the tool does. It omits return value details, but since there is no output schema, that is not fully compensated. Overall, it is adequate for a CRUD update tool with good annotations and schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all 7 properties (100% coverage), so the baseline is 3. The description adds the general instruction to include only changed fields, which relates to parameter usage as a group, but it does not add deeper meaning to individual parameters beyond what the schema already 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 the action ('Update') and the resource ('a brand'), and lists the specific fields that can be modified (name, slug, parent, description, image). This distinguishes it from sibling tools like create_brand, delete_brand, or get_brand.
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 useful usage hint ('Only include fields you want to change') indicating partial-update semantics, but it does not explicitly state when to use this tool versus alternatives (e.g., create_brand for new brands). The context is implied by the tool name and sibling list, not explicitly articulated.
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 (idempotentHint, openWorldHint), the description discloses that only specified fields are changed (partial update) and that the fields param controls response content. This adds valuable context not available 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?
Two sentences, 30 words total. Purpose is stated upfront, followed by two actionable tips. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema and nested objects, the description, combined with rich parameter schemas and annotations, gives the agent enough context to invoke the tool correctly. It covers purpose, partial update semantics, and response field selection.
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 descriptions cover all parameters (100%), so the description adds little beyond repeating the fields param purpose. The mention of 'name, email, or addresses' maps to existing parameters but doesn't provide new semantics beyond 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 customer details with specific examples (name, email, addresses), using a specific verb and resource. It distinguishes from sibling tools like create_customer and get_customer by focusing on 'Update'.
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 usage guidance like 'Only include fields you want to change' and 'Use fields param to request only needed fields,' but it does not explicitly compare with alternatives such as create_customer or get_customer. It implies partial update behavior but doesn't state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds minimal behavioral context beyond the idempotentHint annotation. It notes that HTML is allowed in review content, but that is already in the schema. No contradiction with annotations; the description is safe but shallow.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the primary purpose, and every word earns its place. No redundancy or boilerplate.
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, the description adequately covers the main use cases and is complemented by full parameter documentation and an idempotency annotation. It could mention response behavior, but that is not critical given the context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with all parameters described. The description only restates the three main fields without adding detail beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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 as updating a product review and lists specific supported actions (status, text, rating). This distinguishes it from sibling tools like delete_product_review and 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?
It explicitly says when to use the tool by enumerating the three categories of changes (status, text, rating). It doesn't explicitly name alternatives, but the context is clear that this is for modifications, not deletion or retrieval.
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 include idempotentHint=true and openWorldHint=false, which already provide safety context. The description does not contradict these hints and adds minimal extra behavioral detail, such as that it updates only the named fields. It does not disclose potential side effects, partial update behavior, or return format, but the annotations lower the burden. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the exact purpose without any fluff or repetition. Every word earns its place, and it is appropriately sized for a straightforward update operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple CRUD update tool with no output schema and one required parameter, the description is sufficiently complete. It tells what can be updated, while the schema covers parameter details and annotations cover idempotency. It could mention the 'fields' parameter for controlling response fields, but that is documented in the schema and not essential for selection. Overall, this is complete enough for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters (id, name, order, fields) have clear descriptions. The tool description mentions 'name' and 'sort order' (mapping to 'name' and 'order'), but does not add additional meaning beyond what the schema provides. Baseline for high coverage is 3, and the description aligns with that.
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 the verb 'Update' and the resource 'shipping zone', and specifies the exact fields ('name or sort order') that can be modified. This clearly distinguishes it from sibling tools like create_shipping_zone, delete_shipping_zone, and update_shipping_zone_method.
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 indicates when to use this tool: when you need to change a shipping zone's name or sort order. While it doesn't explicitly name alternative tools, the scope is self-evident; if you need to update other properties or create/delete zones, other sibling tools would be appropriate. 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (idempotentHint=true, openWorldHint=false) already establish the safety profile. The description adds no behavioral context beyond what the schema already lists (e.g., parameters for enabled, title, order, settings). It is consistent with annotations and does not contradict them, but it does not disclose side effects, authorization needs, or response details.
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 combines purpose and usage guidance with zero redundancy or filler. Every word contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 7 parameters and nested settings object, the description adequately covers the action and key use cases. It does not explain prerequisites like how to obtain zone_id/instance_id, but those are in the schema and can be inferred from sibling list tools. Given no output schema, the description is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 7 parameters have descriptions. The tool description summarizes the main parameters (title, order, settings, enabled) but adds no new meaning beyond the schema. Baseline 3 applies since the schema carries the weight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('update') and resource ('shipping method in a zone'), and enumerates concrete actions (enable/disable, change title, order, configure settings). It distinguishes itself from sibling tools like add_shipping_zone_method and delete_shipping_zone_method.
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 identifies when to use the tool ('Use to enable/disable, change title, order, or configure settings like cost'), giving clear context. It does not mention alternatives or exclusions, but the usage scope is unambiguous relative to siblings.
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 only include openWorldHint=false, so the description carries the burden of behavioral disclosure. It does add useful traits: brands are hierarchical, can have images, and are assigned via update_product. However, it does not disclose return behavior, idempotency, duplicate handling, or permission requirements, leaving gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences with no filler. It front-loads the primary action, then adds relationship and workflow context, with every sentence earning its place.
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 6 parameters and no output schema, the description is missing some contextual details such as return value shape and error conditions. However, the schema covers parameter semantics, and the description provides essential relationship context. It is minimally viable but not fully complete for an agent invoking a create operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, establishing a baseline of 3. The description adds meaning beyond schema property descriptions by explicitly noting that brands are hierarchical and can have images, which enriches the purpose of the 'parent' and 'image' parameters. It does not detail 'fields' or 'slug', but the schema already describes those adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the specific verb+resource pair 'Create a product brand,' making the tool's purpose unmistakable. It also adds distinguishing context about hierarchy and images, and mentions the assignment workflow via update_product, which separates it from brand-related siblings like update_brand or delete_brand.
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 that products are assigned to brands via update_product with a brands array, giving clear cross-tool guidance on how to use this tool in a workflow. It does not explicitly name update_brand as the alternative for modifying existing brands, but the context is clear enough for an agent to infer the distinction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral context by explaining that categories are hierarchical and that parent ID enables subcategory creation, which goes beyond the minimal annotation (openWorldHint: false). However, it does not disclose potential side effects, error conditions, or authentication requirements. Given the sparse annotation, the description carries some but not rich behavioral disclosure.
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 short sentences, front-loaded with the primary purpose and no filler. Each sentence adds relevant information: the action, the key parameter behavior, and the overall hierarchical model. It is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with 6 parameters (including a nested object), no output schema, and minimal annotations, the description is adequate but not complete. It covers the hierarchical nature but leaves out expected response format, validation constraints, or error handling. The hierarchy detail helps, but there are clear gaps for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for all 6 parameters, so the baseline is 3. The description adds semantic value by explicitly connecting the 'parent' parameter to subcategory creation, clarifying its purpose beyond the schema's bare 'Parent category ID'. This extra help justifies a score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Create' with a clear resource 'product category', immediately distinguishing it from sibling tools like list_categories, get_category, update_category, and delete_category. The additional note about subcategories further clarifies its unique role in managing hierarchical categories.
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 indicates when to use this tool (to create a category or subcategory) and provides a key usage detail: setting parent ID for subcategories. It does not explicitly exclude other scenarios or name alternatives, but the context is clear enough for a create operation.
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?
With annotations limited to openWorldHint: false, the description carries the main behavioral disclosure. It adds useful constraints (unique code, supported discount types) but does not cover potential side effects, auth requirements, or error behavior. The create verb implies mutation, but no further safety or irreversible-action context is given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, purposeful sentences. The first states the action, the second adds a key constraint, and the third gives a performance tip. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 13-parameter create tool with no output schema, the description is somewhat minimal. It does not explicitly describe the return value (though fields param implies object retrieval) or permissions/error cases. However, the schema covers all parameter semantics, and the openWorldHint provides some closure. It's adequate but leaves gaps.
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 meaning to 'code' by stating it must be unique, and to 'fields' by advising to request only needed fields. It also reinforces the discount_type enum values. This goes slightly beyond the schema's 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 'Create a discount coupon,' a specific verb and resource. It further distinguishes the tool by listing supported discount types (percent, fixed cart, fixed product) and a unique-code constraint, clearly separating it from sibling tools like update_coupon or list_coupons.
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 indicates this is the tool for creating coupons ('Create a discount coupon') and adds practical usage advice ('Use fields param to request only needed fields'). However, it does not explicitly mention alternatives or when not to use it, such as pointing to update_coupon for existing coupons.
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 write nature ('Create') and adds a key behavioral constraint: email must be unique. It also mentions the 'fields' parameter to limit the response, providing some insight into output behavior. However, it does not detail error handling or what the default response contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the primary purpose. Each sentence adds meaningful information: the first explains what it does, the second covers key constraints and parameter hints. No redundant or filler words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so agents would need to understand the return value from the description. While the 'fields' parameter hint suggests a response can be customized, the description does not explicitly state what is returned by default. The nested billing/shipping objects are not explained, but the schema provides their property details. The description is adequate but leaves some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds extra meaning for the 'email' parameter by specifying it must be unique, which is not in the schema. It also reinforces the purpose of the 'fields' parameter. Other parameters (billing, shipping) receive no additional explanation, but the overall value exceeds the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and resource ('a new customer account'), making it distinct from sibling tools like create_product or create_coupon. The verb+resource pairing is unambiguous and differentiates it from other create 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 when creating a new customer but does not explicitly state when to use this tool versus alternatives like update_customer. It mentions the email uniqueness requirement, which is a constraint, but lacks clear exclusions or comparison to other 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 annotations declare readOnlyHint=true, so the description does not need to repeat that it is read-only. It adds value by specifying the exact categories of information returned, which is not obvious from the name alone. It also avoids 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 a single, front-loaded sentence that lists key detail areas without unnecessary words. Every phrase adds useful information, and it is appropriately sized for a simple read-only 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 tool's simplicity (one optional parameter, read-only annotation, no output schema), the description provides sufficient context. It covers the scope of the returned data and leaves parameter details to the schema. No critical gaps are evident.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully describes the only parameter 'fields' with a clear explanation of comma-separated values and defaults (100% coverage). The description's list of content areas mirrors the default fields, adding minimal new insight. At the baseline for full schema coverage, a score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Get' with the resource 'WooCommerce system status' and enumerates the exact areas covered (environment, database, plugins, theme, settings, security), making the purpose unmistakable. It distinguishes from sibling tools like list_system_tools (which lists executable tools) and get_settings (which retrieves specific settings).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by stating what the tool returns, but it does not explicitly address when to use this tool versus alternatives or when not to use it. There is no mention of related tools like list_system_tools or run_system_tool, leaving the user to infer the distinction from the 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?
The annotations declare readOnlyHint=true, and the description does not contradict this. It adds useful context about the returned data (description, product count) and the ability to filter fields. It does not cover error behavior or pagination, but for a simple read operation this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states the tool's purpose, the second gives actionable parameter guidance. No unnecessary words 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?
With a read-only annotation, simple 2-parameter schema, and no output schema, the description adequately conveys the return content and customization via fields. It is complete enough 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 input schema already covers both parameters with descriptions (100% coverage). The description's mention of the fields parameter reinforces the schema but does not add significant new meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('product tag'), and mentions concrete details returned ('description and product count'). This clearly distinguishes it from sibling operations like list_tags, create_tag, update_tag, and delete_tag.
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?
It provides advice on using the fields parameter ('Use fields param to request only needed fields'), but does not explicitly state when to use this tool over alternatives such as list_tags. The intended use case (full details of a single tag) is implied but not contrasted with other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, covering the safety profile. The description adds context about the included fields and the fields param, but does not discuss return format, error handling, or additional behavioral details. This matches the calibration baseline where annotations partially cover transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action, and no wasted words. It efficiently communicates purpose and a key usage tip.
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 single-resource getter with complete schema coverage and strong annotations, the description provides sufficient context. It covers what the tool returns and how to limit fields, leaving no obvious gaps for an AI to correctly select and invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with descriptions, so the baseline is 3. The description reinforces the 'fields' parameter's purpose ('request only needed fields') but adds no additional semantic distinction 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 a specific action ('Get full details of a single variation') and names key content fields (price, stock, weight, attributes), distinguishing it from list_variations (which lists many) and create/update variation tools. It clearly targets a single resource by ID.
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 phrase 'a single variation' implies use when one specific variation is needed, contrasting with list_variations for multiple. However, it does not explicitly name alternative tools or state 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds that the list includes states/provinces and covers all available countries. Since the annotations already declare readOnlyHint=true and openWorldHint=false, this is additional context but does not cover pagination, return structure, or other edge-case behaviors. 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, with the main action in the first and a practical use case in the second. No wasted words, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter and no output schema, the description adequately conveys what is returned (countries with states/provinces) and when to use it. The annotations and schema handle the rest, so 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 input schema provides a complete description of the 'fields' parameter, including its default value. The description itself does not elaborate on parameter usage, but the schema fully covers it, 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 clearly states the tool lists all countries available in WooCommerce, including states/provinces. The verb 'list' and specific resource 'countries' make its function obvious, distinguishing it from sibling tools like list_currencies or list_shipping_zones.
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: setting up shipping zones and tax rules. However, it does not mention alternative tools or exclusion criteria, so it falls short of explicit when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set readOnlyHint=true, so the read-only nature is disclosed. The description adds that it shows specific fields and usage stats, but no additional behavioral traits (e.g., pagination behavior, rate limits) are mentioned. With annotations covering the safety profile, this is adequate but not enhanced.
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 action. It includes essential return fields and a helpful hint about the fields parameter without any filler or redundant 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 4 optional parameters covered in the schema and no output schema, the description is complete. It explains what the tool does, what data is returned, and how to tailor the response. There are no missing critical details given the tool's 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?
Schema description coverage is 100% for all 4 parameters (page, fields, search, per_page). The description only mentions the 'fields' parameter, which is already fully described in the schema. Therefore, the description adds little semantic value beyond the schema, matching the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List discount coupons' with a specific verb and resource. It distinguishes itself from sibling tools like get_coupon, create_coupon, and delete_coupon by focusing on listing. It also specifies the key fields returned (code, type, amount, usage stats), 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?
The description makes it clear this is for listing coupons, which is the appropriate use case versus get_coupon for a single coupon. It provides usage advice for the 'fields' parameter ('request only needed fields'). However, it does not explicitly mention alternatives or when not to use this tool, though the sibling list provides 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?
The description discloses a key behavioral trait beyond the annotations: that only specified fields are updated and omitted fields remain unchanged. This complements the idempotentHint annotation and adds context about the operation's partial-update nature. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single 17-word sentence that is front-loaded with the verb and resource. It includes essential usage guidance without any fluff or unnecessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 14 parameters, nested objects, and enums, but the description only lists a few example fields. It does not mention the required product_id and id, nor does it clarify the return value (no output schema). The partial-update guidance is helpful, but the overall description is minimal given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for all 14 parameters (100% coverage), establishing a baseline of 3. The description adds cross-cutting semantic value by clarifying that only provided fields are changed, which affects how all parameters should be interpreted. It does not repeat the schema descriptions directly.
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 (update), the resource (a variation), and key fields (price, stock, SKU). It distinguishes the tool from siblings like update_product and create_variation by specifying it applies to variations and is an update operation.
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 instruction 'Only include fields you want to change' provides a useful usage parameter guideline, implying partial-update behavior. However, it does not explicitly state when to use this tool over alternatives like batch_update_variations or get_variation, nor does it mention any exclusions or prerequisites.
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?
Without safety annotations (only openWorldHint: false), the description carries the burden. It states the action and that rates are configured later, clarifying scope, but does not disclose whether the operation is idempotent, fails on duplicates, or any authorization requirements. This is a minor gap for a simple add 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?
Two sentences, front-loaded with the action, and every sentence contributes: the first states what the tool does, the second gives valid values and a follow-up step. 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?
For a tool with 3 params, full schema coverage, and no output schema, this description covers the purpose, valid inputs, and post-add behavior. It lacks explicit return value info, but that is not critical given the absence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by explicitly listing valid method_id values and explaining that rates are configured after adding, which provides practical meaning beyond the schema's enum list.
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 'Add a shipping method to a zone,' which is a specific verb+resource. This distinguishes it from sibling tools like list_shipping_zone_methods, update_shipping_zone_method, and delete_shipping_zone_method by the operation type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on valid method_id values and instructs the agent to configure rates via settings after adding, which clarifies the tool's scope. It does not explicitly mention alternatives, but the operation is self-evident and supported by sibling tool names.
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 behavioral context beyond the minimal annotations. It discloses that the default is a private admin note and that customer_note=true triggers an email notification to the customer. This goes beyond the schema and annotations to inform the agent of 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 extremely concise, consisting of three sentences that are all informative. It front-loads the core action ('Add a note to an order') and immediately provides the key behavioral nuance without any 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 create tool, the description covers the core behavior and the important parameter nuance. It does not explain the optional 'fields' parameter, but the schema fully documents it. The absence of an output schema is not a significant gap here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds extra semantics for the customer_note parameter by explaining the email notification and the default private note behavior, providing value beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Add a note to an order.' This is a specific verb and resource, and it distinguishes itself from sibling tools like list_order_notes and delete_order_note by focusing on the creation aspect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by stating 'Add a note to an order' and explains the behavior of customer_note, but it does not explicitly mention when to use this tool versus alternatives or provide exclusions. The guidance is clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only openWorldHint=false in annotations, the description carries the burden of disclosing behavior. It accurately discloses that a refund is created and explains the automatic/manual behavior of api_refund. It omits potential side effects (e.g., order status changes), but the core behavior is transparent and non-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 long, front-loaded with the primary purpose, and every sentence adds value (purpose, amount flexibility, api_refund behavior). There is no redundancy or fluff, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with 6 params, 1 required, and no output schema, the description covers the core functionality: what it does, amount scope, and the key api_refund option. While it lacks explicit mentions of prerequisites or side effects, the schema fully documents parameters and the description adds behavioral context, making it adequately 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?
Schema coverage is 100%, so the baseline is 3. The description reinforces the meaning of amount ('full or partial') and api_refund (automatic vs manual), but these are already documented in the schema. It adds minimal new information beyond the schema, so a 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 function: 'Create a refund for an order.' It distinguishes from sibling tools like delete_order_refund and list_order_refunds by focusing on creation. It also specifies key capabilities (full/partial amount) and a distinguishing feature (api_refund toggle), 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?
The description provides context for usage: it explains how to perform a full or partial refund and how to choose between automatic and manual refunds via the api_refund flag. It doesn't explicitly name alternatives or exclusions, but the usage context is clear and practical.
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 destructiveHint annotation by clarifying that products are not deleted but become uncategorized. This is a valuable non-obvious side effect. It does not mention the soft-delete versus permanent-delete nuance, but the schema already documents the 'force' parameter, so the description's disclosure is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. It immediately states the core action, then adds the essential caveat. No wasted words or redundant padding, 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 simple delete tool with annotations and a well-described schema, the description captures the most critical contextual detail: products become uncategorized. It does not explain return values or mention soft-delete behavior, but those are not essential for this tool's primary usage, and the schema covers the force parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters (id, force, fields) are fully described in the schema, providing 100% coverage. The description itself adds no parameter-specific information, so per the rubric 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 opens with the specific verb-resource pair 'Delete a product category', clearly stating the tool's purpose. It also distinguishes from sibling delete tools by adding the key clarification that products within the category are not deleted but become uncategorized, which resolves any ambiguity about cascading 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 provides clear context for when to use the tool by stating the action and its immediate consequence. However, it does not explicitly mention alternatives or when not to use it (e.g., using delete_product to remove category products first), so it stops short of full usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral context beyond the destructiveHint annotation by explaining that the default is a soft delete (trash) and force=true triggers permanent deletion. It also implies reversibility for the default path. This is valuable additional information not present in 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 short sentences, with the core action first and the important modifier (force behavior) immediately following. Every word earns its place; 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with destructiveHint and no output schema, the description covers the essential decision (trash vs permanent). It doesn't mention the return value despite the 'fields' parameter, but that's a minor omission; the tool's behavior is well understood from 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?
All parameters are already well-described in the input schema (100% coverage), and the description mostly reiterates the force parameter's meaning. It adds the 'trash' context for the default path, but the schema already covers the semantics of id, force, and fields adequately. The description adds minimal new semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Delete a coupon') and resource, and distinguishes itself from sibling delete tools by noting the trash-vs-permanent behavior. The verb and resource are explicit 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?
It provides clear guidance on the default trash behavior versus force=true for permanent deletion, which is directly actionable. However, it doesn't explicitly name alternative tools (e.g., update_coupon or list_coupons) or state when not to use it, so it stops 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?
Annotations already declare destructiveHint:true. The description adds valuable behavioral detail beyond that: it removes the refund entry but leaves the payment intact, and it warns to use caution. This meaningfully augments the structured 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 consists of two concise sentences, immediately starting with the action. Every phrase serves a purpose, with no redundant or fluff content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential aspects for a destructive tool: what it deletes, what it does not affect, and a warning. However, since there is no output schema, it does not describe the response format or the effect of the 'fields' parameter, leaving a minor 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?
The input schema has 100% description coverage for all parameters, including the meaning of 'force' (must be true to permanently delete). The description itself does not add parameter-specific details, 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 'Delete' and a resource 'refund record from an order,' clearly distinguishing it from refund creation (create_order_refund) and listing (list_order_refunds). It also adds the key clarification that payment is not reversed, which defines its unique 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?
Provides clear context that the operation does not reverse payment and includes a caution to use with care. This implies when to use the tool (to remove a refund entry) and when not (if payment reversal is intended). No alternative deletion tool exists among siblings, so explicit exclusion is not needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint: true, so the destructive nature is known. The description adds meaningful context by stating that products using the class will revert to no shipping class, which is a behavioral consequence not covered by annotations. This goes beyond the schema's parameter descriptions.
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 at two sentences, with the primary action front-loaded. Every sentence adds value: the first states the core function, the second explains an important side effect. No redundant or vague language.
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 destructive behavior, a required id, a force parameter with a note, and a fields parameter for output. The description covers the main behavioral consequence, and the schema/annotations handle the rest. While it doesn't mention the return value or force requirement explicitly, those are documented in the schema, making the overall context sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter description coverage, including the id, force, and fields parameters. The description adds no parameter-specific information, so the baseline score of 3 is appropriate since the schema already documents the parameters thoroughly.
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 'Delete a product shipping class' with a clear verb and resource, and the additional sentence about products reverting to no shipping class distinguishes this from other delete operations like delete_category or delete_tag. It is specific and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (when you need to delete a shipping class) and describes the consequence on associated products. However, it doesn't explicitly mention alternatives or when-not-to-use scenarios, but the resource-specific wording makes the usage context 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, so the safety profile is known. The description adds value by specifying the kind of details returned (usage limits, restrictions, expiry) and that the fields param can filter output, going 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?
Two concise sentences, front-loaded with the core purpose and then a helpful usage tip. 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?
The tool is simple with two params and no output schema. The description covers the essential behavior and return content, and the schema provides the rest. 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?
Schema coverage is 100%, with both id and fields described in the schema. The description's mention of the fields param adds no new semantic detail beyond the schema, 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 clearly states the tool 'Get full coupon details' with specific resources mentioned: usage limits, product restrictions, and expiry date. This distinguishes it from sibling tools like list_coupons, which lists coupons, and other get_* tools for different resources.
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 this tool is for retrieving a single coupon's full details, contrasting with list_coupons for listings. It provides clear context on using the fields param to limit response size, but does not explicitly mention alternatives or when-not-to-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only safety. The description adds value by detailing the contents of the response (billing, shipping, line items, payment info) and the field-selection capability, providing more context than the annotation 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?
Two concise sentences with a clear purpose statement followed by a practical tip. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with two parameters, the description sufficiently explains what the tool returns and how to tailor it. It does not explain error cases or require exact output structure, but given the absence of an output schema, the listing of included details is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already explains both 'id' and 'fields' with defaults. The description's mention of 'fields param' is a minor reiteration, adding little semantic meaning beyond the structured 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 verb 'Get' with a specific resource 'single order' and lists the included content (billing, shipping, line items, payment info), which distinguishes it from list_orders and other order-related 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?
It implies usage for retrieving full details of an order, and the 'Use fields param' tip gives practical guidance. However, it does not explicitly name alternatives or state 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is known. The description adds useful filtering context (parent for subcategories, hide_empty for unused categories) but does not disclose likely return volume, pagination behavior, or authorization requirements. This is acceptable given annotation coverage but no rich additional behavior is revealed.
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 main purpose. Each sentence adds value: listing, filtering options, and field selection. No redundant or vague text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward read-oriented list tool with 8 parameters, the description covers the key filtering capabilities (parent, hide_empty) and field selection. Pagination and sorting are schema-documented with defaults, so their absence is not critical. It is sufficiently complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all 8 parameters. The description adds semantic meaning beyond the schema: clarifying that 'parent' filters for subcategories, 'hide_empty' skips unused categories, and 'fields' limits response fields. This helps the agent understand why/when to use these 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 begins with 'List product categories,' which is a specific verb+resource that clearly differentiates it from sibling list tools like list_products or list_tags. It unambiguously states the tool's primary function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing categories and provides context on filtering (by parent, hide_empty, fields). It does not explicitly mention when to use this over alternatives, but the resource-specific operation is clear given sibling names. No exclusions are needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only (readOnlyHint: true), so the description doesn't need to restate safety. It adds value by explaining that each rate defines tax for a region and that filtering is possible, which are useful behavioral details 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 concise, with three short sentences that first state the primary purpose, then a usage tip, then a domain note. 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?
For a simple list endpoint with four fully documented parameters and no output schema, the description covers purpose, filtering, and domain semantics. It does not mention pagination or field selection, but these are implied by the schema defaults, so the overall context is adequate without being exhaustive.
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 a small note about filtering by 'class', which aligns with the 'class' parameter, but doesn't elaborate on the meaning of other parameters or their interaction 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 ('List tax rates') with a specific resource, and adds context about filtering by class and regional scope. This distinguishes it from sibling tools like list_tax_classes (which lists classes) and get_tax_rate (which retrieves a single rate).
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 usage context by illustrating how to filter by tax class ('Filter by tax class to see rates for a specific class'). It does not explicitly name alternatives or exclusions, but the intended use case is clear from the phrase and the tool's 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 already provide idempotentHint=true, and the description adds meaningful context about partial update behavior ('Only include fields you want to change'), which informs the agent that unspecified fields are preserved. It doesn't cover auth or error handling, but the key behavioral trait is disclosed 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 two short sentences with no filler. It front-loads the purpose and immediately provides actionable usage guidance, making every word valuable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 14-parameter update tool with full schema coverage and no output schema, the description effectively conveys update semantics and response control. It omits the requirement for 'id' (though present in schema) but is otherwise complete for typical usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description lists general fields ('code, amount, restrictions, or expiry') but adds no detail beyond what the schema already documents. The 'fields' parameter is mentioned, but its semantics are clear from 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 'Update a coupon's code, amount, restrictions, or expiry' with a specific verb and resource. It distinguishes from siblings like create_coupon, get_coupon, and delete_coupon by explicitly targeting updates to specific coupon attributes.
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: 'Only include fields you want to change' signals partial update semantics, and 'Use fields param to request only needed fields' explains response filtering. It doesn't explicitly mention alternatives (e.g., create_coupon for new coupons), but for an update tool the usage is implied by the action.
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 only provide idempotentHint and openWorldHint, with no readOnly or destructive hints. The description adds meaningful behavioral context by explaining that gateways originate from plugins and cannot be created or deleted, which clarifies the resource lifecycle. It also implies modifications are persistent. This goes beyond the annotations, though it does not detail side effects like how the enabled flag affects checkout or whether settings are merged or replaced.
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 exactly two sentences, front-loaded with the primary action and immediately providing use cases. Every word earns its place, and there is no fluff or repetition of schema details. This is optimally concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 7 parameters and a nested settings object, but the schema covers all parameters. There is no output schema, so a mention of return type would help, but the description provides essential operational context (what actions are possible, lifecycle constraints) that makes the tool usable. It doesn't explain response behavior or whether the update replaces all settings, but these are minor gaps given the simplicity of the tool and the presence of list/get sibling tools for reference.
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 per the rubric. The description's mention of 'enable/disable, change titles, or modify settings' maps to the enabled, title, and settings parameters, but does not add meaning beyond the schema's own descriptions. It does not clarify nuances like how the settings object merges with existing settings, which could be a semantic gap, but the schema already thoroughly documents each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Update') and resource ('payment gateway'), and lists concrete actions (enable/disable, change titles, modify settings). It also distinguishes the tool from potential create/delete operations by explicitly noting that gateways cannot be created or deleted, which differentiates it from any sibling tools that might perform those actions.
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 explicit usage examples ('use to enable/disable gateways, change titles, or modify settings'), giving clear context for when to use the tool. It does not explicitly name alternative tools like list_payment_gateways or get_payment_gateway, but the guidance that gateways come from plugins and cannot be created/deleted effectively tells the agent not to attempt those operations. This is clear context, though it lacks a direct 'when not to use' statement referencing siblings.
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 openWorldHint=false, which covers the safety profile. The description does not add additional behavioral context (e.g., whether updates are instantly applied or response format), so it adds minimal value 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 two sentences plus an example, front-loaded with the verb and resource. Every sentence earns its place with practical guidance, and the example is compact and illustrative.
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 4 parameters and no output schema, the description covers the workflow (get_settings first), the example, and the scope (single setting). It lacks explicit return value info, but combined with the annotations and schema, it is reasonably 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 all parameters are documented. The description adds value by telling the agent to use get_settings to discover valid options and providing an example that maps group_id, setting_id, and value, which clarifies how the parameters relate.
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 'Update a single setting value' clearly identifies the action (update) and the specific resource (setting value), which distinguishes it from sibling tools like get_settings (read) and other update_* tools for different resources. The example reinforces this with a concrete scenario.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to call get_settings first to find the setting ID and valid options, providing clear prerequisite usage. It does not explicitly mention when not to use this tool or alternatives, but the context is sufficient for a generic setting update tool.
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 provide idempotentHint=true, which partially covers safety. The description adds minor behavioral detail like 'pause/resume' for status, but does not disclose other behaviors (e.g., return format, authentication needs). This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence that front-loads the verb and resource, then lists the specific fields. No wasted words; every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters, a simple schema, and an idempotency annotation, the description covers the essential use case. It doesn't mention response shape, but no output schema exists and the description still provides sufficient context for an update operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that status updates correspond to pause/resume behavior, going beyond the schema enum definitions. Other parameters are adequately covered by 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 a webhook and lists specific changeable elements (delivery URL, topic, status, secret). This distinguishes it from sibling tools like create_webhook, get_webhook, and delete_webhook.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool ('Use to change delivery URL, topic, status (pause/resume), or secret'), implying modification of existing webhooks. It doesn't explicitly state exclusions, but the purpose is clear enough in 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?
The annotations include destructiveHint=true, and the description adds valuable context beyond that: it explains that deletion is opt-in via delete=true and that the default is a dry run. This discloses a safety behavior not inferable from the annotation alone, though it could further mention permanence of deletion.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose, and no redundancy. Every clause adds relevant information: what the tool finds, the dry-run default, the delete trigger, and the scan scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional boolean parameter, no required fields, and no output schema, the description covers all necessary context: purpose, scope, safety default, and how to trigger deletion. The absence of an output schema is acceptable since the tool's behavior is fully described.
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%, as the single 'delete' parameter is fully documented in the schema itself. The description repeats the same information ('set delete=true to remove them') without adding semantics beyond the structured data, 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's purpose with a specific verb ('Find') and resource ('orphaned media'), and defines its scope ('not used by any product or category'). This distinguishes it from siblings like list_media and delete_media, which are generic listing/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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: it scans all products and categories, and the dry-run default with delete=true to remove items tells the agent how to invoke it safely. It doesn't explicitly contrast with alternatives, but the unique purpose of finding orphaned media is implicit guidance for when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive behavior, but the description adds critical context beyond that: the inability to delete the Standard class and the consequence of orphaned rates. These are meaningful operational details that help the agent anticipate side effects and potential errors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no filler. Every clause adds value: the action, the restriction, and the consequence. It is front-loaded and immediately informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation, the description covers the essential aspects: what it does, the key limitation (Standard class), and the side effect (orphaned rates). With the annotations and schema fully covering parameters and destructive nature, no critical information is missing for an agent to invoke this tool safely.
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 three parameters are already well-documented in the input schema. The description adds little beyond confirming the operation is 'by slug', which directly maps to the required parameter. No additional parameter meaning is provided beyond what the schema offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Delete a tax class by slug') with a clear resource and method, distinguishing it from sibling tools like delete_tax_rate or delete_shipping_class. It also adds important scope constraints (cannot delete Standard class), 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?
The description provides clear context and exclusions: it warns that the Standard class cannot be deleted and that rates will be orphaned. While it doesn't explicitly name alternative tools, the sibling list allows the agent to infer this tool is for tax classes, and the warning effectively tells the agent when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds value by disclosing that the response includes sensitive fields like 'secret' and 'API version'. This alerts the agent that the output contains confidential data, which is behavioral context not present in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no redundancy. Every word contributes: verb, resource, scope, and noteworthy response contents.
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 retrieval tool with 100% schema coverage and readOnlyHint annotation, the description is fully sufficient. It tells the agent exactly what the tool does and highlights the sensitive data returned, with no missing 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?
Input schema provides 100% coverage with descriptions for both 'id' and 'fields'. The description only references 'by ID' and doesn't clarify the 'fields' parameter, but the schema already handles that. Since schema does the heavy lifting, a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Get' with resource 'webhook' and scope 'by ID', clearly distinguishing it from sibling tools like list_webhooks, create_webhook, update_webhook, and delete_webhook. The mention of 'full details' and 'secret and API version' sets it apart as the detailed getter for a single webhook.
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 it should be used when retrieving a single webhook's full details by ID, which clearly contrasts with list_webhooks for listing. However, it does not explicitly name alternatives or state when not to use it, so it doesn't earn a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals a safe read operation. The description adds behavioral context beyond the annotation by noting the WooCommerce 9.6+ version requirement and the ability to request only needed fields via the fields parameter, which is useful for performance and response shaping. 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 two short sentences with no filler. It front-loads the core purpose ('List product brands'), then adds key operational details (version, filtering, field selection) efficiently. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity, 100% schema coverage, clear read-only annotations, and no output schema, the description is sufficient. It covers the essential context: what it does, version constraint, filtering options, and field optimization. No critical gaps remain for an agent to 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?
Schema description coverage is 100%, so the baseline is 3. The description mentions parent, hide_empty, and fields, but the schema already explains these parameters fully. The only added semantic value is the recommendation to use the fields param to request only needed fields, which is a mild usage tip but does not substantially go 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 with a specific verb and resource: 'List product brands'. It distinguishes itself from sibling list tools (e.g., list_categories, list_tags) by naming 'brands' as the target and adding the WooCommerce 9.6+ context, 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?
The description provides clear use context: to list product brands, with mentions of filtering by parent and hide_empty, and advice to use fields for selective retrieval. It does not explicitly name alternatives like get_brand for single-brand retrieval, but the listing context is evident and no exclusions are 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 provide readOnlyHint=true, so the read-only nature is already known. The description adds useful behavioral context by specifying that both private and customer-visible notes are returned, which is not derivable from annotations. It also hints at response optimization via fields, though no pagination or sorting details are 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 two short sentences, front-loaded with the core purpose. Every sentence adds value: the first states what and the second provides usage guidance. No filler 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 tool's simplicity (2 params, no output schema), the description covers the essential context: what it lists, what note types are included, and how to request only needed fields. This is sufficient 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?
Schema coverage is 100%, so the parameters are already well-documented (order_id, fields with defaults). The description's mention of using the fields parameter adds marginal emphasis but does not introduce new semantic information beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'List all notes for an order.' It also adds specificity by noting it includes both private admin notes and customer-visible notes, which distinguishes it from note creation/deletion tools and clarifies 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 implies when to use the tool (when you need an order's notes) and gives guidance on using the 'fields' parameter to limit response size. It does not explicitly state when not to use it or mention alternatives, but the context is clear enough given sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true, and the description adds meaningful context that gateways are plugin-provided and immutable via API. This explains why there is no create/delete operation and aligns with the read-only annotation, adding value beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the primary action and resource, followed by a concise but relevant note about plugin-provided gateways. No filler or redundant 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 list tool with one optional parameter and a read-only annotation, the description is complete. It covers the scope (all gateways), the immutable nature, and is fully supported by the schema. No output schema exists, so return format is not required to be explained.
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 fully documents the single optional 'fields' parameter with a default list of fields. The tool description does not mention parameters, but with 100% schema coverage, the schema carries the semantic burden. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all available payment gateways, using a specific verb (list) and resource (payment gateways). It also notes gateways are plugin-provided and cannot be created/deleted via API, which effectively distinguishes it from sibling tools like get_payment_gateway and update_payment_gateway.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating it lists all gateways and clarifying they cannot be created/deleted, which tells the agent this is the read-only listing operation. However, it does not explicitly reference alternatives (e.g., 'for a single gateway, use get_payment_gateway'), so it falls short of full explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation openWorldHint=false provides minimal behavioral context, and the description adds little beyond stating the creation action. It doesn't disclose side effects, idempotency, or error behavior, but because annotations exist, the burden is partially met. 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 concise sentences, front-loaded with the primary action. The first sentence states purpose, the second provides a pragmatic alternative, with zero 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?
For a simple create tool with no output schema, the description covers the core purpose and the main alternative. It doesn't mention the optional 'fields' parameter, but the schema already documents that. Given the low complexity, the description is sufficiently complete for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 with the example 'add 2kg to Weight', clarifying that 'name' is the term value and 'attribute_id' must reference the desired attribute. This helps map example values to schema 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 'Add a new value' and identifies the resource as a product attribute term. It provides a concrete example ('2kg' to Weight) and explicitly contrasts with the batch sibling tool, making its purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states 'Use batch_update_attribute_terms for multiple values at once,' giving a clear alternative for batch operations. This establishes when to use this tool (single value) versus the batch tool (multiple values), satisfying the when/alternative criteria.
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 are minimal (only openWorldHint: false), so the description carries the burden. It discloses one key behavioral trait: that for variable products, the tool only creates the parent and variants must be added via create_variation. However, it does not mention other behavioral aspects such as permission requirements, response format, or side effects beyond creation.
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. The second sentence adds essential guidance for variable products without any fluff or repetition of schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 21 parameters, the description provides sufficient context for the most complex scenario (variable products) and the schema covers all parameter details. No output schema exists, but the description's focus on the variable product workflow makes it quite complete for a create operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already well-documented. The description adds extra meaning by instructing to set type='variable' and include the attributes array for variable products, which reinforces the semantics of those parameters 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 'Create a new WooCommerce product' with a specific verb and resource. It also distinguishes the tool's scope by noting that for variable products, the type must be set and attributes included, then create_variation is used for variants, which differentiates it from sibling tools like update_product and delete_product.
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 explains when to use this tool for variable products ('set type='variable' and include attributes array') and directs the user to an alternative tool for the next step ('then use create_variation to add variants'). This provides 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, so the destructive nature is known. The description adds critical behavioral context beyond that: it deletes all attribute terms and removes the attribute from all products. This cascading effect is exactly the kind of disclosure that helps an agent avoid unintended data loss.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence conveys the full destructive scope without unnecessary words. It's front-loaded with the core purpose and immediately adds the high-stakes side effects.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is sufficient for a destructive delete operation, covering the most important side effects (terms, product associations). It doesn't describe return values, but no output schema exists and return values are less critical for a delete tool. Omitting the 'force' requirement is acceptable since the schema documents 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 covers 100% of parameters (id, force, fields) with descriptions for each. The tool description adds no extra parameter information, but given the complete 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?
Description clearly states the action ('Delete'), the resource ('global product attribute'), and the full scope ('all its terms' and 'removes the attribute from all products'). This distinguishes it from sibling tools like delete_attribute_term or delete_category.
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: use when you want to delete an entire global attribute including its terms and product associations. It doesn't explicitly say 'when not to use' or name alternatives, but the sibling set (delete_attribute_term, delete_category) makes the distinction sufficiently 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 destructiveHint: true, but the description adds critical context that the action is permanent and irreversible. This goes beyond the annotation and helps the agent understand the consequence. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action, and every clause earns its place. The warning about irreversibility and the pointer to cleanup_orphaned_media are both valuable and succinct.
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 delete operation with two parameters and no output schema, the description is sufficiently complete. It covers the action, the risk, and a recommended pre-check. It doesn't mention response format, but that is less critical for a delete tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (id and fields are both documented). The description doesn't add extra meaning about parameters beyond what the schema provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Permanently delete'), the resource ('a media item from WordPress'), and emphasizes irreversibility. It also differentiates from the sibling tool cleanup_orphaned_media by positioning that as a pre-step rather than the deletion itself.
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 recommends using cleanup_orphaned_media to find unused items before deletion, providing a clear alternative and prerequisite. This gives strong guidance on when and how to use the tool safely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals a behavioral nuance beyond the destructiveHint annotation: the default operation is a soft delete (trash) and force=true changes it to permanent deletion. This additional context is valuable and not present in the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a two-sentence, front-loaded statement with no extraneous content. It efficiently communicates the core action and the key behavioral option.
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 schema and annotations, the description covers the essential behavior and the main parameter nuance. It does not explicitly describe the return value, but the presence of a 'fields' parameter in the schema implies a response object, making the description reasonably 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?
The schema covers all parameters with 100% description coverage. The description further clarifies the force parameter by stating it overrides the default trash behavior, adding semantic value beyond the schema's 'True to permanently delete'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Delete an order' with a clear verb and resource. It also introduces the trash behavior, which distinguishes it from a hard delete and sets expectations for the delete operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly name alternatives, but it offers clear usage context: 'Moves to trash by default; set force=true to permanently delete.' This guides the agent on when to use the tool and how to adjust behavior, even 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 significant behavioral context beyond the annotations. While destructiveHint=true indicates destructive potential, the description clarifies that the default action is non-destructive (trash) and that permanent deletion requires an explicit flag. This effectively communicates the risk profile and false-positive safety, enhancing trust.
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, consisting of two short sentences. It front-loads the primary purpose ('Delete a product review') and then states the key behavior regarding trash and force. Every word contributes meaning, with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of a delete tool and the presence of destructiveHint annotation, the description is largely complete. It explains the core behavior of trash vs. permanent delete, which is the main contextual nuance. However, it does not mention the return value or any side effects beyond deletion, and the 'fields' parameter's effect on the response is not noted, which is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all parameters described in the schema. The description essentially restates the meaning of the 'force' parameter already given in the schema ('True to permanently delete, false to move to trash'), adding no new information. The 'id' and 'fields' parameters are adequately described in the schema and not elaborated in the description, so no added 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's purpose: 'Delete a product review.' The verb 'Delete' and resource 'product review' are specific and unambiguous. It also distinguishes from sibling delete tools by scoping to product reviews and explaining the trash vs. permanent delete behavior, which differentiates it from other delete_* 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 on how to use the tool: by default it moves to trash, and setting force=true permanently deletes. This informs whether to use this tool based on desired outcome. However, it does not explicitly compare to alternatives or state when not to use it, which is acceptable given the tool's clear purpose.
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 established. The description adds behavioral value by disclosing filtering capabilities and the ability to customize fields, which goes beyond the annotation. 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, front-loaded with the core action, followed by key filters and a practical tip. No wasted words; every sentence contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with 6 parameters and no output schema, the description covers the main purpose and filtering behaviors. Pagination is not mentioned, but the schema documents page and per_page with defaults and constraints, so the description is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions, so the baseline is 3. The description adds a meaningful tip about the fields parameter ('Use fields param to request only needed fields'), which is not redundant with the schema and helps the agent optimize responses.
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 product reviews' – a specific verb and resource. The filtering phrase 'by product IDs, status, or search term' further distinguishes it from sibling tools like get_product_review or delete_product_review.
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 by naming the available filters (product IDs, status, search term), which guides the agent on when this tool is appropriate. It does not explicitly name alternatives or exclusions, but the listing context 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?
Beyond the readOnlyHint annotation, the description adds the completeness claim 'List all' and enumerates the specific groups included (general, products, tax, etc.), which gives the agent a clear expectation of the tool's output. However, it doesn't mention return format, pagination, or other behavioral details, so a score of 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 two concise sentences. The first sentence immediately states the purpose, and the second provides essential follow-up information about using the output with get_settings. 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?
For a simple read-only tool with one optional parameter and no output schema, the description covers the key points: what the tool returns, the specific groups, and the next step. It doesn't explicitly describe the response structure, but the field parameter's default (id,label,description) in the schema partially addresses that. Overall, it is sufficiently complete for an agent to use 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 schema provides 100% coverage for the single optional 'fields' parameter, including its default value. The description does not add additional semantics beyond what the schema already documents. Baseline of 3 is warranted because the schema fully explains 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 clearly states the tool's function: 'List all WooCommerce setting groups.' It uses a specific verb and resource, and the mention of 'Use group ID with get_settings' distinguishes this from sibling tool get_settings, which retrieves options for a specific group.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: it tells the agent that this tool lists groups and that get_settings should be used to see options for a group. This creates a clear workflow and implicitly indicates when to use this tool vs. the alternative.
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?
Given the idempotentHint annotation, the description's statement 'Only include fields you want to change' adds concrete behavioral detail that unspecified fields remain unchanged—valuable context beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler words; every element from the verb to the partial-update instruction is essential.
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, key usage guidance, and field list. Combined with full schema documentation and annotations, it provides sufficient context for an agent to select and invoke the tool correctly, though it omits return-value behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 7 parameters are fully described in the schema, so the description mainly needs to add usage semantics; it does so by emphasizing that only desired fields should be passed, reinforcing the schema's optionality.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Update') and resource ('a category'), and lists the specific fields (name, slug, parent, description, image), making it distinct from sibling tools like create_category or delete_category.
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 phrase 'Only include fields you want to change' provides clear guidance on how to perform partial updates, which is a key usage point for this tool. It implies the tool is for modifying existing categories, distinguishing it from creation and deletion 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 provide idempotentHint=true and openWorldHint=false, but no destructive hint. The description adds the critical behavioral trait that setting images replaces all existing images, beyond what annotations convey. It does not elaborate on other side effects, but the most important one is covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, each earning its place: the action, the partial-update guidance, and the critical image replacement warning. 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?
The tool has 20 parameters and no output schema, but the schema is self-documenting. The description provides the necessary behavioral warning and usage pattern. It falls short of explaining return value or explicitly distinguishing from update_variation, but it is sufficient for an update tool with rich schema coverage.
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 cover 100% of parameters, so baseline is 3. The description adds meaningful semantics about the 'images' parameter (replaces all existing) and sets an overall expectation for partial updates. This goes beyond the schema's simple 'Image URLs' 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 the action ('Update') and the resource ('existing product'). It differentiates from create_product and other product tools by using 'existing'.
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 gives explicit usage guidance: 'Only include fields you want to change' implies partial update semantics. The warning about images replacing existing images is a key usage caution. It does not explicitly mention alternatives, but the use case is straightforward for a product update tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses partial update behavior ('Only include fields you want to change'), which is valuable beyond the annotations. Annotations already indicate idempotency, and the description does not contradict them. It does not cover error conditions or permissions, but for a simple update this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The entire description is a single clear sentence that front-loads the action and resource. 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?
The tool is a simple CRUD update with ample schema coverage and idempotency hint. The description adequately covers the partial update behavior. It doesn't explicitly mention return values, but the 'fields' parameter suggests response customization. No major gaps for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with per-parameter descriptions. The description adds key semantics about partial updates (omitted fields remain unchanged), which the schema alone does not convey. It does not explain the 'fields' return parameter, but the schema handles that.
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 ('Update'), the resource ('product tag'), and the specific fields ('name, slug, or description'). It distinguishes from sibling update tools by specifying 'product 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 when to use this tool (to modify a tag's name, slug, or description) without describing alternatives. It provides clear context but no explicit exclusions or alternative tool references.
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 annotation idempotentHint=true already covers idempotency. The description adds key behavioral context by specifying that only included fields are changed, meaning unspecified fields remain untouched. This goes beyond the annotation and is valuable for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences: 'Update a tax rate. Only include fields you want to change.' It is concise, front-loaded, and contains no unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 12-parameter schema and lack of output schema, the description provides the essential purpose and update behavior. It could mention return values or error conditions, but the available context (annotations, full schema) makes it adequate for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all 12 parameters have descriptions. The description adds meaning by clarifying that only fields to change should be included, reinforcing that id is the only required parameter and others are optional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates a tax rate, using a specific verb and resource. The added note 'Only include fields you want to change' indicates partial update semantics, distinguishing it from create/delete/get/list siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for modifying existing tax rates identified by id. It provides guidance on partial updates but does not explicitly exclude other tools or state when not to use it. However, sibling tool names make the comparison 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 indicate readOnlyHint=true, so the safety profile is covered. The description adds meaningful behavioral context by clarifying that this tool gets attribute details but does not return values/terms, pointing to list_attribute_terms for that. It also notes the fields param for partial responses, which is extra context not directly inferred 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?
The description is two sentences, front-loaded with the core purpose, and every sentence earns its place by providing relevant usage guidance. 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 get tool with two parameters and no output schema, the description is complete: it states what it does, suggests a related tool for values, and mentions the fields param. The schema fills in the parameter details, and annotations cover safety. No significant 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% (both id and fields have descriptions). The description adds no new semantic meaning beyond the schema—'fields param to request only needed fields' essentially restates the schema's 'Comma-separated fields to return'. Therefore, 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: 'Get details of a global product attribute.' It uses a specific verb (get) and identifies the resource (global product attribute), distinguishing it from siblings like list_attributes (listing) and create_attribute (creation).
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 alternative guidance: 'Use list_attribute_terms with the attribute ID to see its values.' This tells the agent when to use a different tool, which is excellent contextual guidance. It also mentions using the fields param for selective requests, further clarifying usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only include openWorldHint: false, so the description carries the burden of behavioral disclosure. It discloses the prerequisite that the parent must be a variable product with matching attributes, which is a key constraint. It does not mention permissions or side effects, but for a create operation this 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?
Two concise sentences, front-loaded with the core action, and each sentence earns its place by providing necessary context. 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?
With 13 parameters, nested objects, and no output schema, the description provides key context (prerequisite, batch alternative) but does not mention return values or error conditions. However, the tool's purpose is straightforward and the schema covers parameter details, so the description is reasonably 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 semantic value by saying 'matching attributes,' which clarifies that the 'attributes' parameter must align with the parent product's defined attributes. This goes beyond the schema's generic 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 uses a specific verb and resource: 'Create a variation for a variable product.' It clearly distinguishes from siblings like update_variation and batch_update_variations by stating 'Use batch_update_variations for multiple at once.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use this tool: 'Parent product must have type="variable" with matching attributes.' It also gives an alternative: 'Use batch_update_variations for multiple at once.' This is explicit guidance on prerequisites and 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 destructiveHint annotation, the description adds key non-obvious details: the default trash behavior, the force option for permanent deletion, and the fact that associated media is not deleted. This substantially enhances the agent's understanding of the tool's 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 long, front-loaded with the main action, and every sentence provides necessary information. There is no unnecessary fluff or repetition of schema details.
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 delete tool with no output schema, the description adequately covers essential behavior: deletion, trash vs. permanent, and the media caveat. It could mention the 'fields' parameter effect on response, but the schema already documents that, so completeness is high.
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 cover all three parameters (id, force, fields) at 100%. The description reinforces the force parameter's meaning by explaining the trash default and permanent deletion, adding value beyond the schema by clarifying the tool's operational semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes a product and distinguishes it from sibling delete tools by specifying the resource (product) and the trash/permanent behavior. This is more specific than simply saying 'delete 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 gives clear context on when to use the tool: to delete a product. It explains the default behavior (trash) and how to permanently delete with force=true. It does not explicitly mention alternatives or when not to use it, but this is not critical for a delete operation.
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:

[![mcp-server-woocommerce MCP server](https://glama.ai/mcp/servers/AmitGurbani/mcp-server-woocommerce/badges/card.svg)](https://glama.ai/mcp/servers/AmitGurbani/mcp-server-woocommerce)

Score Badge

Copy to your README.md:

[![mcp-server-woocommerce MCP server](https://glama.ai/mcp/servers/AmitGurbani/mcp-server-woocommerce/badges/score.svg)](https://glama.ai/mcp/servers/AmitGurbani/mcp-server-woocommerce)

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/AmitGurbani/mcp-server-woocommerce'

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