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

Beyond the readOnly/idempotent annotations, the description discloses rich behavioral details: SEMANTIC ANCHOR (Jaccard similarity ≥0.30), PARTITION FILTER (placeholder fraction >20% returns null), response structure, and FILL CHECK logic (theoretical vs realizable edge, 'do not trade it' if ≤0). These caveats help the agent understand not only what is computed but also the limitations and edge cases.

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 deliberately structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and paragraph breaks for modes. It front-loads the core purpose and each subsequent sentence adds necessary operational detail for a complex tool. No sentence feels wasted; the length is appropriate for 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?

Without an output schema, the description compensates by detailing the response fields: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and the partition_check object in event mode. It also covers filtering rules, fill checking, and points to an alternative tool, making the behavior fully comprehensible to an agent.

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?

Although the input schema already describes both parameters, the description adds deep behavioral context: event 'walks child markets, checks date-axis / threshold-axis ordering AND computes the partition_check', while topic 'searches related events across the platform, flattens markets, runs the comparator on the union'. It also explains the no-args case, which is not in the schema, and provides concrete slug/seed examples.

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This clearly distinguishes the tool from siblings like polymarket_edges or polymarket_fill_risk, and explains its unique methodology. The three modes (no-args, event, topic) 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 tells when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It names an alternative tool for custom sizing ('For custom sizing use polymarket_fill_risk'), and includes a caution about not trading when the fill check shows no realizable edge. This provides clear decision guidance.

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