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

Goes well past the annotations by disclosing defaults for status and payment_status, the memo/note visibility split, the back-office (is_admin) entry mode, and the non-idempotent consequence ('creating twice makes two orders'). It also honestly flags an unknown side effect (possible customer email or invoice generation) and hedges correctly rather than inventing behavior.

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 WRITE marker and the core action, then layers constraints in descending importance; almost every clause carries information. The nested parentheticals pack a lot into one dense paragraph, which makes it slightly harder to scan than strictly necessary.

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 16-parameter mutation with no output schema, the description covers the decisions that most affect correctness: defaults, disclosure risks, idempotency, and entry mode. It never indicates what a successful call returns (e.g., a created order id), which an agent needs since there is no output schema to fall back on.

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 only 31% across 16 parameters, so the description needs to carry more weight than it does. It does add real meaning for email, status, memo/note, and the line-items requirement, but leaves roughly ten parameters (due_date, order_date, tax_rate, contact_id, phone, payment_method, delivery_amount, discount_amount, first/last_name) without any guidance beyond their types.

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 and resource ('create a sales order with line items') plus the endpoint (POST /orders) and the entry mode (back-office order via is_admin). The write framing and line-item scope distinguish it cleanly from the sibling get_order/update_order/list_orders tools without needing 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?

Gives explicit operational direction: use Draft unless the user asks otherwise, and only pass email when the user requests it. It does not name a sibling alternative or exclusion, so it falls short of full when/when-not routing, but the conditional guidance is clear and directly actionable.

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