Server Quality Checklist

Tool Scores

• shopify_recent_product_changesB
  3.3/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's 'List...' phrasing is consistent and adds no contradiction. The description adds the lookback-window scope and the returned field list, which is useful. However, it doesn't disclose pagination behavior despite the 'first' param limiting per-store results, nor clarify whether 'updated' means created or modified. With annotations covering the safety profile, a 3 is appropriate – the description adds some but not rich behavioral context.

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

  Conciseness5/5

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

  A single, efficient sentence with no redundant words. The primary action and scope ('List products updated during a selected lookback window across multiple stores') is front-loaded, with the field list appended at the end. Every word earns its place.

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

  Completeness3/5

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

  For a 3-parameter tool with full schema coverage and read-only annotations, the description covers the basics: purpose, scope, and output fields. However, with no output schema and 21 overlapping sibling tools, it lacks (a) differentiation guidance and (b) clarification of 'updated' semantics and pagination. Given the ambiguity risk and sibling density, it falls short of fully complete.

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

  Parameters3/5

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

  Schema description coverage is 100%; all three parameters (days, first, stores) are documented in the schema with descriptions. The description's phrases 'lookback window' (maps to days) and 'across multiple stores' (maps to stores) reinforce the parameter meanings but add nothing beyond the schema. Baseline 3 is correct when the schema carries the full semantic load.

  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 ('List'), a specific resource ('products updated during a selected lookback window'), and states scope ('across multiple stores') along with included fields (status, inventory, vendor, product type). This is clear and distinct. It loses a point because it doesn't explicitly differentiate from similar siblings like shopify_search_products_many or shopify_get_product_everywhere.

  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 the many overlapping siblings (shopify_search_products_many, shopify_get_product_everywhere, shopify_compare_catalog). The description never states 'use this when you need recent changes' or names an alternative for other cases. An agent reading the description alone cannot decide between this and the search/cross-store tools.

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

• shopify_search_products_manyA
  3.5/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true, so the tool is known to be safe. The description adds 'bounded per-store results and completeness indicators', which is valuable context not in annotations. However, it does not explain what the completeness indicators mean or whether results are capped by the 'first' parameter across all stores.

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

  Conciseness5/5

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

  One sentence, technically dense, front-loads the core purpose and constraints. Zero waste, perfectly sized for an MCP description.

  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?

  Given the tool has 3 parameters, 100% schema coverage, and a single-sentence description, it covers the basics well. However, the lack of an output schema and the mention of 'completeness indicators' without elaboration leaves the agent uncertain about return format and how to interpret partial results. For a search tool across multiple stores, slight additional detail on result structure would improve completeness.

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

  Parameters3/5

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

  The schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds value by mentioning 'per-store results' and 'completeness indicators', but does not clarify the meaning of 'first' (e.g., per store, not total) beyond the schema's 'per store' wording. No extra semantics beyond that.

  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 ('Search') and resource ('products across stores'), and clarifies it supports plain terms or Shopify syntax. It doesn't explicitly distinguish from siblings like shopify_get_product_everywhere or shopify_graphql_query_many, which also search products across stores, but the mention of 'per-store results' hints at its batch nature.

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

  Usage Guidelines3/5

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

  The description implies a use case (searching across multiple stores) but does not state when to prefer this over siblings such as shopify_get_product_everywhere (which might be more exhaustive) or shopify_graphql_query_many (which might allow arbitrary queries). No explicit exclusions or alternatives are given.

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

• shopify_compare_catalogA
  3.6/5.0
  Behavior3/5

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

  With annotations declaring readOnlyHint, idempotentHint, and destructiveHint=false, the safety profile is already covered. The description adds the specific fields being compared, which is useful context, but does not disclose any behavioral traits beyond that, such as how missing handles are handled or the format of the comparison result.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence that efficiently communicates the tool's purpose. It lists the comparison fields without unnecessary elaboration, making it easy for an agent to parse quickly.

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

  Completeness4/5

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

  Given the tool's moderate complexity (two array inputs with validations) and the presence of annotations covering safety, the description is mostly complete. The only gap is the lack of clarity about the output format—a comparison tool typically returns some diff or aggregated view, but this is not described. However, for a read-only tool with well-defined inputs, this omission is minor.

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

  Parameters3/5

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

  Schema description coverage is 100%, so both 'stores' and 'handles' are already well-documented with their types and constraints. The description reinforces the meaning (e.g., 'across multiple Shopify stores' and 'exact handles') but does not add extra semantic detail beyond the schema, such as what constitutes a valid handle or store alias. Baseline of 3 is appropriate.

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

  Purpose4/5

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

  The description clearly states the action ('Compare') and the specific fields (product titles, status, vendor, product type, and inventory) for exact handles across multiple Shopify stores. It is distinct from sibling 'shopify_compare_inventory' because it covers more than just inventory, though it does not explicitly name that alternative.

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

  Usage Guidelines3/5

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

  The description implies the usage: when you need to compare catalog fields across stores. However, it does not explicitly state when to use this tool versus the sibling 'shopify_compare_inventory' or other tools like 'shopify_portfolio_snapshot'. No exclusions or alternative routing are provided, leaving the agent to infer.

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

