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

While annotations already declare read-only, idempotent, and non-destructive behavior, the description adds substantial context: caching at the KV level keyed on all knobs, diagnostics to explain why segments are empty, per-model-family details (including alpha values and thresholds), the 24h-move warning, and the rare-by-design nature of concentrated longshots. It also clarifies the fed-bet exclusion rationale. No contradictions 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 long but well-structured with explicit segment headers and lists. It is front-loaded with the core purpose and quickly moves into actionable details. Some content is repeated (e.g., kelly_fraction details appear twice) and the alpha constants could arguably live in schema, but every section earns its place given the tool's complexity.

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?

With no output schema, the description carries full burden of explaining return values, which it does thoroughly: top-level by_segment structure, diagnostics, fed_note, and per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, etc.). It also explains the meaning of empty segments and the effect of knobs. This is a complete picture for an agent to use the tool effectively.

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 coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by grouping knobs as 'tradeable-edge knobs,' explaining the rationale behind defaults (e.g., slippage_pp references Polymarket's zero fees and typical 20-50bp costs), and clarifying the interaction between min_kelly and min_partition_leg_kelly for partition arbs. This is more than mere restatement.

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 and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly states the tool's purpose as a discovery mechanism for betting opportunities, and distinguishes itself by noting it avoids paging hundreds of markets. The three response segments further clarify the scope.

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 frames usage as 'what should I bet on today' and explains that it discovers opportunities without scanning hundreds of markets, implying it is the go-to screening tool. It also provides a specific exclusion note about fed bets being unreliable and excluded from ranking, which is a clear usage caveat. However, it does not name sibling alternatives or explicitly state when another tool should be used instead.

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