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

Annotations indicate write, non-idempotent, safe operation. Description adds return format, error handling, and creation behavior. No contradiction with annotations.

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

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

The description is well-structured with bullet points, sections (Args, Returns, Examples, Error Handling), and front-loaded with the main action. No redundant sentences.

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

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

Given 15 parameters and no output schema, the description covers creation details, error handling, and an example. It doesn't detail the returned object, but the context is adequate for an AI agent.

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

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

With 93% schema coverage, the description adds value by providing an example, summarizing defaults, and explaining the response_format parameter beyond the schema.

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

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

The description clearly states 'Create a new discount coupon', matching the title and specifying the resource. It distinguishes itself from sibling tools like woocommerce_update_coupon and woocommerce_delete_coupon.

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

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

The description provides an explicit example with 'Use when' and error handling for duplicate codes. It lacks explicit when-not-to-use guidance, but the example and context make usage clear.

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

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

The description adds value beyond annotations by stating that it returns a newly created customer object with an assigned ID and details error responses. Annotations already indicate a mutating action, so the description enhances understanding without contradiction.

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

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

The description is well-structured with separate sections for Args, Returns, and Error Handling, making it easy to parse. It is front-loaded with the primary purpose but contains some repetitive details from the schema. Slightly verbose, but every sentence adds value.

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

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

Given the tool's complexity (8 parameters, nested objects) and no output schema, the description explains the return value and error conditions adequately. However, it lacks details on the complete structure of the returned customer object beyond the ID, and does not cover all edge cases.

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

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

The description explicitly lists all parameters and adds meaning for those not fully explained in the schema (e.g., billing/shipping as address fields, response_format options). With 50% schema coverage, the description compensates well, though it could detail nested object structures further.

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

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

The description clearly states 'Create a new registered customer account' using specific verb 'Create' and resource 'customer account'. It distinctively differs from sibling tools like 'woocommerce_update_customer' or 'woocommerce_list_customers'.

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

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

The description provides clear context for when to use the tool (creating a new customer) and includes error handling for duplicate email/username. However, it does not explicitly state when not to use it (e.g., for updates) or compare to siblings, though it's implicitly clear.

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

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

The description adds significant behavioral context beyond annotations: automatic totals/tax/stock reduction, error responses for invalid products or stock issues, and the effect of `set_paid`. Annotations declare readOnlyHint=false, which aligns with mutation, and the description elaborates on 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.

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

The description is well-structured with an 'Args' section and examples. It is front-loaded with the main purpose. However, it includes a full parameter list that partially duplicates the schema, making it somewhat verbose. Still, it is clear and efficient overall.

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

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

Given the complexity (10 parameters, nested objects, no output schema), the description covers creation behavior, return format (order object with ID and totals), error handling, and example usage. It is sufficiently complete for an agent to use the tool correctly.

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

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

With 80% schema description coverage, the baseline is 3. The description adds value by clarifying the `customer_id` parameter ('omit for a guest order'), the structure of `line_items`, and the `response_format` options. It also explains the `set_paid` boolean effect, enhancing understanding beyond the schema.

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

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

The description clearly states 'Create a new order with one or more line items,' which is a specific verb-resource combination. It distinguishes from sibling tools like update, delete, get orders, and other WooCommerce tools.

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

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

The description provides clear context with examples and error handling scenarios (e.g., missing product, out of stock). It explains automatic calculations and stock reduction. However, it does not explicitly exclude situations where other tools might be preferred, such as using update_order for modifications.

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

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

Annotations set readOnlyHint=false and destructiveHint=false, which aligns with the description of adding a note (non-destructive write). The description adds value by disclosing that customer-visible notes trigger an email, which is a behavioral side effect not evident 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.

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

The description is concise and well-structured: an initial summary, an Args list, Returns, and an Example. Every sentence adds necessary information with no redundancy.

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

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

For a tool with no output schema, the description states 'Returns: The newly created note object', which is sufficient. It covers the two note types, parameter defaults, and provides an example. Minor omission: no mention of error conditions or prerequisites (e.g., order must exist).

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

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

The input schema already describes all 4 parameters (100% coverage). The description enhances this by clarifying that customer_note=true emails the customer and that response_format defaults to 'markdown'. The example also demonstrates parameter usage, adding practical meaning.

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

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

The description clearly states 'Add a note to an order' and distinguishes customer-visible from internal notes. Sibling tools like woocommerce_list_order_notes and woocommerce_create_order_refund have different purposes, so the tool is easily distinguishable.

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

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

Provides a concrete usage example ('let the customer know order 100 has shipped') and explains the customer_note parameter effect. However, it does not explicitly state when not to use this tool vs. alternatives like updating the order or sending a custom email.

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

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

Annotations already provide destructiveHint=true, readOnlyHint=false, idempotentHint=false, openWorldHint=true. The description reinforces this with 'DESTRUCTIVE, hard-to-reverse financial operation' and adds the important behavioral guideline to confirm with the user. 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.

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

The description is well-structured: first sentence states purpose, followed by a critical warning, then a clear listing of arguments with types, return value, an example, and error handling. Every sentence adds value, and it is appropriately concise.

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

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

Given the tool's financial nature and multiple parameters, the description covers purpose, parameters (with types and relations), return type, example usage, and error handling. No output schema exists, but the return is described. Annotations cover safety. 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.

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