• shopify_fulfillment_sla_reportA
  3.6/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the grouping behavior and SLA threshold context, but does not disclose output format, pagination, or potential edge cases, so it adds moderate value beyond the annotations.

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

  Conciseness4/5

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

  The description is a single sentence that is front-loaded with the core action and includes the key configurable SLA aspect. It is efficient and has no redundant wording, though it could marginally benefit from a brief mention of output or scope.

  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?

  Given the schema's rich parameter documentation and the read-only annotations, the description is mostly adequate for an agent to decide to call this tool. However, without an output schema, it does not describe what the report contains (e.g., age buckets or breach counts), which is a gap for an agent needing to interpret results.

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

  Parameters3/5

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

  Schema description coverage is 100%, so all four parameters (first, stores, slaDays, lookbackDays) are already documented in the schema. The description adds no additional parameter-level detail, and with full schema coverage, a baseline of 3 is appropriate.

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

  Purpose5/5

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

  The description states a specific action ('group open unfulfilled orders into age buckets') and a clear objective ('identify orders older than a configurable fulfillment SLA'), which distinguishes it from sibling tools like shopify_list_unfulfilled_orders. The verb and resource are explicit and not tautological.

  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 its use for SLA breach reporting, but it does not explicitly state when to use this tool over alternatives such as shopify_list_unfulfilled_orders or shopify_order_summary. There is no direct comparison or exclusion, leaving the agent to infer the best choice.

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

• shopify_graphql_mutationA
  3.6/5.0
  Behavior3/5

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

  Annotations provide readOnlyHint: false, destructiveHint: true, openWorldHint: true. The description reinforces the mutation aspect and the confirmation requirement, but it doesn't add much beyond the schema's confirm parameter description. It doesn't disclose rate limits, idempotency, or what happens on partial failure—context that would be valuable given the openWorldHint. Since annotations already indicate mutation and non-read-only, the description's additional behavioral context is limited.

  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 action and the crucial rule about confirm. It is front-loaded with the most important information for an agent to decide to use it and to invoke it correctly.

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

  Completeness3/5

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

  The tool is destructive (destructiveHint=true) and has an openWorldHint=true (likely meaning mutations can have unknown effects). The description alerts to setting confirm true only after user authorization, which is critical safety guidance. However, it does not explain what a successful mutation returns, that it only accepts a single mutation (maybe clear from 'one GraphQL Admin API mutation'), or how failures are reported. With no output schema, additional return info would help, but the main use case is clear.

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

  Parameters3/5

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

  Schema coverage is high: mutation, store, confirm, variables all have descriptions. The description adds the key behavioral rule about confirm needing user authorization, which is a semantic beyond the schema's 'must be true' phrasing. However, it doesn't elaborate on the mutation parameter's structure (e.g., expectation of mutation keyword, how variables map) or the store parameter beyond what schema says.

  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 ('Run') and resource ('one GraphQL Admin API mutation against one named store'). It clearly indicates the tool executes a single mutation per call, distinguishing it from batch or query tools. However, it does not explicitly differentiate from sibling tools like shopify_graphql_query or shopify_list_stores, so it relies on the phrase 'mutation' to imply the write nature.

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

  Usage Guidelines4/5

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

  It says when to set confirm to true ('only after the user authorizes the exact store and change'), which is a critical usage condition. It implies this tool is for mutations (vs queries by sibling names), but it doesn't explicitly state when NOT to use it or name alternatives like shopify_graphql_query_many. Provides clear context for required authorization but lacks explicit exclusion of other tools.

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

