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

Annotations already declare readOnly=false, idempotent=true, destructive=false, openWorld=true, so the mutation/idempotency profile is covered; the description adds genuinely new context with the required COUPON_ISSUE permission and the instruction to reuse the idempotency key after a timeout. However, with no output schema it never says what is returned (the code itself?) or whether issuance consumes inventory/usage limits on the coupon — material behavior for an issuance tool.

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 the core action and precondition, then usage contexts, then the hard constraint and auth requirement. No filler or repetition of schema prose.

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 high-complexity mutation with a required nested cart, 8 parameters, 38% schema coverage, and no output schema, the description is too thin. An agent still lacks guidance on what cart/subject/shipping represent in the issuance flow and what a successful response contains.

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 38% across 8 parameters, so the description carries a large burden and does not meet it. It touches coupon_id and idempotency_key (both already documented in the schema) and vaguely gestures at external_reference, but the required nested cart array, subject, shipping, valid_until, and metadata — all of which materially change the call — are unaddressed.

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 an individual code from an existing coupon') plus the precondition that the coupon must use ISSUED distribution, and rules out a likely misconception ('never creates discount rules'). It does not explicitly name the neighboring tools (quote_single_coupon, redeem_single_coupon, get_coupon_issuance), so the distinction from siblings must be inferred from the quote/issue/redeem wording.

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 concrete use contexts ('cart recovery, CRM, or individualized delivery') that tell an agent when this is the right call, and the 'never creates discount rules' clause excludes one wrong usage. No explicit when-not or named alternative (e.g., use quote_single_coupon to preview value first), which keeps it below a 5.

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

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

Annotations already declare readOnly=true, idempotent=true, openWorld=true, destructive=false, so the safety profile is covered. The description usefully adds what does NOT happen (no total calculation, no budget reservation, no consumption) and that missing context causes exclusion rather than an error, but says nothing about result shape, ordering, or how many coupons come back.

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?

Four short sentences, front-loaded with the purpose and then the boundaries; nothing is padded. 'public defaults to true' slightly duplicates the schema's own default/description text, a minor redundancy.

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 a large nested context object, no output schema, and no annotation detail beyond safety hints, the description answers 'what rules apply' and 'what happens with missing context' but leaves the return value entirely unspecified. An agent cannot tell whether it gets coupon identifiers, discount descriptions, or eligibility reasons.

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?

Reported schema coverage is 0% across a deeply nested context object, so the description must compensate and only partly does: it frames the whole 'context' parameter as known customer/cart facts and clarifies the omission semantics, which is the single most important behavioral rule for this parameter. Fields like unit_id, brand_id, location, attributes, shipping and pagination get no explanation at all.

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 gives a specific verb and resource ('Discover coupons') plus the matching condition ('whose configured rules match the known customer/cart context'). The negative clauses ('does not calculate final totals, reserve budget, or consume a coupon') implicitly separate it from the quote_*/redeem_* siblings, though no sibling is named directly.

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?

It establishes this as the discovery step rather than the quoting/consumption step, and explains that omitted context silently narrows results. It does not explicitly say 'call this before quote_*' or name an alternative by name, so routing is inferable rather than stated.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety and repeatability profile is covered. The description adds one genuinely useful behavioral fact beyond that: the response mixes mutable "current state" with "immutable commercial details." It says nothing about behavior when the ID does not exist or about permissions.

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?

One sentence with no filler, front-loaded with the verb and carrying the key mutable/immutable distinction in a compact clause. The only weakness is the slightly indirect phrasing "issued code" where "issuance" would tie back more directly to the parameter name.

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?

This is a one-parameter read-only lookup with full annotation coverage and no output schema, so no return-value documentation is required. Between the annotations and the description's note about current state versus immutable commercial details, an agent has enough to call it correctly; only not-found behavior is unaddressed.

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 100%, and the single issuance_id parameter is documented in the schema as "Issuance ID returned by create_coupon_issuance," which already establishes the linkage to the sibling that creates it. The description adds no further meaning about the identifier or its format.

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 ("Read") and a specific resource ("an individual issued code"), so an agent knows this is a single-entity lookup rather than a list or quote operation. It stops short of naming a sibling to contrast with, but the scope is unambiguous.

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?

There is no explicit when-to-use or when-not-to-use guidance and no reference to alternatives such as find_eligible_coupons, get_coupon_operation, or quote_single_coupon. The word "individual" loosely implies a single-record retrieval as opposed to a search, but the agent must infer this.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description still adds real context beyond that: it discloses that receipts are immutable and that the view includes current payment state and any reversals, and the 'recovery step after a timeout' framing signals eventual consistency. It omits auth requirements, rate limits, and behavior when operation_id is unknown.

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?

