ygo_test_custom_card

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

With no annotations, the description carries the full burden and does disclose real methodology: seeded games, same opponent and AI, alternating who goes first, a 95% interval, and a turn cap where unfinished games never count as wins. It does not disclose cost or runtime, which matters because games run 2-50 per side and the tool plays the actual engine. The comparison design is well described; the operational footprint is not.

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 numbered (1)(2)(3) breakdown front-loads what is measured and the caveat comes last where it belongs. The first sentence is long and clause-dense, but every clause carries information; the second sentence earns its place by setting expectations about the no-deck fallback.

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 7-parameter, no-output-schema tool, the description covers what the run does, how the comparison is controlled, and the main interpretive caveat. What remains thin is the return payload (win rate, usage counts, interval shape) and runtime expectations for up to 100 engine games, so the agent knows what to report and how long to wait.

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 100%, so the baseline is 3, but the description adds meaning the schema lacks: omitting 'deck' triggers a neutral vanilla shell, and 'opponent' defaults to that same neutral shell. It also explains the comparison structure (same seeds and AI, alternating first player) that gives 'seed' and 'games' their significance beyond their one-word schema descriptions.

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 ('Test a custom/unreleased card on the real engine') and then enumerates the three things it measures: script health, AI usage frequency, and win-rate impact. That decomposition separates it from generic duel simulators like ygo_run_duel or ygo_ai_benchmark, though it never names a sibling explicitly.

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 framing 'like a card designer would' plus the three numbered checks makes the intended situation clear: validating a card you authored before trusting its power level. The closing caveat about the neutral vanilla shell is a genuine usage constraint ('checks that the card works, not its real-deck power'). It offers no explicit 'use X instead when...' routing to sibling benchmark or analysis tools.

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