Server Quality Checklist

Tool Scores

• create_categoryC
  2.4/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries full burden for behavioral disclosure. It fails to mention whether this modifies existing data, whether handle is auto-generated if omitted, whether is_active defaults are applied, or how parent-child relationships are validated. Being a create (mutation) tool with zero annotations, more disclosure is needed.

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

  Conciseness4/5

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

  The description is a single efficient sentence with no wasted words. It earns points for brevity, though this is achieved through under-specification rather than tight informational content.

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

  Completeness2/5

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

  For a mutation tool with 4 parameters, zero descriptions, no annotations, and no output schema, the tool description is significantly under-specified. It doesn't explain return values, hierarchical behavior, default values, or validation constraints. The complexity of category structures (parent/child, handle slugs, activation states) warrants substantially more documentation.

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

  Parameters2/5

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

  Schema description coverage is 0%, meaning none of the 4 parameters have meaningful descriptions in the schema. The description provides zero parameter-level information, so it does nothing to compensate for the coverage gap. No info about format, constraints, or semantics for name, handle, is_active, or parent_category_id.

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

  Purpose3/5

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

  The description 'Create a product category' uses a clear verb+resource structure, and it distinguishes from siblings (create_product, create_collection, create_variant) by naming the specific resource. However, it lacks any detail about scope or distinguishing features from create_collection, which appears closely related.

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

  Usage Guidelines2/5

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

  There is no guidance on when to use this tool vs alternatives like create_collection or list_categories. No context about prerequisites, hierarchy rules, or relationship to parent categories is provided despite parent_category_id being a parameter.

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

• create_collectionC
  2.4/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries full burden for behavioral disclosure. It does not state whether this is a mutation (implied by 'create'), whether it's reversible/deleteable, what response it returns, or any side effects. For a creation tool with zero annotation coverage, more context is needed.

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

  Conciseness4/5

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

  The description is a single concise sentence — appropriately short with no wasted words. However, brevity here crosses into under-specification given the zero schema coverage and no annotations.

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

  Completeness2/5

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

  For a 2-param creation tool with no annotations, no output schema, and 0% schema coverage, the description is inadequate. It doesn't cover return values, validation behavior, relationship to categories, or handle auto-generation. Both parameters are undocumented in both the description and the schema.

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

  Parameters2/5

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

  Schema description coverage is 0%, so the description must compensate. It mentions nothing about the 'title' or 'handle' parameters — what a handle is, whether it's auto-generated, uniqueness constraints, or format requirements. The description adds no param semantics beyond the bare schema field names.

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

  Purpose3/5

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

  The description states 'Create a product collection' with a specific verb (create) and resource (collection). However, it doesn't distinguish from the sibling create_category tool or explain what a collection is in this context. It's clear enough as a purpose statement but lacks differentiation.

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

  Usage Guidelines2/5

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

  No guidance on when to use this tool versus create_category, list_collections, or how it fits in a collection workflow. There's no mention of prerequisites (e.g., whether a store context is needed first via get_store_context) or when to prefer collections over categories.

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

• list_collectionsC
  2.6/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries full burden. It fails to disclose whether this is a read-only operation, whether pagination is required for large datasets, default behaviors, or what the response contains. For a list operation this is a notable gap, though 'list' implies read-only nature.

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

  Conciseness4/5

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

  Extremely concise single sentence with no wasted words. However, it borders on under-specification rather than efficient conciseness, slightly reducing the score.

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

  Completeness2/5

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

  With no output schema, no annotations, and a vague one-line description, this tool is under-documented. The schema does cover most parameters, but there's no info about return values, pagination behavior, or potential edge cases. This is a basic listing tool with minimal context for the agent.

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

  Parameters3/5

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

  Schema description coverage is 75%, with limit, fields, and offset already documented in the schema. The description adds nothing about the 'q' parameter (which appears to be the undocumented 25%). No additional meaning is provided beyond the schema.

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

  Purpose3/5

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

  The description states 'List product collections' which names the verb (list) and resource (product collections). However, it lacks specificity about scope (all collections? published only?) and doesn't distinguish from siblings like list_categories, list_products, or list_product_tags beyond the resource name.

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

  Usage Guidelines2/5

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

  No guidance on when to use this tool vs alternatives. There's no mention of context or when listing collections would be preferred over other list tools. The description is too brief to convey usage context.

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

