GammaRips Options Intelligence

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds valuable behavioral details beyond annotations: default date falls back to the most recent report, list view dedupes titles, and limit is clamped to 1-30. This clarifies response behavior without contradicting the annotations.

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 well-organized with a clear overview, bullet-like view explanations, and a short Args section. Every sentence contributes useful information, and the most important distinction between views is front-loaded.

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?

The tool has no output schema, so the description correctly explains what each view returns: report view includes title, markdown content, and scan_date; list view includes scan_date, title, and created_at. Combined with parameter semantics and defaults, the agent has everything needed to call 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 description coverage is 0%, so the description must fully explain parameters. It does: date is a YYYY-MM-DD string for the report view, view selects between 'report' and 'list', and limit controls list count with default and clamp. This adds all necessary meaning beyond the bare schema.

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 clearly identifies the tool as 'The daily intelligence report' with two specific views, 'report' and 'list'. This distinguishes it from sibling tools like get_pool or get_signal, and the resource and actions are explicit.

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?

The description provides clear usage context by explaining when to use each view, including default behavior when date is omitted and the purpose of limit. It does not explicitly mention when not to use this tool versus a sibling, but the domain is distinct enough that no conflicting alternative exists.

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

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.

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

Annotations already mark the tool as read-only, idempotent, and non-destructive; the description adds that it is NYSE-calendar-based, deterministic, and explicitly avoids hallucinating market-open status. It also discloses what each view returns, which goes beyond the annotations alone.

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 compact, front-loaded with the core purpose, and uses bulleted view explanations that are easy to scan. The closing Args section succinctly restates the parameter options without unnecessary detail.

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 one-parameter read-only tool with no output schema, the description covers both views and their return semantics well. No critical invocation detail appears missing; the agent can correctly select the view and understand what to expect.

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?

The input schema only provides a default for the single `view` parameter, so the description carries the full burden. It names the two allowed values and their exact meanings, fully compensating for the 0% schema description coverage.

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 clearly identifies the tool as a market-calendar reference and specifies exactly what each view returns: market open status, next open/close, holiday and early-close flags, or scan dates with signal counts. This distinguishes it from sibling tools like get_liquidity or get_daily_report by domain and resource.

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?

The description provides clear context for choosing between the two views, naming the default and explaining what each view is for. It does not explicitly discuss when to use this tool instead of a sibling, but the use case is unambiguous from the description.

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

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

The description adds substantial behavioral context beyond the readOnly/idempotent annotations: it is versioned server-side and should be re-fetched rather than cached long-term; field lookup is deterministic with no LLM; `field` overrides `name`; and the data contract marks only `feature` columns as safe selection inputs. This significantly helps an agent use the tool safely and correctly.

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 detailed but efficiently organized with a short opening, a bulleted arg-driven breakdown, and a compact parameter list. Every sentence adds useful information, and the structure makes the branching behavior easy to parse. The length is justified by the tool's multi-mode behavior.

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?

With no output schema present, the description must explain return values, and it does: field mode returns a definition plus an `available_fields` list, schema mode returns a data contract with leakage classifications, named playbooks return markdown, and no-args returns a catalog. The precedence rule and safe-feature caveat complete the picture for correct invocation.

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?

The input schema has 0% description coverage, so the description carries the full burden of explaining both parameters. It fully documents valid values for `name` (including special values "schema" and "data-contract"), explains `field` with an example, and explicitly states precedence: `field` overrides `name`.

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 resource (methodology playbook/reference) and enumerates exactly what the tool returns in each mode: field definitions, named playbooks, the data contract, or a catalog. It clearly differentiates itself from sibling tools like get_signal or get_pool by scoping its content to methodology and reference rather than live market data.

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?

The description gives explicit argument-driven usage rules: if `field` is given, look up a field definition; if `name` is given, return a playbook or special schema page; if neither, return the catalog. It does not explicitly discuss when to prefer a sibling tool, but the mode routing is clear enough that an agent can decide when this tool is appropriate.

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

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

Far exceeds the readOnly/idempotent/non-destructive annotations by disclosing leakage-safe construction (outcome columns physically stripped), per-view freshness (features lag 1-2 trading days), snapshot semantics for recommended_oi/recommended_volume, permanent NULL for recommended_spread_pct, subscription gating (anon calls return subscription_required), and the two-era population discontinuity. No statement contradicts the annotations.

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?

