trending_cards

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

With no annotations provided, the description carries the full transparency burden. It discloses the paid cost, corrects previous claims about sales volume/view counts, explains that band/VaR percentages are regime-level constants, and notes the API disclaims certain data via ranked_by.

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 focused and each sentence adds meaningful information: output type, ranking criteria, filter options, caveats, pricing, and sibling-tool comparison. It is appropriately concise without unnecessary 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?

Even without an output schema, the description explains the return shape (ranked list with conformal risk row) and important behavioral details such as coverage across games, cost, and data limitations. This is sufficient for an agent to select and invoke the tool correctly.

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 provides only names and defaults, but the description mentions filtering by game, limit, and min_price, which maps to all three parameters. It does not detail game value format or currency for min_price, but the essentials are covered.

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 the tool returns a ranked list of individual cards by price velocity, with highest absolute movement first, and explicitly distinguishes it from market_snapshot for whole-market summaries. This makes the tool's purpose and 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?

The description gives explicit usage direction: use when a user asks which cards are moving fastest and wants names to act on, and use market_snapshot for day's whole-market summary. This provides clear when-to-use and when-not-to-use guidance.

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