• list_customersC
  2.6/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure, but it reveals nothing beyond the basic action. No mention of pagination behavior, default ordering, whether 'q' does fuzzy matching vs exact match, response size implications, or rate limiting. The 'limit' default of 20 is in the schema, not the description, so even that isn't behavioral disclosure at the description level.

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

  Conciseness4/5

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

  The description is a single short sentence — two words essentially. It's maximal conciseness with zero waste. It's not 'front-loaded' in any meaningful way since it's so short, but there's nothing to trim. However, it errs toward under-specification rather than true conciseness.

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

  Completeness2/5

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

  This is a list/search tool with 4 params, no output schema, and no annotations. The description needs to compensate for the missing structured context but fails to do so. No guidance on the 'q' search parameter semantics, no pagination workflow explanation, no note about what fields are returned by default, and no distinction from sibling list tools. For a tool with this many adjacent list tools, more completeness is needed.

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

  Parameters3/5

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

  Schema coverage is 75% (limit, fields, offset have descriptions; q does not). The description itself adds no parameter information beyond what the schema provides. Since schema coverage is high (75%, above the 80% threshold is marginal but close), baseline 3 is appropriate — the schema does the heavy lifting and the description adds little.

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

  Purpose3/5

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

  The description 'List/search customers' states clear verbs and a resource. However, it's somewhat generic and doesn't distinguish from sibling list tools like list_orders, list_collections, list_products, or list_categories — all of which follow the same pattern. It says what it does but not what makes it unique beyond the resource name.

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

  Usage Guidelines2/5

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

  No guidance on when to use this tool vs alternatives. It doesn't mention scenarios like finding a specific customer, paginating through large customer sets, or how it differs from get_order/list_orders. The 'q' parameter implies search capability, but there's no explicit guidance on search syntax or when search vs list is appropriate.

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

• list_product_typesC
  2.6/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not state whether this is a safe read operation, whether results are paginated by default, or what fields are returned. For a listing resource tool, the only behavioral hint comes from the `fields` and `limit` params in the schema, not the description. There's no explicit statement about the read-only nature or default return size.

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

  Conciseness4/5

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

  A single, efficient sentence with zero wasted words. It's appropriately minimal for a simple list operation, though one could argue it's so terse it borders on underspecification rather than conciseness.

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

  Completeness2/5

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

  Given no annotations, no output schema, and ambiguous relationship to three similar sibling tools (list_categories, list_collections, list_product_tags), the description is under-specified. It doesn't clarify what product types are, how they relate to variants or categories, or how results are structured. For a tool with 4 parameters and no supporting structure, more context is needed.

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

  Parameters3/5

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

  Schema description coverage is 75%, with `limit`, `fields`, and `offset` already documented in the schema. The `q` parameter has no schema description and is not explained in the tool description either — it's likely a search/filter term but unstated. The description adds no parameter meaning beyond what the schema provides, so the baseline-3 applies, with the undocumented `q` param being a minor gap.

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

  Purpose3/5

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

  The description "List product types" uses a specific verb (list) and resource (product types), making the core purpose clear. However, it lacks differentiation from siblings like `list_collections`, `list_categories`, and `list_product_tags` — all of which use the identical 'List X' pattern, so the agent may not immediately understand what distinguishes product types from these similar listing tools.

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

  Usage Guidelines2/5

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

  No guidance is given on when to use this tool versus list_categories, list_collections, or list_product_tags. The description is purely declarative with zero context about the intended use case, filtering capabilities, or scenarios where this tool is the right choice.

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

• list_ordersC
  2.7/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries the full behavioral disclosure burden. It mentions free-text search and paging but doesn't disclose return format, default ordering, whether results are sorted newest-first, or any rate/limit constraints. For a read-only listing tool with zero annotation coverage, this is a meaningful gap.

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

  Conciseness4/5

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

  Two short sentences, zero waste. The description efficiently mentions the core behavior (list recent orders) and key capabilities (free-text, paging). It's appropriately front-loaded and compact, though could arguably add a bit more behavioral detail without becoming verbose.

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

  Completeness3/5

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

  For a read-only list tool with good schema coverage (75%) and no output schema, the description is mostly adequate but lacks some context. It doesn't clarify what 'recent' means, whether results are paginated by the offset/limit pattern described, or how 'q' interacts with fields. No annotations compound the gaps.

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

  Parameters3/5

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

  Schema description coverage is 75%, so most parameters (limit, fields, offset) are already documented in the schema. The description adds 'q' free-text capability beyond the schema. Fields parameter's purpose is reasonably explained in schema. Baseline 3 is appropriate since schema largely handles the load.

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

  Purpose3/5

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

  The description states 'List recent orders' with a clear verb+resource (list orders), and mentions support for 'q' free-text and paging. However, it doesn't distinguish itself from sibling get_order or explain what makes it different from other listing tools, so it's adequate but not fully distinguished.

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

  Usage Guidelines2/5

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

  No when-to-use guidance, no alternatives mentioned. While it's reasonable to infer this is the default order listing (vs get_order for a single order), the description provides no explicit guidance on when to choose this over siblings or any exclusions/prerequisites.

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