Purpose is front-loaded in the first sentence, and the body is partitioned with clear markers (view bullets, TIER:, Liquidity caveat:, Args:) so an agent can locate the relevant section quickly. Though long, the density is high: each paragraph covers a distinct concern (view semantics, access tier, data caveats, parameters) with no filler or repeated boilerplate. The length is proportionate to the tool's complexity.

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?

With no output schema present, the description compensates by describing each view's return shape: enriched has ~21 decision columns and names key fields (news, technicals, catalyst, recommended contract, mom_60); preview names its five fields; features is scoped to identity+features+cohort metadata; raw is the wide pre-cut scan. It also covers error behavior (subscription_required), defaults, pagination, and the liquidity caveat. The only absence is an exhaustive column-name list for the fields projection, which no schema exists to supply.

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 description coverage, the Args section carries the full load and documents all nine parameters: allowed values for view, per-view applicability (min_score raw-only; summary/fields/offset enriched-only), clamps (enriched/raw 1-50, features 1-100, preview 1-20; min_score 0-10), and the YYYY-MM-DD format for scan_date. The schema itself only supplies titles and defaults, so this section is the agent's sole source of semantic meaning.

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?

Opens with a specific verb+resource statement ('The GammaRips candidate pool for a scan date') and decomposes the tool into four distinctly described views, each with its own funnel logic, era, and output scope. It names related siblings (get_playbook, query_outcomes, get_liquidity) so the tool's role in the workflow is unambiguous. An agent can tell this from every sibling without opening another schema.

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?

Explicitly directs when to use which view: enriched as the daily reasoning set for the agent's own contract, raw as the pre-cut scan, features for joining against query_outcomes, and preview as the named free entry point. It also names get_playbook('run-your-own-tournament') for the downstream step and get_liquidity for re-checking stale or NULL liquidity fields, and states the paid-versus-free tier rule that determines whether a call is even worth attempting.

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

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

Beyond the readOnly/idempotent/destructive annotations, the description explains the fail-closed backwardation rule, the leakage-safe as-of semantics, the 1-2 day substrate lag, and the constancy of values per scan_date. This gives the agent a clear behavioral model without contradicting the annotations.

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 front-loaded with the core purpose, then structured into rail explanation, data freshness caveat, args, and returns. Every sentence adds substantive value; no filler or repetition.

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 single optional parameter and an output schema, the description covers the return shape, parameter semantics, safety interpretation, and data lag. An agent has enough to call the tool correctly and interpret its result without further documentation.

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?

The input schema only provides a nullable string with a default of null, but the description compensates fully by specifying the YYYY-MM-DD format and the default behavior (latest scan date carrying regime features). For a single optional parameter, this is complete.

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 clearly identifies the tool's resource and purpose: point-in-time market-regime context for a scan date, including VIX, VIX3M, SPY trend, VIX delta, and the regime safety rail. It does not explicitly differentiate from the listed siblings, but its domain is distinct enough that an agent can infer what it provides.

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?

The implied use case is retrieving regime features for a scan date, and the description gives helpful caveats about substrate lag and leakage-safety. However, it does not explicitly state when to choose this tool over siblings or when not to use it.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds substantial behavioral context beyond that: fail-closed behavior for unknown earnings dates, leakage-safe point-in-time features, the engine applying earnings rails only at pick time, and the error listing alternate dates when a ticker is not in the pool. None of this contradicts the annotations.

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 well-organized with a brief lead sentence, labeled views, and an Args block. It is detailed but every sentence adds necessary information such as defaults, fail-closed semantics, or leakage safety. No filler or redundancy.

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 tool with 6 parameters, two modes, zero schema descriptions, and subtle behavioral rules, the description covers everything an agent needs to invoke it correctly: parameter semantics, defaults, edge cases, derivation rules, and error behavior. Since an output schema exists, not detailing return values is acceptable.

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%, so the description carries the full burden. It compensates thoroughly: each parameter is explained with defaults, required/optional status, view restrictions, and derivation rules (e.g., 'contract' supplying both ticker and expiration). This is far beyond what the bare schema provides.

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 and resource: 'Deep dive on a single ticker/contract.' It then enumerates two distinct views with concrete outputs, making the tool's purpose unambiguous and clearly distinguishable from sibling list/dashboard tools.

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?

