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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, but the description adds substantial behavioral detail beyond that: caching behavior ('Cached 1h at the KV level keyed on all knobs'), why segments may be empty (via _diagnostics), the 24h-move warning ('your edge may already be in the price'), slippage assumptions, and the rare-by-design nature of concentrated longshots. There is no contradiction with annotations.

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 dense and long, incorporating many parentheticals and embedded lists. It is organized with capitalized section labels (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, etc.) and does front-load the core purpose, but it reads as a wall of text. While every sentence contributes information, it could be restructured with bullets for readability. Thus it is not as concise as it could be.

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 no output schema and complex behavior, the description is remarkably complete: it explains the top-level response (by_segment, fed_candidates, _diagnostics), the three model families with their sub-signals, the tradeable-edge knobs, the funnel counters, and caching. It also warns about the Fed signal unreliability. This fully compensates for the lack of an output schema.

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 already covers 100% of parameters with detailed descriptions, so baseline is 3. The description adds extra meaning beyond the schema by explaining the interaction between min_kelly and partition overround (min_kelly never filters partitions because they return 0 at parent level) and clarifying the purpose of min_partition_leg_kelly. This adds value beyond the schema, justifying a 4.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also states the intended use case ('Built for "what should I bet on today"'), and the details on model families and response segments clearly distinguish it from siblings like polymarket_arbitrage, polymarket_edge_tracker, and polymarket_fill_risk.

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 gives clear usage context: 'agents discover opportunities without paging hundreds of markets' and describes tradeable-edge knobs for refining results. It does not explicitly name when NOT to use it or compare it to alternatives, but the Fed-bet warning ('unreliable at meeting-month horizons') provides a specific exclusion case. Thus clear context but no explicit alternative guidance.

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