ht_list_orders

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

The annotations already declare readOnlyHint=true and openWorldHint=true, so the description is not burdened with the safety profile. It still adds genuinely useful context: that results merge online orders with loyalty-card in-store receipts, and which fields come back (date, total, status, item UPCs). It says nothing about pagination limits or how large result sets behave, 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?

A single sentence that front-loads the action and scope, then lists the returned fields compactly. No filler, no redundancy with the title.

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 no output schema, the description usefully enumerates the returned fields, which is the most important thing an agent needs here. It leaves pagination behavior and the default 365-day window to the schema, which is acceptable, though a word on paging would make it fully self-sufficient for a list tool.

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?

The description mentions no parameters at all — not the date range, page, pageSize, or view mode — so it adds nothing beyond the schema. With coverage at 60%, the schema documents startDate/endDate and view but leaves page and pageSize bare, and the description does not compensate for that gap.

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 names a specific verb (List) and resource (past Harris Teeter purchases), then enumerates the two data sources it spans: online orders and in-store receipts on the loyalty card. The word 'past' cleanly separates it from the ht_list_upcoming_orders sibling without needing to name it.

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 word 'past' implies the usage context (historical transactions vs. upcoming orders), which the reader can infer against the sibling list. However, there is no explicit when-to-use/when-not-to-use statement, no mention of the sibling that handles upcoming orders, and no prerequisites called out.

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