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

Annotations already declare the tool to be destructive and non-idempotent, so the description only needs to add contextual behavior. It adds that the operation is on a manual collection and returns the current state, but does not disclose authorization requirements or side effects beyond that.

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

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

The description is a single, front-loaded sentence with no filler. Every word contributes meaning: the action, the resource type, the target, and the return value.

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

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

The description is acceptable for a simple mutation tool given the annotations and schema, but it does not describe the return state format, the store parameter, or the confirm gating behavior. The schema partially compensates, but gaps remain.

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

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

Schema description coverage is only 25%, and the description does not explain parameters. It loosely maps 'products' to productIds and 'collection' to collectionId, but leaves store and confirm without semantic guidance. The description should compensate for the low schema coverage and does not.

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

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

The description states a concrete verb ('Add'), a specific resource ('products to a manual collection'), and an outcome ('return its current state'). This clearly distinguishes the tool from collection creation/update siblings.

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

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

The phrase 'manual collection' provides clear context and implicitly excludes smart/automatic collections. However, it does not explicitly name alternatives or state when not to use the tool, 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.

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

The description calls the export 'read-only', but annotations state readOnlyHint=false and destructiveHint=true. This is a direct annotation contradiction. The description also does not disclose side effects, authorization requirements, or what happens after starting the export.

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

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

The description is compact and front-loaded: it states the operation in the first sentence and the essential follow-up (save the operation ID) in the second. It wastes no words, though the misleading 'read-only' claim harms precision.

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

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

For an asynchronous start command with three required parameters and no output schema, the description omits needed context: what query syntax to use, what 'store' expects, the confirmation/authorization step, and what the operation ID looks like. The annotation contradiction further undermines completeness.

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

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

Schema description coverage is low (33%), with only 'confirm' documented. The description does not explain 'query', 'store', or the confirmation requirement, so the agent is left without semantic guidance for most required parameters.

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

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

The description names a specific action ('Start an asynchronous... bulk export') and resource (Shopify bulk export), and it tells the agent to save the returned operation ID. It does not explicitly name sibling alternatives, but the action is distinguishable from status/query tools.

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

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

No guidance is given about when to choose this tool over alternatives such as shopify_bulk_export_status or direct GraphQL queries. The only context is that it is asynchronous and the ID should be saved, which implies but does not state a usage pattern.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds a small useful behavioral detail by saying 'Partial exports remain explicitly incomplete,' which warns the agent not to treat partial data as complete. However, the word 'Resume' sits awkwardly against the readOnlyHint and may mislead an agent into thinking the tool modifies export state.

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

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

The description is short and front-loads the operation ID, which is good. However, the second sentence is cryptic and the first sentence's wording is imprecise, so the brevity does not translate into clear guidance.

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

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

With no output schema, the description should explain what the agent will receive and how to use the result, but it does not. It also omits how the operation ID is obtained and what status values to expect, leaving the agent with too much uncertainty for a tool that is meant to report status.

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

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

Schema description coverage is 0%, so the description must compensate for the schema's silence. It does clarify that the operation ID is the identifier used to locate the bulk export, but it completely fails to explain the 'store' parameter or how id and store relate.

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

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

The description says to 'Resume a bulk export by its operation ID,' which is ambiguous for a tool named 'status.' 'Resume' implies a state-changing or continuation action rather than a read-only status check, and it does not clearly distinguish this from the sibling shopify_bulk_export_start. The operation ID is mentioned, but the core purpose is obscured.

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

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

No guidance is provided about when to use this tool versus alternatives such as shopify_bulk_export_start or when to poll status. It does not explain that this should be used after an export is started, nor does it describe the intended workflow.

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

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

The description adds value beyond the annotations by disclosing 'bounded selection' and 'per-product outcomes', which help the agent understand partial failures and selection caps. The annotations already cover destructive/non-idempotent behavior, so the description does not need to repeat those. It does not contradict any annotation.

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

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

One concise sentence with the core action front-loaded ('Update explicitly selected products or one collection'). The second clause adds boundedness and result behavior without waste. Every word earns its place.

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

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

The description covers the main action, selection scope, and per-product outcomes, but it lacks important detail: there is no output schema, and 'per-product outcomes' does not describe the response shape. It also does not specify whether productIds and collectionId can be combined or whether confirm is always required beyond what the schema states. For a destructive bulk operation, this is adequate but not fully complete.

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

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

Schema description coverage is only 17% (only 'confirm' has a description), so the description must compensate. It clarifies the two selection modes (productIds vs collectionId) and hints at the maxProducts bound, but it does not clarify whether productIds and collectionId are mutually exclusive, nor does it explain store or status semantics beyond what the schema already shows. Partial compensation, but meaningful gaps remain.

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

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

The description states the verb 'Update' and the resource 'products or one collection', which conveys the bulk-update scope. The phrase 'per-product outcomes' hints at partial results, but it does not explicitly say that the field being updated is 'status', relying on the tool name. The 'one collection' wording is somewhat ambiguous—it could be misread as updating collection metadata rather than applying a status to products in a collection—but the schema and name disambiguate for a careful agent.

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

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

The description gives useful selection context: use this tool for explicitly chosen products or for all products in one collection, with a bounded number of updates. However, it does not name alternative tools like shopify_update_product for single updates, and it does not state exclusions or when not to use this tool. The usage guidance is implied rather than explicit.

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

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

The annotations already establish read-only, idempotent, open-world, and non-destructive behavior. The description adds meaningful context beyond that by stating that bounded scans are labeled as potential rather than definitive gaps, which is an important interpretive caveat for an agent relying on the results.

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

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

The description is two sentences with no filler or redundant content. It front-loads the primary purpose and then adds the crucial bounded-scan caveat, making every sentence valuable.

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

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

For a read-only report tool with rich annotations and well-documented parameters, the description is mostly complete: it gives the purpose, the target inputs, and the key caveat about potential gaps. The only notable absence is detail on the output format or how results are presented, though no output schema is provided.

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

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

Schema description coverage is 100%, so the schema already documents both the `stores` and `first` parameters. The description only generically echoes 'selected stores' and the bounded-scan concept, adding little parameter-specific meaning beyond what the schema already provides.

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

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

The description clearly states a specific action and resource: discovering products that are missing or have differing publication statuses across selected stores. It conveys the tool's scope well, though it does not explicitly distinguish itself from sibling tools like shopify_compare_catalog 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.

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

The description implies a natural use case (finding catalog gaps), but it provides no explicit guidance about when to use this tool instead of similar siblings such as shopify_compare_catalog or shopify_catalog_health. There are no exclusions, alternatives, or selection criteria mentioned.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds scope details such as 'recent products' and 'across selected stores', but it does not disclose the return format, what exactly 'recent' means, or how results are presented. No contradiction with annotations.

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

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

The description is a single, well-structured, front-loaded sentence that conveys all key functionality with no filler. Every clause contributes meaningful information about what the audit covers.

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

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

Input schema and annotations cover parameters and safety, making basic invocation straightforward. However, there is no output schema and the description does not explain what the audit returns, whether results are per-store or combined, or how 'missing' fields are reported. This is a noticeable gap for a multi-dimensional audit tool.

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

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

Schema description coverage is 100%, with the schema already documenting 'stores' and 'first' clearly. The description's mention of 'recent products across selected stores' loosely maps to these parameters but adds no additional semantic value beyond the schema.

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

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

The description clearly names a specific action ('Audit') and resource ('recent products across selected stores'), then enumerates the exact checks performed: missing vendor, product type, SEO fields, featured media, media alt text, and active products without inventory. However, it does not explicitly differentiate itself from similar sibling tools like shopify_catalog_gap_report or shopify_compare_catalog, so it stops short of a 5.

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

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

The intended use case is implied through the audit language and the listed data-quality dimensions, but there is no explicit guidance about when to choose this tool versus sibling audit/report tools. No alternative tools or exclusion criteria are mentioned.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description carries a lighter burden. It does add the behavioral detail that comparison is keyed to 'exact handles', implying exact-match semantics rather than fuzzy search. However, it does not disclose what happens when a handle is absent from one of the stores or how missing data is represented in output.

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

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

A single 22-word sentence with no filler. The verb is front-loaded, the compared fields are enumerated compactly, and the cross-store scope is stated 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.

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