Schema coverage is 100% (all parameters have schema descriptions). The description adds value by clarifying the mutual dependency between 'amount' and 'line_items' (amount required if line_items omitted) and includes an example mapping natural language to parameters. This goes beyond the schema's own descriptions.

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

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

The description clearly states the tool's purpose: 'Issue a refund against an order, either as a flat amount or itemized by line item.' The verb 'issue a refund' is specific and the resource is 'order'. It distinguishes from sibling tools that deal with orders (create, update, delete, list) and other entities.

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

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

The description explicitly warns that this is a destructive, hard-to-reverse financial operation and advises confirming details with the user before calling. It provides an example scenario. It does not explicitly list alternatives, but among siblings, only 'woocommerce_list_order_refunds' exists for refunds, so usage context is clear.

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

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

Annotations provide minimal info (readOnlyHint=false, etc.), but the description adds significant behavioral details: image URLs are imported, response can be markdown or JSON, SKU uniqueness enforcement, and error handling. 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.

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

Well-structured with clear sections (Args, Returns, Examples, Error Handling). However, the Args list is lengthy and largely repeats schema information, which could be more concise. Still, 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.

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

Given no output schema and 16 parameters, the description covers return value, error scenarios, and usage examples. It provides sufficient context for an AI agent to correctly select and invoke the tool, including differentiation from sibling tools.

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

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

Schema coverage is 100%, but the description adds value beyond schema by providing examples, default values, constraints (e.g., 'must be unique store-wide' for SKU, 'numeric strings' for prices), and error handling context. The Args section summarizes parameters effectively.

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

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

The description clearly states 'Create a new product in the WooCommerce catalog' with a list of parameters and examples. It distinguishes from sibling tools like woocommerce_create_product_variation by explicitly stating not to use for creating variations.

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

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

Includes explicit examples of when to use ('add a new t-shirt product') and when not to use ('creating a variation... use woocommerce_create_product_variation'). Also covers error handling for duplicate SKU, guiding proper invocation.

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

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

The description discloses error handling (400 on duplicate category) and states that it returns the newly created object with an ID. Annotations indicate this is a write operation with potential side effects (openWorldHint=true), and the description does not contradict them. However, it does not detail any other side effects or authentication requirements.

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

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

The description is very concise: a single line for purpose, a bullet-like listing of arguments, and a brief error handling note. Every sentence adds value without redundancy.

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

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

Given the tool's simplicity (creating a category with 4 parameters, 1 required), the description covers the main behavior, return value, and error condition. It could mention prerequisites (e.g., authentication) or more on side effects, but overall it is sufficiently complete for an AI agent to use correctly.

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

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

The input schema already describes 3 of 4 parameters (name, parent, response_format). The tool description adds minimal extra meaning (e.g., for parent and response_format, it echoes the schema). The 'description' parameter is left without elaboration in both schema and description.

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

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

The description starts with 'Create a new product category' which is a specific verb+resource combination. The tool name and title also clearly indicate the action of creating a product category in WooCommerce. This effectively distinguishes it from sibling tools like update or delete categories.

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

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

No explicit guidance is provided on when to use this tool versus alternatives (e.g., updating or deleting categories). The error handling hint about duplicate names implies a precondition, but there is no direct statement about when creation is appropriate.

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

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

Beyond annotations (which indicate non-readonly, non-destructive), the description adds the error handling condition that a 400 error occurs if a tag with the same name exists. This provides useful behavioral context.

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

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

The description is concise, well-structured with clear sections for Args, Returns, and Error Handling. Every sentence serves a purpose with no redundancy.

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

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

For a simple creation tool with 3 parameters and no output schema, the description fully covers the purpose, parameters, return value, and error handling. It is self-contained and informative.

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

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

The description repeats the parameter names and types from the schema but adds little additional meaning. The schema already covers name and response_format descriptions; the description adds a note but not deeper semantics.

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

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

The description clearly states 'Create a new product tag.' It uses a specific verb and resource, and distinguishes itself from sibling tools like woocommerce_list_product_tags and woocommerce_update_product_tag.

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

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

The description does not explicitly guide on when to use this tool versus alternatives. It implies its use for creating tags but offers no when-not-to-use advice or comparisons with other tag-relevant tools.

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

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

Annotations already indicate write operation and non-idempotency. The description adds the prerequisite about parent attributes and specific error handling for attribute mismatches, which goes 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.

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

The description is concise, well-structured with sections for args, returns, examples, and error handling. Every sentence adds value without redundancy.

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

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

Given the complexity and lack of output schema, the description covers the main purpose, prerequisites, and error cases. It could mention potential duplicate creation, but overall it is sufficient for agent decision-making.

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

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

With 56% schema coverage, the description compensates by listing all optional parameters and providing a clear example of the required 'attributes' array. It explains the structure but could detail more default behaviors.

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

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

The description clearly states the tool creates a new variation for an existing variable product, using specific verbs and resource. It distinguishes itself from sibling tools like update or delete variations through its verb and prerequisite of parent product attributes.

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

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

The description provides a concrete 'Use when' example and clarifies the prerequisite of having variation-enabled attributes. It lacks explicit when-not instructions but the example and context sufficiently guide usage.

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

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