• update_variantC
  2.7/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It implies mutation but doesn't state what happens to unspecified fields (are they preserved or reset?), whether prices requires multiple price objects, whether manage_inventory interacts with inventory levels, or what the response contains. A mutation tool with zero annotation coverage should describe more behavioral detail.

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

  Conciseness4/5

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

  A single efficient sentence lists the resource and updatable fields with no wasted words. It could be argued it's under-specified rather than concise, but for what it includes, it's tight.

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

  Completeness2/5

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

  For a 6-parameter mutation tool with no annotations and no output schema, this description is too thin. It doesn't explain the prices array structure, the interplay of manage_inventory with inventory tools (set_inventory_level, list_inventory_items are siblings), or what the update response returns. Given the tool is a mutation with side effects, more completeness is warranted.

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

  Parameters2/5

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

  Schema description coverage is 0%, so the description must compensate. It names title, sku, prices, manage_inventory, and options as updatable fields, providing basic mapping to 5 of 6 parameters. However, it doesn't explain the structure of 'prices' (array of objects with unknown shape), the meaning of manage_inventory, or how 'options' maps. The 'options' field isn't even in the schema, creating confusion about whether it's a valid update field or free-form.

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

  Purpose4/5

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

  The description states a specific verb ('Update') with a clear resource ('variant') and enumerates the fields it affects: title, sku, prices, manage_inventory, options. This is clear and distinguishes from sibling create_variant and delete_variant, though it doesn't explicitly name these alternatives.

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

  Usage Guidelines2/5

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

  No context is given for when to use this tool vs alternatives. It doesn't clarify that a variant must first exist, whether create_variant is preferred for new variants, or when delete_variant might apply. There is no guidance on when updating fields would require inventory management (manage_inventory) coordination.

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

• delete_variantC
  2.9/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure, but it only states that the tool deletes a variant. It fails to disclose whether the operation is destructive/irreversible, whether it cascades to inventory levels or line items, what happens to associated data, or what the response format is. For a destructive mutation tool, this is a significant transparency gap.

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

  Conciseness4/5

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

  The description is a single concise sentence that states the core purpose with no wasted words. It's appropriately terse for what it communicates, though it could add useful behavioral context in the same concise style.

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

  Completeness2/5

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

  For a destructive mutation tool with no annotations, no output schema, and zero param schema coverage, the description is under-specified. It should mention the irreversible nature of the action, the need for correct product_id/variant_id pairing, and what happens to dependent entities (inventory, order line items referencing the variant). The tool performs a destructive action on a key commerce entity, so more context is warranted.

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

  Parameters3/5

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

  Both parameters (product_id, variant_id) have zero schema description coverage, so the description must compensate. However, the description doesn't explicitly explain that product_id identifies the parent product and variant_id identifies the variant to delete, though the identifier semantics are fairly self-evident from parameter names. The description adds minimal value beyond the schema.

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

  Purpose4/5

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

  The description 'Delete a variant from a product' uses a specific verb (Delete) and resource (variant), and is clear about the target. It distinguishes from siblings like create_variant and update_variant by using the 'Delete' verb, though it doesn't mention consequences like removing inventory or associated data.

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

  Usage Guidelines2/5

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

  No guidance is provided about when to use this tool vs alternatives, prerequisites (e.g., whether the variant must exist, whether product must exist), or warnings about the irreversible nature of deletion. There's no exclusion guidance naming alternative tools for related operations.

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

