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

With no annotations provided, the description carries full burden and does an excellent job. It discloses that the tool returns no PII, is aggregate-only, optionally filtered by query, and executes against the live store. The 'PCD Level 2 personal-data reads are deferred' statement adds important data-handling 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 front-loaded with the core purpose and key constraints, then provides usage guidance and routing. It's slightly verbose (the routing line could be merged), but every sentence contributes meaningful info, avoiding fluff.

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

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

For a simple tool with two parameters and no output schema, the description is complete. It specifies the exact return (single number), the optional filtering behavior, the query syntax, and the safety guarantee of no PII. This fully equips an agent to decide when and how to invoke it.

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% (both parameters have descriptions), so baseline is 3. The description adds value by explaining the `query` parameter with concrete examples (e.g., 'accepts_marketing:true') and reasserts the companyId scope requirement, effectively enriching 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?

Clearly states it returns an aggregate Shopify customer count (a single number), explicitly differentiating from any tool that returns individual customer data. The description says 'never who they are' to underscore the aggregate-only scope, which distinguishes it from siblings like get_top_customers or list_shopify_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?

Provides explicit when-to-use ('Use when a person or agent needs how many customers exist') and when-not-to-use ('never who they are'), effectively communicating the tool's limitation. However, it does not name specific alternative tools for fetching customer details, so it falls slightly short of the top score.

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