The annotation claims idempotentHint=true, but the description's error handling shows that deleting a non-existent coupon returns a 404 error, meaning the tool is not idempotent. This contradiction causes a score of 1.

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

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

The description is concise (5 sentences) and well-structured with sections for purpose, args, returns, and error handling. No fluff, though could be slightly more front-loaded.

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

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

For a simple deletion tool, the description covers purpose, behavior (trash vs permanent), and error handling. It lacks mention of authorization or prerequisites, but these are likely assumed in the WooCommerce context.

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

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

Schema coverage is 100%, so baseline is 3. The description restates the parameters and their effects, but adds no new 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.

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

The description clearly states the verb 'delete' and the resource 'coupon', and distinguishes this tool from sibling delete tools for other entities (e.g., product, order). It also adds nuance about trash vs permanent deletion.

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

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

The description explains when to use force=true vs default, and provides error handling for invalid coupon_id. While it doesn't explicitly mention alternatives, the sibling context makes it clear that this is the only delete coupon tool.

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

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

Annotations indicate destructiveHint=true and idempotentHint=true, but the description adds critical context: customers don't support trash, deletion is permanent, and existing orders become unlinked. Error handling is also described (404 if not found). This goes 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.

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

The description is well-structured with sections for purpose, args, returns, and error handling. It is concise but includes some redundancy (Args list mirrors schema). It earns its place without being verbose.

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

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

The description covers irreversibility, effect on orders, error handling, and parameters. There is no output schema, so the mention of 'Confirmation of deletion' is helpful but vague. Overall, it provides sufficient context for an agent to use the tool correctly.

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

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

Schema coverage is 100%, with descriptions for both parameters (customer_id and reassign). The description lists these in the 'Args' section but does not add significant new meaning. The reassign parameter's purpose is already clear from the schema. Thus, baseline score is appropriate.

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

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

The description clearly states the tool permanently deletes a customer account, with the verb 'delete' and resource 'customer account'. It also highlights that the action cannot be undone, effectively distinguishing it from other sibling tools like 'woocommerce_delete_product' or 'woocommerce_delete_coupon'.

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

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

The description provides a strong warning about the permanent nature and the effect on existing orders (they remain unlinked). However, it does not explicitly state when to use this tool versus alternatives (e.g., disabling a customer). The guidance is clear but could be more comprehensive.

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

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

Disclosures go beyond annotations: annotations give destructiveHint=true and idempotentHint=true; description adds that default is recoverable trash, force=true is permanent, and includes error responses. 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.

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

Description is concise, front-loaded with the main action, and uses clear structure with a bullet-like list for parameters. Every sentence adds value, no fluff.

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

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

Given no output schema, description includes return values (id, number, status) and error handling. All relevant context for a delete operation is covered.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining the impact of force parameter (trash vs permanent) and error handling context, which is not in schema descriptions.

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

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

The description clearly states 'Delete an order' and distinguishes between moving to trash (default, recoverable) and permanent deletion with force=true. It is specific to orders and differentiates from sibling tools like update_order or create_order.

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

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

The description explains the default behavior (trash) and the alternative (force=true), providing clear when-to-use guidance. It also includes error handling for missing orders. Could mention when to use this versus other order-related tools, but not essential.

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

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

Annotations already indicate destructiveHint=true. The description adds that default move-to-trash is recoverable, and error handling for missing product is provided. No contradiction.

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

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

Very concise and well-structured with sections for Args, Returns, and Error Handling. Front-loaded with the key purpose.

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

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

Even without output schema, the description explains the return (confirmation of id, name, status) and covers error handling. All necessary context is provided.

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

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

Schema coverage is 100% with full parameter descriptions. The description adds behavioral meaning to force (permanent vs trash) and clarifies product_id requirement.

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

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

The description clearly states the tool deletes a product, explains default trash behavior vs permanent deletion, and is distinct from sibling tools for tags, categories, etc.

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

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

Describes when to use (deleting a product) and covers the force parameter for permanent deletion. Does not explicitly exclude alternatives but context is clear from sibling tool names.

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

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

Beyond annotations (destructiveHint, idempotentHint), the description adds that deletion is permanent, force must be true, and products are unassigned. It also documents the expected 404 error response, providing clear behavioral context.

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

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

The description is concise and well-structured with sections for Args, Returns, and Error Handling. Every sentence adds useful information without redundancy.

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

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

Given the simplicity of the tool (2 parameters, no output schema), the description covers purpose, parameters, side effects, and error handling completely. No missing information is evident.

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

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

With 100% schema coverage, the baseline is 3. The description adds meaning by explaining the force parameter's necessity (terms don't support trash) and confirming permanent deletion, adding value beyond the schema.

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

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

The description clearly states the tool permanently deletes a product category and distinguishes it by clarifying that products are unassigned, not deleted. This differentiates from product deletion 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.

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

The description implies usage for permanent deletion but does not explicitly specify when to use this tool versus alternatives like updating the category. No direct exclusion criteria or alternative suggestions are provided.

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

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

Annotations already indicate destructive behavior, but the description adds that deletion is permanent, force must be true, and includes error handling (404). This goes beyond annotations by specifying conditions and outcomes.

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

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

The description is concise and well-structured, using clear sections for args, returns, and error handling. Every sentence provides value, with no wasted words.

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

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

