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

No annotations exist, so the description should disclose behavioral traits. It only states purpose, not whether it's read-only, performance implications, or side effects. As a data retrieval tool, it likely has no destructive behavior, but this is not stated.

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?

Extremely concise with one sentence and no redundancy. However, it lacks structure such as separate sections or bullet points, but given the brevity, it is efficient.

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 4 parameters, no output schema, and no annotations, the description is too minimal. It does not explain what 'coverage summary' means, what the output contains, or how to effectively use parameters like query and limit.

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%, with 4 parameters (dateFrom, dateTo, query, limit) lacking schema descriptions. The description adds no meaning to any parameter, failing to compensate for the lack of schema documentation.

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

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

The description states it provides a 'coverage summary' for source, landing page, and UTM attribution data, which is a specific resource and action. However, 'coverage' is somewhat vague, and the tool name repeats the noun phrase, but overall it distinguishes from sibling sales-focused tools.

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

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

No guidance on when to use this tool versus alternatives. Siblings include many attribution and landing page tools, but the description offers no context for selection.

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

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

With no annotations provided, the description carries the full burden. It discloses the output includes total orders, total spent, and products/quantities, indicating it is a read-only operation. However, it does not mention any potential costs, rate limits, or data freshness.

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

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

The description is a single sentence, which is concise, but it may be too brief. It front-loads the key information but omits important details like parameter semantics and usage context.

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 has 3 parameters with 0% schema coverage, no output schema, and no annotations, the description is insufficient. It does not provide enough context for an AI agent to correctly select and invoke the tool, especially considering the variety of sibling tools.

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 add meaning. It does not explain the parameters 'customerId', 'email', or 'limit' beyond their names. For instance, it is unclear whether both customerId and email are needed or are alternatives, and what the limit parameter controls (e.g., number of products or orders?).

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 it provides a purchase summary for one customer, including total orders, total spent, and products with quantities. This distinguishes it from sibling tools like shopify_list_customers (which lists customers) and shopify_top_customers (which ranks high-value customers).

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

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

The description implies the tool is for retrieving a purchase summary for a single customer, but it does not explicitly state when to use it versus alternatives like shopify_sales_by_customer_product or shopify_top_customers. No guidance on prerequisites or when not to use.

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?

No annotations provided, so the description must fully disclose behavior. It only states outputs but does not mention read-only nature, sorting logic, or any constraints beyond the date range. The tool likely aggregates data but this is not confirmed.

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 extremely concise (12 words) and front-loaded with the key outputs. However, it lacks structure like bullet points or sections. For such a short text, this is acceptable but not optimal.

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 has 4 parameters, no output schema, and many siblings, the description omits critical details like return format, sorting of top codes, and what 'discount totals' specifically means (e.g., count vs amount). The agent may need to experiment to understand usage.

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

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

Schema description coverage is 0%, meaning the description does not explain any parameter. It only implies dateFrom/dateTo are for the range, but schema already shows date-time type. The 'query' and 'limit' parameters are entirely unexplained, leaving the agent to guess their purpose.

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 provides discount totals, discounted order rate, and top discount codes, specifying the output. It distinguishes from sibling tools which focus on other aspects like sales or customers. However, it lacks a verb-+resource structure, reducing clarity slightly.

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

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

No guidance on when to use this tool vs alternatives like shopify_sales_overview. Implicitly it's for discount analysis with dates, but no exclusions or prerequisite conditions 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?

No annotations are present, so the description must carry the full behavioral burden. It only mentions windows but does not define 'inactivity', describe the output format (e.g., list vs. counts), or disclose whether calls are destructive or read-only. Limits or default behavior are not explained.

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

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

The description is a single sentence with no extraneous words, but it sacrifices necessary detail for brevity. It is concise but lacks completeness.

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 no output schema, no annotations, and zero schema coverage, the description is critically incomplete. It does not explain what the summary contains, how inactivity is defined, or how parameters affect results. The agent cannot fully understand tool behavior.

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. However, it does not mention either parameter ('asOfDate' or 'limit') or explain their meaning or usage. The agent gains no additional understanding from the 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?

