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

Beyond the annotations, the description reveals that a payment mandate is required even though the schema lists only cart_id as required, and that mismatched currency or over-cap mandates are denied. It also documents credential setup, optional skyfire-token behavior, and the absence of human login. These details significantly exceed what the annotations provide, and there is no contradiction with readOnlyHint=false, destructiveHint=false, or idempotentHint=true.

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?

The first sentence front-loads the core purpose, and the labeled paragraphs (SKYFIRE TOKEN, PAYMENT MANDATE, CREDENTIAL) are scannable and mostly non-redundant. It is long, but the tool has unusually complex auth prerequisites. Some header/argument alternatives are repeated from the parameter descriptions, so it is not perfectly concise, but every block earns its place.

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 6 parameters and hidden requirements, the description covers setup order, mandatory mandate fields, currency-matching and cap-enforcement failure conditions, header fallbacks, and the no-human-login policy. Since an output schema exists, return-value details do not need to be spelled out. The only omissions are minor edge cases such as discount conflicts, which are not needed to invoke the tool correctly.

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?

Although the schema already describes every parameter, the description adds crucial meaning: payment_mandate is actually mandatory and must match the cart currency with cap enforcement; agent_key is a create_sandbox_key credential; discount_code is required unless source is ucp_identity; and identity_token pairs with source='ucp_identity'. It also introduces the skyfire-pay-id header option, going beyond the schema's field descriptions.

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 and resource: 'Apply a discount or promo code to the cart.' This clearly distinguishes it from checkout/payment siblings like complete_checkout and preview_checkout, and the later mention of UCP identity discounts clarifies the alternative input mode. An agent can understand exactly what the tool does without inspecting 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?

The description gives strong operational guidance: it explicitly tells the agent to call create_sandbox_key first, to pass the key as agent_key or Authorization header, and not to attempt human login. It also explains when to use the payment_mandate argument versus the X-Payment-Mandate header. It does not formally state exclusions like 'use complete_checkout instead,' but the preconditions and alternative paths are clear.

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