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

The annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety is covered. The description then adds genuinely useful behavior beyond that: newest-first default ordering, AND semantics for combined filters, and the pagination loop via limit/offset/next_offset. It does not cover rate limits or result-size expectations for a 19-parameter query, so it adds value but not richly.

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?

Three dense sentences with no filler, front-loading the core scope before the filtering and paging mechanics. The trailing 'GET /orders' endpoint anchor is compact and useful for API-aware agents rather than padding.

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 19-parameter read with no output schema and no required fields, the description supplies the essentials an agent needs: default ordering, AND filter combination, date-range preference, and the offset/next_offset paging contract. It leaves the shape of returned records and result-size limits implicit, but the embedded-data list covers most of what a caller must know before invoking.

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 79%, essentially at the threshold where the schema carries the parameters (limit 1-100, offset/next_offset, date boundary semantics, sort defaults). The description adds only the paging loop pattern (limit, offset, next_offset) and a soft nudge toward a date range; it does not clarify the many name-matching or folder_name-vs-folder_id filters. Baseline 3 is appropriate.

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 ('Search orders') and enumerates what comes back (items, addresses, totals, payment, shipments), which differentiates it from the narrow siblings list_order_items and list_order_shipments. It stops short of explicitly naming those siblings or contrasting itself with get_order, so an agent must infer the boundary between the bulk list and the single-order fetch.

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 concrete operating guidance: 'Filters combine with AND' and 'Prefer a date range: Order Desk asks clients to avoid open-ended queries.' That is real when/how guidance with a stated rationale. It never states when NOT to use this tool or points at an alternative sibling, which keeps it at 4 rather than 5.

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