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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds a genuinely useful behavior beyond that: contact data is masked unless the caller is permitted, which explains why PII may be absent in results. It still omits pagination, detail-level effects, and result ordering.

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, which is good. But for a 19-parameter tool with nested objects and enums, this is under-specified rather than concise, leaving the bulk of the surface undocumented.

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 19 parameters, nested shopify_connection variants, six enums, no parameter descriptions and no output schema, the description should carry much more. It gives no information on filtering semantics, cursor paging, sort meaning, or what summary vs full detail returns.

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% across 19 parameters, so the schema names only cryptic keys like 'funnel', 'order_ref', 'shopify_connection' and 'detail' without explaining them. The description compensates almost not at all — only the masking sentence loosely maps to include_pii, and 'orders and subscriptions' only hints at the kind enum.

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 ('Read') and resources ('store orders and subscriptions'), which tells an agent this is a listing tool for two commerce entity types. It does not, however, explain how it differs from the sibling subscriptions_list or orders_get, leaving ambiguity about which entry point to choose.

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, when-not-to-use, or alternative-naming guidance, despite siblings (orders_get, subscriptions_list, sales_get) that overlap substantially. The only implicit signal is 'contacts masked unless permitted', which doesn't help an agent pick this tool over its neighbors.

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