deckofcards

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

With no annotations provided, the description carries full burden for behavioral disclosure. While it mentions the prerequisite (deck_id from new_deck), it doesn't describe what happens during the draw operation (e.g., cards are removed from deck, potential for empty deck, return format, error conditions). This leaves significant behavioral gaps.

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 sentences with zero waste. The first sentence states the purpose, the second provides essential usage guidance. Every word earns its place, and information is appropriately front-loaded.

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 mutation tool (drawing cards modifies deck state) with no annotations and no output schema, the description is incomplete. It doesn't explain what the tool returns, what happens to the deck after drawing, or potential edge cases (drawing more cards than available). The prerequisite mention helps but doesn't compensate for these gaps.

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 100%, so the schema already fully documents both parameters. The description adds no additional parameter semantics beyond what's in the schema (e.g., no examples beyond the deck_id example already in schema). Baseline 3 is appropriate when schema does the heavy lifting.

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 the specific action ('Draw one or more cards') and the resource ('from an existing deck'), distinguishing it from siblings like new_deck (creates deck) and shuffle_deck (reorders deck). It provides a complete verb+resource+scope statement.

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 states when to use this tool ('Requires the deck_id returned by new_deck'), providing clear context about prerequisites. However, it doesn't specify when NOT to use it or mention alternatives like shuffle_deck for different operations.

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

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

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: it creates and shuffles decks, returns a deck_id, and supports multiple decks via the count parameter. However, it lacks details on error conditions, rate limits, or whether the operation is idempotent, which would be helpful for a mutation tool.

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 appropriately sized and front-loaded, with two concise sentences that directly state the tool's action and outcome. Every sentence earns its place by covering creation, shuffling, deck count, and the return value without any waste.

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?

Given the tool's moderate complexity (a mutation with one parameter) and no annotations or output schema, the description is mostly complete. It covers the purpose, usage, and key behavior, but could improve by addressing potential errors or the format of the returned deck_id to fully compensate for the lack of structured data.

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 schema description coverage is 100%, so the input schema already documents the count parameter fully. The description adds minimal value by mentioning 'multiple decks' which aligns with the schema, but does not provide additional semantics beyond what the schema specifies, such as constraints or usage examples.

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 the tool's purpose with specific verbs ('create and shuffle') and resource ('new deck of playing cards'), and distinguishes it from sibling tools by mentioning it returns a deck_id for subsequent draws, which implies it's the initial deck creation tool versus draw_cards and shuffle_deck.

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 provides clear context for when to use this tool (to create and shuffle a new deck) and implicitly suggests alternatives by mentioning deck_id for subsequent draws, but does not explicitly state when not to use it or name specific alternatives like shuffle_deck for existing decks.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool shuffles a deck and returns drawn cards, which implies a mutation (reshuffling) and a resetting effect. However, it doesn't disclose key behavioral traits such as whether this requires specific permissions, if the shuffle is random or deterministic, what happens to the deck state (e.g., order changes), or any rate limits. For a mutation tool with zero annotation coverage, this is a significant gap.

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 appropriately sized and front-loaded, consisting of a single, efficient sentence: 'Shuffle (or re-shuffle) an existing deck, returning all drawn cards back into it.' Every word earns its place by conveying the action, target, and effect without redundancy or unnecessary detail.

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?

Given the tool's complexity (a mutation operation with no annotations and no output schema), the description is partially complete. It covers the basic purpose and effect but lacks details on behavioral aspects (e.g., permissions, shuffle randomness) and output (since no output schema exists). For a tool that modifies state, this leaves gaps in understanding how it behaves and what it returns, making it adequate but with clear room for improvement.

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 has 100% description coverage, with the 'deck_id' parameter fully documented in the schema. The description does not add any meaning beyond what the schema provides (e.g., it doesn't explain the format of 'deck_id' further or provide usage examples). Since schema coverage is high, the baseline score is 3, as the description doesn't compensate but also doesn't detract.

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 the tool's purpose: 'Shuffle (or re-shuffle) an existing deck, returning all drawn cards back into it.' It specifies the verb ('shuffle') and resource ('an existing deck'), and distinguishes it from siblings by mentioning 'returning all drawn cards back into it,' which implies a resetting action not present in 'draw_cards' or 'new_deck.' However, it doesn't explicitly differentiate from 'new_deck' in terms of creating vs. modifying, which prevents a perfect score.

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 implies usage by specifying 'an existing deck,' suggesting it should be used on decks already created (likely via 'new_deck'), and 'returning all drawn cards back into it' hints it's useful after drawing cards (via 'draw_cards'). However, it lacks explicit guidance on when to use this tool versus alternatives (e.g., 'new_deck' for a fresh shuffle or 'draw_cards' for drawing without shuffling), and no exclusions or prerequisites are stated.

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