The description states 'Customer inactivity summary' which implies a summary resource but lacks a clear verb. It specifies fixed windows (30/60/90/180 days), giving some context, but does not clarify whether it returns counts or lists. It also fails to distinguish from siblings like 'shopify_customer_purchase_summary' or 'shopify_repeat_purchase_windows'.

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

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

No guidance is provided on when to use this tool versus alternatives such as 'shopify_list_customers' or 'shopify_retention_overview'. No context on prerequisites or scenarios is 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?

With no annotations provided, the description must carry the full burden of behavioral disclosure, but it only hints at a specific counting method for new customers. There is no mention of whether the operation is read-only, what data is returned, pagination behavior, or any side effects. The description is insufficient to understand the tool's behavior.

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

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

The description is a single short phrase, which is concise but lacks structure: no sentences, no clear subject-verb-object. It is minimally acceptable but could be improved with a proper sentence.

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

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

Given the tool has 5 parameters, no output schema, and no annotations, the description is far too brief. It does not explain the output format, pagination, or the meaning of 'accurately counted new customers'. The tool's functionality is under-specified for an agent to use 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?

The schema has 0% description coverage for its 5 parameters, and the tool description adds no additional meaning beyond the parameter names and types. For example, 'query' and 'limit' are not explained. The description mentions the sortable metrics (netSales, orders, newCustomers) but does not clarify their usage or how the query parameter works.

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

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

The description states the output concerns 'landing-page performance by sales, orders, and accurately counted new customers', which broadly indicates the tool's focus. However, it lacks a verb (e.g., 'get' or 'list') to clearly express the action performed, and the phrase 'by' is ambiguous as to whether it filters or groups results. The purpose is somewhat clear but not actionable or precise.

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

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

The description provides no guidance on when to use this tool versus the many sibling tools (e.g., shopify_sales_by_source, shopify_attribution_quality_summary). There is no mention of context, prerequisites, or alternatives, leaving the agent to guess when this tool 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?

The description states the tool is read-only, which is a key behavioral trait. However, it does not mention pagination behavior despite the 'limit' parameter, nor does it disclose potential rate limits or response structure. With no annotations provided, the description carries the full burden but only partially addresses it.

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

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

The description is a single sentence that is clear and concise. No extraneous words. However, it could be slightly more structured by separating the read-only indication from the list of included fields. Still, it earns its place with efficiency.

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

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

Given the lack of output schema, the description lists some return fields (orders count, amount spent) but omits other common details like pagination, total count, or default behavior. The tool is relatively simple with only two parameters, so the description is minimally adequate but not comprehensive.

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% (only 'query' has a description), and the tool description adds no parameter information beyond the schema. The 'limit' parameter lacks any explanation in either the schema or the description, and the description does not clarify how the parameters interact (e.g., pagination with query filtering).

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 it lists customers and includes orders count and amount spent. The verb 'list' and resource 'customers' are specific, and the read-only designation is helpful. However, it does not differentiate from sibling tools like shopify_customer_purchase_summary or shopify_inactive_customer_summary, which could cause ambiguity for an AI agent deciding which tool to use.

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

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

The description implies the tool is for listing customers, but it provides no explicit guidance on when to use it versus alternatives. Siblings include other customer-related tools (e.g., shopify_top_customers, shopify_customer_purchase_summary), and no when-not-to-use or alternative tool suggestions are given. The usage is implied but not clearly directed.

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?

With no annotations provided, the description carries the full burden. It discloses 'read-only' behavior but omits other critical traits such as pagination, sorting defaults, rate limits, or error handling. This is insufficient for a mutation-free list operation with multiple filter parameters.

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

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

A single sentence that is concise and direct, front-loading the main action and output. Although very brief, it avoids fluff and redundant information. Slightly more structure (e.g., bullet points for parameters) would improve scannability but not essential.

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 list tool with no output schema, the description covers the core purpose and read-only nature. However, it lacks details on pagination, sorting, or intended use cases. Given the complexity (4 optional parameters) and sibling list tools, more contextual cues (e.g., batch retrieving orders) would be beneficial.

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% (query parameter has description). The tool description does not add meaning to any parameters; it only mentions output fields. For a tool with 4 parameters, this is a significant gap, especially for createdAfter/createdBefore (date-time format) and limit (default/max).

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 action ('List'), the resource ('Shopify orders'), and the scope ('read-only'), along with output fields (customer, amount, line items). This distinguishes it from sibling tools that are analytical summaries, establishing a specific verb+resource pattern.

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

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