For a deletion tool with no output schema, the description covers the key behavioral aspects: permanent deletion, product unassignment, force requirement, and error response. 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.

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

Schema coverage is 100% with clear parameter descriptions. The description repeats schema info for 'force' and adds minimal extra context ('required to be true'). It does not add significant meaning beyond what the schema provides.

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

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

The description clearly states it permanently deletes a product tag, and explicitly clarifies that associated products are not deleted. This provides a specific verb and resource, distinguishing it from sibling delete tools like woocommerce_delete_product.

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

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

The description mentions that products are unassigned, implying safe deletion, but does not explicitly state when to use this tool versus alternatives like updating a tag or deleting other resources. No direct when-not-to-use guidance is provided, but the context of unassignment offers some usage insight.

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

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

Annotations declare destructiveHint=true, and the description reinforces this by stating deletion is permanent and that variations do not support trash. It also describes error responses, adding context beyond annotations.

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

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

The description is extremely concise, with a clear purpose line followed by structured sections for args, returns, and error handling. Every sentence adds value.

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

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

Given the tool's simplicity and annotations, the description covers all necessary aspects: action, parameters, permanence, return confirmation, and error handling. No output schema needed.

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

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

The description provides clear explanations for all three parameters, including the default/behavior of 'force', which the schema only partially covers. This compensates for the low schema description coverage (33%).

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

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

The description explicitly states 'Permanently delete a product variation,' which clearly identifies the action (delete) and resource (product variation). It distinguishes this tool from sibling delete tools like woocommerce_delete_product or woocommerce_delete_product_tag.

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

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

No guidance is given on when to use this tool vs alternatives (e.g., when to delete a variation vs a product). The description only explains that deletion is permanent and how errors are handled.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by specifying the error response format and the response_format options, providing additional behavioral context beyond annotations.

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

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

The description is concise with clear sections (Args, Returns, Error Handling). It front-loads the main purpose and uses minimal text to convey essential information. Every sentence serves a purpose without redundancy.

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

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

Given no output schema, the description states 'Returns: Full coupon object' and lists included restrictions. It also covers error handling. While it could list more details (e.g., usage counts), it is adequate for a single-resource retrieval tool.

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

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

Schema coverage is 100%, so the schema already fully describes both parameters. The description merely restates parameter names and options without adding new semantic meaning. Baseline score of 3 is appropriate.

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

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

The description clearly states it retrieves full details for a single coupon, including specific restrictions. This distinguishes it from sibling tools like woocommerce_list_coupons (list) and woocommerce_create_coupon (create). The verb 'Retrieve' and resource 'single coupon' are explicit.

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

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

The description does not provide explicit guidance on when to use this tool versus alternatives (e.g., list vs get, or when to use markdown vs json). It only mentions error handling for non-existent IDs. Usage context is implied but not stated.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds useful context: the return of a full customer object and explicit error handling for missing customer IDs. This goes beyond the annotations without contradicting them.

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

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

The description is concise with a clear structure: a one-sentence purpose, followed by Args, Returns, and Error Handling sections. Every sentence adds value, with no unnecessary repetition or filler.

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

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

Given the tool's simplicity (2 parameters, read-only, no output schema), the description covers purpose, parameters, return type, included fields, and error behavior. It sufficiently equips an agent to invoke the tool correctly, though more detail on the return object structure could be provided.

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

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

Both parameters are fully described in the schema (100% coverage). The description merely restates the parameter names and types without adding new semantic information beyond what the schema provides. Thus, it meets the baseline expectation.

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

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

The description clearly states 'Retrieve full details for a single customer', specifying the action (retrieve) and the target (single customer). It lists specific data returned (billing/shipping addresses, order count, lifetime spend), distinguishing it from sibling tools like list, create, update, and delete customers.

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

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

While the purpose implies use for retrieving a specific customer's full details, the description does not explicitly state when to use this tool versus alternatives (e.g., woocommerce_list_customers for browsing multiple customers). No direct when-not or 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.

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

Annotations already declare readOnly, idempotent, and non-destructive. Description adds value by detailing the return (full order object) and error handling behavior (specific 404 message). 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.

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

Description is concise with clearly separated sections for purpose, arguments, returns, and error handling. Every sentence adds value with no redundancy.

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

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

Given the tool is a simple retrieval with 2 parameters and no output schema, the description fully covers what the tool does, its parameters, return content, and error handling. No gaps.

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

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

Schema already describes both parameters with 100% coverage (order_id as integer, response_format as enum with default). Description reiterates response_format default and mentions markdown/json but adds no new semantics beyond schema.

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

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

Description clearly states 'Retrieve full details for a single order' and lists included fields (line items, addresses, payment, etc.). This distinguishes it from sibling list_orders, which returns a list, not full details.

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

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

Description implies use for retrieving a single order's full details. It does not explicitly contrast with list_orders, but the purpose is clear. Error handling for 404 adds practical guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds value by specifying error handling (returns 404 on not found) and mentioning the return format, providing behavioral details 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.

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

The description is highly concise with two paragraphs and bullet-style Args. It front-loads the main purpose and includes all essential information without any filler, making every sentence valuable.

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

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

Despite lacking an output schema, the description lists the fields returned (description, pricing, stock, etc.) and covers error handling. Given the tool's simplicity (single product retrieval), the description is complete enough for an agent to understand what to expect.

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

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

