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

Annotations already cover readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is handled. The description adds genuine context beyond that: results are newest-first, unshipped-only by default, and it requires a Cotlet API key with access to this app. It does not mention pagination or result caps, which is the remaining gap.

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 first sentence ('Orders from your Merch Orders page with items, buyer and shipping address') is largely subsumed by the second ('Lists physical orders from your Merch Orders page, newest first, with the items bought, the buyer, the shipping address...'), so a full sentence is spent restating. The remaining sentences are information-dense and front-loaded, but the duplication costs it.

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 no output schema, the description covers what comes back (items, buyer, address, shipped state), the default sort and filter, the search keys, the auth requirement, and the downstream tools that consume order_id. Only pagination/result-limit behavior is left unaddressed.

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 100%, so since/until/search/unshipped_only are already documented in the schema, including their defaults. The description restates the search semantics and the unshipped-only default but adds no date-format or range syntax beyond the schema. The 3-baseline is correct when the schema carries the parameter burden.

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 (list physical merch orders) plus what each row contains (items, buyer, shipping address, shipped flag). The word 'physical' separates it from bandcamp_list_sales, and the description explicitly names the sibling tools it feeds into (mark_order_shipped, refund_merch_order).

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?

Gives clear operational context: default is unshipped-only, default window is implied, search accepts email/last name/payment ID, and order_id is passed on to mark_order_shipped or refund_merch_order. It never states when NOT to use it (e.g., versus bandcamp_list_sales or bandcamp_export_sales_report), so it stops short of full when/when-not routing.

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