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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does well by explaining issuer-domain matching, empty expiry_date handling, value_type constraints, item_type special requirements, and the return of the created item. It does not cover authorization, idempotency, or duplicate handling, but the provided details are substantial and genuinely useful.

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 dense but every sentence earns its place. It front-loads the core action and then efficiently packs the critical parameter constraints into a compact block. There is no filler or repetition of schema trivia.

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 9-parameter tool with no annotations, this description is remarkably complete. It covers the non-obvious behavioral rules, value formats, domain matching, expiry semantics, and item-type restrictions. The output schema exists, so not explaining return shape in more detail is acceptable. An agent could plausibly invoke this tool correctly with only this description.

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 compensate. It explains issuer, redeem_code, expiry_date, value_type, item_type, and value constraints in detail. It omits explicit semantics for name, currency, and description, though those are fairly self-evident or covered by schema defaults. The description does not just repeat the schema; it adds real 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?

The description opens with a specific verb-resource pairing: 'Create a new item (coupon, voucher, gift card or loyalty card).' This clearly separates it from the sibling list/get/update/mark_used/delete tools. The inclusion of domain-specific constraints further reinforces what the tool is for.

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 clearly implies when to use the tool: when creating a new coupon-type item. It does not explicitly say 'use coupon_update instead for existing items' or list exclusions, but the sibling names combined with 'Create a new item' give adequate context. A small gap is the absence of direct alternative 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?

With no annotations, the description carries full responsibility for behavior. It explicitly discloses that the operation is permanent and irreversible ('cannot be undone'), which is a key trait for a destructive action. However, it does not mention other potential behavioral aspects such as required permissions, side effects on related data, or error behavior when the id does not exist.

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 short and front-loaded, stating the action and key constraint immediately. The slight redundancy between 'permanently delete' and 'cannot be undone' is minor and does not detract from clarity. No filler or unnecessary details.

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 single-parameter delete with an output schema, the description conveys the core action and irreversibility. However, it lacks usage context relative to the five sibling tools and leaves parameter meaning underspecified. An agent could likely invoke it correctly, but important context for decision-making 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 description coverage is 0%, so the description must compensate. It only says 'by its id', which essentially restates the existence of the item_id parameter without adding meaning such as 'the coupon's unique identifier' or expected format. This does little to help an agent understand the parameter beyond the schema itself.

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 clearly states a specific verb ('delete') and a permanent action, indicating the resource is removed by its id. While 'item' is generic rather than 'coupon', the tool name and sibling set make the intent unambiguous, and it distinguishes itself from list/get/create/update/mark_used.

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?

No guidance is provided on when to use this tool versus alternatives like coupon_mark_used or coupon_update. There are no prerequisites, exclusions, or conditions stated. An agent only knows 'delete' but not when deletion is appropriate relative to the other operations.

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?

With no annotations provided, the description must bear the full burden of explaining behavior. 'Get' makes the read-only intent reasonably clear, but the description does not disclose what happens when the id does not exist, whether any authorization is required, or whether the response is guaranteed to include all fields.

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 a single sentence with no wasted words. It front-loads the action, specifies the scope, and includes the essential id format detail without 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 simple one-parameter retrieval tool with an output schema, the description covers the core invocation details well. It could be more complete by explicitly naming the resource type and adding usage guidance about when to choose this tool over coupons_list.

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?

The schema only describes item_id as a string with no format details. The description adds that the id is a UUID string, which is valuable semantic information, and 'by its id' clearly maps to the single parameter. With one parameter, this is sufficient coverage.

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 clear verb ('Get') and identifies the resource ('single item') and the lookup method ('by its id'). It clearly separates this from list/create/update/delete siblings, though it never explicitly names them or uses the term 'coupon'.

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 intended use is implied: call this when you need full details for one item by its UUID. However, there is no explicit comparison to alternatives such as coupons_list, no when-not-to-use guidance, and no mention of when mutation tools would be appropriate.

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?