• shopify_list_unfulfilled_ordersA
  3.6/5.0
  Behavior3/5

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

  Annotations already convey read-only, idempotent, and non-destructive behavior. The description adds a key behavioral detail (independent per-store results) and the status filter (open, unfulfilled), which are not in the annotations. However, it omits information about pagination, ordering, or output structure, which would be contextually useful. Meets the baseline for having annotations.

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

  Conciseness5/5

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

  The description is a single, concise sentence that front-loads the core purpose and key scoping detail (independent per-store results). No filler or redundant wording.

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

  Completeness4/5

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

  Given it is a list tool with read-only annotations and a complete schema, the description covers the essential purpose and key behavioral nuance. It does not describe the exact return format, but for a list tool this is often predictable. The lack of an output schema shifts some responsibility to the description, yet the description adequately outlines the main result grouping.

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

  Parameters3/5

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

  The input schema provides full descriptions for all three parameters, so the description adds marginal value. The phrase 'independent per-store results' hints at the behavior of the stores parameter but does not elaborate beyond the schema's own store-alias documentation. Baseline of 3 applies due to 100% schema coverage.

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

  Purpose5/5

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

  The description clearly states a specific verb (List), resource (recent open, unfulfilled orders), and scope (across multiple Shopify stores with independent per-store results). This is detailed enough to differentiate from general list tools and sets precise expectations.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives such as shopify_graphql_query or shopify_portfolio_snapshot. It does not mention any prerequisites, exclusions, or conditions that would direct an agent to choose this tool over others.

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

• shopify_store_locationsA
  3.6/5.0
  Behavior3/5

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

  Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the agent knows this is safe. The description adds the scoping of 'selected stores or full portfolio', which is useful. However, it doesn't describe what the output looks like (e.g., a table of locations with statuses) or any pagination or volume limits. Since annotations cover the safety profile well, this is acceptable but could add more.

  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 sentence with moderate length, front-loaded with the key action 'Review' and the resource 'locations'. It lists the multiple dimensions efficiently without verbose detail. It's concise and structured reasonably, though it could be slightly more scannable with a bullet list, but it's fine.

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

  Completeness4/5

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

  For a read-only review tool with a single optional parameter and full schema coverage, the description is fairly complete. It tells the agent what it does, the dimensions covered, and the scoping (selected or full portfolio). It lacks a note on output format or typical use cases, but given the simplicity and annotations, it's solid. The sibling tools provide context, and the description adequately distinguishes it.

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

  Parameters3/5

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

  Schema description coverage is 100%: the only parameter, 'stores', is described as 'Stores to include. Omit this field to include every configured store.' The description also mentions 'selected stores or the full portfolio', which aligns. The description adds no additional detail beyond the schema, but since coverage is high, baseline 3 is appropriate.

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

  Purpose4/5

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

  The description clearly states the tool reviews location status across multiple dimensions (active, inactive, legacy, fulfillment, inventory, and address status) for selected stores or the full portfolio. It distinguishes this from siblings like shopify_list_stores (which lists stores) and shopify_get_shop_info (which gets shop info). However, it doesn't explicitly differentiate from potential inventory-focused siblings like shopify_compare_inventory or shopify_low_stock_report, though the focus on locations helps.

  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 says 'across selected stores or the full portfolio', giving a clear sense of when to use it: to review location status across stores. It implies it covers a broad portfolio-wide review of locations, which could be distinguished from more specific reports. However, it doesn't explicitly state when NOT to use it or name alternative tools for specific location sub-queries (like inventory status might be better handled by shopify_compare_inventory).

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

• shopify_compare_collectionsA
  3.7/5.0
  Behavior4/5

  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 meaningful behavioral context beyond annotations, noting exact handles (not fuzzy matching) and listing the specific attributes compared. This gives a clear expectation of comparison semantics.

  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 front-loaded sentence and largely efficient. It lists all key comparison areas in a compact presentation. It loses a point due to the awkward repeated 'collection collections' phrase and because 'Compare exact collection' initiation could be clearer.

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

  Completeness4/5

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

  For a low-complexity tool with 100% schema coverage and read-only/idempotent non-destructive annotations, the description is largely sufficient. It conveys the main purpose and comparison fields. It does not define output format, but in the context of a comparison tool, comfortable to infer output shape from the listed fields.

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

  Parameters3/5

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

  Schema description coverage is 100% (stores and handles both have descriptions). The description adds no further detail about parameter padding, formats, or conventions beyond what the schema already provides. Baseline 3 is appropriate when the schema covers all parameters consistently.

  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 operation (Compare) on a specific resource (exact collection handles) across stores and enumerates the compared fields. This distinguishes it from sibling compare tools (compare_catalog, compare_inventory, compare_prices). Minor typo 'collection collections' slightly reduces clarity but does not undermine intent.

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

  Usage Guidelines3/5

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

  The description implies usage for cross-store collection comparison but gives no explicit when-to-use, when-not-to-use, or alternatives guidance. An agent can infer from the resource name that this is for collections, not inventory or prices, but no explicit routing is provided.

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

