market_snapshot

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 explicitly reveals that this is a PAID call, details the payment method and cost, and warns that the server returns a 402 unless payment is made. It also notes the previous misdocumentation (BUG-2) to prevent budget surprises. This goes beyond typical disclosure and is highly transparent about the operation's side effects (cost, potential failure).

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 efficiently organized: the first sentence states the purpose and scope, the second block conveys critical cost/payment information, and the final sentence provides usage guidance and the alternative. No sentence is wasted; even the audit reference is compact and relevant. The structure is front-loaded with the core functionality, making it easy to parse.

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 only one optional parameter, no output schema, and no annotations, the description covers the essential aspects: what the tool returns (gainers/losers, volume leaders, per-game breakdown), when to use it, the cost, and the alternative. It does not list the 25 game names or specify the response structure, but that is a minor gap for a single-parameter, read-only summary tool.

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 does so by explaining the 'game' parameter indirectly: 'optionally for one game' and 'per-game breakdown across all 25 supported card games' imply that passing a game filters the snapshot to that game, while omitting it returns the whole-market summary. It doesn't list the 25 games or the expected string format, but the meaning is clear enough for a single optional parameter.

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 clear, specific statement of what the tool does: 'The DAY'S MARKET REPORT in one call, optionally for one game: biggest gainers and losers by % change, volume leaders, and the per-game breakdown across all 25 supported card games.' It also explicitly differentiates from a ranked pick list and later names the sibling tool (trending_cards) that serves that alternative purpose, making the distinction unmistakable.

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 when-to-use guidance: 'Use this when: a user asks "what happened in the card market today?" or "which games are moving?".' It then states the alternative: 'For a ranked list of individual cards with a risk row each, use trending_cards.' This covers both when and when-not, fully orienting the agent to choose correctly.

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