No guidance is provided on when to use this tool versus alternatives. For example, there is no mention of when to use list_orders over list_customers or any of the analytical tools. The description does not specify use cases, prerequisites, or exclusions.

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

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

The description notes 'read-only,' which is a key behavioral trait. However, with no annotations provided, the description should also mention aspects like pagination, sorting, or data freshness, which are absent.

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 short sentence that front-loads the purpose and key return fields. Every word earns its place; no redundancy.

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

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

For a simple list tool, the description conveys the core functionality and return data. However, it omits details on pagination, sort order, and how the query parameter works, which are necessary for an agent to use the tool correctly without additional trial and error.

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% (only query described). The tool description does not add any meaning to parameters beyond what is in the schema, e.g., it doesn't explain that 'limit' controls page size or how 'query' filters products.

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 'List Shopify products (read-only)' and specifies the returned fields (variants, SKU, price, inventory quantity). This distinctively differentiates it from sibling tools like shopify_list_customers or shopify_list_orders.

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

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

No guidance on when to use this tool vs alternatives (e.g., shopify_top_products). The description does not mention any prerequisites, filters, or limitations that help an agent decide to use this tool.

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?

With no annotations, the description carries full burden for behavioral disclosure. It does not explain what defines 'new customers', how grouping aggregates data, or any side effects. This is insufficient for a mutation-like aggregation 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?

The description is very short (one sentence), which is concise but at the cost of missing critical information. It could be expanded without becoming verbose.

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 no output schema, five parameters, and no annotations, the description is severely incomplete. It fails to explain output format, parameter details, or edge cases.

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% (no parameter meanings provided). The description only hints at the 'groupBy' enum values but does not clarify the required date range or optional query and limit 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 clearly states the tool groups new customers by source, UTM campaign, or landing page. It uses a specific verb and resource, and implicitly differentiates from sibling tools like 'shopify_sales_by_source' or 'shopify_list_customers'.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, context, or exclusions.

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

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

With no annotations, the description carries full burden. It only states the high-level purpose without disclosing behavioral traits such as how rates are calculated, required permissions, or edge cases. This is a significant gap.

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

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

The description is a single, efficient sentence with no wasted words. However, the brevity contributes to incompleteness in other dimensions.

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 complexity (4 parameters, no output schema, no annotations) and many sibling tools, the description is too sparse. It does not explain output structure, window semantics, or how the tool differs from related tools.

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%, yet the description adds no semantic information about parameters like dateFrom, dateTo, asOfDate, or limit. The agent must infer meaning solely from property names and constraints.

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 computes repeat purchase rates for fixed 30/60/90/180-day windows. It identifies the specific verb and resource, but does not explicitly differentiate from sibling tools like shopify_time_to_second_order.

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

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

No guidance on when to use this tool versus alternatives. There is no mention of prerequisites, limitations, or exclusion criteria, leaving the agent without decision support.

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?

With no annotations, the description carries full burden but only mentions retrieval of KPIs, omitting important traits like read-only nature, output format, or any side effects.

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

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

The description is a single sentence, which is concise but under-specified. It lacks structure that would help an agent efficiently parse key 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 the complexity (4 parameters, no output schema, no annotations), the description is incomplete. It does not explain return values or how the cohort window relates to parameters.

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 description does not explain any parameters despite 0% schema description coverage. Parameters like dateFrom, dateTo, asOfDate, and limit are left completely undefined.

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 it returns retention KPIs for customers whose first order falls within a cohort window, effectively conveying the purpose and distinguishing it from sibling tools like time_to_second_order.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of use cases, prerequisites, or when not to use it.

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

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