• shopify_catalog_healthA
  3.8/5.0
  Behavior3/5

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

  Annotations already disclose the operational profile: readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description contributes useful scoping — 'recent products' and 'selected stores' — plus the concrete list of attributes checked. It doesn't disclose potential nuances like API rate limiting across multiple stores, failure behavior on one bad store alias, or result shape, but for a safe read-only audit the description plus annotations are adequate.

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

  Conciseness5/5

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

  A single, well-constructed sentence with zero wasted words. The key verb 'Audit' is front-loaded, and the list of six audit dimensions is compact yet exhaustive. Every element earns its place — no filler, no redundancy.

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

  Completeness4/5

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

  For a read-only, idempotent audit tool with 100% schema coverage and descriptive annotations, the definition is thorough: it names the exact checks, the scoping via 'recent' and 'selected stores,' and the input shape. The only minor omission is the lack of any description of the output/report format, but since no output schema exists and the audit criteria are explicit, an agent has enough to call it correctly.

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

  Parameters3/5

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

  Schema description coverage is 100% — both `first` ('Maximum recently updated products scanned per store.') and `stores` ('One to ten configured store aliases') are documented inline. The description's 'recent products' loosely maps to the `first` parameter and 'selected stores' maps to `stores`, but adds no new syntax or format detail beyond what the schema already provides. Per the baseline rule (coverage >80%), score 3 is appropriate.

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

  Purpose5/5

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

  The description names a specific verb ('Audit'), a precise resource ('recent products across selected stores'), and an exhaustive list of audit dimensions (missing vendor, product type, SEO fields, featured media, media alt text, active products without inventory). Despite sharing the 'catalog' them with siblings like shopify_catalog_gap_report and shopify_compare_catalog, the distinctive multi-attribute check list makes its purpose unmistakable and non-overlapping.

  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 its usage context — auditing catalog hygiene across selected stores — through the phrase 'across selected stores' and the specific checks performed. However, it never names alternatives or when NOT to use it. Given the crowded sibling space (shopify_catalog_gap_report, shopify_compare_catalog, shopify_recent_product_changes), explicit exclusion guidance would have earned a higher score; as-is, the agent must infer fit from the audit criteria.

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

• shopify_compare_inventoryA
  3.8/5.0
  Behavior3/5

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

  Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the detail that it compares 'selected SKUs' and covers multiple stores, which aligns with the read-only comparison nature. It does not describe pagination, rate limits, or the exact output format, but the read-only nature is well covered by annotations. There is no contradiction.

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

  Conciseness5/5

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

  The description is a single clear sentence that front-loads the action and resource, then specifies the parameters (SKUs, stores) and the fields compared. Every phrase adds value—no filler or repetition. It is appropriately concise for the complexity.

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

  Completeness4/5

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

  For a read-only comparison tool with 100% schema coverage and strong annotations (readOnly, idempotent, non-destructive), the description covers the key inputs (SKUs, stores) and the comparison dimensions (inventory, price, status, catalog). It doesn't describe the output format, but since there is no output schema and the tool is read-only, the missing return description is a minor gap. It is nearly complete for correct invocation.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already fully documents both parameters (stores and skus) with their constraints and formats. The description repeats the scope ('selected SKUs', 'across multiple Shopify stores') but does not add new semantic meaning beyond the schema. The baseline of 3 is appropriate because the schema carries the heavy lifting.

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

  Purpose5/5

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

  The description clearly states the action ('Compare'), the resource ('inventory, price, product status, and catalog details'), and the scope ('for selected SKUs across multiple Shopify stores'). It is distinct from sibling tools like list_stores, get_shop_info, and graphql_query variants, making the tool's purpose immediately recognizable.

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

  Usage Guidelines3/5

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

  The description implies usage when a cross-store comparison of inventory/price/status/catalog details is needed, but does not explicitly state when NOT to use it or mention alternatives like shopify_compare_catalog. It provides no exclusions or selection guidance relative to siblings, so the agent must infer the right context from the verb and target.

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