• list_categoriesC
  2.9/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries the full burden of behavioral disclosure. It doesn't state whether this is a read-only operation, whether it requires auth, pagination behavior beyond the offset param, or what the default sort order is.

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

  Conciseness4/5

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

  The description is a single concise sentence with zero wasted words. It's efficient but arguably too minimal given the lack of annotations and the 4-parameter schema.

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

  Completeness2/5

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

  For a tool with no annotations, no output schema, and an undocumented 'q' parameter, the description is inadequate. It doesn't mention what fields are returned, default pagination limits, or filtering behavior of 'q'. The schema helps but the description leaves significant gaps.

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

  Parameters3/5

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

  Schema coverage is 75%, so most parameters (limit, fields, offset) are already documented in the schema. The 'q' parameter lacks a description, and the tool description doesn't compensate for that gap, but the schema covers the majority.

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

  Purpose4/5

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

  The description 'List product categories' uses a clear verb+resource construction that properly identifies the tool's function. It distinguishes from siblings like list_collections and create_category, though it doesn't explicitly contrast them.

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

  Usage Guidelines2/5

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

  No guidance is given on when to use this tool versus alternatives like list_collections or list_product_tags. The description is a bare statement of function with no context about filtering, scoping, or performance considerations.

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

• list_product_tagsC
  2.9/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It doesn't mention pagination defaults beyond the limit param, whether results are ordered, what the response shape is, or whether this covers all store tags or a scoped subset. For a list operation with no annotation coverage, this is thin.

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

  Conciseness4/5

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

  The description is a single efficient sentence with zero waste. It's appropriately laconic for a straightforward list operation, though it could add minimal value without bloating.

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

  Completeness2/5

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

  For a list tool with no annotations and no output schema, the description should provide more context. It doesn't mention pagination behavior, field selection guidance, or the purpose/typical use case of product tags in the Medusa ecosystem. The 4-parameter surface with pagination support suggests moderate complexity that the description doesn't unpack.

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

  Parameters3/5

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

  Schema description coverage is 75% — the limit, fields, and offset parameters already have descriptions in the schema. The description adds no parameter-level meaning beyond what the schema provides. The 'q' parameter lacks a schema description, but the tool description doesn't compensate for that gap either. Baseline 3 is appropriate.

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

  Purpose4/5

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

  The description 'List product tags' has a clear verb+resource structure. It's distinguishable from siblings like list_products, list_product_types, and list_categories by the specific resource (tags), though it doesn't explicitly note the distinction.

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

  Usage Guidelines2/5

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

  No guidance on when to use this tool versus alternatives. There's no mention of prerequisites (e.g., whether tags are a Medusa concept separate from categories/types), no exclusions, and no indication of when this would be preferred over list_categories or list_product_types.

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

• create_variantB
  3.1/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries full burden for behavioral disclosure. It mentions the primary inputs (options + prices) but does not disclose whether this requires product ownership/permissions, whether existing variants are replaced or appended, inventory implications, or behavior of optional fields like manage_inventory and sku. For a mutation tool with zero annotation coverage, key behaviors remain opaque.

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

  Conciseness4/5

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

  The description is a compact two-sentence structure that front-loads the core action and includes a concrete, useful example. It's efficient with few wasted words, though it could be expanded to cover critical behaviors without becoming bloated.

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

  Completeness2/5

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

  With 6 parameters, no output schema, no annotations, and no guidance on return values or side effects, the description is insufficient for a mutation tool. It covers options and prices but leaves sku, manage_inventory, and title semantics undocumented, and gives no sense of what the response contains or error conditions to expect.

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

  Parameters3/5

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

  Schema description coverage is only 17%, and the description partially compensates by explaining options (map of option title->value) and prices (array of {amount, currency_code}) with a concrete example. However, it doesn't clarify sku, manage_inventory, or title semantics beyond what the schema shows, leaving several parameters under-specified.

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

  Purpose4/5

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

  The description states 'Add a variant to an existing product' with a specific verb+resource, clearly defining the action. It also implicitly differentiates from siblings like create_product and update_variant by specifying it adds to an existing product, though it doesn't explicitly name alternative tools.

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

  Usage Guidelines3/5

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

  The description implies usage context ('Add a variant to an existing product') but provides no exclusions or explicit when/not-to-use guidance. It doesn't differentiate from update_variant or delete_variant for the agent, though the example usage gives practical framing.

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