No annotations provided, and the description does not disclose any behavioral traits such as whether it is read-only, performance characteristics, or side effects. The minimal phrase 'aggregate orders' implies a safe read operation but lacks explicit confirmation.

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 very concise at one sentence, but it under-specifies the tool's functionality. Conciseness should not come at the cost of missing essential details.

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, no annotations, and only a vague purpose statement. The tool requires four parameters without any guidance on output format, aggregation keys, or pagination, making it incomplete for an agent to use 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%, and the tool description provides no explanation for any of the four parameters (limit, query, createdAfter, createdBefore). The agent must guess their purpose and constraints.

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 it aggregates orders to answer who bought what and how much, indicating a per-customer-per-product aggregation. This distinguishes it from sibling tools like list_orders or top_products, though it could be more explicit about the grouping dimensions.

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

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

No guidance on when to use this tool versus alternatives. It does not mention scenarios, prerequisites, or exclusions, leaving the agent to infer usage from the name alone.

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?

No annotations exist, and the description only states the basic function. It does not disclose aggregation details, data freshness, pagination behavior, or how 'normalized' is defined.

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

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

The description is a single concise sentence, but it sacrifices critical information for brevity. While front-loaded, it under-specifies the tool's capabilities and requirements.

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 four parameters, the description is far too minimal. It lacks return format details, parameter explanations, and behavioral context, making it incomplete for reliable tool selection.

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%, yet the description provides no explanation for the parameters (dateFrom, dateTo, query, limit). The agent must rely solely on parameter names, which is insufficient for correct usage.

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 returns sales data grouped by source or referrer, but it does not differentiate from sibling tools like shopify_sales_by_utm or shopify_sales_overview, which also provide sales breakdowns.

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

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

No guidance is provided on when to use this tool vs. alternatives or when to avoid it. There is no mention of prerequisites, use cases, or exclusion criteria.

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?

No annotations exist. The description does not disclose whether the operation is read-only, destructive, or any rate limits/authentication requirements. Only a high-level function is given.

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?

Single sentence, no redundancy. However, could be improved by adding a brief list of grouping options without excessive length.

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 5 parameters, 2 required, and no output schema, the description is insufficient. It doesn't specify what 'Sales' measures (revenue, count?), how date range works, or the output format. An agent would need to infer or experiment.

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 0% schema description coverage, the description adds no meaning to any of the 5 parameters. The input schema has enums and defaults but the description doesn't explain what 'query' filters or how 'limit' behaves.

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 it returns sales grouped by UTM dimensions (source, medium, campaign). It implicitly differentiates from siblings like shopify_sales_by_source and shopify_sales_overview by specifying the grouping dimension.

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

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

No guidance on when to use this tool versus alternatives like shopify_sales_by_source or shopify_attribution_quality_summary. No mention of prerequisites or when not to use.

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?

No annotations provided, so the description carries full burden. It only states the tool returns 'Sales KPIs' without disclosing whether it's read-only, any authentication needs, rate limits, or data freshness. Insufficient for a tool with 5 parameters.

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

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

The description is a single concise sentence that front-loads the core purpose. However, it is slightly too brief given the tool's complexity, missing opportunities to add value without significant bloat.

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?

Without an output schema, the description should explain what KPIs are returned (e.g., total sales, order count, AOV). It does not. With 5 parameters and 0% schema description coverage, key contextual information is missing, making it difficult for an AI agent to invoke 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%, meaning parameters like 'query' and 'limit' are not explained in the description or schema. The tool description adds no meaning beyond the schema field names and types, leaving agents uncertain about how to use 'query' (e.g., filter syntax) or the exact meaning of 'comparePreviousPeriod'.

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 retrieves 'Sales KPIs for a date range' with optional period comparison, distinguishing it from sibling tools like shopify_sales_timeseries which focus on trends.

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

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

No guidance on when to use this tool versus other sales analysis tools (e.g., shopify_sales_timeseries, shopify_sales_by_source). The only hint is the comparePreviousPeriod option, but no explicit when/when-not advice.

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?

With no annotations, the description should disclose behavioral traits like read-only nature, data scope, or performance considerations. It only states the grouping interval, missing critical context.

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

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