For a two-parameter tool with full schema coverage and rich annotations, the description is minimally viable: an agent knows what to pass and that the call is safe. But with no output schema, the description does not clarify the return shape or how missing handles across stores are reported, which matters for interpreting comparison results.

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

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

Schema description coverage is 100%, so the schema already documents both parameters; the baseline is 3. The description adds modest value by clarifying which product attributes will be compared for the given handles, but it does not explain store alias resolution or handle matching behavior beyond what the schema provides.

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

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

The description states a specific verb ('Compare'), a precise resource (product titles, status, vendor, product type, and inventory for exact handles), and a clear scope (across multiple Shopify stores). The listed field set distinguishes it implicitly from siblings like shopify_compare_collections, shopify_compare_prices, and single-store get/search tools.

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

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

No when-to-use or when-not-to-use guidance is provided, and no alternatives are named. Given overlapping siblings such as shopify_compare_inventory, shopify_compare_prices, and shopify_get_product_everywhere, an agent has no way to know which cross-store comparison tool to select for a given task.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds useful behavioral detail about what is compared: titles, sort order, product counts, SEO fields, and collection images. It does not describe handling of missing handles, but this is not a major gap given the annotation coverage.

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

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

The description is a single, front-loaded sentence with no filler. Every phrase adds information: the operation, the resource scope, and the specific fields involved.

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

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

The description is sufficient for a simple comparison tool, but there is no output schema and no statement about return format, missing handles, or how differences are presented. Given the tool compares up to 100 stores and 50 handles, a sentence about result structure or handling missing values would make it more complete.

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

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

Schema description coverage is 100%, and both parameters ('stores' and 'handles') are already documented in the input schema. The description restates 'exact collection handles' and lists comparison fields, which adds output context rather than new parameter-level meaning. This aligns with the baseline 3 for high schema coverage.

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

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

The description uses a specific verb ('Compare') with a clear resource ('exact collection handles') and scope ('across stores'). It also lists the exact fields involved, making the tool's purpose unambiguous and distinguishable from comparison siblings like shopify_compare_inventory, shopify_compare_prices, and 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.

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

The phrase 'across stores' implies the intended use case: comparing the same collection handles across multiple configured stores. However, the description does not explicitly state when to choose this tool over related tools such as shopify_compare_catalog or shopify_get_collection, nor does it mention exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds context about the scope of comparison but does not disclose additional behavioral traits such as output structure, pagination, or store-alias requirements. No contradiction with annotations exists.

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

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

The description is a single efficiently worded sentence that leads with the main verb and captures the core scope without any filler. Every word contributes to meaning, making it well suited for quick agent parsing.

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

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

The description is adequate for a relatively simple two-parameter comparison tool with strong annotations, but no output schema exists and the description does not mention what the response looks like. It also leaves 'catalog details' vague and does not help the agent distinguish this from other comparison tools, leaving some contextual gaps.

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

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

Schema description coverage is 100%, with clear descriptions for both skus (1–50 exact SKUs) and stores (1–100 configured aliases). The tool description adds no parameter-specific meaning beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description states a specific verb (Compare) and resource (inventory, price, product status, catalog details for selected SKUs across multiple Shopify stores). This clearly conveys the core function. It does not explicitly differentiate from overlapping siblings like shopify_compare_catalog or shopify_compare_prices, so it stops short of a 5.

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

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

The intended use case is implied: comparing multiple attributes for chosen SKUs across several stores. However, there is no explicit guidance on when to use this tool instead of the many related sibling tools, nor any stated exclusions or prerequisites. The presence of overlapping tools like compare_catalog and compare_prices makes this a noticeable gap.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral detail by specifying that the tool compares both price and compare-at price and that it highlights mismatches and missing variants, going beyond the schema.

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

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

The description is a single, focused sentence with no filler. It front-loads the action and scope, and every word contributes to understanding the tool's purpose.

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

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

For a read-only comparison tool with two well-described parameters, the description adequately conveys the core operation and output intent. However, without an output schema, it does not specify the exact return structure, and it does not address edge cases like SKUs absent from all stores; a bit more detail would make it fully complete.

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

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

Schema description coverage is 100%, and the schema already describes both parameters well: 'skus' as exact SKUs and 'stores' as configured store aliases. The description adds no new parameter-level meaning, so the baseline score of 3 is appropriate.

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

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

States a specific verb ('compare'), a precise resource ('price and compare-at price for exact SKUs across selected stores'), and a concrete outcome ('highlight mismatches or missing variants'). This clearly differentiates it from sibling tools like compare_inventory and compare_catalog.

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

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

The description clearly implies this tool is for price comparison of exact SKUs across a chosen set of stores, which provides clear context for when to use it. It does not explicitly name alternatives or exclusions, but the scope is specific enough that an agent can infer the appropriate use case.

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

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

Annotations already cover the write/destructive profile (readOnlyHint=false, destructiveHint=true), so the bar is lower. The description adds useful context beyond annotations: the manual-vs-smart distinction and the channel-publishing side effect. However, it does not explain the destructive risk flagged by destructiveHint=true for a create operation, nor the confirm authorization gate.

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

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

Two short sentences (~20 words) with zero wasted language. The core purpose is front-loaded and the second sentence adds a targeted parameter behavior. Every word earns its place.

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

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

This is a complex tool (9 params, nested ruleSet/image objects, no output schema, non-idempotent, destructive annotation) yet the description is minimal. It omits how manual vs smart collection parameters relate, default publication behavior when publicationIds is absent, and any indication of return values or the confirm requirement. An agent has too little context to call this correctly on the first try.

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

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

With only 11% schema description coverage (only 'confirm' is documented), the description carries the burden of explaining 9 parameters but only addresses publicationIds. The manual-vs-smart phrasing vaguely implies productIds vs ruleSet but never states which parameter drives which behavior, leaving most parameters semantically undocumented.

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

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

The description states a specific verb+resource ('Create a manual or smart collection') that clearly distinguishes it from update/get/search siblings. However, the second sentence about publishing overlaps conceptually with shopify_publish_resource's domain, and no sibling is named to disambiguate.

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

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

The description implies when to use the tool (when creating collections) and gives a use-case hint ('Pass publicationIds to publish to explicitly selected channels'). But it offers no explicit exclusions or alternatives, leaving an agent to infer when update_collection, add_to_collection, or publish_resource would be more appropriate.

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

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

Annotations already flag this as non-read-only, non-idempotent, and destructive, so the safety profile is covered. The description adds the audience and start-date scoping, which is mildly useful, but it does not disclose the confirm/authorization flow, the irreversible storefront impact implied by destructiveHint, or that it creates new resources without modifying existing ones.

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

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

The single sentence is lean and front-loaded with the action, earning its place. However, for a 15-parameter tool with a confirm gate, this brevity shades into under-specification rather than efficient conciseness; an 'appropriately sized' description would need a few more sentences to cover the required confirmation and targeting options.

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

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

The tool has high complexity (15 params, 6 required, confirm-gated, destructive annotation, no output schema), and the description explains none of this. An agent can guess the happy path but not how to satisfy the confirm parameter, whether productIds and collectionId are mutually exclusive, or what the side effects are. This is a significant completeness gap for a creation tool.

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

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

Schema description coverage is only 7% (only 'confirm' has schema documentation), placing the full burden on the description. The description names percentage, start date, and customer audience, mapping to percentage, startsAt, and customerEligibility/customerSegments, but 12 other parameters—including productIds, collectionId, usageLimit, and minimumPurchaseAmount—receive zero semantic context from either source.

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

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

The description states a specific verb ('Create'), a specific resource type ('percentage discount'), and two distinguishing constraints ('explicit start date and customer audience'). It clearly differentiates from the product/collection creation siblings, though it does not name any alternative and leaves open whether other discount types exist.

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

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

There is no guidance on when to use this tool versus alternatives. Siblings like shopify_graphql_mutation or shopify_bulk_update_product_status could conceivably overlap, and the description never states that this is the canonical way to create a discount, nor what conditions favor it over GraphQL.

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

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

