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

The annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds substantial behavioral context beyond that: 'Cached 1h at the KV level keyed on all knobs', the 24h-move warning when the recent move exceeds the edge, and the _diagnostics block with funnel counters explaining why segments are empty. These details are not redundant with annotations and help the agent anticipate response behavior.

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 front-loaded with the main purpose, but it is a single monolithic paragraph with long run-on sentences and no bullet points or section breaks. While every sentence carries useful information, the lack of structure makes it harder to parse; it would benefit from separating the model families, response structure, and knobs into clearly labeled sections.

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 return values, and it does thoroughly: it lists the fields carried by every opportunity (edge_pp_net, kelly_fraction, liquidity, etc.), the top-level response structure (by_segment, fed_candidates, _diagnostics), and even the reasons for empty segments. Combined with the parameter explanations and caching behavior, the description is complete for the tool's complexity.

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 baseline is 3, but the description adds significant value beyond the schema. For example, min_liquidity is described as 'drop thin-book opportunities where executing the edge would walk the book past breakeven', and min_partition_leg_kelly is explained in relation to min_kelly, clarifying that basket trades always return kelly_fraction_half=0 at the parent level. This rationale and usage guidance go far beyond the schema's 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?

The description opens with 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' which clearly states the verb (scan/return), resource (Polymarket markets), and purpose (opportunity discovery). It further differentiates from siblings by identifying the use case 'what should I bet on today' and noting it avoids paging hundreds of markets.

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 the tool ('what should I bet on today') and explains the three response segments and tradeable-edge knobs, including when to apply filters like min_liquidity and max_spread_pp. However, it does not explicitly name alternatives or state when not to use this tool compared to sibling tools like polymarket_arbitrage, so it lacks explicit exclusions.

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