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

The description goes well beyond the annotations (readOnlyHint, idempotentHint) by explaining the concrete outcomes: statuses (CREATED, RUNNING, COMPLETED, CANCELED, EXPIRED, FAILED), the pre-signed JSONL URL valid for 7 days on COMPLETED, and partialDataUrl/errorCode on FAILED. This adds valuable behavioral context that annotations do not capture, and it does not contradict the annotations.

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

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

The description is appropriately concise and well-organized: a one-line purpose, a status list with outcome behavior, and then a clearly labeled Args section. Every sentence adds value—no fluff. It could be slightly more compact (e.g., merging statuses and outcomes), but it is efficient and easy to scan.

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

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

For a polling tool with an output schema, the description covers all necessary operational details: the ID format, shop requirement, API version default, and what happens on completion and failure. The output schema handles specific return fields, so the description need not enumerate them. Combined with the annotations (read-only, idempotent), an agent has everything needed to call this tool correctly.

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

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

Schema description coverage is 0%, so the description must (and does) fully explain each parameter. It details the operation_id format (gid://shopify/BulkOperation/<numeric-id>), the shop parameter including when it is required (multiple stores configured), and the api_version override with the default value. This is far more informative than the schema's bare titles and 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?

The description opens with a specific verb and resource: 'Poll a bulk operation's status by ID.' It clearly distinguishes this from siblings like shopify_bulk_query (which presumably creates a bulk operation) and shopify_graphql_query by focusing on status polling. The purpose is unambiguous and leaves no room for misidentification.

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 states the tool's function and provides context on how to use it (e.g., passing an operation_id in the proper format). It doesn't explicitly say 'use this after starting a bulk operation' or 'when not to use it,' but the description of the operation_id and the existence of shopify_bulk_query as a sibling make the intended workflow clear. No exclusions are stated, but the context is strong enough for an agent to infer the appropriate use case.

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

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

Annotations provide readOnlyHint=true and openWorldHint=true, but the description significantly expands on behavioral details: async execution, background processing, JSONL output, restrictions (connection limits, depth limits, id requirement), and API version-specific concurrency limits. This goes well beyond the annotations, giving agents a full picture of what to expect.

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

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

The description is concise and well-structured, front-loading the core purpose and usage context. The restrictions are clearly bullet-listed, and the Args section is logically placed. No redundant sentences; every sentence adds value. Minor deduction for not being even more streamlined, but it's appropriately sized given the complexity.

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

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

Given the tool's complexity (async, multiple restrictions, API version nuances), the description covers all critical aspects: purpose, usage, restrictions, return type (BulkOperation ID), and how to proceed (poll). The output schema likely describes the return structure, so not detailing the response format is acceptable. Sibling tools are distinct and the description clearly differentiates them.

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

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

The input schema has 3 parameters with 0% description coverage; however, the description's 'Args' section provides meaningful context for each: 'query' is described as a read-only GraphQL document with a single root connection, 'shop' is clarified as a store alias or domain required when multiple stores are configured, and 'api_version' is noted as an override with a default. This adds value beyond the schema's type-only information, but could be even more explicit (e.g., format for query).

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

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

The description clearly states the tool's purpose: launching an async bulk export of a read-only GraphQL query. It distinguishes itself from siblings by specifying it is for large datasets where paginated queries become impractical and explicitly mentions polling with shopify_bulk_poll for results. The verb 'launch' and resource 'async bulk export of a read-only GraphQL query' are specific and non-ambiguous.

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

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

Provides explicit usage guidance: use when exporting datasets too large for paginated queries (>10k records or hundreds of pages). It also contrasts with 'normal' queries implicitly by referencing pagination alternatives. While it doesn't explicitly name shopify_graphql_query for smaller queries, the mention of 'paginated queries' serves as a clear alternative. Restrictions are thoroughly listed, aiding correct invocation.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is established. The description adds valuable behavioral context: precise cost points for each mode, a caution to use the full schema sparingly, and clarifications on parameter defaults and requirements. No contradiction with annotations, and it goes beyond what annotations alone tell the agent.

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 tightly structured: the purpose is front-loaded in the first sentence, followed by a compact cost/usage paragraph, then a clean 'Args:' block. Every sentence adds essential information—no filler, no repetition. The layout makes scanning effortless.

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, the description covers everything needed to call it correctly: mode selection, cost implications, parameter semantics, and references to the shop resolution tool. An output schema exists to handle return shapes. Combined with the annotations, nothing critical 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 description coverage is 0%, leaving the description to carry the full burden. It does this excellently: type_name is explained with a regex and examples, shop is tied to shopify_list_stores with a condition, and api_version is given a default and override instruction. Every parameter is fully documented beyond the raw schema, exceeding the baseline expected for low 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 states a specific verb ('introspect') and resource ('Shopify store's Admin GraphQL schema'), and clearly distinguishes two modes: fetching a single type vs the full catalog. This unambiguously separates it from siblings like shopify_graphql_query, which performs actual queries. No ambiguity remains.

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

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

Explicit guidance on when to pass type_name (cheap, ~50 points) vs omit it (expensive, ~800 points, 'use sparingly'). It also tells when shop is required and references shopify_list_stores. However, it doesn't explicitly name sibling tools as alternatives for other operations, so the when-not-to-use guidance is slightly implicit. Still, the cost/size guidance is strong.

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 readOnlyHint annotation, the description adds real behavioral detail: 'The query string is parsed and validated as read-only before transmission,' and mutation/subscription operations are rejected except for the narrow `bulkOperationCancel` exception. This meaningfully expands on what the annotations already declare without contradiction.

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

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

The description is front-loaded with purpose and structured into idiomatic patterns and per-argument details. It is somewhat long and repeats the bulk-query alternative twice, but the length earns its place because most content is call-critical rather than decorative.

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 an output schema present, the description does not need to explain returns. It covers the required query format, variables, shop selection, api versioning, pagination patterns, search usage, and the bulk export boundary. No essential call context appears missing.

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

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

Schema description coverage is 0%, but the description compensates by explaining each parameter: the GraphQL document shape and restrictions, the `variables` dict, the `shop` alias/domain requirements, and `api_version` default plus 'YYYY-MM' format. This turns a bare schema into usable guidance.

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 'Execute a read-only GraphQL query against a Shopify store's Admin API,' naming a specific verb, resource, and constraint. It then clarifies this is the 'Universal entry point for reading any data the token's scopes permit' and lists resource types, which distinguishes it from mutation and bulk 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?

It clearly says to use the tool for reading any data the token permits and explicitly warns that write mutations are rejected. It also provides an alternative: 'For datasets >10k records, use shopify_bulk_query instead,' so an agent knows when to switch tools.

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

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

Annotations already indicate readOnlyHint=true and openWorldHint=true, so the description's extra detail about the cached `name` field and the `refresh` bypass behavior adds meaningful transparency. The description also discloses that data is fetched once per process and cached, which helps the agent understand freshness semantics beyond what annotations convey.

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

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

The description is well-structured and front-loaded: it states the core purpose in the first sentence, then the return shape, usage guidance, and a single clearly documented parameter. Every sentence earns its place, and the Args section is minimal and scannable.

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

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

For a simple read-only listing tool with one optional parameter, the description is complete: it specifies the return fields, the caching behavior, the refresh condition, and the mapping use case. The output schema also exists, so the description does not need to over-explain return types, and no critical invocation detail 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?

Although schema description coverage is 0%, the description fully documents the single `refresh` parameter: 'If True, bypass the shop-name cache and re-fetch from Shopify' and explains when to use it. This compensates for the missing schema description and gives the agent actionable semantics.

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

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

The description opens with a specific verb and resource: 'List all Shopify stores configured for this agent.' It clearly explains the return shape and also gives a concrete use case, distinguishing this tool from the GraphQL and bulk-query siblings by emphasizing it returns the agent's configured store list, not API queries.

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: to match user intent to a configured store, including a concrete example. It also provides the conditional guidance that if only one store is configured, `shop` can be omitted. It does not explicitly exclude alternatives, but the usage context is clear enough.

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

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

Annotations already mark readOnlyHint, but the description adds substantial behavioral context: it specifies the cost bucket shared with GraphQL, returns `tableData.columns`, `tableData.rows`, and `parseErrors`, and explains the error behavior when parsing fails. This goes well beyond what the annotations declare, providing concrete operational expectations.

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 long but tightly organized: a one-line purpose, a syntax block, dataset/token listings, several examples, and a return-format note. Each section earns its place, and the most critical information is front-loaded. No fluff 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 tool with a complex query language, the description is remarkably complete. It covers the syntax, allowed datasets, time tokens, example usages, return structure, and error handling. It even notes the API version default. There is no obvious missing information an agent would need to call it correctly, and the presence of an output schema further reduces the need for return-type detail.

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 fully compensate. It does: it explains the `query` syntax in detail, clarifies `shop` as 'store alias or domain. Required when multiple stores are configured', and notes `api_version` overrides the default '2026-04'. This adds meaning far beyond the bare 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?

The first sentence states a specific verb ('Run'), resource ('ShopifyQL analytics query'), and target ('against a Shopify store'). The description also distinguishes it from siblings by positioning it as a reporting-language query, separate from GraphQL and bulk tools.

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

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

The description clearly explains the tool's domain ('analytics query', SQL-like reporting) and notes the required scope ('read_reports') and that it consumes the same cost bucket as GraphQL. However, it does not explicitly contrast with sibling tools (e.g., 'use this for analytics, use GraphQL for other queries'). The guidance is strong but not fully explicit about when to choose this over alternatives.

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