The description gives detailed context for choosing 'detail' vs 'earnings', including defaults, derived parameters, and the important instruction to check every candidate yourself because pool rows can carry earnings-window names. However, it does not explicitly contrast with sibling tools, so the 'when to use vs alternatives' aspect is left mostly to inference.

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

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

Annotations already mark this read-only, idempotent, and non-destructive; the description adds rich non-obvious behavior beyond that: the 200-row surface cap truncates oldest-first and reports truncated/matched_rows/partial_scan_date, null aggregates mean not measured yet rather than zero, and policy_version 'all' returns repudiated cohorts that must not be aggregated. It also warns fixed-exit composites are negative by construction and that data is closed-window paper research.

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 structure is excellent: high-level framing, bulleted views, then a parameter list, with the most important caveats front-loaded in the first paragraph. Its length is mostly justified by the tool's complexity, but it is not tight: policy_version/null semantics are explained twice and non-actionable boilerplate such as 'not investment advice' adds little.

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 high-complexity tool with no schema descriptions and no enums, the description is unusually complete: it covers return units, truncation behavior, cohort caveats, null conventions, and view-specific modes. It still leaves some string filter values implicit (e.g. allowed direction, outcome, and exit_reason values, and the expected scan_date format), and an output schema exists so return-shape details are not needed here.

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 description coverage and 26 parameters, the description carries the full burden and succeeds: it explains per-view filter applicability, horizon defaults, limit ranges, aggregate_only behavior, include_open semantics, and policy_version's pair-plus-cohort_start meaning. It also clarifies tricky distinctions such as same_day vs 3d and labels vs surface modes.

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?

Opens by identifying the tool as the realized-outcome and receipts substrate and then enumerates nine named views with distinct resources and verbs, e.g. labels row-level realized bracket labels, surface MFE/MAE excursions, positions receipts. This makes the tool's purpose unmistakable and separates it from the sibling signal/pool/report tools.

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?

Each view bullet is an applicability rule: aggregate_only on surface is explicitly 'use it for exit design', exit_rule is 'RESEARCH-ONLY bring your exit, we score it', and positions/performance are defined as receipts vs cohort aggregates. Negative guidance is also explicit: never pooled, never a strategy track record, NOT option PnL, and don't render null aggregates as results.

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

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

The description reveals several behavioral traits beyond the readOnly/idempotent annotations: it does not simulate exits, it serves first-crossing sequences from the tape, minute paths have a specific engine-table fallback, tape is thin so absent bars are meaningful, and touch times are evidence rather than tick-perfect truth. These details materially shape how an agent interprets results.

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 organized with a clear lead sentence, two bulleted mode explanations, a data-caveat paragraph, and a structured Args list. Every sentence adds operational value, and the most important scoping information ('does NOT simulate or validate exits') is front-loaded. Despite its length, it is efficiently structured for a 7-parameter tool with dual modes.

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?

The description covers mode-specific behavior, parameter semantics, defaults, constraints, data-quality caveats, and explicitly disclaims investment advice. An output schema exists, so detailed return-structure documentation is not required from the description. There are no significant gaps that would prevent an agent from invoking 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 description coverage is 0%, so the description must carry all parameter semantics. It delivers with an Args section that explains each of the 7 parameters, including required/optional status, defaults, format examples (e.g., OCC ticker, YYYY-MM-DD), mode-specific applicability, and behavior such as 'date is ignored' in day mode and the 120-day cap on from_date/to_date.

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 precise statement: 'Raw option price data for YOUR OWN entry/exit rule', then clarifies that the server does NOT simulate or validate exits and returns bars. It clearly identifies the resource (option price bars), the verb (replay/return), and the two granularity modes, making the tool's role unambiguous relative to simulation-type siblings.

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?

The description gives explicit usage context for each granularity mode: minute for a single intraday session with an optional bracket, day for daily OHLCV to mark or replay a paper position. It also states exclusions: 'does NOT simulate or validate exits' and 'date is ignored' in day mode. However, it does not explicitly name sibling alternatives like get_signal or get_playbook, so the 'when-not-to-use' guidance is implied rather than directly referencing other tools.

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