• shopify_compare_pricesA
  3.8/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, fully covering the safety profile. The description adds that it 'highlights mismatches or missing variants,' which is useful behavioral context. It does not contradict annotations, but it also doesn't disclose error handling or partial-match behavior. Given the strong annotation coverage, a 3 is appropriate.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence with zero filler. It clearly states the action, scope, and expected output in a compact structure. Every word earns its place, making it easy to scan.

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

  Completeness4/5

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

  For a read-only comparison tool with two well-documented parameters and comprehensive annotations, the description covers the core information: what is compared, across which stores, and what it returns (highlights of mismatches/missing variants). It lacks explicit mention of error handling or edge cases, but given the low complexity and the safety profile already provided, this is a minor gap.

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

  Parameters3/5

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

  Schema coverage is 100% for both parameters, with the schema already describing stores as 'Configured store alias' and skus as 'One to fifty exact SKUs to compare.' The description doesn't add parameter-specific syntax or format details beyond the schema; it only reinforces the tool's purpose. Baseline 3 applies.

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

  Purpose5/5

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

  The description uses a specific verb ('Compare') and clearly identifies the resource ('price and compare-at price for exact SKUs across selected stores'). It distinguishes itself from sibling tools like shopify_compare_inventory or shopify_compare_catalog by focusing on pricing rather than inventory or catalog content, so an agent can tell them apart without opening schemas.

  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 its usage (when you need to compare prices across stores) but does not explicitly state when to prefer this over similar sibling tools (e.g., shopify_compare_inventory) or mention any exclusions or conditions. It leaves the agent to infer the right tool from the resource being compared.

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

• shopify_catalog_gap_reportA
  4/5.0
  Behavior4/5

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

  The annotation already marks it read-only, idempotent, and non-destructive Committees/cdbe1136-ac80-4e3c-b22d-2cbfe0e0ed7f/0c5f24ae-c72b-4b85-bc2e-26a37atham. The description adds the critical nuance that bounded scans are labeled as potential rather than definitive gaps, which is behavioral context beyond the annotations. No contradictions with annotations.

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

  Conciseness5/5

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

  Two sentences deliver the core purpose and an important operational caveat. The main verb 'Discover' and the result type are front-loadedcase, making the tool instantly identifiable. No fluff.

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

  Completeness4/5

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

  As a read-only report tool with no output schema, the description communicates what the scan produces (missing/different publication statuses) and how results are qualified (potential, due to bounded scans). It doesn't detail result formatting, but that's not expected given the absence of an output schema. Slightly more detail about the 'bounded' nature (e.g., the first parameter limit) would improve it.

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

  Parameters3/5

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

  Schema provides 100% description coverage for both stores and first. The description references 'bounded scans', which indirectly touches on the first parameter but does not add specific parameter guidance. Baseline 3 is appropriate since the schema fully documents parameters and the description adds little beyond the word 'bounded'.

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

  Purpose5/5

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

  States a specific verb ('Discover'), a clear resource ('products across stores'), and the two distinct outcomes (missing or different publication status). The title reinforces the purpose. This clearly differentiates from single-store siblings like shopify_catalog_health or shopify_compare_inventory.

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

  Usage Guidelines3/5

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

  The description implies when to use it — when you need to compare products across stores — but gives no explicit guidance on when not to use it or which alternative to prefer. No siblings are named. It's adequate but lacks direct comparative guidance.

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

• shopify_get_shop_infoA
  4/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the context that it is safe to call before sensitive changes, but does not disclose details about the response format or any other behavioral traits. With strong annotations, the description adds marginal value beyond them.

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

  Conciseness5/5

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

  The description is two concise sentences, both adding value: the first states the primary purpose, and the second provides a critical usage context. No wasted words, and the most important information is front-loaded.

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

  Completeness4/5

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

  Given the simplicity of the tool (one parameter, no output schema), the description plus annotations are sufficient for an agent to call it correctly. It does not describe the return shape, but for an info-getter that is not critical, and the usage guidance covers the main operational context. Small gap remains, so a 4 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?

  The schema covers 100% of parameters, with a clear description for the single 'store' parameter ('Configured store alias, such as main-store or wholesale-store'). The description adds no additional meaning about the parameter, so it relies on the schema. Baseline 3 is appropriate.

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

  Purpose5/5

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

  The description states a specific verb (get), a resource (identity and account information), and a clear scope (from one named Shopify Admin store). It clearly distinguishes itself from the sibling shopify_list_stores by emphasizing a single store, so an agent can infer the difference without further context.

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

  Usage Guidelines4/5

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

  The description provides explicit guidance on when to use the tool: 'before a sensitive change to make sure that the selected store is correct.' This gives a concrete context, though it does not explicitly list alternative tools or when not to use it, so it falls short of full differentiation.

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

