Contract Liquidity

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

Far beyond the readOnly/idempotent annotations, the description discloses cache-first semantics ('engine re-reads the pool every ~10 min in market hours'), the `live=true` force-fetch escape hatch, update cadence for each metric (OI once each morning, day_volume live), and the critical design decision that bid/ask/mid/spread are deliberately absent rather than NULL. This prevents an agent from misinterpreting missing spread data as an error.

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 dense but every section earns its place: mode semantics, freshness/absence caveats, and parameter docs all matter for correct invocation. The structure is clean (bolded mode headers, trailing Args block), but the opening sentence is grammatically awkward ('the read the pool's session-frozen ... cannot give you') and could be tightened.

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 dual-mode tool with cache behavior, staleness semantics, and an absent-fields caveat, the description covers everything an agent needs: mode routing, defaults, constraints, refresh intervals, and what metrics to substitute for missing spread data. The output schema covers return structure and annotations cover the safety profile, so nothing critical is left unspecified.

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 description coverage is 0%, and the Args section fully compensates: `contract` is specified as an OCC ticker 'verbatim from the pool's `recommended_contract`' and as the mode-switch trigger, `contracts` carries the max-60 constraint, `scan_date` gets a YYYY-MM-DD format plus default ('latest pool'), and `live` is scoped to single-contract mode. Every parameter gains meaning the schema alone cannot convey.

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 by positioning the tool against the pool's session-frozen `recommended_oi`/`recommended_volume`, then crisply defines the two modes: a single-contract snapshot and a whole-pool batch call. The resource (contract liquidity) and the operation (read/fetch) are unambiguous, and the contrast with `get_pool`'s frozen data helps an agent tell siblings apart.

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?

Mode selection is made explicit ('chosen by whether you pass a single `contract`'), the batch mode is positioned as 'the batch companion for the ~10:00 ET decision window', and the description tells the agent what NOT to use this for (no bid/ask/mid/spread) and which fields to judge fill risk from instead. It does not explicitly name sibling alternatives like `get_pool` or `get_signal` as when-not-to-use options, so the exclusion guidance is slightly implicit.

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