• get_orderB
  3.1/5.0
  Behavior2/5

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

  No annotations are provided (no readOnlyHint, destructiveHint, or other safety indicators), so the description carries the full burden of behavioral disclosure. It only states 'Get full details' without clarifying whether this is a safe read, what 'full details' encompasses, whether it might fail for certain order states, or what the response structure looks like. For a tool with zero annotation coverage, more behavioral context is needed.

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

  Conciseness4/5

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

  A single efficient sentence with zero waste. The description is appropriately short for a simple get-by-id tool. It front-loads the primary action clearly. It could arguably be slightly more informative, but for a one-parameter read tool, this length is reasonable.

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

  Completeness2/5

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

  This is a single-parameter read tool with no output schema and no annotations. The description covers the basic purpose but leaves significant gaps: no output structure, no error/success conditions, no explanation of related sibling context (list_orders returns summaries vs this returns full details). For a moderately complex retrieve operation, the description should add a bit more context than a bare single sentence.

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

  Parameters3/5

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

  With only 1 parameter and 0% schema description coverage, the description must explain the 'id' parameter. The phrase 'by id' loosely signals that id is the order identifier, but the description doesn't clarify what kind of id (system ID vs external reference), or its format/length. However, with a single self-evident parameter named 'id' and the tool named 'get_order', the parameter meaning is inherently clear from naming context.

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

  Purpose4/5

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

  The description states a clear verb+resource ('Get full details of one order') and specifies the lookup key ('by id'). It's distinct from siblings like list_orders (which lists multiple) and get_product (different resource). However, it doesn't explicitly distinguish from list_customers or other get_ tools, though the resource name is self-evident.

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

  Usage Guidelines3/5

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

  The intent is implied: use when you need full details of a single order. However, there's no explicit guidance on when to use get_order vs list_orders, no mention of prerequisites (e.g., order must exist), and no alternative tools named. Basic context exists but no exclusions are provided.

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

• list_inventory_itemsB
  3.2/5.0
  Behavior2/5

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

  No annotations provided, so the description carries the full burden. It states it lists items and optionally searches, but doesn't disclose pagination behavior beyond the schema's offset param, default result cap, whether results are ordered, what fields each item contains, or rate-limit/auth implications. It does mention using 'fields' to keep responses small, which is a partial behavioral hint. No contradiction with annotations (none exist).

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

  Conciseness4/5

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

  Single efficient sentence in the description; params carry their own detail. Minimal waste. Could arguably add more value, but the structure is appropriately terse and front-loaded.

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

  Completeness3/5

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

  The tool has 4 optional parameters, no output schema, no annotations, and no nested objects. It's a moderately simple filtered-list operation. The description covers the search feature but omits details like default sort order, pagination semantics interplay between offset/limit, and what the default return shape looks like. Adequate for a simple listing tool, but with clear gaps given zero annotation support and no output schema.

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

  Parameters3/5

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

  Schema coverage is 75%: 'limit', 'fields', and 'offset' are documented in the schema, but 'q' has no description there. The description adds meaning for 'q' (search by sku/title), which compensates for the one undocumented parameter. The description doesn't add format details beyond what schema provides for the other three params. Baseline 3 is appropriate.

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

  Purpose4/5

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

  Clear verb+resource: 'List inventory items'. It also notes optional search by sku/title via 'q', distinguishing it as a listing/search tool. However, it doesn't explicitly distinguish from sibling tools like list_products, list_orders, or list_collections — those are different resource types, so the resource name provides enough differentiation.

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

  Usage Guidelines3/5

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

  The description implies it's for browsing inventory items and optionally searching. It doesn't name alternatives (e.g., when to use list_products vs this tool, or when to use set_inventory_level for mutations). No exclusions or when-not-to-use guidance. Adequate but minimal context.

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

• list_productsB
  3.2/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries the full behavioral burden. It does not disclose whether this is a read-only operation, response format, default pagination behavior, or performance considerations. For a listing tool with no annotations, more behavioral context (e.g., read-only safe, returns array of products) would be expected.

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

  Conciseness4/5

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

  A single concise sentence front-loaded with the core purpose (list/search products) followed by supported filter dimensions. Focused and efficient with no wasted words. Good density of useful information.

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

  Completeness3/5

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

  For a listing tool with no output schema and no annotations, the description is adequate but minimal. It covers main dimensions (search, status, taxonomy filters) but omits pagination guidance, default behavior, and return value shape. With 9 parameters and no output schema, it would benefit from a bit more context while remaining reasonable.

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

  Parameters3/5

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

  Schema description coverage is 56%, meaning several params (tag_id, type_id, category_id, collection_id) have no schema-level descriptions. The description mentions these filters at a high level ('filtering by collection/category/tag/type id') which partially compensates, but doesn't add detail about accepted ID formats or behavior when multiple filters combine. Baseline 3 is appropriate given partial coverage with some description compensation.

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

  Purpose4/5

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

  The description clearly states this tool lists/searches products and enumerates the filtering dimensions (free-text, status, collection/category/tag/type). It distinguishes itself reasonably from siblings like get_product (single product retrieval) and list_orders/list_customers (other entities). However, it doesn't explicitly contrast with the sibling list tools.

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

  Usage Guidelines3/5

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

  The description lists what filtering is supported but does not state WHEN to prefer this over alternatives like get_product, or when not to use it. No guidance on pagination via limit/offset or the tradeoff with fields is explicitly described in the prose, though the schema documents some of it.

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

