wafle_checkout_orders_list

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds value by describing the checkout pipeline state flow (cart→MP/Stripe/transfer→paid) and the filtering capabilities. This goes beyond the structured metadata without contradicting 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 two sentences, with the primary purpose front-loaded. It efficiently conveys the resource, the pipeline, the key filters, and the alternative legacy tool without any fluff or 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 read-only list tool with annotations and a schema that already covers defaults and parameter descriptions for several fields, the description provides adequate context: the pipeline, key filters, and a critical alternative. It does not explain response shape or pagination behavior, but these are less critical given the readOnly and idempotent hints and the schema's limits.

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 43%, so the description should compensate. It explicitly mentions status, since, and email as filters, and the slug/store context, but does not provide semantics for limit, offset, or until. The description adds some meaning to the status filter and the since format, but the gaps in parameter documentation remain.

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 orders from the wafle_orders table for a store,' naming the specific verb and resource. It also distinguishes itself from the sibling `wafle_orders_list` by explicitly noting the different table and legacy WC 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?

It provides explicit guidance to use `wafle_orders_list` for legacy WC orders, creating a clear exclusion. It also mentions the filterable dimensions (status, since, email) and the new checkout pipeline, implying when this tool is appropriate. It lacks explicit 'use this when' phrasing, but the alternative direction is clear.

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