Beyond annotations, the description adds meaningful behavioral context: the store is 'real' but 'temporary', 'a merchant can claim' it, and 'No existing store is modified' — which aligns with destructiveHint=false. It also explains idempotency behavior ('Reuse requestId after interruptions to prevent duplicate creation'), going beyond the bare idempotentHint=true annotation.

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

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

Two tight sentences: the core purpose is front-loaded, followed by the non-destructive guarantee and the idempotency instruction. Every sentence earns its place and there is no filler.

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

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

For a creation tool with 4 params and no output schema, the description covers the essential outcome and safety characteristics. It does not describe the return value, claim process details, or store lifetime, but the action and constraints are sufficiently clear 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.

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 adds meaning for requestId (reuse for idempotency) but does not explain name, country, or userUnderstandsNewStoreOnly. Those names are largely self-explanatory and schema constraints provide additional detail, but the description could do more to clarify the consent parameter.

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

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

The description states a specific action ('Create a real temporary Shopify store') and resource ('preview store'), and explicitly differentiates from modifying existing stores. This clearly distinguishes it from sibling getter tools like shopify_get_preview_store and shopify_get_new_store_previews.

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

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

The description gives clear context: use this to create a temporary, claimable store, and it explicitly says no existing store is modified. It lacks an explicit 'when not to use' or named alternative, but the action is unambiguous and the requestId-reuse guidance provides practical usage direction.

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

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

Annotations already declare the destructive, non-read-only nature, so the description adds no new safety signal. It does add useful behavioral context: the default status is DRAFT, and collection membership is intentionally not handled. However, it does not disclose side effects, confirmation requirements, or response behavior beyond what the schema's confirm parameter hints at.

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

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

The description is three short sentences with no filler. The core action is front-loaded, the default behavior is stated next, and the scope boundary regarding collections is noted last. Every sentence earns its place.

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

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

For a destructive, 13-parameter creation tool with no output schema, the description covers the main creation scope and an important default, but it remains terse. It omits return behavior, constraints around option-variant combinations, and what happens after creation, so it is adequate but not complete.

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

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

With only 8% schema description coverage, the description carries more weight. It adds group-level meaning for options, variants, and images, and clarifies that the default status is DRAFT. However, it leaves most of the 13 parameters semantically underdocumented, such as price, vendor, tags, productType, and descriptionHtml, so it only partially compensates for the sparse schema.

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

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

The description uses a specific verb-resource pair ('Create a product') and explicitly enumerates the subresources it handles: options, variants, and images. It also previews the draft default and clearly separates collection membership from this tool's scope, distinguishing it from siblings like shopify_update_product or shopify_add_to_collection.

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

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

The verb 'Create' and the statement that collection membership is a separate step imply when to use this tool, but no sibling tools are explicitly named and there is no explicit when-to-use/when-not-to-use guidance. The agent is left to infer that updates should go to shopify_update_product.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context beyond those annotations: it warns that Shopify may cap counts and that the tool preserves precision visibility even when capping occurs. No contradiction with the annotations.

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

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

The description is two sentences with no redundant wording. It front-loads the core action and resource, then adds a single useful caveat about count capping.

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

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

For a two-parameter read-only comparison tool with no output schema, the description covers the essential invocation context: selected stores, period comparison, and capping behavior. It leaves return-format details unspecified, but that is not critical for tool selection or correct parameter usage.

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

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

Schema description coverage is 100%, so the schema already documents both 'stores' and 'days'. The description reinforces that periods are current and previous, which aligns with the 'days' parameter, but it does not add new semantic detail beyond the schema.

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

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

The description uses a specific verb and object: 'Compare new-customer counts across the current and previous periods for selected stores.' This clearly distinguishes it from sibling comparison tools like shopify_compare_inventory or shopify_compare_prices by naming the exact metric and time-window behavior.

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

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

The description conveys what the tool does but provides no guidance on when to choose it over alternatives, such as shopify_list_customers or shopify_run_analytics_query. There are no explicit conditions, exclusions, or references to sibling tools.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds a meaningful caveat beyond that: scans can be incomplete when a store exceeds the row limit, and the report labels those cases, which is important for correctly interpreting results.

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

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

Two sentences with no filler. The main purpose is front-loaded, and the caveat is stated immediately after, making the description highly scannable.

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

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

For a read-only report with fully documented parameters and rich annotations, the description conveys what the report outputs—duplicate SKUs and shared SKUs—and its main caveat about incomplete scans. It does not enumerate output fields, but no output schema exists and the stated scope is sufficient for selecting and invoking this tool.

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

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

Schema description coverage is 100%, so the schema fully documents both stores and first. The description does not need to repeat parameter details; the row-limit caveat is related to first, but the schema already explains the maximum scan count.

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

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

The description opens with concrete verbs and a specific resource: finding duplicate SKUs both within each store and shared across stores. This scope clearly separates it from sibling report tools like shopify_low_stock_report 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.

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

The description clearly states when an agent would want this report—when duplicate SKUs need to be detected inside or across stores—so the use case is evident. It does not name alternatives or explicit exclusions, but the purpose is specific enough to avoid confusion with most sibling tools.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable behavioral detail beyond annotations, including labeling generated concepts as examples rather than supplier offers or verified products, and constraining image usage to available relevant URLs. This meaningfully reduces the risk of fabricating or misrepresenting results.

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

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

The description is concise and front-loaded with the main purpose, followed by fallback behavior and constraints. Each sentence adds meaningful guidance, though a little more precision about parameters and output could be included without bloating it.

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

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

Given three parameters and no output schema, the description gives enough to select and start invoking the tool, including important labeling and image constraints. However, it does not explain what the tool returns, how limit affects results, or how to determine whether a category lacks suitable samples. Some invocation details remain under-specified.

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

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

The input schema provides structural constraints but no semantic descriptions, so the description must compensate. It explains the query as the basis for generating concepts and clarifies that generatedCandidates drives draft-creation cards. However, the limit parameter is not addressed at all, and generatedCandidates semantics are only partially explained. This is adequate but has clear gaps.

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

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

The description opens with a clear verb and resource: 'Find sample products across published Shopify demo catalogs.' It also distinguishes itself from sibling search tools by specifying sample/demo context and the fallback behavior of generating original product concepts rather than searching the full catalog.

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

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

The description provides clear usage context: use it to find sample products, and when no suitable sample exists, generate concepts and pass generatedCandidates. It does not explicitly name alternatives or exclusions, but the demo-catalog scope and fallback conditions give an agent enough context to decide when to invoke it.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds meaningful behavior beyond that: it scopes to open unfulfilled orders, groups them into age buckets, and applies a configurable SLA threshold. No contradiction with annotations.

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

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

The description is a single, front-loaded sentence with no filler. It efficiently communicates both the grouping behavior and the SLA breach detection purpose.

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

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

The schema and annotations are strong, but there is no output schema and the description does not describe the report's return structure. Usage guidance relative to similar order/report tools is also missing. Enough to invoke correctly, but not complete for an agent deciding which report to use.

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

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

Schema description coverage is 100%, so the baseline is 3. The description echoes 'selected stores' and 'configurable fulfillment SLA', which map to stores and slaDays, but does not add meaningful detail beyond the schema because all parameters are already documented.

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

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

The description states a specific action ('Group open unfulfilled orders into age buckets') and a clear goal ('identify orders older than a configurable fulfillment SLA'). This distinguishes it from list-oriented siblings such as shopify_list_unfulfilled_orders and other report tools.

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

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

No sentence explains when to prefer this report over siblings like shopify_list_unfulfilled_orders or shopify_order_summary, nor any exclusions. The agent must infer usage from the title and sibling names.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false, so the safety profile is covered. The description adds useful behavioral context by clarifying that only 'a page of products' is returned, implying pagination rather than a full product listing.

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

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

The description is a single concise sentence with no filler. It front-loads the action and immediately states the resource and return contents.

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

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

The high-level return content is present and annotations cover safety, but with no output schema and no parameter descriptions in the schema or prose, the agent gets the minimum viable information. It is enough for a simple get-by-id call but not for confident parameter construction or sibling routing.

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

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

Schema description coverage is 0%, so the description carries the compensation burden, but it only hints at 'collection' (id) and 'a page of products' (first/after). It does not explain the store parameter, the after cursor, or the first limit beyond what the schema itself already shows.

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

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

