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

The description contributes real behavioral facts beyond the annotations: a 60-day date boundary, a five-page/500-order read ceiling, and the important caveat that payment and refund values reflect current state rather than period cash flow or attribution. But it frames the operation as 'read-only' while annotations declare readOnlyHint=false and destructiveHint=true, and it never says what the import persists or what side effect justifies the destructive flag. The 'use a stable operationId' hint gestures at idempotency that annotations already claim, without adding substance.

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?

Four short sentences with the core purpose and the hardest constraint (60-day window) front-loaded, and no filler. 'Finite' echoes the title, and the operationId instruction sits oddly between purpose and data-semantics sentences, but nothing is wasted.

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?

An output schema exists and the safety/limits are partly covered, so the description need not explain return values. Still, for a required-parameter-heavy, nested, state-changing import tool, it omits where imported results surface, how this relates to recover_stop/stop_store_orders, and the side effects that make it destructive.

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 50% schema description coverage, the description partially compensates: it tells the agent operationId must be stable and pins query.from/to to the last 60 days, which the schema does not enforce. It says nothing about work_id, request_key (the actual idempotency key), storeId provenance, or read_skills, leaving half the surface to the schema 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?

States a specific verb and resource ('Request a finite ... Shopify order report') plus hard scope boundaries (60-day window, max five pages and 500 orders). It does not distinguish itself from the many closely named siblings such as native.genads_store_order_request, native.genads_store_order_reporting, or native.genads_store_orders, so an agent must infer which one to call.

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 60-day window and row/page caps implicitly define when this call is valid, and the payments/refunds caveat implies the use case (order-level values, not cash flow). However, there is no explicit when-to-use vs when-to-use-an-alternative guidance against the adjacent store-order and reporting tools, and no prerequisites for storeId are named.

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