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

Beyond the annotations, the description discloses real behavioral traits: the value is 'sealed, never shown back' (only kind, last two chars and status are visible via whoami/my_orders), and the code is 'deleted after the drive that used it.' This lifecycle and secrecy context is genuinely useful. Minor tension: it describes a delete while destructiveHint is false, but the deletion is expected/intended so this is not a clear contradiction.

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?

A single bloated, semicolon-chained sentence mixes several ideas (buying, add/replace kinds, removal, sealing, lifecycle). It is not front-loaded: the concrete action comes after the vague 'our agent buy your plan' preamble, so the reader must work to extract the point.

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, the description correctly covers the return-adjacent behavior (value is hidden; only kind, last two chars, status shown) and the deletion lifecycle. However, it omits the add-vs-replace semantics and required order_id origin details are left to the schema, leaving the picture only partially complete.

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 75%, so the schema already documents kind, value, remove and order_id. The description loosely maps kind to its options ('a discount code, a test-mode login or a seat') and restates the remove flag, adding little beyond what the schema provides. Baseline 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 title ('Add or remove the code for your order') and phrases like 'add or replace a discount code, a test-mode login or a seat' convey a verb+resource, but the description buries this under rambling prose ('Let our agent buy your plan, on an order you placed'). The purpose is recoverable but not cleanly stated, and no sibling (pay_order, pay_check, order) is named for contrast.

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?

'until a drive has it' hints at when the code is consumed and 'remove: true deletes it' covers removal, but there is no explicit when-to-use guidance or routing to alternatives like pay_order or order. The agent must infer the workflow from ambiguous fragments.

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