The description states the specific verb 'Get' and resource 'collection', then enumerates the response scope: collection details, rules, and a page of products. This clearly separates it from shopify_get_product and from search/update/compare collection siblings.

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

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

The purpose implies this is the tool to use when a caller needs a single collection's details, rules, or product page. However, it never names alternatives or says when not to use it, so routing among the many collection-related siblings is left to inference.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds a behavioral detail beyond annotations: results are paginated with a cursor and can span multiple locations. It does not reveal return format, max pages, or any rate-limit implications, but nothing contradicts the annotations.

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

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

Two terse sentences: the first states the operation and filter options, the second gives the key pagination behavior. No filler or repetition; information is front-loaded and easy to scan.

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

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

For a simple read-only query with annotations and a small schema, the core invocation is described, and the pagination hint is helpful. Still, with no output schema and zero parameter descriptions, an agent is left to infer the meaning of 'first' and store, and what fields the returned inventory levels contain.

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

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

Schema coverage is 0%, so the description carries the burden. It usefully maps productId to 'by product', inventoryItemId to 'by inventory item', and after to pagination. However, it says nothing about the required store parameter or the first page-size parameter, and it does not explain the Shopify GID format beyond the schema patterns.

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

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

The description uses a specific verb ('Get') and identifies the resource ('inventory') with clear filter dimensions: by product or inventory item. It does not explicitly name a sibling tool, but the read-oriented wording differentiates it from write tools like shopify_set_inventory and analysis tools like shopify_low_stock_report.

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

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

The description gives a concrete how-to for pagination ('Use inventoryItemId and after to page through additional locations'), which is useful usage guidance. However, it never states when to prefer this tool over alternatives such as shopify_compare_inventory, shopify_store_locations, or shopify_set_inventory, leaving the choice largely implicit.

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

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

Beyond the annotations, the description discloses asynchronous execution, the creation of temporary new stores, a claim link, the use of Shopify Dawn, idempotent requestId reuse, and post-claim editability of products, pricing, and copy. This meaningfully extends the annotation hints and contains no contradiction.

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

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

The description is front-loaded with the primary behavior and includes necessary operational details. It is slightly redundant, repeating 'Generate concrete design specifications' and 'Generate demo products and designs,' which keeps it from a perfect score, but it remains compact and readable.

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

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

The description is complete enough for invocation: it covers scope, async behavior, claim link, idempotency, and that existing stores are unaffected. Since there is no output schema, it could have explicitly pointed to a status-check sibling tool, but the async language and requestId reuse make the next step inferable.

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

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

With schema description coverage only at 11%, the description compensates by explaining that designs and products should be generated from the brief, that products are demo concepts, and that 1–3 previews are built. It does not explicitly define every parameter such as country or name, but the names and schema constraints make those reasonably inferable.

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

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

The description opens with a specific, actionable verb: it starts an asynchronous build of 1–3 designed storefront previews on separate NEW temporary Shopify stores, with a real claim link. It clearly distinguishes itself from sibling preview/read tools by emphasizing NEW stores and stating it does not alter an existing store, even though the tool name contains 'get'.

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

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

The description provides clear context for when to use the tool: when the user wants new storefront previews generated from a brief. It explicitly says it does not alter existing stores, implying it is not for existing-store work, and instructs the agent to reuse requestId after interruption. It stops short of explicitly naming the status-check sibling tool, but the context is otherwise clear.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior, so the description does not need to repeat those. It adds useful context that the underlying operation is asynchronous and that returned links are fresh. It does not disclose polling cadence, link expiry, or error behavior, but the safety profile is covered by annotations.

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

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

One focused sentence with active verbs and no filler. The core action and intended result are front-loaded, and every word earns its place.

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

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

For a single-parameter, read-only status poll with rich annotations, the description states the action, the object, and the returned artifacts. It does not mention polling recommendations or what 'fresh' means relative to prior links, but this is a minor gap for a low-complexity tool.

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

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

The schema describes requestId only with a UUID format and pattern, and the description does not explicitly document it. However, the wording 'Check an asynchronous storefront preview request' maps naturally to requestId, giving some semantic context. With 0% schema description coverage, the description could compensate more, but the single parameter is straightforward and self-named.

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

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

The description uses specific verbs ('Check', 'retrieve') and names the resource: an asynchronous storefront preview request. It clearly conveys that the tool returns fresh preview and claim links, and 'status' implies polling an in-flight request. It does not explicitly distinguish itself from sibling preview tools like shopify_get_new_store_previews or shopify_get_preview_store, so it misses full sibling differentiation.

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

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

The phrase 'asynchronous storefront preview request' implies the tool should be used while a preview request is in progress, but the description gives no explicit when-to-use guidance and does not mention alternatives or exclusions. Context makes the intended usage reasonably apparent without being explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the pagination behavior of line items ('a page of line items'), which maps to the first/after parameters — useful context beyond the 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.

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

A single, front-loaded sentence with no filler; every phrase ('shipping, fulfillment, tracking, a page of line items'') adds scope information. It is concise without being under-specified.

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

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

With no output schema, the description's list of returned entities partially documents the return value, but pagination mechanics and the semantics of the required 'store' parameter are undocumented. For an agent to invoke the tool correctly, it must infer what 'store' means (store identifier/domain) from context or the sibling set.

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

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

Schema description coverage is 0%, so the description must compensate for the four undocumented parameters. It loosely maps id to 'order' and first/after to 'line item pagination', but the required 'store' parameter is never explained, and the gid format is left to the schema pattern.

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

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

The description opens with a specific verb and resource ('Get order') and enumerates the exact data scope: shipping, fulfillment, tracking, and a page of line items. This clearly signals single-order retrieval as opposed to list tools like shopify_list_orders, though it never names a sibling explicitly.

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

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

No guidance is given on when to prefer this tool over competing siblings such as shopify_order_summary or shopify_list_orders. The only usage signal is the weak implication that you use this when you need full order detail, with no exclusions or alternative routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context that the store is temporary and app-created, but it does not clarify what 'refresh' means in terms of output or side effects, which would have added 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.

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

The description is one short, front-loaded sentence with no filler or redundant wording. It earns its place, though the brevity leaves some important behavioral and parameter details unstated.

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

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

For a simple tool with one required parameter and strong annotations, the description is minimally viable: it states the operation and scope. However, with no output schema and no parameter-level guidance, it leaves the return behavior and the exact expected input format unstated, so the agent still has to infer important details.

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

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

The schema has 0% description coverage, and the description does not explain the 'store' parameter beyond implying it refers to the temporary store created by the app. This gives some contextual clue, but it does not specify whether the expected value is a store ID, domain, or name, so the parameter meaning remains under-specified.

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

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

The description names a specific action ('Refresh preview and claim links') and a specific scope ('temporary store created by this app'), which makes the tool's purpose clear. It distinguishes itself from general store tools, though it does not explicitly contrast with the sibling preview tools like shopify_get_new_store_previews.

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

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

The description implies when to use the tool: when a temporary store's preview and claim links need to be refreshed. However, it provides no explicit guidance about when not to use it or which alternative sibling tools to prefer, such as shopify_get_new_store_previews or shopify_get_new_store_preview_status.

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

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

Annotations already establish the tool as read-only, open-world, idempotent, and non-destructive. The description adds a meaningful behavioral caveat that is not derivable from the schema or annotations: returned cursors must be followed independently.

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

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

Two short sentences with no filler; the core purpose is front-loaded and the pagination caveat is a distinct, valuable addition. Every sentence earns its place, even though the brevity contributes to incompleteness penalized elsewhere.

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

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

For a tool with five parameters, no output schema, and no schema-level parameter descriptions, this is too sparse. The roles of store, id, and first are left implicit, and the exact relationship between after/mediaAfter and variants/media is not fully clarified. The cursor note helps but does not make the definition complete enough for an agent to call it correctly on first try.

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

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

Schema description coverage is 0%, so the description must compensate for the five parameters. It only hints that after and mediaAfter relate to cursors via the mention of variants/media and 'returned cursor'; it does not explain store, id, first, or the precise difference between the two cursor parameters.

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

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

The description uses an active verb with a specific resource and names the key returned content: product details, variants, and media. It is clearly distinguished from search/list siblings in intent, though it does not explicitly carve out boundaries against close siblings like shopify_get_product_everywhere or shopify_search_products.

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

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

No guidance is given on when to prefer this tool over alternatives such as shopify_search_products, shopify_get_product_everywhere, or shopify_find_sample_product. The only procedural instruction is about cursor pagination, not about tool selection or context.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds useful behavioral context by promising a normalized cross-store matrix and naming the exact output categories, which goes beyond the annotations without contradicting them.

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

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

One sentence conveys the action, scope, lookup key, and output in a front-loaded, compact way. Every word contributes meaning, with no filler or redundancy.

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

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

For a read-only lookup tool with fully described parameters, the description is nearly complete. The main gap is that 'normalized product' and 'inventory matrix' are not further explained, and there is no output schema to define those structures, but the high-level output is sufficient for most selection and invocation needs.

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

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

All three parameters are fully documented in the schema, so the description does not need to repeat them. It slightly reinforces the exactness of 'identifier' and the selected-store scope, but it adds little semantic value beyond what the schema already provides.

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

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

The description names a specific verb ('Find'), a precise resource (one exact SKU or product handle), and the scope ('across selected stores'), which clearly separates it from single-store tools like shopify_get_product and search-oriented tools like shopify_search_products. It also states the output shape, a normalized product, price, status, and inventory matrix, making the tool's purpose unmistakable.

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

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

The description makes clear it is for exact SKU/handle lookup across multiple selected stores, which implies when to use it over list/search tools. It does not explicitly name alternatives or state when not to use it, but the context is strong enough for an agent to select it correctly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, 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.

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.

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.

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.

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.

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.

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds a useful hint about the return focus—store identity and granted scopes—but does not discuss auth, rate limits, or other behavioral traits.

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

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

The description is a single front-loaded sentence with zero filler. For a one-parameter read-only introspection tool, this is appropriately concise and every word contributes meaning.

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

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

The description states what is inspected, but there is no output schema and no clarification of what 'store identity' includes or how the 'store' parameter should be formatted. It is adequate for a simple tool but not fully self-sufficient.

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

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

The only required parameter, 'store', has no description in the schema and the schema description coverage is 0%. The tool description never mentions the parameter, so an agent must infer whether 'store' means a domain, handle, or ID from the parameter name alone.

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

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

The description uses the specific verb 'Inspect' and names the exact resource: store identity and granted access scopes. It clearly conveys what the tool does, though it does not explicitly distinguish it from similarly scoped siblings like shopify_get_shop_info.

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

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

No guidance is provided on when to use this tool versus alternatives such as shopify_get_shop_info or shopify_switch_shop. The purpose clause implies usage when store identity or access scopes are needed, but there are no explicit conditions, prerequisites, or exclusions.

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

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), lowering the bar for the description. The description adds genuine behavioral value beyond annotations by stating what the agent receives — processing status and a CDN URL — and by disclosing the non-creation behavior ('without creating another file') in domain terms. It does not enumerate possible status values, but that is a minor gap given the annotation coverage.

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

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

