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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description goes further by disclosing a negative output trait ('Label files are not returned') and a cost/weight trade-off versus the summary tool. It still doesn't describe pagination behavior or rate limits, keeping it short of a 5.

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, front-loaded with the core purpose before the alternative-tool pointer and the output caveat; virtually no filler. Slightly packed with clause-level detail, but every sentence earns its place.

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 carries the return-value burden and partially does so ('full order details', labels excluded, next_page pagination). It covers status scoping, filtering, sorting and paging adequately for a 7-parameter list tool, though it never sketches the response shape beyond 'full order details'.

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 71%, so most parameters are already documented in the schema (filter syntax, status default, page_size, page_number with next_page hint). The description restates the filter example and default status but adds nothing new for include, sort_column, or sort_direction. Baseline 3 for partial-coverage schemas 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+resource ('List full order details'), its scope constraint ('for one status'), and the underlying endpoint 'GET /api/orders (no id)' which separates it from starshipit_get_order. It also explicitly names the sibling it is heavier than, starshipit_orders_summary, so the agent can route without opening either schema.

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 an explicit alternative and the condition that selects it ('Heavier than the summary: use starshipit_orders_summary for overviews'), which is real routing guidance. It does not address the closely-named siblings starshipit_list_unshipped_orders / list_shipped_orders / list_printed_orders or starshipit_search_orders, though the 'one status' framing implicitly covers the former.

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