• set_inventory_levelB
  3.4/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full behavioral disclosure burden. 'Set' implies a state-changing write operation, which is reasonably clear, but it doesn't describe effects like whether overrides are absolute or additive, whether there are validation constraints (e.g., negative quantities rejected), or whether changes are reversible. It's a mutation tool with no annotation coverage, so more context would be valuable.

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

  Conciseness4/5

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

  Two sentences, efficient and front-loaded with the core purpose first. The second sentence provides useful pointer context. No wasted words.

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

  Completeness3/5

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

  For a 3-parameter, all-required mutation tool with no annotations and no output schema, the description is adequate but thin. It tells the agent what the tool does and how to find required IDs, but says nothing about the return value, error cases, or semantic behavior of stocked_quantity (absolute set vs. delta). Given the tool's simplicity, a 3 is fair but borderline.

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

  Parameters2/5

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

  Schema description coverage is 0%, and the description does not explain any of the three parameters beyond their schema types. Nothing clarifies what stocked_quantity means (units? whether it's an absolute overwrite?), or what format location_id and inventory_item_id take. With zero coverage, the description should compensate but doesn't.

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

  Purpose4/5

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

  The description uses a specific verb ('Set') with a clear resource ('stocked quantity for an inventory item at a stock location'), which clearly distinguishes it from the sibling read tools like list_inventory_items. It's clear but doesn't explicitly contrast with siblings beyond the reading tools.

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

  Usage Guidelines4/5

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

  The description names sibling tools list_inventory_items and get_store_context as prerequisites for finding the required IDs. This provides helpful context on how to gather inputs, though it doesn't explicitly say when NOT to use this tool or contrast it with other mutation tools.

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

• medusa_admin_requestA
  3.6/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the burden of behavioral disclosure. It does disclose that POST/DELETE are destructive and instructs the user to confirm first, and notes the path must start with /admin. However, it doesn't disclose auth requirements, rate limits, response format, or what happens on errors. It's an escape hatch—inherently higher-risk—but the description does flag the key risk (destructive actions).

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

  Conciseness4/5

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

  The description is compact at two sentences, front-loads the core purpose ('low-level escape hatch'), and packs the key constraints (path must start with /admin, destructive confirmation). Every sentence earns its place. Could add a tiny concrete example, but overall is efficient and well-structured.

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

  Completeness4/5

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

  Given this is a general-purpose HTTP passthrough with no output schema and no annotations, the description does a reasonable job covering the essential guidance: what it does, when to use it, key constraints, and safety warnings. It doesn't over-specify return values (reasonable for an unspecified endpoint), but is adequately complete for an escape-hatch tool. The naming of uncovered domains helps the agent route correctly.

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

  Parameters3/5

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

  Schema coverage is 75%, so most parameters are already documented in the schema. The description adds the constraint that path must start with /admin, which is useful context beyond the schema's example. However, it doesn't explain the interaction between body/query and method semantics (e.g., which methods typically take a body), nor provide examples of how to combine the parameters.

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

  Purpose4/5

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

  The description clearly states it's a low-level escape hatch to call any Medusa Admin API endpoint directly, with specific verb (call) and resource (Medusa Admin API). It explicitly lists uncovered use cases (fulfillments, price lists, promotions, refunds, uploads), distinguishing it from the curated sibling tools. Slightly weaker on naming exactly what it returns.

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

  Usage Guidelines4/5

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

  The description explicitly says 'Use for anything the curated tools don't cover' and lists examples of uncovered domains, which signals when this should be used vs sibling curated tools. It also warns about POST/DELETE being destructive and says to confirm with the user first. However, it doesn't explicitly name alternative tools for covered use cases or state 'don't use this if a curated tool exists' as explicit exclusion guidance.

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

• get_productA
  3.7/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full burden. It discloses what is returned (variants, options, prices, images, tags), which is useful behavioral context. However, it doesn't mention error behavior for non-existent ids, auth requirements, or pagination/nesting depth of the response.

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

  Conciseness5/5

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

  A single efficient sentence covers purpose and included data. Zero wasted words, perfectly front-loaded with the action and subject.

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

  Completeness3/5

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

  A simple read-only single-record fetch with fully documented parameters and rich return content listed. The description covers the key retrieval scope. However, with no annotations and no output schema, it could benefit from noting error/not-found behavior and whether variants/options are nested or flat.

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

  Parameters3/5

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

  Schema coverage is 100%, so both parameters are documented in the schema. The description mentions the included data which relates to fields, but doesn't add detail beyond the schema for the 'fields' parameter format examples or the meaning of the wildcard syntax beyond what the schema already provides. Baseline 3 applies.

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

  Purpose5/5

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

  Clear specific verb+resource: 'Get a single product by id'. Explicitly enumerates what's included (variants, options, prices, images, tags), distinguishing it from list_products and other product operations. The scope is unambiguous.

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

  Usage Guidelines3/5

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

  The description implies single-record retrieval by id but doesn't explicitly contrast with list_products for bulk retrieval, nor mention when the 'fields' param is helpful for keeping responses small. Usage context is clear from the name and schema but no explicit when/when-not guidance is given.

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

• create_productA
  3.8/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full transparency burden. It does disclose meaningful behavioral details: variant prices use major currency units, images should be public URLs, and status controls visibility. However, it doesn't mention defaults beyond 'draft' status, what happens on creation (e.g., whether handle auto-generation is the only auto behavior), or potential side effects. Given multiple behavioral disclosures, 3 is appropriate.

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

  Conciseness4/5

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

  The description is a single paragraph, reasonably compact for the complexity it covers. It front-loads the core action and then provides key operational details plus a concrete example variant. It's somewhat dense with commas and chained clauses, but every sentence adds meaningful guidance. A slightly more structured format could help, but it's efficient for 20 parameters.

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

  Completeness4/5

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

  For a 20-parameter creation tool with low schema coverage and no annotations or output schema, the description does a solid job explaining the most complex and error-prone aspects: variant/option relationships, currency formatting, and status semantics. The concrete example variant bridges the gap on complex nested structures. Gaps remain for several parameters (type_id, material, category_ids semantics), and there's no explanation of return behavior, but the description handles the core complexity well.

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

  Parameters4/5

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

  Schema coverage is only 45%, so the description must compensate for undocumented parameters. It adds substantial value: explains the variant structure with a full JSON example, clarifies currency unit format, and explains that images are public URLs. However, 20 parameters exist and 11 have no schema description, leaving several (type_id, material, subtitle, weight, discountable, collection_id, etc.) unexplained in both schema and description. The description covers the most critical creation parameters well.

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

  Purpose4/5

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

  The description clearly states 'Create a product' with a specific verb and resource, and elaborates on key creation aspects (options, variants, status, images). It doesn't explicitly differentiate from siblings like create_variant (which is for adding variants to existing products) or update_product, but the creation-focused purpose is clear and distinct enough given the verb.

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

  Usage Guidelines4/5

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

  The description provides usage context by explaining key workflows: how to structure options/variants, how to set publish status ('draft' vs 'published'), and how to pass images. It explains the variant structure with a concrete example. However, it doesn't explicitly state when to use this vs alternatives like create_variant or update_product, nor does it mention prerequisites like needing type_id or category_ids.

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

• update_productA
  3.8/5.0
  Behavior3/5

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

  No annotations provided, so description carries the burden. The description discloses partial-update behavior and the publish mechanism, but doesn't state what happens to fields not specified (whether they're preserved), whether collection_id must reference an existing collection, or any auth/permission requirements. Mutation is implied by 'Update' but reversible behavior isn't documented.

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

  Conciseness4/5

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

  Focused two-sentence description with no wasted words. The publish example is concrete and useful. Could be marginally more structured but is cleanly front-loaded with the primary purpose.

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

  Completeness3/5

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

  For a mutation tool with no annotations and no output schema, the description should clarify more: whether unspecified fields are preserved (partial vs. full replace), validation constraints, and response behavior. The partial-update hint and publish example are helpful but the tool leaves meaningful ambiguity for an agent deciding how to invoke it safely.

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

  Parameters3/5

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

  Schema description coverage is 0%, so the description carries full burden for the 8 parameters. The description lists several parameter names (title, description, status, thumbnail, collection_id) and explains the status='published' effect, but handle, subtitle remain undocumented in both schema and description. It adds some meaning beyond the bare schema but doesn't compensate for the full coverage gap.

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

  Purpose5/5

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

  Clear verb+resource ('Update fields on an existing product') with explicit enumerated fields (title, description, status, thumbnail, collection_id). Distinguishes from create_product and delete_product siblings by focusing on partial updates.

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

  Usage Guidelines4/5

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

  States 'Only include fields you want to change' which clarifies partial-update semantics, and gives a concrete publishing example ('To publish: set status='published''). Lacks explicit when-not-to-use guidance but context is reasonably clear given sibling tool names.

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