A single 12-word sentence that front-loads the action ('Read') and the resource, with a contrastive clause earning its place by differentiating from the upload sibling. There is no filler, no repetition of schema information, and the structure puts the most decision-relevant information first.

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

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

For a simple 2-parameter read-only tool with rich safety annotations, the description covers the basic resource and outcome, and since no output schema exists, the mention of 'processing status and its CDN URL' usefully signals the return content. However, it omits workflow context (that this is typically called after shopify_upload_image), the set of possible status values, and behavior when the image is not found, so an agent is left to infer the polling workflow.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining parameters, yet it says nothing about 'store' or 'id'. The only semantic hint comes from the schema's pattern (^gid:\/\/shopify\/MediaImage\/[0-9]+$), which reveals id is a MediaImage GID; 'store' is left entirely unexplained. The description's mention of 'image processing' loosely implies id refers to an uploaded image, but this is weak compensation for a 0% coverage gap.

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

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

The description opens with a specific verb 'Read' and a clear resource: 'image processing status and its CDN URL'. The trailing clause 'without creating another file' explicitly contrasts this read operation with the sibling shopify_upload_image tool, making the scope and differentiation unambiguous.

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

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

The phrase 'without creating another file' implies this tool is for checking an existing upload rather than initiating a new one, providing implied usage context. However, it never names the alternative (shopify_upload_image) or states explicit conditions like 'use after uploading an image' or 'use shopify_upload_image if you need a new file', so the guidance remains implicit rather than directive.

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

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

Annotations provide 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds meaningful behavioral context beyond annotations: parallel execution and per-store success/error isolation. It does not discuss rate limits or aggregation details, but the core execution behavior is disclosed.

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

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

Two sentences with no filler. The core operation, scope, execution mode, and result model are all conveyed efficiently, with the most important constraints front-loaded.

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

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

For a network-fan-out tool with full schema coverage, helpful annotations, and no output schema, the description covers the essential details: read-only query, multiple stores, parallel execution, and per-store result isolation. It could be slightly richer on the exact return shape, but it is sufficient for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100% for all three parameters, so the schema already documents query, stores, and variables. The description reinforces the 'same query across stores' relationship but does not add new parameter-level meaning beyond what the schema provides, matching the baseline for full coverage.

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

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

The description clearly states a specific verb ('Run'), the resource ('the same read-only GraphQL Admin API query'), and the differentiating scope ('across multiple named stores in parallel'). This distinguishes it from sibling tools like shopify_graphql_query without needing to open the schema.

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

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

The description clearly identifies the intended use case: running one read-only query across several stores. It does not explicitly name alternatives or state when not to use this tool, but the parallel multi-store scope is clear enough to guide selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the description does not need to restate those. It adds a small amount of useful context by scoping the schema to the store API version, which aligns with the open-world hint, but it reveals nothing about output shape or edge behavior.

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

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

The description is a single front-loaded sentence with no filler or repetition. Every word adds meaning, and the core verb and resource appear immediately.

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

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

Given the lack of an output schema, zero parameter documentation, and the presence of closely related query/mutation/validation tools, this description is too thin for an agent to confidently invoke the tool. It does not explain what the returned schema information looks like, how to format type_name, or when this exploration tool is the correct choice over siblings.

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

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

Schema description coverage is 0%, so the description must compensate for the two undocumented parameters, store and type_name. It does not explain what format store should take, how type_name maps to GraphQL type names, or what happens if the type does not exist. The phrase 'Admin GraphQL schema' weakly implies type_name is a GraphQL type, but that is not enough.

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

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

The description names a specific verb ('Explore') and a clear resource (the Admin GraphQL schema) scoped to the store's API version. It is clear enough to distinguish the general intent from query/mutation tools, though it does not explicitly call out sibling alternatives.

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

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

The wording implies this tool is used when you need to inspect or explore GraphQL schema types, but it does not explicitly state when to use it versus shopify_graphql_query, shopify_graphql_mutation, or shopify_validate_graphql_codeblocks. Guidance is only implied, not stated.

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

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

Annotations already declare the operation read-only, idempotent, non-destructive, and open-world. The description adds meaningful extras beyond those annotations by mentioning Shopify protected-data permissions and cursor pagination, giving an agent useful operational context.

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

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

Two short sentences with no filler. The action and resource are front-loaded, and the permission caveat is stated efficiently. Every sentence earns its place.

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

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

For a simple paginated list/search tool, the description and annotations cover safety and basic purpose well. However, without an output schema and with sparse parameter documentation, an agent still has to infer several operational details such as query syntax, cursor handling, and store requirements.

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

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

Schema description coverage is 0%, so the description must compensate for undocumented parameters. It only broadly implies cursor pagination and search behavior from 'after', 'first', and 'query', but it does not explain the store parameter, query syntax, cursor format, or parameter relationships, leaving important semantics to inference.

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

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

The description states a specific action, 'search', a specific resource, 'customers', and the pagination mechanism. It is clearly distinguishable from sibling tools by resource, even without explicitly naming an alternative.

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

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

Usage context is implied: use it to search or list customers. However, there is no explicit when-to-use versus when-not-to-use guidance or named alternative, and the protected-data note only signals a precondition rather than tool selection context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context by disclosing that the API uses cursor pagination and accepts Shopify search-filter syntax, which are not present in 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.

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

