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

The description goes far beyond the readOnlyHint/idempotentHint annotations, revealing specific thresholds (>3pp deviation), filtering logic (Jaccard ≥0.30), placeholder-slug handling, and the fill-check behavior. It even explains the meaning of null arb signals and that a zero realizable edge means the overround is not in the book. This is rich, non-obvious context that directly informs agent decision-making.

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 highly structured. It begins with the core purpose, then logically moves through mode selection, semantic anchor, partition filter, response format, and fill-check guidance. Every sentence carries operational weight, and the section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) make the content scannable. No filler or redundancy.

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 present, the description compensates by enumerating response fields: opportunities[] with gap_pp, suggested_trade, reasoning; partition_check with sum_yes_prices, gap_from_1, placeholders_filtered; and fill_check with theoretical vs realizable edge. It also covers mode-specific behavior, thresholds, return signals, and safety warnings, making it fully adequate for complex arbitrage scanning without requiring external lookups.

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?

While the schema already describes `event` and `topic`, the description adds significant meaning beyond the schema's short definitions. It details what happens in each mode: event walks child markets and checks date-axis/threshold-axis ordering; topic flattens related events and runs comparator on the union. It also provides concrete example slugs and seed questions, substantially enriching the semantic understanding of each parameter.

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, action-oriented statement: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It then clearly enumerates three invocation modes (no-arg trending scan, event, topic), which distinguishes it from sibling tools like polymarket_edges and polymarket_fill_risk. The purpose is concrete and unambiguous.

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?

Explicit usage direction is provided for each mode: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', and 'pass topic for a themed cross-event scan.' It also gives alternative guidance with 'For custom sizing use polymarket_fill_risk' and warns against trading when realizable_edge_pp ≤ 0. These are clear when-to-use and when-not-to-use signals.

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