ze_apply_couponApply a coupon code to an order after explicit user consent. Validates the code without completing checkout.
applyCoupon(couponCode: String!). Dual-gated. Does not checkout.
| Name | Required | Description | Default |
|---|---|---|---|
| coupon_code | Yes | ||
| response_format | No | markdown | |
| explicit_user_intent | No | Must be true after the user explicitly asked for this write. |
Changes observed during successful MCP inspections.
v0.1.4Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey that this is a non-read, destructive write. The description adds that the operation is 'Dual-gated' and 'Does not checkout,' which are useful boundary statements. However, it does not explain what the two gates are or what side effects applying a coupon may have on the cart or order.
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 description is one compact line, front-loaded with a code signature and two high-signal caveats. There is slight redundancy because 'applyCoupon(couponCode: String!)' repeats the tool name and parameter, but the overall structure is efficient and easy to scan.
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?
There is no output schema, and the description does not explain return behavior, outcome confirmation, or what the second gate is. The crucial 'dual-gated' mechanism is never expanded, leaving the definition incomplete for a write tool that requires explicit user intent.
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 33%, so the description should compensate for undocumented parameters. It merely repeats the couponCode signature and does not explain coupon code semantics, response_format behavior, or how explicit_user_intent gates the operation. This leaves most parameters semantically unexplained.
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 action ('applyCoupon') and explicitly disambiguates from checkout operations with 'Does not checkout.' It is clear about the verb and resource, though it relies partly on the title and does not specify whether the coupon applies to a cart or an order.
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 only an implied usage context: this tool applies a coupon and does not perform checkout. It does not name an alternative tool, such as ze_checkout_preview or ze_complete_checkout, nor does it explain when to use this tool versus those siblings. 'Dual-gated' hints at prerequisites but leaves them unspecified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.