A single sentence with no filler: the verb, resource, and two structuring concepts are immediately clear. The key distinctions (search filters, cursor pagination) are front-loaded in the sentence.

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

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

The tool is simple and annotations cover safety, so a short description is partially sufficient. However, with no output schema and no parameter documentation, the description doesn't mention return behavior, sorting/limits beyond the schema, or how this list relates to sibling list/get/order-summary tools, leaving moderate inferential gaps.

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

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

Schema description coverage is 0%, so the description must compensate; it only hints that 'query' is a Shopify search filter and that 'after'/'first' relate to cursor pagination. It does not explain the required 'store' parameter, the default/maximum page size, or the shape of the query syntax, leaving most of the burden on the schema's bare property names.

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

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

The description states a clear action ('List') on a specific resource ('orders') and adds two distinguishing capabilities: Shopify search filters and cursor pagination. It doesn't explicitly contrast with siblings like shopify_list_unfulfilled_orders or shopify_get_order, but the resource and modifiers make its basic purpose unambiguous.

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

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

No usage context or alternative routing is provided; it never mentions when to choose this tool over shopify_list_unfulfilled_orders, shopify_get_order, or shopify_order_summary. The phrase 'Shopify search filters and cursor pagination' hints at capabilities, but does not state conditions or exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds prerequisite context but does not disclose return shape, pagination, or other behavioral details; with these annotations, this is acceptable 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.

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

A single, short sentence that front-loads the verb and resource and immediately states the relevant usage context. Every word is purposeful, with no redundant filler.

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

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

For a simple one-parameter read-only tool, the description gives the core purpose and timing. However, with no output schema and no explanation of the store parameter or response structure, there is some ambiguity left for the agent. Annotations cover safety, but the description alone is only moderately complete.

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

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

Schema description coverage is 0%, and the description does not mention the store parameter at all. It adds no meaning beyond the schema's name, type, and length constraints. Since the description must compensate for low schema coverage, this is a notable gap, even though the single parameter is relatively self-explanatory.

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

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

The description states a specific verb ('List') and resource ('publication IDs'), and clarifies the operational purpose by saying 'before publishing products or collections.' This clearly distinguishes it from publishing, search, and other sibling tools.

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

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

The description explicitly communicates when to use this tool: before publishing products or collections. It does not name alternatives or exclusions, but the timing context is clear enough for an agent to select it as a prerequisite step.

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

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

Annotations already declare readOnlyHint=true and 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.

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.

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.

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.

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.

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.

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context beyond the annotations by noting the results are independent per store and the orders are recent, open, and unfulfilled.

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

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

The description is a single, well-structured sentence with no redundant phrasing. Key scoping details, multi-store and unfulfilled, are front-loaded, making the tool's purpose immediately clear.

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

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

The definition is complete enough for a read-only list operation: the scope, filtering, multi-store behavior, and parameter constraints are all clear, and annotations cover side-effect safety. With no output schema, return format details are not described, but this is a minor gap given the tool's simplicity.

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

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

The input schema has 100% coverage for all three parameters, including defaults and constraints, so the description does not need to repeat parameter details. The description's 'recent' and 'per-store results' wording aligns with the days and first parameters but adds no new parameter-specific semantics.

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

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

The description states a specific action and resource: listing recent open, unfulfilled orders across multiple Shopify stores. It also highlights a distinguishing trait, independent per-store results, which separates it from single-store order tools like shopify_list_orders.

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

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

The description clearly implies the intended use case: retrieving unfulfilled orders across multiple stores rather than from a single store. It does not explicitly name alternatives or exclusion conditions, but the multi-store framing gives an agent enough context for selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it targets only active variants and explicitly separates low, zero, and negative inventory, which informs the agent about result categorization.

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

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

Two concise sentences with no filler. The core behavior is front-loaded, and the inventory categorization detail is placed immediately after, making it easy to parse quickly.

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

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

With only two simple parameters and strong annotations, the description is mostly complete for invocation. There is no output schema, but the description compensates by specifying the result categorization ('low, zero, and negative inventory') and the target scope ('every active product variant across selected stores'). A more detailed return format would be helpful but is not essential.

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

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

Schema description coverage is 100%, so both 'stores' and 'threshold' are already documented with clear meanings. The description adds no new parameter syntax or format details beyond the schema, so the baseline of 3 is appropriate.

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

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 'Find[s] every active product variant at or below an inventory threshold across selected stores.' It also adds unique behavior by separating low, zero, and negative inventory, which differentiates it from general inventory lookup tools like shopify_get_inventory_levels.

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

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

The description gives clear context for when this report is appropriate: when the agent needs active product variants across multiple stores at or below a threshold. It does not explicitly name alternatives or exclusions, but the cross-store and threshold scoping make the intended usage apparent.

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

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

Annotations already declare readOnly, open world, idempotent, and non-destructive behavior. The description adds useful context beyond annotations by specifying that currency totals remain separate and by enumerating the financial and fulfillment dimensions summarized. This enriches the agent's understanding of what the tool actually returns.

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

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

The description is two concise sentences. The first sentence front-loads the core purpose and the exact order metrics included, while the second adds a crucial, non-obvious behavioral detail about currency separation. Every word earns its place.

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

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

No output schema is present, but the description clearly names the categories of data summarized and flags currency behavior. Annotations cover the safety/idempotency profile. The only notable omission is the exact response shape, but for a summary tool this is less critical given the explicit metric list.

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

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

Schema description coverage is 100%, and the description adds no parameter-level detail beyond what the schema already documents. The 'days' and 'first' parameters are well defined in the schema, so the description does not need to compensate. It maps 'across selected stores' to the stores parameter but without extra syntax or formatting detail.

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

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

The description uses a specific verb and resource: 'Summarize recent order values, discounts, shipping, tax, cancellations, and financial and fulfillment statuses across selected stores.' This clearly distinguishes it from list/get order tools by emphasizing aggregation across stores, while still naming concrete order dimensions.

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

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

The description clearly signals when this tool is appropriate: for high-level multi-store order summaries rather than per-store order lists or single-order lookups. It does not explicitly name alternatives like shopify_list_orders or state exclusions, but the aggregation context is clear enough for an agent to route correctly.

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

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

The annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive behavior. The description adds valuable context beyond annotations by noting the snapshot is read-only and that counts are included only 'when scopes permit,' which warns the agent about conditional output depending on authorization. No contradiction exists.

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

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

Two sentences with no filler. The first sentence establishes the core action and scope, and the second sentence states the snapshot contents and the key scoping caveat. Every sentence earns its place.

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

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

For a simple tool with one optional parameter and comprehensive annotations, the description is largely complete. It explains what the output-like snapshot contains and notes the permission sensitivity of the counts. It doesn't describe the exact return format or error behavior, but those are not required given the low complexity and the absence of an output schema.

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

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

The input schema already fully documents the single 'stores' parameter, including the omission behavior. The description mentions selected or every configured store, but adds no additional semantic detail about parameter format, aliases, or constraints beyond what the schema provides. Baseline 3 is appropriate because schema coverage is 100%.

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

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

The description uses a specific verb and resource: 'Create a read-only operating snapshot' across stores, and elaborates exactly what the snapshot includes (shop identity and product, order, customer, and location counts). This clearly distinguishes it from narrower sibling report 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.

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

The description clearly indicates this tool is for a portfolio-level overview across selected stores or all configured stores. It doesn't explicitly name sibling alternatives or state when not to use it, but the scope is unambiguous enough for an agent to select it appropriately among the many report-style siblings.

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

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

The annotations already signal mutation (readOnlyHint=false) and destructive potential (destructiveHint=true), but the description adds no behavioral context such as irreversible visibility changes, permission requirements, or the effect of publishing on existing sales channels. It does not contradict the annotations, but it also does not disclose anything beyond the bare action.

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

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

A single, front-loaded sentence with no filler: subject, action, resource, and target are all present. Every word earns its place.

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

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

For a destructive, non-idempotent mutation with four required parameters and no output schema, the description is too thin. It omits the confirm/authorization requirement, how to obtain valid publicationIds, and any guidance on when publishing is appropriate, so a new agent would need to infer too much.

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

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

