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

Annotations already cover the read-only, non-destructive, open-world profile, so the description correctly spends its budget on what annotations cannot express: the export is one row per product line with rows grouped into orders (a critical shape gotcha), pagination terminates on an empty page, and only one status filter may be applied at a time. It does not mention rate limits or export size limits, which keeps it from 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 information-dense sentences, front-loaded with the resource and its payload, then filter constraints, then paging. Nothing is wasted, though the first sentence is long enough that the paging rule could be scanned past — a small structural cost.

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 and eight optional parameters, the description carries its weight: it explains the return shape (rows per product line grouped into orders, with addresses and shipment tracking), how to page to completion, and the endpoint. An agent has everything needed to call it correctly and interpret the result.

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 every parameter including the status enum and per_page bounds is already documented; baseline 3 applies. The description echoes the 'one status at a time' limit and the page/next_page contract but adds no syntax or format detail (e.g. timestamp format for created_after/updated_before) beyond what the schema provides.

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 gives a specific verb and resource ('List or search the fulfillment orders of this Zenfulfillment account') and then enumerates exactly what each order carries (status, reference, shop order number, totals, addresses, product lines, shipments with tracking). That field inventory makes it unmistakably distinct from siblings like zenfulfillment_get_order (single record) or zenfulfillment_list_returns, so an agent can select it 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?

It states operational constraints — 'Filter by ONE status, created/updated time or free text' and the paging loop ('pass next_page back as page; an empty page is the end') — which is genuinely useful invocation guidance. But it never says when to prefer this over zenfulfillment_get_order or zenfulfillment_list_returns, so routing between siblings is left implicit.

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