Schema coverage is 100%, so the schema fully describes both parameters. The description paraphrases product_id and response_format, but also adds the note that the function returns a 'Full product object,' which is not in the schema, adding meaningful context beyond the structured data.

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

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

The description explicitly states 'Retrieve full details for a single product by ID' and lists the specific fields included, clearly distinguishing it from sibling tools like 'woocommerce_list_products' which lists multiple products and 'woocommerce_get_product_variation' for variations.

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

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

The description clearly indicates this tool is for retrieving a single product by ID. While it does not explicitly say when not to use it or mention alternatives, the context of sibling tools makes the usage context evident. It is adequate but could be improved with explicit exclusions.

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

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

Annotations already declare readOnlyHint: true, idempotentHint: true, destructiveHint: false, so the description's burden is low. It adds error handling details (specific HTTP 404 message) and return format info, which provide useful behavioral context without contradiction.

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

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

The description is structured with an 'Args:' section, a 'Returns:' line, and an 'Error Handling:' section. It is fairly concise and front-loaded with the main purpose. Minor redundancy (e.g., listing parameters that are already in schema) but overall efficient.

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

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

With no output schema, the description adequately explains return values ('Full variation object including attributes, pricing, and stock') and error behavior. It covers enough for a read-only tool, though the return format is not fully detailed.

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

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

Schema coverage is 100%, so the schema already describes all parameters. The description restates them but adds the 'parent product ID' and 'variation ID' labels, and specifies the default value for response_format. This adds marginal value beyond the schema.

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

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

The description clearly states 'Retrieve full details for a single product variation,' using a specific verb and resource. It distinguishes from sibling tools like 'woocommerce_list_product_variations' (list vs. single) and 'woocommerce_get_product' (different resource).

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

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

The description implies usage for retrieving a single variation by requiring both product_id and variation_id. It does not explicitly compare with alternatives or state when not to use, but the context from sibling tools makes the purpose clear.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds context about the return structure (list of {slug, name, total}) and the effect of the response_format parameter. 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.

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

The description is concise, with clear separation of purpose, parameters, return structure, and example. It is front-loaded with the main action and resource types. No unnecessary text.

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

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

For a tool with 2 parameters, full schema coverage, and no output schema, the description provides sufficient context: it explains each parameter, the output format, and gives an example. It is complete for its complexity level.

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

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

Schema description coverage is 100%. The description adds value by clarifying the default for response_format and providing an example that demonstrates the parameter usage and output structure. This goes beyond the schema alone.

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

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

The description clearly states the tool's purpose: getting a breakdown of total counts by status for a resource. It specifies the five valid resources (orders, products, customers, coupons, reviews) and gives an example. This distinguishes it from sibling reporting tools like woocommerce_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.

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

The description provides an example of when to use the tool ('how many orders are currently pending vs completed') and explains the resource and response_format parameters. However, it does not explicitly state when not to use it or compare it to alternatives.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds context about the default period (current week) but does not disclose other behavioral traits like rate limits or exact return structure. It does not contradict annotations.

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

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

The description is well-structured with an args list and examples, front-loading the purpose. It is reasonably concise, though the first sentence could be streamlined. Every sentence adds value.

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

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

Given no output schema, the description mentions 'Sales totals summary' but does not enumerate fields. However, for a simple reporting tool with good annotations and parameter documentation, this is adequate. The description covers when to use and parameter interplay.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining that date_min/date_max override period, specifying the default response_format, and providing usage examples. This justifies a score of 4.

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

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

The description clearly states it retrieves aggregate sales totals (revenue, orders, items, tax, shipping, discounts, refunds) for a period or custom date range. This distinguishes it from sibling tools like woocommerce_get_top_sellers_report and woocommerce_get_report_totals, which focus on different metrics.

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

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

The description provides explicit guidance on when to use period versus date_min/date_max, with examples. It explains the default behavior when no parameters are given. However, it does not explicitly mention when to use alternative tools, such as using woocommerce_get_top_sellers_report for top sellers, which would improve clarity.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the return format (list of products with id, title, quantity), ordering (descending by quantity), and default behavior (current week). This provides useful context beyond the annotations, though annotations already cover safety and 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.

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

The description is structured with clear sections (Args, Returns, Examples) and uses concise language. Every sentence adds value without redundancy. It is front-loaded with the core purpose and provides details efficiently.

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

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

Given the tool's simplicity and the absence of an output schema, the description covers all necessary aspects: return structure (product_id, title, quantity), ordering, default behavior, and parameter relationships. It provides enough information for an AI 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.

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining the mutual exclusivity of 'period' and 'date_min/date_max' ('overrides period'), specifying defaults (current week when no period/range given), and providing example usage. This goes beyond the schema's simple descriptions.

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

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

The description clearly states the verb ('Retrieve') and resource ('best-selling products') and specifies the scope ('by quantity sold for a period or custom date range'). It distinguishes itself from sibling tools like woocommerce_list_products (which lists all products) and woocommerce_get_sales_report (which provides overall sales figures).

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

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

The description provides concrete examples for when to use the tool (e.g., 'What were our best selling products this year?') and explains parameter mutual exclusivity between 'period' and 'date_min/date_max'. It does not explicitly mention when not to use it or compare with alternatives like woocommerce_list_products, but the context is sufficient.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral context like default pagination (max 100 per page), optional filters, and return format details, but does not mention error handling or rate limits.

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

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

