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

Beyond the readOnlyHint annotation, the description discloses the return format ('Returns exact / not_found per name, with the canonical spelling and id for the ones that exist'), performance characteristics ('Cheap, batched'), and safety ('safe'). It also explains the input modes (names array or text decklist). No contradictions with annotations.

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 a bit longer than minimal but every sentence adds value: core action, return info, usage guidance, rationale, efficiency, and input modes. It is front-loaded with the main action and remains structured. Could be tightened slightly, but there is no fluff.

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 a simple schema (2 optional params), an output schema present, and read-only annotations, the description provides sufficient context for an agent to know when and why to use the tool, what to expect in return, and how to invoke it. It covers both parameters and the tool's place in the broader workflow of validating Magic card names.

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 input schema provides no descriptions for the two parameters, so the description must compensate. It clarifies that 'names' is an array of card names and 'text' is a pasted decklist, and that either can be accepted. While it doesn't detail text decklist format or edge cases, it gives meaningful semantics beyond the bare schema types.

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 a specific verb ('Check') and resource ('card names') with a clear scope ('in bulk'). It distinguishes itself from siblings by focusing on validation of real card names, returning canonical spelling and id, while siblings like get_card or search_cards serve different purposes. The phrase 'the most common failure in Magic assistance is confidently naming cards that do not exist' underscores its unique role.

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 explicitly tells agents to 'Call this reflexively before presenting any decklist or card recommendation you generated' and notes it is 'safe to call on every card you are about to mention.' It provides strong when-to-use context but does not mention alternative tools or any when-not-to-use scenarios, so it falls just short of a 5.

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