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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real context beyond that: the deckId mode returns cards, rule checks, missing-card ownership gaps, and completion cost, plus it implies a signed-in user is required. Pagination or list-size limits are not mentioned.

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?

Two tight sentences, front-loaded with the resource and then the mode branches. Every clause conveys distinct information with no 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?

With no output schema, the description must convey what comes back, and it does so for both modes (list vs. cards/rule checks/missing cards/cost). For a two-parameter read tool this is close to sufficient, though list-mode bounds and how to obtain a deckId are absent.

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 50%: source is well documented in the schema (USD vs EUR per vendor), but deckId has no schema description. The description compensates by explaining that deckId switches the response to that deck's cards and analysis, which tells the agent what the parameter actually does. It does not state the ID format or where to obtain it.

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 resource (the signed-in user's saved decks) and splits behavior by input mode, so an agent knows exactly what it retrieves in each case. It does not explicitly contrast itself with close siblings like my_collection or validate_deck, so the distinction from those tools must still be inferred.

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?

It gives clear conditional usage: call with no arguments to get the list, call with deckId to get that deck's cards and analysis. That is effective mode-selection guidance, but it names no alternative tool (e.g., validate_deck for rule checks, my_collection for owned cards) and states no exclusions.

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