Summarize Orders Across Shopify Stores

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

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

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

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

Two sentences, both substantive. The first front-loads the tool's main function and covered dimensions; the second adds a crucial currency-scoping caveat. No filler.

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

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

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

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

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

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

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

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

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

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

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

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

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