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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds substantive context beyond them: corpus size (1.5M+ cards across named games/sports), that prices come from 'real sold listings' in USD, and that both ungraded and PSA 10 values are returned. It slightly overlaps the output schema by naming returned card ids, but that framing is chaining guidance rather than redundant return documentation.

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?

Front-loaded with the decision rule, then capability, then chaining and exclusions — every sentence carries information. The middle corpus-enumeration sentence is long but dense with disambiguating games/sports, so little could be cut without losing selection signal.

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?

For a search tool with an output schema and full annotations, the description covers the remaining burden: when to reach for it first, what corpus it spans, what currency and grade tiers it returns, and which tools to chain into. Nothing needed to call it correctly is missing.

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 75% and the query parameter already carries examples ('Umbreon VMAX Evolving Skies', '1986 Fleer Jordan') and set_id points to list_sets. The description's 'by name, set, number and year' largely restates what the schema demonstrates and says nothing about the game enum or the limit bounds (default 10, max 50). Baseline 3 is appropriate.

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?

States a specific verb and resource (search cards) plus the exact intent it serves: 'when the user names a trading card and wants its value, price, or whether to grade it.' It also distinguishes itself from siblings by positioning as the entry point that feeds get_card_prices, grading_roi and get_price_history.

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 when-to-use ('use this first when the user names a trading card') and explicit when-not ('not for sealed product, for cards you already have an id for, or for price prediction'). The exclusions map directly to siblings like get_card_prices and get_set_cards, so an agent can route without guessing.

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