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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description goes well beyond by disclosing null semantics ('executable_in_band is null when no live mid was captured; it is never guessed'), flat sizing ('Flat 0.5 unit sizing'), ordering ('Ordered by event start time only — not a quality ranking'), exclusions ('compound_confidence is not included'), and authentication requirements. No behavioral aspect is left undisclosed.

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 long but each sentence earns its place by adding distinct, useful information. It is front-loaded with the core purpose, then the delta from get_oracle_board, then specific field semantics, sizing/ordering, auth, and finally parameter docs. It is structured and not repetitive, though it could be trimmed slightly without losing value.

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?

The tool has substantial complexity: multiple gates, null behavior, sizing, ordering, auth, and parameter nuances. The description addresses all of these. An output schema exists, so return format is covered separately. Nothing an agent needs to call this tool correctly is missing.

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 carries full responsibility for both parameters. It adds real meaning: 'sport' gets example values and the instruction to omit for all sports, and 'limit' gets a range (1-60) and a clear 'Max plays' semantic. This exceeds the bare schema types and gives an agent enough to pick correct inputs.

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 opens with a specific verb+resource: 'Return the Oracle board plus whether each whale fill is still buyable.' It then differentiates from the sibling get_oracle_board by naming the exact additional fields (executable_price and executable_in_band) and the shared gates, so an agent can instantly tell what this tool does and how it differs.

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 references get_oracle_board as the base and explains the added value, which implies when to use this tool (when buyability matters) vs. the sibling. It also provides explicit usage conditions (Premium/MCP Pro requirement) and clarifies that empty results are normal. However, it does not name any other alternative tools or state a hard 'use this only when X' rule, so it stops short of exhaustive routing guidance.

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