The description is concise with a clear 'Args:' section listing parameters and their defaults. Every sentence adds value; no redundant or wasted text.

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

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

The description covers search, pagination, sorting, and output formats. It explains return fields (code, amount, discount type, usage count/limit, expiry) without an output schema, which is adequate for a list tool.

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

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

Schema coverage is 100% with detailed descriptions. The description adds value by clarifying that 'search' matches against coupon code and 'code' is an exact match, and reiterates default values for sorting and pagination.

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

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

The description states 'Search and list discount coupons defined in the store' with a specific verb and resource, distinguishing it from sibling tools like woocommerce_get_coupon (single) and create/update/delete operations.

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

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

The description implies usage for listing/searching coupons with filters, pagination, and sorting, but does not explicitly provide when-not-to-use or compare with alternatives like woocommerce_get_coupon.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds important nuance that guest checkout customers are excluded, and details pagination/sorting defaults, enhancing understanding 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.

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

Well-structured with Args, Returns, Examples sections. Every sentence adds value; no redundancy or fluff.

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

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

Despite no output schema, description details return fields (id, email, name, order count, total spent) and covers all parameters with pagination limits, fully informing usage.

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

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

Schema description coverage is 100%, but the description adds usage examples (e.g., email='jane@example.com') and organizes parameters with clear explanations, providing extra context.

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

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

The description clearly states 'Search and list registered customers' with a specific exclusion of guest checkout customers, distinguishing it from other tools like 'woocommerce_get_customer'.

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

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

Provides explicit examples of when to use (e.g., find customer by email) and when not to use (guest order lookup with pointer to billing details), offering clear alternative guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the behavior is transparent. The description adds that the tool returns a list of notes with specific fields, which is consistent.

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

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

The description is concise, front-loaded with the purpose, and includes a clear Args list and return description. Every sentence adds value without redundancy.

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

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

Given the rich annotations and complete schema, the description fully covers the tool's behavior. It specifies the return fields despite the lack of an output schema, making it complete.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds clarity by explaining the response_format options (markdown for human-readable, json for machine-readable) and the type parameter's default value, enhancing understanding beyond the schema.

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

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

The description clearly states the tool lists notes attached to an order (internal/customer), with examples like fulfillment updates and payment logs. It is distinct from sibling tools like create_order_note or list_orders.

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

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

Provides context on when to use (listing notes for an order) with examples, but does not explicitly state when not to use or contrast with alternatives like create_order_note.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description confirms the read-only nature and adds return fields, but does not elaborate on other behavioral traits like rate limits or side effects beyond what annotations provide.

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

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

The description is concise, with a single sentence for purpose and a compact parameter listing. It is front-loaded and every sentence adds value.

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

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

No output schema, but the description specifies returned fields (id, amount, reason, refunded line items), which is sufficient for a list tool. More detail on pagination behavior or error conditions would improve completeness.

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

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

Schema coverage is 100%, so baseline is 3. The description repeats parameter defaults and options, adding marginal value beyond the schema (e.g., grouping the parameters). It does not introduce new semantics.

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

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

The description clearly states 'List refunds issued against an order.' The verb 'list' and resource 'refunds' with context 'issued against an order' is specific and distinguishes from sibling tools like create_order_refund or list_orders.

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

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

The description focuses on parameters but does not explicitly state when to use this tool compared to alternatives like get_order or create_order_refund. Usage context is implied but not detailed.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context beyond annotations: pagination details (default per_page=20, max 100), response format options, and what fields are returned. It does not contradict annotations.

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

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

The description is well-structured with an introductory sentence, parameter list, return info, and examples. It is not excessively verbose, though it could be slightly tighter. Still, every sentence adds value and is front-loaded with the main purpose.

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

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

Given 11 parameters, no required, and no output schema, the description covers all parameters, explains return fields (id, number, status, total, currency, customer, line item count), and notes pagination limits. This is sufficient for an agent to understand the tool's behavior and output.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra value by listing all parameters with defaults, providing usage examples (e.g., status, after, customer), and clarifying the search parameter matches billing details. This goes beyond the schema descriptions.

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

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

The description clearly states the tool 'Search and list store orders' with specific filters. It distinguishes from the sibling tool 'woocommerce_get_order' by noting when not to use it for full detail, and from other list tools by focusing on orders.

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

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

