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

The description adds substantial behavioral detail beyond the annotations: it explains the partition-check mechanism, semantic similarity threshold (Jaccard ≥ 0.30), placeholder filtering, and the fill-check logic with realizable edge. It clearly warns 'do not trade it' when realizable_edge_pp ≤ 0, and the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are consistent with this read-only analytic description. No contradictions.

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 and every sentence adds unique value. It front-loads the core purpose, then uses bolded labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to organize complex behavioral rules. No filler or redundant statements.

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 (two modes, multiple filters, output schema absent), the description covers response shapes, thresholds, edge cases, and failure signals (e.g., 'skipped_low_similarity surfaces the rejected pair count'). It even provides usage guidance for when the partition signal fires. This is as complete as needed for an agent to select and invoke the tool correctly.

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%, but the description goes far beyond the schema by explaining not just what each parameter is but how the tool uses it: event slugs are resolved via walking child markets, topic seeds are expanded via search and flattened, and each mode returns different signal structures. It also provides concrete example values that illustrate the expected format.

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three modes (trending_scan, event, topic) and contrasts with sibling tools by describing unique mechanisms and output types.

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 when-to-use guidance is provided: 'Call with NO args for a trending_scan', pass `event` for a specific market, or `topic` for cross-event scanning. It also gives examples of valid inputs, explains when `topic` is preferred ('catches ... patterns that single-event misses'), and directs users to `polymarket_fill_risk` for custom sizing—an explicit alternative.

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