With no annotations, the description carries the behavioral burden, and it does so well: it discloses that the operation is a toggle, not a setter, that calling again reverses the state, and that the returned item reflects the new state. This is important non-idempotent behavior that an agent must know before invoking the 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?

The description is three short sentences with no filler. The core action is front-loaded, followed by essential toggle behavior and return-state information. Every sentence contributes value.

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?

The description adequately covers the toggle behavior and response for a simple one-parameter tool, and the output schema handles return-value details. However, it is missing basic contextual details such as the fact that item_id refers to a coupon identifier and any guidance about choosing this tool over coupon_update.

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%, and the description does not explain item_id beyond calling it an 'item.' The description fails to clarify what kind of ID is expected, its format, or how it relates to coupons, leaving the agent to infer the parameter's meaning from the schema alone.

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 clearly states a specific action: toggling the used status of an item, which is distinct from list/get/create/delete operations. However, it does not explicitly distinguish itself from coupon_update, which could also plausibly change a coupon's used status.

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 implies when to use the tool—whenever you need to flip the used status—and explains the effect of repeated calls. It does not, however, provide explicit guidance on when to use this tool versus coupon_update or other siblings, leaving some selection ambiguity.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It explicitly states that used and expired items are hidden by default and that `include_used`/`include_expired` opt in to show them, and it defines the meaning of `days_left` (negative = expired). This is meaningful behavioral context beyond the raw schema, though it doesn't mention pagination or ordering.

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 about five short lines and every sentence contributes a distinct piece of usable information: scope, search behavior, item type values, default visibility, and the output field. It is front-loaded with the core action and avoids 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?

Given the tool has four optional parameters and no annotations, the description covers all parameters, the default behavior, and the key output field semantics, making it complete for correct invocation. The presence of an output schema means return structure is already specified, so no additional return-value explanation is needed.

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?

The input schema has 0% description coverage, so the description must compensate. It does: it defines `search` as substring matching over name, issuer, and redeem_code; enumerates valid `item_type` values; and explains the boolean flags' effect on default visibility. Every parameter receives semantic meaning beyond its type/default.

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 the verb 'List' and explicitly enumerates the resources: vouchers, coupons, gift cards, and loyalty cards. This clearly distinguishes it from sibling tools like coupon_get or coupon_create, which target single records or mutations.

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 provides clear, operable guidance: it tells the agent when to use `search` (substring matching on name, issuer, redeem_code) and how `item_type` filters values. It also explains the default hiding of used/expired items and how to enable them, giving clear context for invoking the tool correctly. It does not explicitly reference alternative sibling tools, but the list-oriented context is unambiguous.

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?

Even with no annotations, the description discloses important behaviors: only provided fields change, the full list of editable fields, the expiry_date format, the valid value_type enums, and the return value. It does not mention permissions, reversibility, or null-field semantics, but it carries more behavioral weight than the typical update tool description.

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 compact and front-loaded: two sentences establish the core behavior and return value, then a tight list of editable fields adds the necessary detail. Every sentence earns its place; there is no fluff or repetition.

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 9 parameters, 0% schema coverage, and no annotations, the description covers the essential ground: update semantics, editable fields, validation formats, and the return. The existence of an output schema covers response shape. The remaining gaps are minor (e.g., whether providing null clears a field, error behavior if item_id not found) but do not seriously impede correct invocation.

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 compensate. It lists every editable field and adds meaningful constraints: expiry_date format, value_type allowed values. It does not explain what each field represents (e.g., value vs. currency) or address how explicit nulls are handled, but it maps directly to the schema and provides more than the raw parameter names.

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 ('Update') and resource ('existing item by id'), immediately distinguishing it from list, get, create, mark_used, and delete siblings. It also clarifies the partial-update semantics ('Only provided fields change'), so an agent knows exactly what this tool does and what it is not.

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 clearly conveys the context for use: updating an existing coupon by id without replacing the whole object. It does not explicitly name alternatives or exclusion conditions, but the sibling tool names make the distinction obvious and the partial-update behavior inherently separates it from create/delete. Slightly more explicit routing would earn a 5.

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