The description provides explicit use cases with examples ('show me pending orders from this week') and explicitly tells when not to use this tool ('Don't use when: you need full line-item and address detail for one order (use woocommerce_get_order)'). This gives clear guidance on when to use vs alternatives.

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

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

Annotations already declare readOnlyHint true, destructiveHint false, idempotentHint true. Description adds useful behavioral details: returns paginated list with specific fields (id, name, slug, product count), default pagination, and max per_page.

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

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

The description is concise with a bullet-like structure that clearly presents parameters and return values. Every sentence contributes meaning without redundancy.

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

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

Given the simplicity of the tool and the presence of annotations, the description is complete. It explains all parameters, return format, and default values. No output schema exists but the return description is sufficient.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining parameter purposes (search matches name, parent filters children, etc.) in a clear, organized list, going beyond the schema's descriptions.

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

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

The description clearly states it lists product categories, which is a specific verb+resource. It distinguishes from sibling tools that create, update, or delete categories.

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

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

No explicit when-to-use vs alternatives guidance. However, the purpose is self-evident, and there is no direct alternative like a 'get' for categories. The absence of usage context lowers the score.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds value by detailing output structure (paginated list with specific fields), response_format options, and limitations (no variations coverage). 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.

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

The description is well-organized into sections: overview, exclusion note, parameter list with inline explanations, return value summary, and usage examples. It is concise yet comprehensive, with no wasted sentences.

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

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

Given 16 parameters, 100% schema coverage, and no output schema, the description fully compensates by explaining return structure, providing examples, and referencing sibling tools. It is complete and actionable for an agent.

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

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

Schema coverage is 100%, but the description adds significant meaning by grouping parameters, providing explanation of how each is used in context (e.g., 'Match against name/SKU/description' for search), and including practical examples that clarify parameter combinations (e.g., on_sale and max_price).

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

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

The description clearly states the tool searches and lists products in the WooCommerce store catalog. It distinguishes itself by noting it does not return variations, directing users to woocommerce_list_product_variations for that purpose, and differentiates from woocommerce_get_product for single product retrieval.

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

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

Explicit usage guidance is provided, including when to use (e.g., 'find all out of stock products'), when not to use (e.g., needing details of a known product ID), and alternative tools to use instead (woocommerce_get_product, woocommerce_list_product_variations).

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

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

Annotations already indicate safe, read-only behavior. Description adds useful context: returns paginated list with id, name, slug, product count, and default response format. 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.

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

Extremely concise: one sentence for purpose, bullet points for parameters. No fluff. Information is well-structured and easy to scan.

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

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

For a list tool with no output schema, the description fully specifies the return value (paginated list with specific fields) and all parameters are documented. Complete for its purpose.

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

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

Schema covers all parameters (100% coverage). Description adds meaning: 'match against name' for search, defaults for sorting and pagination, and response_format options.

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

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

The description clearly states the tool lists product tags, which is distinct from sibling tools like create/delete tags. Uses specific verb 'List' and resource 'product tags'.

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

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

No guidance on when to use this tool versus alternatives like woocommerce_list_product_categories or woocommerce_list_products. No mention of scenarios or prerequisites.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral details: return format options, pagination limits (max 100), default values, and error handling behavior. 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.

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

The description is concise with clear sections (Args, Returns, Error Handling). It is front-loaded with the core purpose. No redundant or excessive text.

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

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

Given 4 parameters, no output schema, and rich annotations, the description covers purpose, parameters, return fields (id, sku, price, stock, attribute options), pagination, and error handling. It provides sufficient context for an agent to use the tool correctly.

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

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 minimal extra nuance (e.g., max 100 for per_page, default page=1) but largely repeats schema info. It does not provide deeper semantics beyond what the schema already offers.

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

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

The description clearly states it lists all variations of a variable product, with a concrete example (T-shirt with Size/Color). It distinguishes itself from sibling tools like woocommerce_get_product_variation (single) and woocommerce_list_products (list products).

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

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

The description includes pagination defaults and error handling (returns empty list if product not variable), which provides context for when the tool works or returns nothing. However, it does not explicitly contrast with alternatives like get_product_variation for single variations.

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

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

Description discloses mutation ('Update'), partial update ('Only supplied fields are changed'), and error handling (404). Annotations already indicate idempotent and non-destructive. The description adds value by specifying behavior 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.

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

The description is moderately concise but includes a redundant Args list that largely duplicates the schema. Every sentence adds some value, but the structure could be tighter.

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

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

For a tool with 12 parameters and no output schema, the description covers mutation, partial updates, and error handling. However, it omits details about the return value structure and does not address edge cases like invalid field values.

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

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

Schema description coverage is only 25% (2 of 12 params have descriptions). The description lists parameter names but adds little semantic detail beyond the schema. The example connects coupon_id and date_expires, but overall does not compensate for low schema coverage.

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

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

The description clearly states the action ('Update fields on an existing coupon') and specifies the resource ('coupon') and scope ('existing'). It distinguishes from sibling tools like create and delete by emphasizing update on an existing entity.

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

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

The description provides an example and error handling notes, giving some usage context. However, it lacks explicit guidance on when not to use this tool (e.g., when to use create_coupon instead) or mention of prerequisites.

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

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

The description adds context about partial updates and error handling (404 for missing customer), complementing annotations that indicate idempotency and non-destructiveness.

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

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

The description is concise with four sentences covering purpose, args, returns, and error handling, front-loaded with the key point.

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

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

The description adequately covers the main aspects for a simple CRUD update, but could improve by detailing nested parameters and validation behavior.

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

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

Given low schema coverage (29%), the description lists the parameters and default response_format but lacks details on nested billing/shipping structures, providing partial compensation.

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

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

The description clearly states the tool updates an existing customer and that only supplied fields are changed, distinguishing it from create, delete, and get tools.

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

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

The description implies usage for partial updates but does not explicitly state when to use this tool over creating or deleting, or provide exclusions.

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

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

Annotations indicate idempotent and non-destructive; description adds context about avoiding accidental stock/total recalculation by omitting line-item edits, and includes error handling example. No contradiction.

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

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

Reasonably concise with clear sections (Args, Examples, Error Handling). First sentence is effective. Minor redundancy with schema listing.

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

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

No output schema; return value is vaguely described as 'the updated order object'. Could elaborate on billing/shipping structure or status enum meanings, but error handling is covered.

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

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

With low schema coverage (43%), the description lists key parameters but provides limited additional semantics beyond the schema. For example, billing/shipping are mentioned but not detailed.

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

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

The description clearly states the tool updates order status, addresses, or notes, and explicitly excludes line-item edits, distinguishing it from 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.

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

Provides when-to-use example ('mark order 100 as completed') and when-not-to-use guidance (line-item edits with alternative approach), though it doesn't explicitly contrast with all sibling tools.

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

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

Annotations already indicate this is a write operation (readOnlyHint=false) and not destructive. The description adds crucial context: partial update behavior, return format (markdown or json), and error handling (404 for missing product). This goes beyond annotations to inform the agent of expected outcomes.

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

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

The description is well-organized with clear sections: purpose, args, returns, examples, error handling. Every sentence adds value, and there is no redundant information. It is concise and easy to parse.

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

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

Given the tool's complexity (15 parameters, 1 required) and absence of output schema, the description covers key aspects: partial update, error handling, and return object. It could mention that tag_ids and category_ids replace existing assignments (though schema notes this), but overall it is sufficiently complete for an agent to use the tool effectively.

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

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

Schema description coverage is only 27%, so the description should compensate. It lists all parameters but provides no detailed semantics (e.g., valid values for status, how category_ids/tag_ids behave). The examples clarify a couple of parameters but leave most undocumented. Baseline is lower due to low coverage, and the description adds marginal value.

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

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

The description clearly states 'Update fields on an existing product', which distinguishes it from create, delete, and other product operations. It also specifies that only provided fields are changed, leaving others untouched.

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

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

Examples illustrate common use cases like marking out of stock or setting sale price, clearly implying when to use this tool. However, it does not explicitly state when not to use it (e.g., for creating a product), though that is implied by the sibling tool names.

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

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

Annotations indicate mutation and idempotency. Description adds that it returns the updated category object and lists error handling for 404, providing behavioral context beyond annotations.

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

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

The description is brief and well-structured with sections for args, returns, and error handling, containing no superfluous information.

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

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

For a simple update tool with 5 parameters and no output schema, the description covers purpose, parameters, return, and error handling adequately. It could mention additional constraints but is generally complete.

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

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

With schema coverage at 40%, the description lists all parameters (id required, name/description/parent optional, response_format with default), compensating for missing schema descriptions and clarifying usage.

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

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

The description explicitly states 'Update fields on an existing product category', using a specific verb and resource, and distinguishes it from sibling tools like create and delete.

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

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

It is clear the tool is for updating an existing category, with implicit differentiation from create/delete siblings. Error handling guidance for non-existent IDs is provided, but no explicit when-to-use vs alternatives is stated.

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

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

The description adds behavioral details beyond annotations: it specifies error handling (404 for missing ID), response_format options, and return type. Annotations already indicate idempotent and non-destructive, which are consistent.

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

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

The description is extremely concise: one sentence for purpose, a bullet list of args, and error handling. No wasted words, and essential information is front-loaded.

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

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

Given the tool's simplicity, the description covers the purpose, parameters, error handling, and return type. Annotations fill in idempotence and safety. No missing critical information for an update endpoint.

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

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

With 50% schema coverage, the description compensates by listing updateable fields (name, description) and clarifying id is required. It also explains response_format defaults. However, it doesn't add meaning for name or description beyond listing them.

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

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

The description clearly states 'Update fields on an existing product tag,' which is a specific verb and resource. It distinguishes itself from sibling tools like create, delete, or list product tags.

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

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

The description implies usage for updating existing tags via the word 'update,' but does not explicitly contrast with create or delete operations. The context is clear enough, but lacks 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.

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

Annotations already provide readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds error handling details (404 on not found), return value ('Returns: The updated variation object'), and confirms idempotency by stating only supplied fields change. This provides behavioral context beyond the annotations.

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

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

The description is well-structured with an intro, Args list, Returns, and Error Handling sections. It is concise and front-loaded with the purpose. Minor improvement could be more bullet-point style for readability.

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

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

Given the tool has 9 parameters, 2 required, no output schema, and annotations, the description covers the essential aspects: required IDs, updatable fields, output format, and error handling. It provides sufficient context for an agent to use the tool correctly.

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

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

Schema description coverage is only 11%, but the description lists the parameters (product_id, variation_id, sku, regular_price, sale_price, manage_stock, stock_quantity, stock_status, response_format) and groups them as 'pricing, stock, SKU.' It mentions response_format default and error handling. While not exhaustive, it adds meaning beyond the sparse schema descriptions.

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

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

The description clearly states the tool updates fields on an existing product variation, focusing on pricing, stock, and SKU. It uses the verb 'update' and specifies the resource, making it distinct from sibling tools like create, get, delete, and list variations.

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

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

The description implies usage for modifying existing variations through 'Update fields on an existing product variation' and 'Only supplied fields are changed.' However, it lacks explicit when-to-use or when-not-to-use guidance and does not mention alternatives among siblings.

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