• shopify_graphql_queryA
  4/5.0
  Behavior3/5

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

  Annotations already cover the key safety profile (readOnlyHint, idempotentHint, destructiveHint false), so the description does not need to restate them. It adds useful behavioriac context: query targets a single stored alias and cursor pagination should be used. But it does not disclose error behavior, response shape, or the consequence of a malformed GraphQL query. The additional context is modest but not missing an essential behavior.

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

  Conciseness5/5

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

  The description is two concise sentences, front-loads what the tool does, and immediately gives actionable guidance (cursor paganation, minimum field configuration) without wasting words. Every sentence earns its place.

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

  Completeness4/5

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

  Given the annotations and 100% schema param coverage, the main description is complete enough for correct selection and invocation. It tells the agent that this is a single read-only query, and gives the most important query style instructions. There is no outout schema, and the descr doesn't mention how the response is formatted, but for a raw GraphQL tool that is low risk and common knowledge.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the individual parameters are already fully documented in the schema. The description does not add per-parameter meaning beyond saying 'one named store' and 'read-only', but it does contextualize the query's purpose. That is helpful but not compensating for any parameter 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?

  The description states a specific action ('Run one read-only GraphQL Admin API query') and a specific resource ('against one named store'). It also differentiates from sibling tools by emphasizing that it runs a single query rather than many, and is read-only rather than mutation.

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

  Usage Guidelines4/5

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

  It clearly conveys the intended context: a single read-only query against one store. It also gives hand-on guidance about scaffolding the query with cursor pagination and only necessary fields. It does not explicitly name alternatives or exclusions, but the phrase 'one named store' makes it easy to route to this tool rather than query_many or mutation.

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

• shopify_graphql_query_manyA
  4/5.0
  Behavior4/5

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

  Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds useful context beyond annotations: parallel execution and per-store success/error isolation. No contradictions with annotations.

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

  Conciseness5/5

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

  A single sentence that names the action, resource, and distinctive behavior. No redundant words; front-loaded with the core purpose.

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

  Completeness4/5

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

  For a three-parameter tool without an output schema, the description covers the key behavioral aspects (parallel, read-only, per-store results). It does not detail the response format, but annotations and schema provide sufficient context for an agent to invoke it correctly.

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

  Parameters3/5

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

  Schema covers 100% of parameters with descriptions, so the baseline is 3. The description does not add new information about parameters beyond what the schema provides, such as the distinction between variables or the exact format of stores.

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

  Purpose5/5

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

  The description states a specific verb ('Run'), resource ('GraphQL Admin API query'), and scope ('across multiple named stores in parallel'). It clearly distinguishes from the singular shopify_graphql_query sibling by emphasizing multiple stores and parallel execution.

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

  Usage Guidelines3/5

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

  The description implies usage for multiple stores via 'across multiple named stores', but does not explicitly contrast with the single-store sibling (shopify_graphql_query) or state when to choose one over the other. Usage context is present but not formalized.

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

• shopify_portfolio_snapshotA
  4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true, and the description reinforces this with 'read-only'. It adds valuable context that results depend on scopes ('when scopes permit'), and that it includes specific counts. This exceeds the annotation baseline without contradiction.

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

  Conciseness5/5

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

  Two well-structured sentences with the core purpose front-loaded and the scope condition clearly stated. No redundant information or filler.

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

  Completeness4/5

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

  Given the low complexity (one optional parameter, no output schema), the description adequately explains what the snapshot includes and the scope dependency. It does not detail error conditions or exact response format, but covers the essential content for an agent to call it correctly.

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

  Parameters3/5

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

  The schema provides complete documentation for the single 'stores' parameter, including format and omission behavior. The description merely restates this ('selected stores or every configured store') without adding new semantics beyond the schema's coverage, so baseline 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states a specific verb ('Create') and resource ('read-only operating snapshot') and differentiates it from siblings by focusing on portfolio-level aggregation across multiple stores, which is distinct from single-store or query-based tools.

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

  Usage Guidelines3/5

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

  The description implies usage for portfolio-level snapshots ('across selected stores or every configured store') but does not explicitly state when to prefer this over alternatives like shopify_get_shop_info or shopify_graphql_query. The context is implied rather than explicit.

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

