Fantasy Solvers – Balatro Lab

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description usefully discloses the exact-mode validation limits (12 draw cards, two hands, two discards) and that validation mirrors HTTP, but these limits largely restate the conditional schema and no cost, latency, or result-shape context is given.

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?

Three sentences, front-loaded with the purpose, and no padding. But 'with the same contract and validation as HTTP' is cryptic and consumes space without conveying actionable meaning.

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?

This is a complex tool with nested objects, conditional schema branches, and no output schema, yet the description is only three terse sentences. With 0% parameter coverage and no return-value explanation, an agent lacks enough to construct a valid call confidently.

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% across 6 parameters, so the description must carry the load. It only clarifies explain_actions and hints at analysis_mode (exact vs immediate); contract_version, budget_score_calls, request_id, and the required state object fields are left entirely to the schema, which does not describe them either.

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 ('Compare') and resource ('all immediate plays or exact small-deck play/discard values'), so the agent knows it enumerates and compares candidate actions. It does not explicitly differentiate itself from the sibling recommend_action, which likely does the same computation but returns a single pick, leaving that distinction to inference.

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?

'Select explain_actions for particular branches' and the mode-specific limit note imply when each mode applies, giving implied usage guidance. However, there is no explicit statement of when to choose this over recommend_action or evaluate_hand, and no stated prerequisites or exclusions.

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?

Annotations already declare the operation is read-only, idempotent, non-destructive, and closed-world. The description adds meaningful behavioral context beyond those annotations: played and held order is optimized rather than evaluated literally, and unsupported effects are rejected. It still omits return format and broader failure behavior, but the added semantics are valuable.

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 terse and front-loads its core claim before adding optimization and rejection semantics. Every sentence contributes some signal, though the opening is jargon-heavy and could be clearer without becoming longer.

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 tool with seven parameters, nested objects, no schema descriptions, and no output schema, the description is materially incomplete. It omits most parameter semantics and does not describe the return value beyond the vague phrase 'immediate score.' Annotations cover safety, but the remaining gaps are large.

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% for seven parameters, so the description carries the full burden. It only touches on 'played' and 'held' semantics, and says nothing about contract_version, jokers, levels, discards, or request_id. This leaves most parameter meaning undocumented.

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 presents a noun phrase ('Versioned optimized immediate score from bengine-core') rather than a specific verb-resource statement. It implies that the tool evaluates a hand and computes an optimized score, but it does not explicitly distinguish the tool from siblings like compare_actions or recommend_action. The added notes about optimizing played/held order and rejecting unsupported effects add some specificity.

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?

There is no explicit when-to-use guidance, no when-not-to-use exclusions, and no named alternatives among the sibling tools. The description only indirectly suggests the tool is for scoring a hand, leaving the agent to infer its role relative to compare_actions, get_solver_capabilities, and recommend_action.

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?

Annotations already disclose readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds value by enumerating the categories of information returned (identity, contract version, effects, assumptions, limits), but gives no format, stability, or freshness detail beyond that enumeration.

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?

A single front-loaded fragment with no filler; every term maps to a returned content category. It is arguably overly compressed, but nothing in it is wasted.

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?

Low-complexity, zero-argument tool with full annotation coverage and no output schema; the description is the only source of return-value information and it names the main content categories. A slightly richer statement of what the returned identity/limits look like would make it fully self-sufficient.

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 tool takes zero parameters, so the baseline is 4. There is nothing for the description to clarify beyond the (empty) schema, and it does not introduce any parameter confusion.

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 name plus description make it clear this is a metadata/introspection tool that reports the engine's identity, contract version, supported effects, assumptions and limits. It is cleanly distinguishable from the action-oriented siblings (compare_actions, evaluate_hand, recommend_action). However the description itself is a telegraphic noun list with no verb, so it leans on the tool name to state what it actually does.

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?

There is no when-to-use guidance at all, and no mention of the alternative siblings. For a capabilities endpoint the obvious guidance ('call this before invoking the solver to learn what it supports') is absent, leaving the agent to infer the invocation context.

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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description adds genuine context: results are exact model math rather than estimated real-game success, all optimal ties are returned, draw explanations are reconciled, and no recommendation is produced on incomplete jobs. The caveat about model vs. real-game success is exactly the kind of expectation-setting that prevents misuse.

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?

Three tight sentences with the central claim front-loaded and no filler; exclusions are appended efficiently. Slight cost from dense, undefined jargon, but every sentence carries information.

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 6-parameter, deeply nested, no-output-schema tool with zero schema descriptions, the description should explain the input contract and return shape. It covers the conceptual scope well but leaves the entire parameter surface and the result structure ('all optimal ties', 'reconciled draw explanations') undefined, which is a material gap for correct invocation.

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% across 6 parameters including a deeply nested state object, so the description carries the full burden and fails to document any parameter (contract_version, analysis_mode, explain_actions, budget_score_calls, request_id are all unmentioned). It gives no hint about the card-string encoding, the level structure, or what explain_actions accepts. The mention that ties/draw explanations are returned loosely implies explain_actions but adds no semantics.

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 conveys that this computes exact action values (play/discard choices) under optimal continuation for a small-deck model, which is a real verb+resource statement. However, phrases like 'the supported model' and 'exact_blind_survival' are never grounded, and it never plainly says it recommends the best action nor contrasts itself with evaluate_hand or compare_actions. Useful but leaves an agent inferring the core purpose.

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?

There is implied scope ('no recommendation on incomplete jobs', 'No A2/full-deck sampling'), which are exclusions of a sort, but they are stated as opaque jargon with no explanation of what A2 or a 'job' is. Nothing says when to call this versus compare_actions or evaluate_hand, and no prerequisites are given.

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