firestarter_seller_orders

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's 'Read-only: never changes anything' is redundant but harmless. It adds value by disclosing that each order line carries the order_id used in confirm/ship and that the tool covers Shopify orders, expanding beyond the annotation's generic read-only flag.

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 about three sentences long and front-loads the core purpose and fields. It includes the fulfillment flow, usage triggers, and a read-only note without fluff. Each sentence earns its place, though the flow description could be seen as slightly beyond the minimal scope.

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 to rely on, the description covers what fields are returned, how to use the result (order_id for follow-ups), the coverage of Shopify, and reinforces the read-only nature. For a zero-parameter list tool, this is sufficient for an agent to call it correctly and understand its role in the larger workflow.

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?

The input schema is empty (0 parameters), so there is nothing to explain. Per the rubric, 0 params gets a baseline of 4. The description adds no parameter details because none exist; it focuses on output and usage, which 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?

The description states a specific verb and resource: 'View the seller's incoming orders' and enumerates the exact fields returned (product, quantity, amount, net payout, order status, payout status, carrier tracking). It also implicitly distinguishes itself from siblings by positioning itself at the start of the fulfillment flow, which is unique in the large sibling list.

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?

It explicitly says when to use this tool: 'Use whenever a seller asks about their orders, sales, what sold, or recent activity.' It also maps the flow to the two follow-up tools (confirm_order and ship_order) and notes it covers Shopify orders, giving the agent clear routing guidance without needing to open other tool schemas.

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