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

Annotations declare readOnlyHint=false and destructiveHint=false, so the mutation/safety profile is partly covered; the description goes beyond them by disclosing that nothing reaches the supplier and no stock moves until send_purchase_order, and that unlinked items are rejected. That draft-state semantics is the key behavioural fact an agent needs and is not derivable from the annotations.

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?

Front-loads the create-as-draft fact first, then the prerequisite order, then per-field caveats, then the confirm-before-send advice. Sentences are dense but every one carries a decision-relevant fact with no filler.

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 10-parameter mutation tool with no output schema, the description covers workflow, prerequisites, side-effect semantics and field conventions well. The only gap is that it never says what comes back (e.g. the created draft order id) that the agent would need to chain into send_purchase_order; with no output schema that would have been worth one clause.

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 100%, so the baseline is 3, but the description adds sourcing and editability context the schema lacks: variantId/unitCost come from get_supplier_items with the matching outletId, unitCost is prefilled from the supplier link but editable for negotiated prices, and quantity is in the item's selling unit. It largely restates the schema's string-amount and fractional-quantity notes, hence not a 5.

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?

States a specific verb+resource ('Write a new order to a supplier') and immediately distinguishes itself from hub_send_purchase_order and hub_update_purchase_order by clarifying that the record is only a DRAFT. An agent can route between create/send/update without opening a 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?

Gives an explicit, ordered prerequisite chain (get_suppliers → get_outlets → get_supplier_items with that outletId), names the follow-up call (send_purchase_order), and states the exclusion condition (an item not linked to this supplier is refused). This is exactly the when/when-not/alternatives guidance the dimension asks for.

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