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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it delivers: it reveals account scoping ('admin sees all') and the non-obvious refund=1 semantic (auto-refund candidates map to refund_pending status). These are behaviors an agent could not infer from the schema alone. It stops short of covering output format or pagination, but for a read-style list operation the disclosed traits are the important ones.

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?

Two sentences with no fluff. The primary action and filters are front-loaded before the scope note, and the refund nuance earns its place as genuinely non-obvious information. Every sentence adds value.

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 only three optional simple filters, no nested objects, and no output schema, the description covers the essentials: purpose, filter semantics, and scoping. The main omissions—return format and pagination—are secondary for a list operation, and the absence of any annotation coverage is offset by the read-only implication of 'List'. Adequate-plus for the complexity level.

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 coverage is only 33% (only refund has a description), so the description must compensate, and it partially does: it names all three parameters and adds the refund=1 ↔ refund_pending mapping. However, supplier_id and status receive only name-drops with no added semantics beyond the enum values already visible in the schema, so the compensation is incomplete.

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 opens with a specific verb+resource ('List purchase orders') and clarifies scope ('scoped to your account, admin sees all'), which distinguishes it from sales/RFQ/shipment list tools among the siblings. However, it never names a sibling or explicitly contrasts itself, so differentiation is indirect—an agent must infer that mu_rfq_list or mu_sales cover different resources.

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?

Usage context is implied: this is the tool for listing purchase orders, and the filter syntax (supplier_id, status, refund=1) gives operational how-to guidance. But there is no explicit when-to-use vs. alternatives statement, and with 29 siblings including several list tools (mu_rfq_list, mu_sales, mu_list_mine, mu_ship_orders), an explicit routing note would meaningfully improve selection accuracy.

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