Two sentences, no filler, and the resource scope is front-loaded before the usage guidance. Every clause adds information an agent would otherwise have to guess.

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, so the description usefully enumerates what the inspection returns (receipts, payment, reversals), which is the main thing an agent needs. For a one-parameter read tool this is close to complete; only failure semantics for an unknown operation_id are absent.

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?

With a single parameter at 100% schema description coverage, the schema already carries the semantics ('operation_id returned by a successful redeem'). The description adds only the light constraint 'when operation_id is known,' which is essentially the required flag restated. Baseline 3 applies when the schema does all the work.

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?

Names a specific verb ('Inspect') and a specific resource ('a redemption operation'), then enumerates the sub-resources returned: immutable receipts, current payment, reversals. This distinguishes it from the quote/redeem/revoke siblings, though it never explicitly contrasts itself with reverse_operation or record_operation_payment, which is why it falls short of a 5.

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 two concrete use conditions: reconciliation, and 'first recovery step after a timeout when operation_id is known.' The precondition on operation_id is a useful gate. It does not state when NOT to use it or name the sibling to pick instead (e.g., reverse_operation once recovery is confirmed needed), so it is clear context without exclusions.

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

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

Annotations only flag readOnlyHint=false and non-idempotency; the description adds the genuinely non-obvious behavior that all supplied codes must be eligible and applied (all-or-nothing failure) and how stacking order changes the outcome. It stops short of saying whether a reservation persists, how long it lasts, or how partial failures surface.

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 sentences, each load-bearing: scope first, strategy semantics second, eligibility contract last. No filler and no repetition of schema structure.

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?

A deeply nested 4-parameter tool with 0% schema description coverage and no output schema needs more than strategy hints; the description never explains what the context object is for or what a successful quote returns. Only the smallest parameter (selection) is meaningfully documented.

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 0%, so the description must carry parameter meaning. It usefully explains the two selection.strategy values and the 2–10 code bound, but says nothing about context (cart, user, unit_id, brand_id, location, shipping, payment_method) or cart_id, which is the bulk of the schema.

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 uses a specific verb pair ('Validate and calculate') plus a clearly scoped resource ('2–10 known coupon codes'), which distinguishes it from quote_single_coupon by cardinality. It does not explicitly name the sibling it replaces, so the differentiation is implied rather than stated.

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?

'Known coupon codes' and the 2–10 bound imply when this tool applies versus discovery siblings like find_eligible_coupons, but that routing is never made explicit. No statement tells the agent when to prefer quote_single_coupon or what prerequisite state (e.g. an existing cart) is required.

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

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

Annotations declare a non-destructive, non-idempotent, open-world write; the description adds the crucial nuance that the write is a 'temporary quote reservation' and that totals are 'authoritative' (server-computed, not client-supplied). It does not disclose the reservation's lifetime/expiry or what a repeated call does given idempotentHint=false, which are real gaps for a write tool.

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 with the action front-loaded, followed by usage and exclusion. Nothing is redundant and every clause carries information.

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?

Adequate at the workflow level, but for a nested-object, three-parameter, non-idempotent pricing/reservation tool with no output schema, an agent still lacks guidance on reservation expiry, error cases for invalid codes, and how the many optional context fields affect results.

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% and the description compensates minimally, only implying that context.cart is the cart being priced. The optional context fields that plausibly change eligibility or totals (user age/sex, location, shipping amount, payment_method, attributes, unit_id, brand_id) are explained nowhere in schema or description, and cart_id vs the inline cart array is never clarified.

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?

Specific verbs (validate, calculate, create a reservation) applied to a single named resource (one coupon code against the cart). The closing clause 'Do not use for catalog discovery' actively separates it from find_eligible_coupons/recommend_integration_flow, and 'single' plus the sibling quote_multiple_coupons makes the scope unambiguous.

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 an explicit when-to-use ('before redeeming or displaying a final discount') and one explicit exclusion (catalog discovery). It stops short of naming the alternative tools directly or stating what to do if the coupon is invalid, so it is clear but not fully routing.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's added value is the cost/side-effect statement: local execution, no commercial effect, no API allowance consumed. That is exactly the kind of context an agent needs to call this freely before committing to a real operation. It omits what the recommendation actually looks like on return, which is the remaining behavioral 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 the purpose before the cost profile and the usage trigger. Every sentence carries distinct information and nothing is repeated from the title or schema.

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 simple three-parameter routing tool with no output schema, the description covers purpose, cost, and trigger well. What it leaves out is the shape of the response (a flow name, a step list, sibling tool names) and any explanation of the two boolean inputs. An agent knows when to call it but not quite what it will get back or how the flags change the answer.

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 0%, so the description is the only place parameter meaning could be supplied, and it supplies none. The business_goal enum values are largely self-describing, but payment_confirmed and operation_id_known are undocumented anywhere, and the description never explains how those flags alter the recommended flow. The enumerated action list loosely mirrors the enum but adds no guidance on selecting among the nine values.

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 and object: choose the correct Cupom Center workflow before making API calls. It also frames the tool's role as a pre-flight router by enumerating the action families (discover, quote, issue, redeem, record payment, inspect, reverse) that map onto the sibling tools. It stops short of naming the sibling tools directly, so the differentiation is implied rather than explicit.

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?

