grade_card

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

With no annotations provided, the description fully carries the behavioral burden and does so admirably: it discloses the $0.10 paid cost, the three accepted rails, that Solana settlement is verified, the exact returns (PSA/Beckett subgrades + overall score + free ROI verdict), and the underlying methodology (Qwen, OpenCV, BGS capping). This is rich disclosure beyond mere mutation.

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?

Well-organized and front-loaded with the core purpose and pipeline before the payment details. Slightly verbose in places — the internal audit reference ('Audit 2026-07-30, BUG-12') is arguably noise for an agent — but every functional sentence earns its place.

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?

Strong coverage for a complex paid, multi-rail tool with 2 params and no output schema. The pipeline, returns, cost, rails, and usage are all present. Remaining gaps are the unexplained game parameter and whether the $0.10 payment is required before the call or settled after, which are material but minor against an otherwise complete definition.

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 for the two parameters, but it largely does not. image_url is only implicitly covered by 'trading card image,' and the required/default game parameter is never explained at all (what games are supported beyond the Pokemon default, what values are valid). The description adds almost no parameter-level meaning.

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+resource ('AI-grade a trading card image') and details a 3-stage pipeline that anchors the purpose. It distinguishes itself from the sibling grade_or_not by clarifying it produces an actual PSA/Beckett-calibrated grade rather than just a go/no-go verdict.

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?

Ends with an explicit 'Use this when: a user has a card image and wants to know what grade it would receive from PSA or Beckett,' which gives clear invocation context. However, it never names alternatives like grade_or_not or check_accuracy, nor states when NOT to use this tool.

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