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

No annotations are provided, so the description carries the full burden. It discloses the default window (72h), the output structure (score, triggered signals, top 5 positioners, methodology), and the aggregated nature of the scan. It implicitly conveys a read-only operation via 'returns', but it does not explicitly state side-effect freedom or auth requirements.

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?

Single cohesive paragraph that front-loads the core purpose and lists the 5 signals efficiently. It is dense but all information is relevant, no redundancy, and it covers inputs, outputs, and defaults without excessive length.

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?

No output schema exists, so the description must explain return values – it does thoroughly (score, CLEAN/CRITICAL categories, evidence, top 5, methodology). For a complex tool with 4 parameters and 5 signal types, it covers all essential behavioral and output aspects with no obvious critical gaps.

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%, so baseline is 3. The description adds meaning by explaining the window is 'before market end' and that min_position_usd is the threshold for flagging large positions, enriching the schema's basic descriptions for these parameters.

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?

States 'Real-time insider-trading signal scan for a single Polymarket market' – a specific verb (scan) and resource (Polymarket market). It enumerates 5 distinct signal types, clearly differentiating it from sibling tools that focus on individual signals like pg_position_timing_anomaly or pg_pre_event_flow_analysis.

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?

No explicit when-to-use or alternative recommendations. It implies usage for single-market insider signal scanning, but does not contrast with sibling tools such as pg_market_integrity_scan or pg_information_advantage_score, leaving the agent to infer placement.

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