The description is very short (6 words), which is concise but lacks structure. It earns its place as a minimal statement but omits necessary details.

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 6 parameters, no output schema, and no annotations, the description is severely inadequate. It fails to explain what the time series contains (e.g., revenue, count), optional parameters, or output format.

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

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

Schema description coverage is 0%, and the description adds no meaning to any of the six parameters. The mention of grouping intervals hints at the 'interval' parameter but does not explicitly inform about dateFrom, dateTo, query, limit, or comparePreviousPeriod.

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 provides a sales time series grouped by day, week, or month, distinguishing it from sibling tools that focus on specific aspects like attribution or discounts.

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

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

No guidance on when to use this tool versus alternatives such as shopify_sales_overview or shopify_sales_by_source; the description merely implies usage for time-based grouping.

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?

No annotations are provided, so the description carries full burden. It does not disclose behavioral traits such as whether the tool includes customers without a second order, how date range filters apply, or if data is real-time. The description is too minimal for transparency.

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

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

The description is a single sentence, front-loaded with the core functionality. It is concise but likely too terse given the missing parameter and behavioral details.

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?

Without an output schema, annotations, or parameter descriptions, the description is incomplete. It does not explain the output format, edge cases, or default behavior, making it difficult for agents to use 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%, meaning the input schema provides no parameter descriptions. The tool description does not explain the meaning or formats of the parameters (dateFrom, dateTo, asOfDate, limit), leaving agents to guess from names only.

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 that the tool provides distribution and summary statistics for days between first and second order. The verb is implied, and the resource is specific. However, it does not differentiate from the sibling tool 'shopify_repeat_purchase_windows' which might have overlapping functionality.

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

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

No guidance is provided on when to use this tool versus alternatives. The description lacks context about prerequisites, typical use cases, or situations where this tool is preferred.

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?

With no annotations, the description bears the burden of behavioral disclosure. It mentions the customerType filter but does not explain that date range is required, that the output is a list, or any other behaviors. It provides minimal context beyond the schematic defaults.

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

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

The description is a single, concise sentence of 12 words, which is efficient. However, it lacks structure such as bullet points or sections that could improve readability for an agent.

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 absence of an output schema and 0% parameter coverage, the description is incomplete. It does not explain return values, the role of the query parameter, or the effect of limit, leaving an agent without sufficient context for correct invocation.

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 description only mentions the customerType parameter indirectly ('optional new/returning filter'). With 0% schema description coverage, the description should document other parameters like sortBy, limit, and query, but it does not add meaning beyond the schema.

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

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

The description clearly states the tool returns top customers sorted by sales or volume, with an optional filter for new/returning customers. This distinguishes it from sibling tools like shopify_list_customers or shopify_customer_purchase_summary by focusing on ranking by performance metrics.

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 guidance on when to use or alternatives is provided. However, the purpose is clear enough that an agent can infer it should be used when needing a ranked list of top customers by sales/volume, though comparative context with siblings is missing.

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?

No annotations are provided, so the description is the sole source for behavioral disclosure. It does not mention whether the operation is read-only, whether results are paginated, or how missing data is handled. The description only restates the tool's obvious purpose.

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

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

The description is a single sentence, which is concise, but it lacks structure. It does not front-load key information like required parameters or usage context. It could be improved with bullet points or clearer phrasing.

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 6 parameters, no output schema, and many siblings, the description is insufficient. It does not specify the return format, how grouping by product vs variant affects results, or how the 'query' parameter works. The agent is left with many unknowns.

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

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

Schema description coverage is 0%, so the description must compensate. But it adds no explanation for any parameter: 'query' (free text search?), 'limit' (maximum results?), 'sortBy' (enum values are listed but not defined). The agent must infer meaning from names alone.

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

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

The description clearly states it returns top products or variants sorted by net sales, gross sales, units sold, or orders. This is a specific verb+resource combination. However, it lacks explicit distinction from sibling tools like shopify_sales_by_customer_product or shopify_sales_overview, so it's not a perfect 5.

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

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

The description provides no guidance on when to use this tool versus alternatives. With many sibling analytics tools, the agent gets no help selecting the appropriate one. No when-not or prerequisite info is given.

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