• shopify_customer_growthA
  4.2/5.0
  Behavior4/5

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

  Annotations already confirm this is a safe read-only, idempotent operation case. The description adds valuable behavioral nuance: that count precision is preserved even when Shopify caps a count. This tells the agent that the output includes a precision flag or similar, which is not inferable from the schema or annotations. No contradiction with annotations.

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

  Conciseness5/5

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

  Two short sentences convey the essential purpose and a key output nuance. The core function is front-loaded in the first sentence, and the second adds relevant detail about precision. Every word earns its place; no fluff or repetition.

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

  Completeness4/5

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

  Given the tool's moderate complexityants, no output schema, and the fact that it returns aggregated counts, the description covers the essential output behavior (comparison across periods, precision visibility when capped). It could be more explicit about the output structure (e.g., whether it returns a table with per-store rows), but the description is sufficient for an agent to understand the deliverable and its caveat. Annotations handle safety, so the description adequately fills in the remaining context.

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

  Parameters3/5

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

  The input schema already provides full coverage (100%) with descriptions for both parameters: 'days' (period length) and 'stores' (aliases). The description adds no extra parameter detail beyond mentioning 'selected stores' and 'current/previous periods', which maps directly to the schema. Since coverage is high, a baseline of 3 is appropriate.

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

  Purpose5/5

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

  The description states a specific verb (compare), resource (new-customer counts), and scope (across current and previous periods for selected stores). It clearly distinguishes this tool from the many other Shopify reporting tools in the sibling list, which focus on other domains (orders, inventory, catalog, etc.).

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

  Usage Guidelines4/5

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

  The description makes the comparison goal explicit, so an agent can infer that this tool is for customer-growth analysis rather than other reports. However, it does not explicitly state when to prefer this tool over alternatives (e.g., if a more granular or raw count tool exists), nor does it mention any exclusions. Still, the context is clear enough for typical use.

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

• shopify_duplicate_sku_reportA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare readOnly, idempotent, and non-destructive behavior, so the description does not need to repeat that. It adds useful behavioral context by mentioning that incomplete scans are labeled when a store exceeds the row limit, which is information not available from the annotations or schema.

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

  Conciseness5/5

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

  The description is two sentences with no filler. The primary action is front-loaded, and the important caveat about incomplete scans is placed second where it is still easy to notice.

  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 two-parameter report tool, the description covers the core behavior and an important boundary condition caused by the row limit. It does not describe the exact return format, but the schema and annotations handle parameter and safety details sufficiently for correct invocation.

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

  Parameters3/5

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

  Schema description coverage is 100%, and both the 'stores' and 'first' parameters are already documented in the input schema. The description adds only the row-limit concept that aligns with 'first' but does not meaningfully extend parameter understanding beyond the schema.

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

  Purpose5/5

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

  The description states a specific verb and resource: it finds duplicate SKUs within each store and SKUs shared across stores. This clearly separates it from sibling report and query tools like shopify_low_stock_report or shopify_catalog_health.

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

  Usage Guidelines4/5

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

  The description gives clear context for when the tool is appropriate: when duplicate or cross-store SKU overlaps need to be detected. It does not explicitly name alternatives or exclusion conditions, but the purpose statement itself provides enough guidance for an agent to select it.

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

• shopify_get_product_everywhereA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral context by stating that the result is normalized and includes product, price, status, and inventory matrix. It does not cover not-found or partial-match behavior, but the annotation coverage lowers the bar.

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

  Conciseness5/5

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

  A single sentence that front-loads the core action and scope, then states the output. Every phrase earns its place with no redundancy.

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

  Completeness4/5

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

  For a read-only lookup with three well-documented parameters and no output schema, the description gives a sufficient high-level picture of inputs and return content. It could be more complete about the shape of the matrix and not-found behavior, but it is not missing critical invocation information.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already documents stores, matchBy, and identifier. The description adds no parameter-specific syntax or format details beyond what the schema provides, so the baseline 3 applies.

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

  Purpose5/5

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

  The description states a specific verb ('Find'), a precise resource (one exact SKU or product handle), and a scope (across selected stores), and it names the output (normalized product, price, status, inventory matrix). This clearly distinguishes it from sibling search and comparison tools.

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

  Usage Guidelines4/5

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

  The description gives clear context for when to use the tool: when an agent needs one exact SKU or handle matched across selected stores. It does not explicitly name alternatives or exclusions, so it stops short of a 5.

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

• shopify_list_storesA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true, so the description need not repeat safety traits. It adds the valuable behavioral note 'does not expose access tokens,' which is a security guarantee beyond the annotations, and 'remains connected' implies filtering of disconnected stores, adding context about what 'list' means.

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

  Conciseness5/5

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

  The description is two sentences with no filler. It front-loads the main action and scope, then adds a single important security clarification. Every word earns its place.

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

  Completeness4/5

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

  For a zero-parameter, read-only list tool, the description is sufficient. It covers the core operation and a key security aspect, though it does not specify what the return list contains (e.g., store names, IDs). Since there is no output schema, this minor gap is acceptable given the tool's simplicity and the annotations covering safety.

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

  Parameters4/5

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

  The input schema has zero parameters, so there are no semantics to describe. The description does not need to compensate for missing parameter docs, and the baseline for zero-parameter tools is 4.

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

  Purpose5/5

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

  The description states a specific verb ('List'), resource ('Shopify Admin store'), and scope ('remains connected to this plugin'), clearly distinguishing this from sibling tools like shopify_get_shop_info or shopify_graphql_query. It is unambiguous about what the tool does.

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

  Usage Guidelines3/5

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

  The description implies usage: an agent would use this to enumerate connected Shopify stores. However, it does not explicitly compare to alternatives or state when not to use it, such as 'use shopify_get_shop_info for a single store's details.' The context signals are sufficient for inference but not explicitly provided.

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

