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

Annotations already cover the read-only, idempotent, non-destructive profile, and the description adds substantive context above that bar: the comparison source (src/scope-requirements.ts), the tool:resource naming convention for multi-resource tools, and the default all-stores behavior. It omits failure handling for unknown store names, which keeps it from a 5.

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 core function is front-loaded in the first clause, with the default-behavior note as a short trailing sentence. The parenthetical about src/scope-requirements.ts is slightly implementation-detailed but earns its place by telling the agent where requirements come from.

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 does the work of describing the return content (shop identity, granted scopes, missing scopes, tools that would fail), which is what an agent needs. Annotations cover safety. Only minor gaps remain, such as behavior on an invalid store string.

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 carry the meaning, and it does explain that stores is one-or-many and optional (omitting it checks all). However it gives no format guidance (store handle vs domain) or mention of the 50-item cap, so the compensation is partial, matching the baseline-3 expectation for a single low-coverage 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?

Names a specific verb+resource (report shop identity and granted Admin API scopes) and adds a second distinct function (compare against every tool's scope requirement and flag failures). That combination clearly separates it from siblings like shopify_get_shop_info or shopify_list_stores, which just fetch identity.

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 states the operational context clearly (preflight scope validation) and explains that omitting stores checks every configured store, which is genuine usage guidance. It does not explicitly say when to prefer this over shopify_get_shop_info or shopify_list_stores, so it stops short of full 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 destructiveHint=true, readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is partly covered. The description adds the important non-obvious trait that dryRun defaults to true and previews without creating anything, though this largely restates the schema's dryRun description rather than adding new depth (no mention of auth requirements or rate/quantity limits).

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

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

Three dense sentences, front-loaded with the core mode distinction and ending on the highest-risk behavior (dryRun default). No filler; every clause carries actionable information.

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

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

For a mutation with no output schema, the description covers the key modes, publishing, and the dry-run default, and even notes that a non-dry-run call reads the result back. It stops short of enumerating required fields (store, title) or the sortOrder/descriptionHtml options, leaving minor gaps against a 9-parameter nested 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?

Schema description coverage is only 11% across 9 parameters, so the description must compensate, and it only covers productIds, ruleSet, publicationIds and dryRun. The mode-based semantics (manual vs smart) are genuinely useful, but image, sortOrder, descriptionHtml, store and title receive no interpretive guidance beyond their raw schema types.

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 and resource ('Create a ... collection') and immediately distinguishes its two creation modes: manual (productIds) vs smart (ruleSet). An agent can tell this apart from shopify_update_collection without opening either 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?

It maps parameters to intent ('Pass publicationIds to publish to explicitly selected channels'), which implies when to use each field, but it never states when to prefer a manual vs smart collection beyond the parameter, and gives no exclusions or routing against update_collection. Usage is implied rather than prescribed.

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 readOnlyHint=false, so the mutation profile is known. The description adds genuinely useful behavior: dryRun defaults to true and resolves segments/previews without creating, which tells the agent the call is safe by default. It stops short of noting that dryRun:false performs an irreversible write.

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 with the core action front-loaded and the dryRun caveat following. No filler, though the second sentence could explicitly flag the write-vs-preview distinction more sharply.

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 15-parameter, 5-required destructive mutation with 7% schema coverage and no output schema, the description is far from complete. It covers the dryRun behavior well but omits the semantics of most parameters and any indication of what the read-back result 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 7% (essentially just dryRun), so the description must carry the burden for 15 parameters. It alludes to percentage, start date, and customer audience, but leaves productIds, collectionId, usageLimit, minimumQuantity, minimumPurchaseAmount, appliesOncePerCustomer and others unexplained in both schema and description.

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

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

States a specific verb and resource ('Create a percentage discount code') plus scope ('explicit start date and customer audience'). It is clearer than its siblings, none of which create discounts, though it never explicitly contrasts itself with a generic mutation tool like 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 explains the dryRun default but gives no guidance on when to use this tool versus alternatives such as shopify_graphql_mutation or shopify_run_action. No prerequisites or exclusions are 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 flag destructiveHint=true and readOnlyHint=false, and the description adds meaningful operational context: dryRun defaults to true (a safe preview), notifyCustomer defaults to false, which scopes are required, and that Shopify may report additional missing scopes for fulfillment-service orders. It does not fully explain reversibility or side effects, but it adds real 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?

Three sentences, front-loaded with the core action and scope, with auth and default behaviors following. No filler, though the tracking-parameter cluster is glossed rather than explained.

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 with no output schema, the description covers the essential operational details: dryRun default (with the note that preview is non-mutating and false applies and reads back), notifyCustomer default, and required scopes. It stops short of documenting the individual tracking parameters, which is the main remaining 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 coverage is only 14%, so the description carries most of the burden, yet it only generically references 'optional tracking' and restates defaults (notifyCustomer, dryRun) that the schema already declares. store, orderId, trackingUrl, trackingNumber, and trackingCompany get no semantic help, leaving key parameters 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 states a specific verb (fulfill) and resource (an order's fulfillment orders), and even narrows the scope to remaining quantities of OPEN and IN_PROGRESS orders. It is clearly distinguishable from generic mutation siblings, though it does not explicitly name an alternative tool.

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 by 'fulfill the remaining quantities' and the note about which fulfillment orders are eligible, plus required scopes. However, there is no explicit when-to-use vs when-not guidance and no named alternative among the many 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 declare destructiveHint=true and readOnlyHint=false, so the safety profile is partly covered. The description adds genuinely important context the annotations do not convey: the dryRun:true default previews input without creating anything, and the default status is DRAFT. That is meaningful behavioral disclosure for a mutation tool, though it stops short of describing auth requirements or read-back 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?

Two tight sentences with no waste. The core action is front-loaded and the crucial default behaviors follow 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?

For a 13-parameter mutation tool with no output schema and near-zero schema descriptions, the definition should do more. The dryRun/status defaults are well covered, but most parameter semantics and any output/read-back expectation are left unstated.

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%, so the description must compensate for 13 mostly-undocumented parameters. It names the concepts (options, variants, images, collection, defaults) but adds little meaning beyond the field names and does not explain tags, price, store, vendor, productType, collectionId format, or descriptionHtml.

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 product") and scopes exactly what the tool assembles: options, variants, images, and an optional manual-collection add. The verb cleanly separates it from the sibling update_product, so an agent can identify it 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?

There is no explicit when-to-use guidance, no exclusions, and no mention of alternatives such as update_product or create_collection. The 'add it to a manual collection' clause even raises a question (when to use this vs create_collection) that the description never resolves.

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 this as a safe, idempotent, read-only operation. The description goes further by disclosing the content and shape of the response and, crucially, the destructive-flag propagation to shopify_run_action's confirm parameter — behavior the annotations cannot express. It stops short of noting limits such as depth cost or unknown-mutation handling.

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 dense sentence, front-loaded with the core idea ('Full signature of one Admin API mutation') then enumerating the returned artifacts. It is long but each listed artifact corresponds to real output, so little is wasted, though the list could be tightened.

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 carries the burden of explaining return values and does so thoroughly, plus it covers the destructive/confirm interaction with shopify_run_action. A describe-only tool with a fully documented 4-param schema needs little more, though a note on error behavior for unknown mutations would close the 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 100%, so mutation, depth, store, and apiVersion are already documented in the schema with types, patterns, and defaults. The description mentions an 'expanded input object' concept (loosely mapping to depth) but adds no syntax or semantics beyond the schema, so the baseline 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 exactly what the tool returns for one Admin API mutation: arguments with types, expanded input fields, payload fields, a GraphQL document, a variables template, a scope hint, and a destructiveness flag. It is specific and verb+resource oriented via the name/title, though it never explicitly contrasts itself with siblings like shopify_graphql_schema or shopify_run_action.

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 gives clear conditional routing by explaining that if the mutation is destructive, shopify_run_action requires confirm set to the mutation name — effectively telling the agent to describe before running. However, it never states when to prefer this over shopify_graphql_schema or what to do for read queries.

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, non-destructive, so the safety profile is covered. The description adds useful behavior beyond that: the seven return fields (including a destructive flag and which dedicated tools already cover each action) and the discovery-then-execute workflow.

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?

Three sentences, front-loaded with purpose, then return payload, then next steps. No filler and nothing repeated from the schema.

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 exists, and the description covers the return shape and the follow-on tool chain, which is what an agent needs to act. It omits pagination behavior (limit/offset, the 50-cap) and default store/apiVersion resolution, leaving a minor gap for a discovery tool.

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

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

Schema coverage is only 43% across 7 params, but the description does explain the two most consequential ones - keyword search (query) and optional category. limit, offset, includeDeprecated and the apiVersion interplay remain undocumented anywhere, so it only partially compensates for the 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?

States a specific verb+resource+scope: search every Shopify Admin API mutation, including the hundreds of write actions that lack a dedicated tool. This cleanly distinguishes it from sibling search/describe/run tools and from the dedicated mutation tools listed.

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?

Explicitly tells the agent what to do next (shopify_describe_action for the signature, then shopify_run_action), which is strong routing guidance. It doesn't state a when-not or contrast against shopify_search / shopify_graphql_schema, so not a full 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?

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior: 'Follow each returned cursor independently' for pagination and 'Partial exports stay marked incomplete' for bulk operations, plus the per-resource return contents.

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 core purpose is front-loaded in one sentence, followed by a scannable per-resource list where each bullet carries distinct information. It is long but nearly every line earns its place; density is acceptable given nine resource modes.

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-mode read tool with no output schema, the description covers what each resource returns and its id type well. It falls short only on the store parameter, the pagination params (after/first), and any auth/rate-limit context.

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

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

Schema coverage is 56%, so the description must compensate, and it does meaningfully: it explains that 'id' is a different GID type per resource (Product, Collection, Order, InventoryItem, MediaImage, etc.), and clarifies the optional 'namespace'/'key' and 'filenames' behavior. However, `store`, `after`, and `first` are never explained in the description or 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?

States a specific verb+resource+scope: 'Read one record by GID from one store.' The resource list enumerates exactly what kinds of records can be fetched, clearly distinguishing a direct GID read from sibling search/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?

Usage is implied by 'Read one record by GID,' but there is no explicit when-to-use or when-not guidance (e.g., versus shopify_search or shopify_graphql_query) and no stated prerequisites. The agent must infer that a GID is required to prefer this over searching.

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?

Goes well beyond the annotations by explaining the confirm-gating workflow, the special confirm-as-mutation-name requirement for destructive mutations (including arg-dependent cases like ARCHIVED status or notifyCustomer), denylist refusal, and per-field result statuses. This is exactly the behavioral detail an agent needs for a destructive tool.

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 dense paragraph that is front-loaded with the core action, then the confirm workflow, then result semantics. It is long but nearly every sentence carries operational information; nothing is 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 destructive, no-output-schema tool with nested variables, the description covers authorization prerequisites, the destructive-confirm protocol, denylist behavior, return-status vocabulary, and retry guidance after partial/unknown outcomes. Little an agent needs to invoke correctly is 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: it clarifies that confirm may be the mutation name for destructive mutations and ties result fields to top-level mutation fields. It doesn't expand much on the variables object, which the schema already documents.

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 and resource ('Run one GraphQL Admin API mutation against one named store') and implicitly distinguishes itself from the query siblings. An agent can immediately tell this executes writes rather than reads.

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?

Gives clear when-to-use guidance: set confirm to true only after the user authorizes the exact store and change, and defers destructive-mutation specifics to shopify_describe_action. It also notes denylisted mutations are refused, matching shopify_run_action. It doesn't explicitly contrast mutation vs. shopify_graphql_query, but routing 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 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, idempotentHint, openWorldHint, and non-destructive, so safety is covered. The only extra hint is 'this store's API version' (schema varies by version), but there is no word on what is returned (SDL text, type list, field metadata) or how it behaves for unknown type names.

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. It is efficient, though the brevity here reflects under-specification as much as tight writing.

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 introspection tool with annotations covering safety and no output schema, the description still omits the two things the agent most needs: what type_name refers to and what the call returns. It is too thin given 0% parameter coverage.

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 both required parameters are undocumented. The description implies type_name is a GraphQL schema type but never says so explicitly, nor does it clarify the store identifier's format — a significant gap for a tool whose core input is a type name.

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 pairs the verb 'Explore' with the resource 'Admin GraphQL schema' and scopes it to the store's API version, which is slightly more than the name alone. However, it does not distinguish itself from near-siblings like shopify_graphql_query, shopify_graphql_mutation, or shopify_describe_action, so the agent must infer that this is introspection rather than execution.

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 reach for schema exploration versus running a query or calling describe_action, and no mention of prerequisites. An agent gets no routing signal.

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 readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower, but the description adds real value: per-user filtering, that unconnected stores are named with a connect link, and that access tokens are never exposed. That privacy note is a non-obvious, useful behavioral disclosure.

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

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

Three tight sentences, front-loaded with the core action and then the mode-dependent nuance and privacy guarantee. No filler or repetition.

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 listing tool with no output schema, the description covers scope, tenancy behavior, and privacy adequately. It stops short of describing the per-store fields returned, which an agent must infer.

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 tool takes zero parameters per the schema (100% coverage, empty properties), so there is nothing for the description to disambiguate. Baseline 4 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+resource: listing every Shopify Admin store still connected to the plugin. This is unambiguous and separable from siblings like shopify_get_shop_info or shopify_check_access 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 conveys clear context for when its behavior applies, notably the hosted server / per-user mode case, which an agent can use to anticipate output. It does not name a competing alternative or an explicit 'call this first' trigger, 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 destructiveHint=true and openWorldHint=true, so the mutation risk is known. The description adds the key behavioral fact that dryRun defaults to true (safe preview by default) and the 25-item cap per operation, which materially affects how an agent stages calls.

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 tight sentence with the mutation semantics front-loaded, followed by the read alternative and the safety default. 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?

With no output schema and sparse schema descriptions, the description covers the important surface: dual operations, batch limit, owner scope, dry-run default, and the read path. It omits return/auth details, but for a 4-param tool with an explicit dryRun preview this is close to sufficient.

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

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

Schema description coverage is only 25% (dryRun only), so the description must compensate. It adds the 25-item limit, that both set and delete accept any owner GID, and the dryRun default, but says nothing about the required namespace/key/ownerId fields or the nested item shape, leaving the bulk to 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?

States specific verbs (set/delete) and the resource (metafields), names the underlying GraphQL operations (metafieldsSet/metafieldsDelete), and even routes the read case to a sibling. An agent can distinguish this from shopify_get and shopify_graphql_mutation immediately.

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?

Explicitly tells the agent to read metafields via shopify_get resource metafields, which is a real alternative-tool route. It also flags the dryRun default so the agent knows the initial call is non-mutating. No exclusions for when NOT to use it against shopify_graphql_mutation, so not 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?

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered; the description adds material context on top: required scope, the dryRun default that prevents accidental writes, and the per-redirect result vocabulary (applied/rejected/unknown) plus store status. It does not say whether rejected items are retryable or how partial failures are rolled back, which keeps it out of 5 territory.

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?

Three dense sentences, with the mutation scope and outcomes front-loaded and the prerequisite, alternative tool and dryRun default trailing. No filler, though 'List them with shopify_search resource redirects' is slightly compressed and reads awkwardly.

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 carries return-value disclosure and does so (per-redirect outcome, store status), and it covers auth scope, batch limits and the dryRun default. For a destructive, non-idempotent batch mutation this is close to complete; only failure/partial-success handling is unaddressed.

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 50% and the description largely restates what the schema already encodes: the 100-item cap mirrors maxItems, and the dryRun default mirrors the schema description. The create item fields (path, target) and the store parameter are not clarified beyond their names, so 3 is the right baseline.

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 pair and resource ('Create and/or delete up to 100 URL redirects'), plus the batch scope (100 each) and the per-item outcome shape. It also names the sibling to use for the read path (shopify_search resource redirects), so an agent can place it relative to the listing tool without opening a 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?

Gives the access prerequisite ('Requires write_online_store_navigation'), the default safety behavior ('Defaults to dryRun:true'), and routes listing to shopify_search. It stops short of explicit when-not-to-use conditions, but the context needed to choose and call it is present.

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/destructiveHint, so the safety profile is covered. The description adds genuine behavioral context beyond that: per-store fan-out ('each store returns its own result') and 'completeness indicators', which tells the agent results may be partial across stores. It omits rate limits and error/partial-failure 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?

Front-loaded with the tool's purpose, then a scannable per-report bullet list. The length is justified by 17 enum values, though some lines restate schema-level facts; still, every bullet carries selection-relevant information.

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

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

Given a 12-parameter, 17-mode tool with no output schema, the description is nearly complete: it covers report selection, required inputs, and partial-result behavior. What's missing is a clearer statement of the return shape per report (it only hints at 'columns, rows and a chart hint' for analytics).

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

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

Schema coverage is 100% (baseline 3), but the description adds meaningful value the schema lacks: it assigns each of the 12 parameters to the specific reports that consume them and supplies defaults the schema does not state (threshold default 10, days default 7, first defaults per report). This goes beyond the structured fields.

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 and resource ('Run one read-only report across selected stores') and enumerates the 17 selectable report values with their scope, which distinguishes it immediately from siblings like shopify_search, shopify_get, and shopify_graphql_query.

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?

Each report line states the inputs it needs ('Needs skus (1-50)', 'stores optional (all stores)', 'Needs query and read_reports'), which effectively routes the agent to the correct report value. It does not, however, say when to prefer this tool over shopify_search or shopify_graphql_query for overlapping data, so it stops short of explicit alternatives.

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

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

Beyond the annotations (readOnlyHint false, destructiveHint true, idempotent false, openWorld true), it discloses that IDs are re-looked-up before apply, that unresolvable IDs refuse the apply, that incomplete previews arise from search/filter/all targets or >250 IDs, that mutations are never retried automatically, and that per-user mode caps authority to the staff account. This is unusually rich behavioral detail.

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

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

It is a long, dense paragraph with some run-on sentences, but it is front-loaded on the dryRun-default behavior and every clause carries operational information. Little is padding, though a bulleted structure would have aided scanning.

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 8-parameter, nested-object, no-output-schema tool, the description covers the mutation/document relationship, dryRun default, incomplete-preview logic, apply refusal, confirmation, retry policy, and permission scoping. It does not describe the actual result payload an apply returns, which is the remaining gap given no output schema exists.

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 75% and several parameters already carry descriptions, yet the prose adds real meaning the schema lacks: mutation names build a default document, a supplied document must call the named mutation, variables are shared across stores while variablesByStore merges per-store by ID, and confirm must equal the mutation name. It is not a full 5 because dryRun and stores syntax are left to 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 states a specific verb and resource ('Run any Shopify Admin API mutation') and adds scope ('on one to one hundred stores'), which implicitly separates it from a single-store mutation sibling. It never explicitly names shopify_graphql_mutation, so the differentiation from that closest alternative is left for the agent to infer.

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 spells out the default mode (dryRun validates nothing is changed), the condition to apply (dryRun false), the escalation path when the preview is incomplete (acknowledgeIncompletePreview), and the extra requirement for destructive mutations (confirm set to the mutation name). These are explicit when/when-not signals an agent can act on directly.

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 readOnly/idempotent annotations, the description discloses cursor pagination, parallel multi-store execution with per-store results and cursors, ordering ('newest first'), and an auth/permission constraint ('Protected customer data permissions apply'). It omits rate limits and result-shape details, but adds substantial context against annotations that already cover the safety 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?

The two-sentence preamble is front-loaded with the core behavior and pagination, followed by a scannable per-resource list. Given 12 resources and their individual quirks, the length is justified, though the list is dense.

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 carries return-value burden and does so adequately by explaining cursors, per-store results, and per-resource page sizing. It stops short of detailing the general return shape, so it is strong but not fully self-contained.

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 71%, and the description adds meaning by mapping the query parameter to specific resources (and flagging those with no query), reinforcing the store vs stores parallel semantics, and noting type is required for metaobjects. This goes beyond the schema text, though it does not fully compensate for the uncovered 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 opens with a specific verb+resource ('List or search one kind of record') and then enumerates all 12 resource kinds, so an agent knows exactly what universe the tool covers. It clearly reads as the general read/search dispatcher, distinct from the mutation and graphql 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?

Per-resource notes give real usage context: which resources take a query ('Shopify product search syntax'), which take none ('no query; 100 per page'), and that metaobjects requires 'type'. It stops short of naming alternatives (e.g., shopify_get, shopify_graphql_query) or stating when not to use it, so it does not reach 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?

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?

Annotations already flag destructiveHint=true, readOnly=false and openWorld=true, so the safety burden is partly lifted. The description adds genuinely useful mechanics beyond the annotations: compare-and-set semantics where compareQuantity must equal the live available quantity, and that dryRun defaults to true and previews without changing anything. It omits auth/store-authorization requirements and rate limits, so not a 5.

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?

Three tight sentences that lead with the operation, then the safety constraint, then the preview default. No filler. Slightly dense in the middle clause but each 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, 8-parameter mutation with no output schema, the description covers the critical CAS contract and dry-run default, but leaves six parameters unexplained and says nothing about the read-back behavior after applying. Adequate but with clear gaps against the tool's complexity.

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 only 13%, far below the 50% threshold, so the description must compensate and only partly does. It clarifies the two highest-risk parameters (compareQuantity's CAS condition and dryRun's preview behavior), but store, quantity, locationId, reason, idempotencyKey and inventoryItemId are left entirely to the schema. Baseline 3 given the partial compensation against a real 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?

States a specific verb ('Set available inventory') plus the resource and scope ('at one location'), and distinguishes itself from the read path by pointing at shopify_get. An agent can tell this apart from shopify_update_prices or shopify_update_product without opening a 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?

Gives a clear prerequisite workflow: read current inventory via shopify_get first, then set with a matching compareQuantity. It also explains the default dryRun preview path. It does not name when NOT to use this tool or contrast it with sibling mutation tools, 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?

Annotations already declare destructiveHint=true, idempotentHint=false, readOnlyHint=false and openWorldHint=true. The description adds real value beyond that by disclosing the safe default (dryRun:true, so nothing changes unless explicitly disabled) and naming the backing mutations, though it doesn't say what a dry run returns or what happens if a tag is already 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?

Two compact sentences, front-loaded with the verb/resource and the owner types, with the important dryRun default trailing. 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 destructive 5-param mutation with no output schema, the description plus annotations cover the essentials: what changes, on which objects, and that it defaults to a non-mutating preview. It is slightly thin on result behavior after dryRun:false, but the dryRun schema entry covers the read-back.

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 20%, and the description adds little beyond confirming that the owner is addressed 'by GID' and that both add and remove are supported. It does not cover the add/remove array constraints (min length 1, max 50 items), the store parameter, or the GID pattern, leaving most of the param surface to 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?

Specific verb pair (add/remove) plus the resource (tags) and the four owner types it operates on, and it cites the underlying mutations (tagsAdd/tagsRemove). An agent can distinguish this from shopify_update_product or shopify_metafields without opening schemas.

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

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

Usage is implied by identifying the owner types and the tagsAdd/tagsRemove mutations, and the dryRun default hints at the preview-then-apply workflow. However, no explicit when-to-use guidance, no exclusions, and no named alternatives (e.g., whether to prefer shopify_update_product for tags) are given.

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, readOnlyHint=false, and idempotentHint=false, so safety is partly covered. The description adds genuinely new behavior: dryRun defaults to true and returns a preview, whereas dryRun:false applies the change and returns before/after state. It still omits permission/authorization or blast-radius details beyond the schema's dryRun note.

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 tightly written sentences with the mutation scope front-loaded and the dryRun semantics immediately after. Dense and free of filler, though the second sentence is long enough that it reads more like a schema clarification than a standalone guide.

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 9-parameter destructive mutation with no output schema and 22% schema coverage, the description adequately covers the commit/preview mechanic and return shape but leaves several documented-only-in-schema fields (title, sortOrder, descriptionHtml, ruleSet) unexplained. It is minimum viable rather than 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 22%, so the description must carry more of the burden. It explains addProductIds (manual-collection semantics) and the dryRun flag, and names image and rules loosely, but never clarifies title, sortOrder, descriptionHtml, the id gid format, or the ruleSet structure.

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?

Specific verb + resource ('Update collection fields, rules or image'), and it enumerates the collection-specific operations including adding products to a manual collection. It does not explicitly contrast with siblings like shopify_update_product or shopify_create_collection, but the resource and field list make the intended target 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?

Usage is implied (you call this to modify an existing collection) and the dryRun default gives a preview-first workflow, but there is no explicit when-to-use/when-not guidance or routing to alternatives such as shopify_graphql_mutation or shopify_create_collection. The agent must infer when applying versus previewing is appropriate.

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

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

Annotations already declare readOnly=false, destructive=true, idempotent=false, and openWorld=true; the description adds rich context beyond them. It explains the dryRun preview/apply cycle and return shape (current/change vs before/after), clarifies exactly what replaceTags destroys, and names the required write_customers permission. 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?

Four compact sentences front-load the core operation, then cover dryRun behavior, tag semantics, scope, and authorization. Every sentence carries useful information with no filler or repetition, making it easy for an agent to parse quickly.

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

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

With no output schema, the description still explains what dryRun:true and dryRun:false return, which covers the agent's need to understand outputs. It also covers authorization, tag behavior, and out-of-scope concerns, leaving only basic schema constraints (id format, store, note/email patterns) to the schema itself, which is appropriate.

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 50%, so the description needs to compensate somewhat. It adds meaning beyond the schema by explaining the interaction between addTags, removeTags, and replaceTags, and by restating dryRun default behavior and its return semantics. It does not cover id or store beyond the required schema constraints, but the tag semantics are the key non-obvious 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?

States a specific verb (Update), resource (customer), and the exact updatable fields (note, email, tags), while also naming the underlying customerUpdate mutation. This clearly distinguishes it from sibling tools like shopify_update_product or shopify_update_order, so an agent can route correctly 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?

Gives clear context: use this to update note, email, and tags, with a default dryRun preview and explicit tag add/remove/replace semantics. It also states a prerequisite (write_customers) and one scope exclusion (email marketing consent is out of scope). It stops short of naming alternatives, but no sibling tool directly competes for this operation.

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?

Goes well beyond the annotations: it explains the dry-run default and what each mode returns, describes exactly how addTags/removeTags/replaceTags affect existing tags (including the destructive nature of replaceTags), and states the required authorization scope. This materially improves safe invocation of a destructive mutation.

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?

Four tight sentences, each carrying distinct information: scope of updatable fields, dry-run semantics, tag-mode semantics, and permission requirement. Zero filler and the core action 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?

For a destructive, non-idempotent mutation with no output schema, the description covers the critical unknowns: safety mode, return behavior, tag semantics, and auth scope. It leaves minor gaps around individual scalar field behavior but is otherwise sufficient 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?

With schema description coverage at only 44%, the description compensates by clarifying the semantics of the dryRun flag and all three tag parameters, which are the ambiguous fields. It does not explain note/email/shippingAddress behavior (e.g., nulling a note), so it is strong but not complete.

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 + resource ('Update order note, email, shipping address and tags') and even names the underlying action (orderUpdate). An agent can distinguish it from siblings like shopify_update_product or shopify_update_customer without opening any 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?

Provides useful operating context (dryRun defaults to true; 'Requires write_orders') and preference guidance among tag modes ('Prefer addTags or removeTags' implied via replaceTags warning), but never states when to choose this tool over an alternative or when it should not be used. Usage is implied rather than prescribed.

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 flag destructiveHint=true and idempotentHint=false, and the description substantially adds to that: exact-match SKU resolution vs Shopify's prefix search, duplicate/conflict rejection before any write, ambiguous-SKU skipping, read-back verification, per-item outcome and store status vocabularies, and result trimming that never drops non-applied items. This is unusually rich 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?

One dense paragraph that front-loads the verb, resource, and scope before the resolution/validation/verification mechanics. Nearly every sentence carries operational value, though the outcome-status enumeration is somewhat heavyweight.

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 exists, yet the description explains return values (per-item outcome, store status, trimming guarantees), edge cases (shared SKUs, conflicting duplicates), and safety (dryRun default). An agent has everything needed to call and interpret 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 coverage is 80%, already documenting store, stores, dryRun, and allowDuplicates. The description reinforces the store/stores duality, the dryRun-default behavior, and the duplicate-SKU semantics, adding meaning beyond raw field names though not new syntax.

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 (set) and resources (price, compareAtPrice, unitCost) for a precise scope (up to 250 SKUs, one store or several in parallel), distinguishing it from sibling update_product. An agent can identify the operation and its granularity 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?

Gives clear context for when to use it: bulk SKU-level price updates, store vs stores for parallel multi-store writes, and dryRun defaulted on. It does not name a specific alternative (e.g., shopify_update_product) for single-product edits, so it stops short of explicit when-not 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 flag destructiveHint and openWorldHint, but the description adds real consequence detail: dryRun previews by default and returns before/after on apply, and a status of ARCHIVED/DRAFT removes the product from every sales channel. It adds meaningful context but omits auth/permission and rate-limit 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?

Front-loaded with the core purpose, then compact sentences for dryRun, tag semantics, and status side effects. Every sentence carries information, though the tag explanation is slightly dense.

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 14-parameter mutation with no output schema, the description covers the highest-stakes behaviors (preview workflow, tag add/remove/replace, status effects) and return values. The remaining gap is the many field parameters that get no semantic explanation.

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 29% schema description coverage, the description must carry more weight, and it only clarifies dryRun, the three tag parameters, and status. Many of the 14 parameters (id, store, images, vendor, variants, productType, descriptionHtml, removeMediaIds) are left to the schema with no added meaning.

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

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

States a specific verb (Update) and resource (product) plus the surface scope: fields, variants, media, tags. This clearly separates it from the sibling shopify_create_product and the other update_* tools without needing to open a 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?

Gives clear operational context: dryRun defaults to true for a preview and must be set false only after the user authorizes the exact change. It does not name alternative tools or explicit when-not-to-use conditions, so it stops short of full 5-level 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 declare destructive/openWorld/non-idempotent, and the description adds real value beyond them: that the call blocks and waits for processing before returning a CDN URL, and that the default dryRun:true sends nothing to Shopify. It doesn't cover failure/timeout behavior during the wait.

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, front-loaded with purpose then the critical dryRun default. Nothing is wasted, and the safety-relevant default is called out prominently.

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 exists, so stating the return value (CDN URL) and the follow-up retrieval path is valuable. Combined with annotations covering the mutation profile, the definition is nearly complete, though the low parameter coverage and unspecified imageFile/sourceUrl exclusivity leave a small 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 only 17%, so the description must compensate. It clarifies the imageFile-vs-sourceUrl choice and the dryRun default, but says nothing about alt, filename, or store semantics, leaving several parameters 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?

States a specific verb (upload), resource (image file or HTTPS image), destination (Shopify Files), and outcome (waits for processing, returns CDN URL). It also names shopify_get's uploaded_image resource as the follow-up path, making it distinguishable from other mutation 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?

Explains the operating mode clearly: dryRun defaults to true and previews without sending anything, and points to shopify_get for later verification. It does not, however, state when to prefer imageFile over sourceUrl, or any preconditions beyond the schema's own dryRun note.

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

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

Annotations already cover readOnlyHint, idempotentHint, destructiveHint, and openWorldHint, so the safety profile is fully declared. The description adds that validation is performed against 'this store's API version' and that operations are not executed, which adds useful context. However, it doesn't describe the response shape, error behavior, or rate limits.

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

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

One sentence, front-loaded, zero waste. States the verb, resource, constraint, and non-execution guarantee in the minimum words needed.

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?

Annotations cover the safety profile and the description covers the non-execution guarantee, but with 0% schema coverage, no output schema, and no guidance on the codeblocks structure or store reference, the definition leaves the agent without the information needed to construct a correct call.

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 both parameters (store, codeblocks) are undocumented in both schema and description. The nested codeblocks object's fields (content, revision, artifactId) are also unexplained. The description only obliquely references 'operations' without clarifying the codeblock structure's role.

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 (validate) and resource (Admin GraphQL operations) with the key distinguishing property of not executing. Distinguishes from siblings like shopify_graphql_query and shopify_graphql_mutation, though it doesn't name them explicitly. Sibling differentiation is implied by the 'without executing' clause.

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

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

No explicit when-to-use guidance, no alternatives named, no conditions described. The 'without executing them' clause hints at the use case but doesn't state when an agent should choose this over shopify_graphql_query or shopify_graphql_schema.

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