It gives a clear trigger condition: 'Use it whenever it is unclear whether to...' followed by the full list of decision points. That tells an agent when this tool is preferable to guessing among siblings. It does not explicitly say when to skip it (i.e., when the operation is already obvious, call the sibling directly), which keeps it from a 5.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false and openWorldHint=true, and the description adds context the annotations cannot: no money movement, no coupon re-consumption, and the required PAYMENT_WRITE scope. It still says nothing about what happens on a conflicting duplicate external_id or what a successful call returns, which is the remaining gap for a write tool.

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 the action and the scope limit, then the side-effect exclusions, then the permission requirement. No filler and nothing redundant.

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 two-parameter, nested-payload write with no output schema, the description covers purpose, side-effect boundary, idempotency context and authorization. A note on retry/duplicate semantics for external_id and the shape of a success response would close the remaining gap.

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 50%, with operation_id, external_id, amount and paid_at documented in the schema itself and method/currency left bare. The description reinforces the 'integral payment' constraint that the amount must equal the operation total, but adds no format, matching, or provenance guidance beyond the schema text.

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 (record a payment on an operation) and immediately bounds the scope: the payment is already confirmed by an external provider. The negative clauses ('does not charge or capture money', 'does not consume coupons again') separate it from the redeem_* siblings in the same namespace.

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 precondition for use is explicit: the external provider must have already confirmed the payment. It also steers the agent away from redeem/quote tools by disclaiming charging and coupon consumption, though it never names a specific alternative or states what to do instead when the payment is not yet confirmed.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds genuinely new behavioral facts: atomic all-or-nothing semantics ("Either all applicable uses/budgets confirm or none do") and the requirement to preserve code order and selection strategy from the quote. It stops short of saying what exactly is consumed or what a partial failure looks like in the response.

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 the atomic guarantee and constrained immediately by cardinality and ordering rules. Nothing is repeated from the title and no sentence is filler.

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 7-parameter, deeply nested mutation with no output schema, the description covers the most important invariant (atomicity) and the ordering constraint but omits the quote/cart/payment relationship and failure reporting. An agent knows what the call guarantees but not fully what it requires in order to build a valid payload.

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 0% at the top level, so the description must carry the burden; it partially does by constraining coupon_codes to 2–10 and explaining that selection/strategy must mirror the quote. The remaining five parameters (cart_id, order_id, quote_id, payment, context) get no mention at all, so an agent still cannot tell how quote_id relates to this call or why payment is sometimes supplied.

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?

"Atomically confirm 2–10 coupons previously calculated together" gives a specific verb (confirm/redeem), resource (multiple coupons) and cardinality scope, which cleanly separates it from redeem_single_coupon. It never names the sibling or the quoting tool it depends on, so the differentiation is inferential rather than explicit.

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?

"Previously calculated together" implies it must follow a multi-coupon quote and that the inputs come from that quote, which is useful sequencing context. It does not state explicit preconditions (e.g. a valid quote_id / non-expired quote), nor when to prefer redeem_single_coupon or reverse_operation instead.

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

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

Annotations already declare a non-read-only, destructive, idempotent, open-world operation, so the safety profile is covered. The description does add useful context beyond that — no money is charged and payment should only be supplied after external confirmation — but it never addresses the risk side of a destructive redemption: whether it can be undone, what happens if the coupon is already redeemed or expired, or what errors surface.

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 tight sentences with the action front-loaded and sequencing second; little waste. 'As a commercial operation' is the only phrase that adds vagueness rather than information.

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 destructive, multi-parameter write with no output schema, the description is adequate on the input side but silent on outcomes — an agent cannot tell what a successful redemption returns (applied discount, final total, operation id) or how failures are reported. The payment-must-equal-total constraint is only in the schema, not reinforced operationally.

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?

