compare_card_prices

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

No annotations are provided, so the description carries full behavioral burden. It mentions grouping by source and currency and a 10-card limit, which adds value, but it doesn't disclose what happens when more than 10 IDs are given (rejection, truncation, error), output structure details, or whether price data is live or cached. For a comparison tool this is thin behavioral coverage.

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?

A single concise sentence that delivers a clear, front-loaded purpose. No wasted words. Could arguably do more, but there's no fluff or redundancy to penalize.

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 an output schema which reduces the need to explain return values, but the tool does not fully document parameter semantics (preferred_source, preferred_variant), the card limit behavior, and lacks annotations. For a tool with 3 parameters at 0% description coverage, the description is under-equipped to guide correct usage.

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. The description doesn't explain any parameter semantics: what card_ids format is expected, what preferred_source values are valid (only a default of 'auto' is hinting), or what preferred_variant means. The 10-card cap hinted in the description does relate to card_ids size, but the other two params are entirely unexplained.

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+resource: 'Compare up to 10 card prices, grouped by source and currency.' It clearly states what the tool does and the key behavior of grouping by source and currency. However, it doesn't fully distinguish from siblings like get_card_prices, compare_printings, or summarize_card_value, which may cover overlapping functionality.

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 no guidance on when to use this tool versus alternatives like get_card_prices, summarize_card_value, or compare_cards. With a large sibling list including several other comparison/price tools, the lack of when-to-use or when-not-to-use guidance is a notable gap.

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