• delete_productA
  4.2/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the action is permanent and irreversible, giving the agent the critical safety information needed before invoking a destructive operation. It doesn't mention side effects (e.g., associated variants/inventory behavior), but the permanence warning is the key behavioral trait and is explicitly disclosed.

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

  Conciseness5/5

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

  Two concise sentences that deliver the full message: what the tool does and the critical safety warning. Zero filler, every word earns its place. Perfectly front-loaded with the core action.

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

  Completeness4/5

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

  For a single-parameter destructive operation with no output schema and no annotations, the description covers the essential elements: what it deletes, how it's identified, and the permanence warning. It doesn't describe associated-resource cascade behavior, but for a simple delete-by-ID tool, the description is sufficiently complete for an agent to use it safely and correctly.

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

  Parameters3/5

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

  With only 1 parameter and 0% schema description coverage, the schema provides no documentation for the 'id' field beyond its type (string). The description states 'by id' and clarifies it refers to the product ID, which adds context. However, with a single obvious parameter named 'id' and the description explicitly mentioning 'by id', the baseline is adequate even without schema coverage — the description names the parameter's semantic meaning.

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

  Purpose4/5

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

  The description clearly states the verb (delete), the resource (product), and the identifier used (by id). It's unambiguous about the action and target. However, it only differentiates from siblings like delete_variant through the explicit 'product' resource, which is clear enough given the sibling names.

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

  Usage Guidelines5/5

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

  The description explicitly states 'This is permanent' and instructs to 'confirm with the user first.' This provides a clear when-to-use guardrail: the agent should confirm with the user before invoking, distinguishing this destructive action from read-only sibling tools. It also implicitly signals this is NOT for variants (delete_variant exists separately).

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