With only 17% schema description coverage across 6 parameters and nested objects, the description has to carry weight, and it does clarify that cart_id, context.user.id, and quote_id are alternative correlation keys — a choice the schema does not explain. However, order_id and the required context.cart contents get no mention, and the payment-vs-context.payment_method relationship is left implicit.

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 gives a specific verb and resource ('Confirm one coupon as a commercial operation'), and 'one coupon' implicitly separates it from the sibling redeem_multiple_coupons. It is clear enough to distinguish from quoting and issuance tools, though the word 'confirm' is slightly softer than the actual redemption semantics implied by the destructive annotation.

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?

It states sequencing explicitly: normally call after quote_single_coupon and reuse the same cart/context, and include payment only after external confirmation. It stops short of saying when NOT to use it (e.g., bulk redemption, which routes to redeem_multiple_coupons) or how it relates to record_operation_payment and reverse_operation.

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

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

Annotations already flag destructiveHint, idempotentHint and openWorldHint, so the bar is lower, yet the description still adds real value: it discloses that counters and budgets are released, that the backend reclassifies the record as cancellation or refund depending on payment state, and that no money moves at the payment provider. Only the failure/edge behavior for an already-reversed operation is left implicit.

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 with the core action and side effects front-loaded, and the negative constraints ('no reason or partial amount', 'does not move money') placed last. The middle sentence about backend classification is dense but each clause is informative.

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 one-parameter destructive mutation with full annotation coverage and no output schema, the description covers what is destroyed, what is released, and what does not happen downstream at the payment provider. It could be more complete about preconditions (operation must be in a redeemable/redeemed state) but nothing essential for invocation is missing.

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 100% and the single operation_id parameter is documented as coming from a successful redeem, so the schema carries the load. The description adds only the implicit constraint that exactly one operation is affected, which is the baseline expectation rather than extra meaning.

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 ('Fully reverse') and resource ('one coupon operation') with explicit scope ('fully'), plus the side effect of releasing usage counters and budgets. It does not name the sibling it differs from (e.g. revoke_coupon_issuance vs. this operation-level reversal), so it falls short of full sibling differentiation.

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?

Usage is implied by 'one coupon operation' and the schema note that operation_id comes from a successful redeem, and the description rules out partial reversals or reason arguments. However, it never explicitly says when to use this versus revoke_coupon_issuance or what state the operation must be in, leaving the agent to infer routing.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description gets credit for adding a real precondition: only *active* issuances can be revoked, and consumed/expired codes cannot be revived. It does not describe what happens on repeat invocation of an already-revoked ID or what the response contains.

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 the action, then the behavioral caveat, then the usage constraint. No filler and nothing repeated from the schema.

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 one-parameter destructive mutation with no output schema, the description covers scope, idempotency, and the key precondition. The main remaining gap is error/already-revoked behavior, which an agent would likely need when retrying.

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 100% and the single parameter is documented as the ID returned by create_coupon_issuance. The description's "individual" wording reinforces single-record semantics but adds no new meaning about the identifier itself, so baseline 3 applies.

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+resource with scope qualifiers: "Revoke one active individual issuance" tells the agent it operates on a single issuance, not a batch. It does not name a sibling to distinguish from (e.g. reverse_operation), so it stops short of a 5.

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 a positive condition ("Use only when the individual code must no longer be accepted") and an implicit exclusion (consumed or expired codes cannot be reactivated). It never names an alternative tool or states when another sibling should be preferred, so guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds that the server does the choosing and that optimization targets coverage or total discount, but it never explains why the call is non-idempotent, whether selections reserve or lock coupons, or what happens when no coupon qualifies. With annotations carrying the load, this is a moderate additive contribution.

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 tight sentences: capability, precondition, exclusion. The scope constraint is front-loaded and no sentence is filler.

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?

This is a complex nested tool with five parameters, no output schema and no documented return shape. The description communicates the trigger and the optimization axis but omits result semantics (what a selection response contains, e.g. per-unit coupon assignments) and the meaning of the nested context object, which an agent needs to build a correct call.

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 0%, so the description must carry parameter meaning, and it does not. It hints at the priority enum ("by coverage or total discount") and the 1–20 unit bound, but leaves mode (single vs multiple), context (user/location/payment_method — clearly eligibility inputs), and max_coupons_per_unit entirely unexplained. The most consequential parameter, mode, is ambiguous between one coupon per unit and several, which can cause wrong invocations.

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?

"Automatically select public coupons for 1–20 marketplace/store units" names a specific verb (select), a specific resource (public coupons), and the scoping constraint (per unit). It also draws a hard boundary against code validation, which separates it from the quoting siblings.

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?

Explicit trigger given: use only when the cart is partitioned into units and the integration wants Cupom Center to choose by coverage or total discount. The negative case ("not for validating a known code") rules out the quote/redeem path. It stops short of naming the concrete siblings (find_eligible_coupons, quote_multiple_coupons) an agent should pick for non-partitioned or single-code flows.

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