Coupang category top 30

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

The description goes well beyond the annotations (readOnlyHint=false, idempotentHint=true) by disclosing that data is a once-daily snapshot reused across calls, that each category/day costs 300 credits regardless of limit, that re-fetching the same snapshot is free, that free credits are consumed first, that an ambiguous/non-matching category name returns a list and charges nothing, and that the first paid use requires accept_terms. This is exactly the cost/idempotency/terms context an agent needs before invoking a credit-spending, non-read-only 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 trigger condition is front-loaded in the first clause, and every later sentence carries load-bearing pricing, caching, or terms information. The parenthetical column enumeration ('sale price, coupons, seller type, monthly buyers …') is slightly padded for what it conveys.

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, yet the description enumerates the returned columns, names the `snapshot_date` field, and explains the list-return path for ambiguous category names, alongside cost, caching, and consent requirements. An agent has everything needed to call this correctly and to explain the charge to the user.

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%, so the baseline is 3; the description adds real meaning on top by explaining that cost is per category per snapshot regardless of `limit`, that `snapshot_date` reports the caching day, and that `accept_terms` gates only the first paid use. It does not explain how `csv_path` interacts with row return (that stays in the schema), keeping it just short of a 5.

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 verb and resource — retrieving today's top 30 best-selling products for a Coupang category, with the exact column set (price, reviews, delivery, detail-page columns) and the optional price-comparison use. It is unmistakably distinct from the sibling tools (login, me, catalog, run, fetch, coupang_categories), which the agent can rule out immediately.

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?

"Use when the user wants today's best-selling / top 30 products of a Coupang category ... or a price comparison" gives a clear triggering condition. It lacks an explicit 'use coupang_categories first to resolve a name' routing instruction and states no exclusions, so it stops short of a full when/when-not/alternatives treatment.

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