• get_store_contextA
  4.4/5.0
  Behavior3/5

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

  There are no annotations provided, so the description carries full burden for behavioral disclosure. It describes a read/context operation implicitly ('Return store defaults'), which strongly implies non-destructive behavior. However, it doesn't explicitly state it performs no side effects, requires no auth, or describe the return format. Fair but not rich.

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

  Conciseness5/5

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

  Two sentences, zero wasted words. First sentence delivers the purpose and the data scope; second sentence gives the actionable 'when-to-use' trigger. Exceptionally tight and front-loaded.

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

  Completeness4/5

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

  For a zero-parameter, context-priming tool with no annotations and no output schema, it describes what it returns conceptually and when to call it. The main gap is not describing the exact return structure (e.g., how to extract each code/ID), but given its simplicity the description is adequate and complete enough to guide correct invocation.

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

  Parameters4/5

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

  The tool has 0 parameters and 100% schema coverage (nothing to cover), but the description compensates by specifying exactly what data the agent receives (regions, currency codes, sales channels, stock locations, price preferences). Since 0 params = baseline 4 by the rubric, it earns the comfortable baseline.

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

  Purpose5/5

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

  Specific verb+resource: 'Return store defaults an agent needs BEFORE creating products.' It lists the specific data delivered (regions & currency codes, sales channels, stock locations, price preferences), distinguishing this from sibling product creation/listing tools clearly. It's a distinct setup/context-gathering tool.

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

  Usage Guidelines5/5

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

  Explicitly says 'Call this first when unsure about currency_code / sales_channel_id / location_id.' This directly ties usage to a precise trigger condition (uncertainty about specific identifiers) and positions it as a precursor to create_product. Strong exclusions/context guidance.

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