list_orders

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

readOnlyHint=true already tells the agent this is a safe read, so the description's extra value is the default ordering (newest first) and the filter semantics. It says nothing about result volume, paging behavior, or what happens when a broad filter matches thousands of orders, which matters for a list endpoint defaulting to limit 20.

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?

Two dense sentences with the resource and ordering front-loaded and no filler. The parenthetical enumerations make it long-ish but every clause carries usable information.

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?

Return shape is covered by the output schema and safety by annotations, so the remaining burden is filter and paging semantics. The filtering is well covered, but with five parameters and a default page size of 20, the absence of any paging guidance leaves a real gap for an agent that will likely need more than one page.

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 coverage is 0%, so the description must carry parameter meaning and it partly does: it enumerates the eight status values (the schema has no enum) and explains that customer accepts an id, email, or name. However it never maps its "date range" wording to the actual after/before parameters and completely omits limit, leaving pagination semantics undocumented.

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?

"Recent orders, newest first" names the resource and the sort order in one clause, which clearly distinguishes this from get_order. It never names the sibling it defers to, but the list-vs-single distinction is obvious from the wording.

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 filter clauses imply when the tool is useful (browse recent orders, narrow by status/date/customer), but there is no explicit when-to-use/when-not or pointer to get_order for a known id. Usage is inferred rather than guided.

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