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

The description extensively discloses behavioral traits beyond the readOnly/idempotent annotations: it details the three response segments, the five model families within them, the edge metrics (edge_pp_net, kelly_fraction, etc.), the 24h-move warning, and the caching policy. It also explains that Fed bets are excluded from ranking due to data limitations, and that diagnostic counters are included to explain empty segments. This far exceeds the annotation baseline.

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 verbose but front-loaded with a clear purpose sentence. It packs a great deal of technical detail (model family thresholds, sports-specific alpha values, funnel counters) into a dense wall of text. While well-structured with segmented clauses, it is longer than necessary and would benefit from a brief usage summary or bullet points. It's informative but not concise.

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?

There is no output schema, so the description must explain the return structure. It does so thoroughly, listing the top-level fields (by_segment, fed_candidates/fed_note, _diagnostics) and the per-opportunity fields. It also covers edge cases (e.g., empty segments via diagnostics, Fed bets excluded). Given the tool's complexity, the description is highly complete.

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 covers 100% of the 9 parameters with descriptions, so the baseline is 3. The tool description adds significant value by explaining how min_kelly interacts with partition_arbs (never filters them, applies per-leg instead) and clarifying the role of min_liquidity/max_spread_pp as 'tradeable-edge filters.' This context is not present in the schema and is crucial for correct usage.

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+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly states the tool's purpose and differentiates itself by focusing on opportunity discovery for 'what should I bet on today' without paging hundreds of markets, and by describing three response segments (model_driven, structural_arbitrage, concentrated_longshot) that distinguish it from sibling tools.

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 a clear use case ('what should I bet on today') and explains when to use it for discovering opportunities without exhaustive market paging. It also explains how the tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly) can be used to filter results. However, it does not explicitly mention when not to use this tool or point to alternatives (e.g., polymarket_arbitrage for pure cross-market arbitrage), so it's clear but lacks exclusion guidance.

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