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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context on top: it requires a QuantGeeks plan, it makes the call prompt for sign-in, return contents vary by plan tier, `fresh` and `age_min` appear only while the session is open, and changes are capped at 12 unless `detail` is 'all'. These are exactly the behavioral traits an agent cannot infer from structured fields.

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?

Every sentence carries information, but the paragraph is dense and back-loaded — the access/plan caveats occupy the opening position while the actual return shape arrives third. It reads as one packed block rather than a front-loaded statement of purpose followed by usage detail, which makes scanning harder than necessary.

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?

Seven parameters with a nested `history` object and an output schema mean the description need not explain return formatting, and it correctly focuses on plan-dependent variability and the VEX-vs-gamma distinction. What it does not cover is failure behavior beyond the sign-in/plan case — e.g. what happens for a symbol with no derived readings — but for a read-only analytical tool this is close to complete.

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 the baseline would be 3, but the description adds real meaning beyond the schema: the 60-point ceiling on `history`, the 12-change cap that `detail` 'all' lifts, the HH:MM ET format expectation, and the fact that node readings here are VEX/vanna rather than the ladder's gamma nodes. That last point materially affects how a caller interprets the returned numbers.

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 states a specific verb+resource: it returns derived readings for a symbol or GLOBAL, including a single `bias` whose provenance (regime read for SPX/SPY/QQQ when the plan includes reads, otherwise the reading's own) is spelled out. It also explicitly distinguishes itself from quantgeeks_get_gex_ladder (gamma nodes at a time) and quantgeeks_get_node_history (over time). The only drag is that the first two sentences are about access gating, which delays the actual purpose statement.

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?

It gives concrete modes of use — default latest values, or supply `at` (HH:MM ET), `history` {from,to,every_min>=5}, or `metric` to narrow — and names the sibling tools to use instead for gamma nodes at a time or node history over time. What is missing is a clear statement of when to reach for this tool at all versus, say, quantgeeks_get_regime_reads or quantgeeks_read_the_board, but the exclusions it does give are precise.

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