Search Orders

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered; the description goes further by disclosing error codes (400 empty phrase, 401 bad keys, 429 rate limit) and pagination behavior via the has_more flag. The rate-limit and empty-input failure modes are exactly the kind of operational context an agent cannot get from annotations or schema.

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 description is front-loaded with the core purpose and then cleanly sectioned into When to use, Parameters, Returns, and Errors, which is easy to scan. The parameter list largely duplicates the schema and is the one section that does not fully earn its space, but overall there is little wasted prose.

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 four-parameter search tool with an output schema already defined, the description covers the missing pieces an agent needs: what is searched, partial matching, pagination signal, and failure modes. Nothing material for a correct invocation is left undisclosed.

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 all four parameters are already documented with defaults, bounds, and an enum for response_format. The description's parameter block restates the same defaults and max 250 rather than adding new meaning such as matching semantics, phrase length behavior, or how limit interacts with has_more; baseline 3 applies.

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 and resource ("Search orders in StarShipIt") and immediately scopes the search to a free-text phrase across order numbers, references, recipient names, and tracking numbers. The line "Use when you need to find a specific order but don't have the exact order_id" implicitly separates it from get_order and the many list_* siblings, so an agent can route correctly without opening the 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?

There is an explicit "When to use" block with the selecting condition (no exact order_id) plus the note that partial matches are supported. It stops short of naming the alternative tools (e.g. starshipit_get_order for exact IDs, or the status-scoped list_* tools), so the agent must infer the exclusions rather than being told them.

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