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

The description provides rich operational transparency for a paid endpoint: cost in credits and USD, the 402 payment-envelope behavior, and two auth paths (X-API-KEY on the MCP connection or x402 out-of-band). Since no annotations are present, this information is genuinely valuable and exceeds what structured fields would have offered. The only gap is that core runtime semantics ('running count', 'empirical posting distribution') remain weakly explained, but the cost/auth/error disclosures are exemplary.

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 information-dense and covers a wide surface area (semantics, pricing, auth, error behavior) in a compact space, but it reads as one long run-on of em-dash-laden clauses with no sentence or paragraph breaks. Pricing details ('$1.70-$2.49/credit by pack size') could arguably be trimmed or moved, and the dense structure makes parsing harder than necessary. Every sentence earns partial keep, but the lack of structural signposting hurts scannability.

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?

For a paid tool with no annotations and no output schema, the description covers the most mission-critical contexts: payment flow, auth, error handling, and a concrete example. It also acknowledges a dependency path for more param docs. However, return-value shape is never described (no output schema, and the description doesn't compensate), and the core semantics are still uncertain without external domain knowledge, so it falls just short of a 5.

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?

With 0 schema parameters, the baseline is 4, and the description does document the ?handle= query parameter ('?handle=elonmusk narrows'), adding real usage semantics. The schema defers all parameter documentation to a separate 'instruments' tool, which shifts burden, but the description's example with the handle parameter partially compensates. Slight deduction for relying on an offloading reference rather than documenting the parameter shape directly.

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 attempts to define the tool ('Polymarket weekly tweet-count bin scan') with specific, domain-specific detail, and clearly distinguishes it from a bare tautology. However, it lacks a clear verb+object structure, and phrases like 'best band-disjoint divergence' are nearly impenetrable, leaving the central purpose murky even to a semi-informed reader. It's specific in intent but the clarity is compromised by dense, unexplained quant jargon.

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?

There is useful operational guidance: the tool is paid, auth is via X-API-KEY or x402, and uncredentialed calls return a 402 envelope. However, given ~45 scan_/signal_ siblings (e.g., signal_polymarket, scan_compare), there is no explicit instruction on when to choose this tool over alternatives, and no exclusions are stated. Usage context is implied via pricing and auth details rather than explicitly framed as 'use when...'.

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