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

Annotations already declare write, non-destructive, non-idempotent, closed-world behavior. The description adds the auth scope requirement ('orders:write'), which is genuinely useful extra context. However, for a purchase tool it says nothing about charging, cost bounds, failure/refund behavior, or what an order represents — a notable gap.

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 short sentences, front-loaded with what the tool does, then the prerequisite and the auth requirement. No wasted text.

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?

Given 10 parameters, no output schema, and a money-moving operation, the description is thin: it doesn't describe what is returned (order object) or the charging model. Pointing to get_offers helps, but key behavioral context for a purchase is left to the schema.

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 80%, so the schema already documents most parameters (offer, models, context, question, idempotency_key, client_order_key, etc.). The description adds no parameter-level detail beyond the schema baseline, so a 3 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 ('Buy') and a resource concept ('bounded model question or review'), which maps to the create_order tool. It differentiates from siblings by directing to get_offers, though it never explicitly uses the word 'order' or clarifies the bound/limit semantics.

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?

Clear context for use: consult get_offers first for models, limits and payment rails, and requires scope 'orders:write'. That preconditions the call well, but it doesn't state when NOT to use this versus authorize/credit flows or what to do if offers are unknown.

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