• shopify_low_stock_reportA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the agent knows this is a safe read-only operation. The description adds the behavioral detail of how the result is categorized (low, zero, negative), which is not in the annotations or schema. It doesn't overpromise or contradict annotations. However, it doesn't disclose whether the threshold applies per-variant or aggregate across stores, or how 'active' is defined, but that's a minor gap. Given the annotations cover the safety profile, a 4 is warranted for the added categorization context.

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

  Conciseness5/5

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

  The description is a single, well-structured sentence that front-loads the core purpose ('find every active product variant at or below an inventory threshold') and adds a critical separator detail at the end. Every word contributes; no filler or redundant phrases. It respects the front-loading principle.

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

  Completeness4/5

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

  For a read-only reporting tool with annotations that declare safety and idempotency, the description covers the core scope and result categorization. The schema handles all parameter definitions, so the description doesn't need to repeat them. The only missing piece is what the output looks like (e.g., which fields are returned), but with no output schema and the description's categorization promise, it's reasonably complete. A 4 is justified because it's clear enough for an agent to select and invoke, though an explicit return format hint would make it a 5.

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

  Parameters3/5

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

  Schema description coverage is 100% - both 'stores' and 'threshold' have detailed descriptions in the schema itself. The description adds context that the tool uses these to filter and categorize, but it doesn't provide syntax or format details beyond the schema. The schema already explains that 'stores' is aliases and 'threshold' is the max quantity, so the description adds minimal extra value. Baseline 3 is appropriate.

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

  Purpose5/5

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

  The description uses a specific verb ('find'), a precise resource ('active product variant'), and a clear condition ('at or below an inventory threshold'). It separates the result into low, zero, and negative inventory, which adds nuance that distinguishes it from generic inventory tools. Though it shares the 'report' suffix with siblings like shopify_duplicate_sku_report, the scope (inventory threshold across stores) is unique.

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

  Usage Guidelines4/5

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

  The description clearly indicates the purpose (inventory management) and the operator model (selected stores via 'stores' parameter). It does not explicitly name alternatives or state when not to use this tool, but the scope over multiple stores and the threshold concept make the usage context clear. Since there are sibling tools like shopify_compare_inventory and shopify_catalog_health, a brief mention of those would have made it a 5, but it's mostly clear.

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

• shopify_order_summaryA
  4.2/5.0
  Behavior4/5

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

  The description adds value beyond annotations: it discloses that currency totals remain separate, which is a non-obvious behavior. The readOnly/idempotent/destructive annotations already signal safety, so the bar is lower; the description complements them appropriately without contradicting.

  Agents need to know what a tool does to the world before 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, both substantive. The first front-loads the tool's main function and covered dimensions; the second adds a crucial currency-scoping caveat. No filler.

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

  Completeness4/5

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

  Given the read-only nature, no output schema, and 100% schema coverage of params, the description covers the aggregate scope, the fields included, and the currency behavior. It doesn't detail return format or performance implications of multi-store queries, but for a summary tool these are optional; the essentials are present.

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

  Parameters4/5

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

  Schema coverage is 100%, so the baseline is 3. The description adds semantic nuance by clarifying that the returned data is aggregated ('summarize') and that currency totals are kept separate across stores — a detail the schema does not convey. This extra meaning justifies above baseline.

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

  Purpose5/5

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

  The description uses a specific verb ('Summarize') with a clear resource ('orders') and scope ('across selected stores'). It enumerates the exact dimensions covered (values, discounts, shipping, tax, cancellations, financial/fulfillment statuses), making the tool's purpose unambiguous and distinct from siblings like shopify_list_unfulfilled_orders or shopify_compare_catalog.

  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 analytics context ('Summarize recent order... across stores') but does not explicitly state when to prefer this over alternatives, nor does it exclude use cases. There is no when-not guidance or direct sibling mention, leaving the agent to infer appropriate usage from the word 'Summarize'.

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