updateCoupon

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

Description discloses merge semantics (partial update) and the critical relationship between coupon_type and discount_amount, which goes beyond annotations. While annotations include destructiveHint:true, the description clarifies that omitted keys remain unchanged, reducing ambiguity. It does not discuss side effects or idempotency, but annotations already cover that.

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?

Description is concise and front-loaded. It directly states the core merge operation in the first sentence, then adds crucial usage details (coupon_type dependency, alternative tools) in subsequent sentences, with no redundant 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?

Given no output schema, the description could mention return values or success indicators, but the tool's purpose is clear and the merge behavior is well explained. The description covers key dependencies and alternatives, making it adequately complete for an update operation with complex field interactions.

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?

Description adds meaning beyond the input schema by explaining the merge behavior and the conditional nature of discount_amount based on coupon_type. Although the schema provides detailed descriptions for many properties (suggesting high coverage), the description clarifies the update semantics and the need to adjust discount_amount when changing coupon_type, which is not evident 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?

Description clearly states the tool's purpose: '既存クーポンの設定を差分マージします' (merge existing coupon settings by diff). It explains that only keys included in shop_coupon are updated, and omitted keys remain unchanged. It also distinguishes from sibling tools createCoupon, deleteCoupon, and getCoupon, providing a distinct verb-resource pair.

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 guidance on when to use this tool vs alternatives: '新規作成は createCoupon、削除は deleteCoupon、現在値は getCoupon を参照' (for new creation use createCoupon, for deletion use deleteCoupon, for current values refer to getCoupon). It also warns about the dependency between coupon_type and discount_amount, and notes that discount_amount is unnecessary for delivery_charge.

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