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

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 "rare-by-design" nature of concentrated longshots with explicit gate values, the Fed disclaimer about unreliable signals, and the "24h-move warning" that the edge may already be priced in. This gives agents a rich understanding of how the tool behaves and its limitations.

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 its core purpose in the first sentence, then each subsequent section delivers dense, non-redundant operational detail—model families, response structure, per-opportunity fields, filters, and caching. While long, every sentence earns its place for a tool of this complexity, and there is no filler or repetition of schema information.

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 fully documents the response shape: "RESPONSE TOP-LEVEL: by_segment{...}, fed_candidates/fed_note..., and _diagnostics{...}" plus the per-opportunity fields like edge_pp_net, kelly_fraction, liquidity, and the 24h warning. It also explains why segments can be empty (top-N stale, gates, knobs), making the tool actionable even in edge cases.

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 has 100% parameter coverage with detailed descriptions for all 9 parameters, so the baseline is 3. The description adds extra semantics by explaining how knobs interact: "TRADEABLE-EDGE KNOBS: min_liquidity / max_spread_pp drop opportunities where edge isn't realizable" and "min_kelly never filters them" for partitions. It goes beyond the schema's per-parameter text, earning 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 first sentence states a specific verb+resource+scope: "Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price." It also distinguishes itself from siblings by explicitly targeting the "what should I bet on today" discovery use case, avoiding the need to page hundreds of markets, which separates it from tools like polymarket_arbitrage or 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 clearly frames when to use the tool: "Built for 'what should I bet on today' — agents discover opportunities without paging hundreds of markets." It also provides practical guidance on knobs like min_liquidity and max_spread_pp to drop unrealizable edges. However, it does not explicitly name alternatives or state when not to use this tool versus related siblings, so it falls short of a 5.

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