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

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses extensive behavioral details: the response segmentation under by_segment, edge calculation net of slippage, Kelly fractions capped at 0.25, the 24h-move warning, partition overround design with placeholder-slug filters, the 'rare-by-design' nature of concentrated_longshot, and the 1h caching keyed on knobs. It even explains why partition arbs return kelly_fraction_half=0 at the parent level, giving callers essential internal knowledge.

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 highly detailed and systematically structured with all-caps section headers (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL), making it scannable. However, it is very long and includes some duplication of schema parameter descriptions. While every sentence adds useful information, the sheer length makes it less concise than ideal for an agent to parse quickly.

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 the tool's complexity (9 optional parameters, no output schema), the description is remarkably complete. It thoroughly explains the response structure (by_segment, fed_candidates/fed_note, _diagnostics), the reasoning behind filters, and even the caching behavior. Callers would have a clear mental model of what to expect and why certain segments might be empty, making this a fully self-contained description.

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 provides 100% parameter coverage with detailed descriptions, so the baseline is 3. The tool description adds meaningful context beyond the schema, such as the 'TRADEABLE-EDGE KNOBS' overview and the critical explanation for min_partition_leg_kelly (that partition arbs always return parent-level kelly=0, so this knob filters per-leg instead). This extra context justifies 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+outcome: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further clarifies the intended use case ('Built for "what should I bet on today"'), clearly distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker by focusing on edge discovery from Pipeworx data.

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: for daily discovery of betting opportunities without paging hundreds of markets. It also gives detailed guidance on knobs (e.g., min_liquidity/max_spread_pp to drop unrealizable edges) and a caveat about Fed bets being unreliable. However, it does not explicitly name alternative tools or state when NOT to use this tool in favor of a sibling, so it stops 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.