Schema description coverage is only 25% (only confirm is documented), so the description must compensate for the other parameters. It clarifies 'id' as product/collection and hints that publicationIds are the targets, but it does not cover 'store' or the confirmation gate beyond what the schema already states.

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

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

The description names a specific verb ('Publish'), the resources ('a product or collection'), and the target ('explicit publication IDs'), so an agent can identify what the tool does. It does not explicitly contrast it with siblings such as shopify_create_product or shopify_bulk_update_product_status, but the wording is specific enough to avoid confusion.

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

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

There is no guidance about when to choose this tool over alternatives like shopify_list_publications or shopify_graphql_mutation, and no exclusions or prerequisites. The only hint is 'explicit publication IDs', which implies the caller must already know the target publication IDs, but this is not developed.

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

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

Annotations already declare the operation read-only, idempotent, and non-destructive, so the safety burden is covered. The description adds behavioral scope beyond annotations: filtering by update recency and enumerating the included product attributes, which tells the agent what to expect in results. No contradictions with annotations were found.

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

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

The description is a single, well-packed sentence front-loaded with the action and resource. Every phrase earns its place, and it avoids repeating schema-level parameter details or annotation content.

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

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

For a simple, read-only multi-store listing tool with 100% schema coverage and no output schema, the description provides enough invocation context and even previews return fields. It could be slightly stronger by naming a sibling tool to avoid confusion with similar multi-store search tools, but that gap is minor.

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

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

The input schema covers all three parameters (stores, days, first) with meaningful descriptions, so the baseline is 3. The description's 'lookback window' and 'across multiple stores' loosely map to days and stores but add no syntax or format detail beyond what the schema already provides.

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

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

The description names a specific verb ('List'), a clear resource ('products updated during a selected lookback window'), and a multi-store scope that distinguishes it from single-store search siblings like shopify_search_products. It also enumerates the returned product fields (status, inventory, vendor, product type), so an agent can identify the tool's niche without opening the schema.

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

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

The description establishes a clear trigger condition: products that changed within a selected lookback window across stores, which maps naturally to the days and stores parameters. It does not explicitly name alternative tools or exclusion criteria, but the scoping language is specific enough to separate this from generic search and report tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description does not need to restate safety. It adds useful behavioral context by noting the reports access requirement and the return shape (columns, rows, chart metadata). No contradiction with annotations is present.

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

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

The description is a single efficient sentence that front-loads the action, names the query language, specifies the return content, and includes the key access requirement. Every part earns its place with no filler.

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

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

For a two-parameter read-only tool, the description gives a reasonable overview and return format, and annotations cover safety. However, the lack of parameter details, no output schema, and no guidance on store naming or ShopifyQL syntax leave meaningful gaps for an agent trying to call the tool correctly.

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

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

Schema description coverage is 0%, so the description carries the burden for explaining parameters. It indicates that 'query' is ShopifyQL, but it does not explain the 'store' parameter, expected formats, or any additional semantics. The description only partially compensates for the lack of schema documentation.

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

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

The description states a specific verb and resource: 'Run ShopifyQL and return columns, rows and chart metadata.' This clearly identifies the tool's purpose and distinguishes it from siblings like shopify_graphql_query or shopify_graphql_mutation.

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

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

The description implies usage for ShopifyQL analytics queries and adds a prerequisite ('Requires reports access'), but it does not explicitly explain when to choose this tool over alternatives or when not to use it. The usage context is clear enough to infer, but no exclusions or alternative routing are provided.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior, so the description does not need to restate that. It adds useful context by specifying 'manual and smart collections' and 'cursor pagination', which clarifies scope and pagination behavior beyond the schema.

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

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

The description is a single, front-loaded sentence with no filler or redundant information. Every word adds value: the resource type is explicit and the pagination behavior is stated concisely.

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

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

For a read-only, simple search tool, the description combined with annotations and schema provides a minimally viable picture. However, it lacks details such as query syntax, sorting behavior, and what the returned paginated response looks like, and there is no output schema to fill that gap.

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

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

Schema description coverage is 0%, so the description must compensate, but it only alludes to pagination without explaining store, query, first, or after parameters. The phrase 'cursor pagination' gives some meaning to first/after, but it does not make the parameter semantics clear.

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

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

The description states a clear, specific verb-resource pair: 'Search manual and smart collections' with cursor pagination. It unambiguously differs from sibling tools like shopify_get_collection, which retrieves a single collection, and shopify_compare_collections, which compares collections.

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

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

The description implies when to use the tool—when searching or listing collections—but does not explicitly state when not to use it or which sibling to prefer. No alternative tools are named, so the agent must infer usage context from the name and sibling list.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so no mutation risk is hidden. The description adds behavioral context beyond the annotations by specifying that the tool returns source links and that no store credentials are sent. It does not describe chunking or pagination behavior, but the annotations lower the burden for safety-related disclosure.

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

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

The description is two short sentences with no filler. The first sentence front-loads the core action and output, and the second sentence adds a meaningful behavioral/security trait. Every sentence earns its place.

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

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

This is a relatively simple tool with rich annotations, and the description does convey that it searches docs and returns source links, making it minimally usable. However, api_name is left unexplained, there is no output schema to clarify return structure, and there is no guidance on result count semantics, so clear gaps remain.

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

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

Schema description coverage is 0%, so the description must compensate for undocumented parameters. It indirectly implies that 'prompt' is the documentation query, but it does not explain 'api_name' or 'max_num_results.' An agent would not know what api_name values are valid or how result limiting behaves, making this a clear gap.

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

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

The description uses a specific verb and resource: 'Search Shopify documentation' and states the deliverable: 'return source links.' This clearly distinguishes it from sibling tools that operate on store data, products, orders, or GraphQL schema rather than documentation search.

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

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

The description gives clear context for when to use the tool: whenever an agent needs to search Shopify documentation. It also adds the useful note that no store credentials are sent, which helps frame it as a safe documentation lookup. However, it does not explicitly name alternatives or when-not-to-use conditions, 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.

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

The annotations already establish read-only, idempotent, open-world, and non-destructive behavior, so the bar is lower. The description adds cursor pagination as a behavioral trait, but it provides no details about page size, cursor format, or result ordering. This is useful but minimal context beyond the annotations.

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

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

The description is a single clause with no filler, and the key elements—action, resource, and pagination—are front-loaded. Every word earns its place, and it is about as efficient as a description can be for this tool.

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

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

With no output schema, undocumented parameters, and four parameters to handle, the description is too terse to let an agent understand what the response looks like, how to construct a valid query, or how pagination actually behaves. It covers the core idea but leaves significant operational details missing.

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

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

Schema description coverage is 0%, and the description only hints that 'after' and 'first' relate to cursor pagination. It does not explain the meaning of 'query', the Shopify search syntax, the 'store' parameter, or the cursor format, so it fails to compensate for the missing schema-level parameter documentation.

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

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

The description states a clear verb and resource ('Search products') and calls out cursor pagination, which distinguishes it from single-product fetch tools like shopify_get_product. However, it does not clarify how it differs from the very similar sibling shopify_search_products_many or mention the store scope implied by the required 'store' parameter.

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

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

There is no guidance on when to use this tool versus alternatives. It gives no conditions, exclusions, or pointers to sibling tools such as shopify_search_products_many, shopify_get_product, or shopify_find_sample_product.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description goes beyond these by disclosing that results are 'bounded per-store' and that completeness indicators are returned, which warns agents that results may not be exhaustive. It does not explain the semantics of those indicators, but the added behavioral context is meaningful.

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

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

Two sentences with no filler. The core purpose is front-loaded, and every clause contributes: multi-store scope, query flexibility, bounded results, and completeness signaling.

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

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

For a multi-store search tool with no output schema, the description covers the key invocation concerns: which stores, what query syntax, result limits, and the existence of completeness indicators. It does not describe the exact return structure or how completeness indicators behave, but the schema and annotations cover the remaining structured information.

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

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

Input schema coverage is 100%, so the parameters are already documented. The description adds value by explaining that 'query' accepts either plain terms or Shopify product-search syntax, and that results are bounded per store, which maps to the 'first' parameter. This goes beyond a baseline schema-only understanding.

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

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

The description clearly states a specific verb and resource: 'Search products across selected stores.' It also specifies query flexibility ('plain terms or Shopify product-search syntax') and distinguishes the tool from single-store siblings by emphasizing the multi-store scope.

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

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

