browse_orders

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

With no annotations provided, the description must carry the behavioral burden. It accurately signals read-only retrieval and highlights that order_id returns detailed single-order information. However, it does not disclose pagination, default limit behavior, list-mode return shape, or how filters interact.

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 sentences front-load the core purpose, then compactly list filtering capabilities and the special order_id behavior. There is no meaningful filler; 'powerful filtering options' is slightly promotional but does not harm clarity.

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 tool with 11 parameters and no annotations or output schema, the description provides a useful overview but is incomplete. It does not explain list-mode return structure, pagination, default limit, sort behavior, or whether filters combine additively, so an agent would still need to infer several execution 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 100%, so the schema already documents all 11 parameters; the baseline is 3. The description adds slight value by grouping filters and connecting order_id to detailed output, but it mostly restates schema information rather than deepening it.

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 first sentence uses a specific verb ('retrieves') and resource ('Shopify orders'), clearly distinguishing this from sibling tools like browse_products and browse_customers. The final sentence adds a distinct single-order mode via order_id, making the tool's dual behavior explicit.

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 description implies use for order retrieval and filtering, and it enumerates filter categories, but it does not explicitly say when to choose this over query_shopify, browse_customers, or other siblings. There are no exclusions or alternative routing cues beyond the word 'orders'.

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