The phrase 'across selected stores' clearly implies this is the multi-store search tool, especially in contrast to sibling tools like shopify_search_products. However, it never explicitly names alternatives or states when not to use it, so it stops short of full routing guidance.

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

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

Annotations already declare the tool destructive and non-idempotent. The description adds the compare-and-set protection behavior, explaining that the write is conditional and prevents stale overwrites, plus the necessity of a preceding read. This is meaningful behavioral context beyond the annotations. No contradiction exists.

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

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

The description is exactly two sentences with no filler. The first sentence states the action and mechanism; the second delivers the key precondition. Every word serves a purpose, and the critical safety instruction is front-and-center.

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

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

The description covers the core workflow—read first, then perform a compare-and-set write—and is appropriate for the main path. However, with 8 parameters, no output schema, and a destructive annotation, it leaves gaps such as what a successful set returns, how a compare conflict is reported, and the purpose of optional reason. The confirm requirement is only in the schema, not reinforced in the description.

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

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

Schema description coverage is only 13%, with only confirm having a description. The description's mention of compare-and-set and 'read first' provides some meaning for compareQuantity and quantity, but it leaves store, reason, inventoryItemId, locationId, and confirm's role largely unexplained in the description. The schema constraints give limits but not semantic intent, so the description does not sufficiently compensate.

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

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

The description states a clear action ('Set available inventory') with a specific resource and adds the compare-and-set mechanism, which distinguishes it from sibling read/compare tools like shopify_get_inventory_levels and shopify_compare_inventory. However, it doesn't explicitly tie back to the sibling set of tools or elaborate on the exact scope of 'available inventory.'

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

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

'Read inventory first' is a direct, explicit precondition that tells the agent to obtain the current quantity before setting. It also implies the value for compareQuantity should come from that prior read, which is a valuable usage guideline. It doesn't explicitly mention alternatives or when not to use this tool, but the context of a guarded write is well conveyed.

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

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

Annotations already mark the tool as read-only, idempotent, non-destructive, and open-world, so the safety profile is covered. The description adds useful behavioral context by listing exactly which kinds of location status are reviewed, giving the agent a concrete sense of what the operation surfaces.

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

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

The description is a single, well-structured sentence that front-loads the action and resource before listing the status dimensions. Every element contributes to clarifying scope and behavior, with no filler or redundancy.

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

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

For a simple read-only reporting tool with one optional parameter, the description, combined with the annotations, gives enough context to invoke it correctly. It could be even more explicit about the return shape, but the enumerated status categories largely compensate for the absence of an output schema.

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

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

The input schema already provides 100% description coverage for the only parameter, 'stores', including its alias format and the omit-to-include-all behavior. The description's phrase 'selected stores or the full portfolio' merely echoes the schema, adding no meaningful new semantic value.

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

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

The description names a specific resource ('locations') and a clear action ('Review'), and enumerates the relevant status dimensions (active, inactive, legacy, fulfillment, inventory, address) and scope (selected stores or full portfolio). This clearly distinguishes it from the sibling tools, none of which target store locations specifically.

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

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

The description conveys when the tool is appropriate: for reviewing location status across chosen stores or the whole portfolio. It does not explicitly compare against alternatives or state exclusions, but the context is clear enough for an agent to select this tool for location-level status review.

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

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

The annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds context beyond those: it says the operation does not disconnect other stores and that callers must keep passing the store alias, which clarifies the persistent-call contract. No contradiction with annotations.

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

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

Two short, front-loaded sentences with no filler. The purpose and the critical usage rule are both present, and every clause earns its place.

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

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

For a one-parameter, annotation-rich tool, the description is largely complete: it explains the operation, the store alias input, and the call contract. The only notable gap is that, with no output schema, it does not state what the tool returns or how to detect success, but the simple scope makes this a minor omission.

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

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

The schema has 0% description coverage for the 'store' parameter, so the description carries the burden. It explains that the parameter is a store alias and that the alias is needed on every call, adding meaning that pure schema constraints (string, 1-64 chars) do not provide. It does not say what alias formats are accepted.

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

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

The description uses a specific verb ('Resolve') and names the resource ('a named store'), and notes it does so without disconnecting other stores, which clarifies its scoped behavior. It does not explicitly differentiate from siblings like shopify_list_stores or shopify_get_shop_info, so it stops short of a 5.

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

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

The instruction 'Continue to pass the store alias on every call' gives clear operational guidance for how to use the tool and confirms that the agent must keep supplying the alias. It implies the trigger (when a named store needs to be resolved) but does not name excluded alternatives or when-not-to-use cases.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is known. The description adds 'with a before/after result', which reveals something about the return shape. However, it does not disclose that changes are permanent or that confirm=true is required, leaving behavioral transparency mostly to annotations and schema.

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

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

The description is a single front-loaded sentence with no filler. It communicates the core purpose quickly, though the phrase 'fields, rules or image' is compact but somewhat imprecise. Overall it is appropriately concise.

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

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

For a destructive mutation tool with 8 parameters, nested objects, no output schema, and a required confirm field, the description is incomplete. It lacks guidance on when confirmation is needed, how partial updates behave, what the before/after result actually contains, and what constraints apply to ruleSet or image. The description does not provide enough context for an agent to invoke this tool safely and correctly.

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

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

Schema description coverage is only 13%, so the description must compensate for under-documented parameters. It only groups parameters into 'fields, rules or image' and fails to explain the semantics of id, store, confirm, ruleSet, sortOrder, descriptionHtml, or image. This is insufficient for an 8-parameter tool with nested objects.

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

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

The description states a clear verb ('Update') and resource ('collection'), and names the kinds of changes ('fields, rules or image'), distinguishing it from create_collection and get_collection. However, 'fields' is vague because the schema supports specific fields like title, descriptionHtml, and sortOrder, so it is not fully precise.

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

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

The description gives no guidance on when to use this tool versus alternatives such as shopify_create_collection or shopify_update_product. It does not mention prerequisites, the confirm authorization step, or when to prefer another mutation tool. Usage is only implied by the tool name and the generic 'Update' verb.

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

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

Annotations already declare the safety profile (readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true), and the description adds one useful behavioral detail: it returns a before/after result. However, it does not disclose that a confirm=true authorization is required for the exact change, nor the destructive side effects of replacing variants or removing media (removeMediaIds). No contradiction with annotations exists.

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

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

A single front-loaded sentence: verb first, then resource, then scoped payload categories, then the distinguishing before/after return behavior. Every word earns its place and nothing merely repeats the schema, making it efficiently structured.

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

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

For a destructive, non-idempotent, open-world mutation with 12 parameters, no output schema, and only 8% schema description coverage, a 10-word description is materially incomplete. It omits the confirm authorization requirement, the distinction from bulk-update and raw-GraphQL siblings, and what the before/after result actually contains.

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

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

Schema description coverage is only 8% — only the confirm parameter carries a description. The tool description contributes a light organizational mapping of the 12 parameters into three buckets (fields, variants, media), which helps, but it does not explain required params (store, id, confirm), the confirm authorization contract, or GID patterns. Given the very low coverage, the description should compensate far more than it does.

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

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

The description names a specific verb ('Update'), a resource ('product'), and the scope of what can be changed ('fields, variants and media'), which clearly distinguishes it from create/read siblings like shopify_create_product and shopify_get_product. It does not explicitly name alternatives such as shopify_bulk_update_product_status, so an agent must infer the boundary rather than have it stated, keeping this just below a 5.

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

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

There is no guidance on when to use this tool versus closely related siblings such as shopify_bulk_update_product_status (granular single-product update vs. bulk status change) or shopify_graphql_mutation (raw GraphQL access). No preconditions, exclusions, or alternative-routing information is provided at all.

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

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

Annotations already indicate a destructive, non-read-only mutation. The description adds useful behavioral context beyond those flags: it waits for async processing and returns a CDN URL, and it supports local files or HTTPS URLs. It doesn't fully describe side effects, but it meaningfully supplements the annotation profile.

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

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

A single, front-loaded sentence conveys the action, input forms, processing behavior, and output. Every phrase is informative and there is no filler or redundant restatement of the tool name.

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