GammaRips Options Intelligence

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds valuable behavioral detail beyond that: defaulting to the most recent report when date is omitted, deduplicating titles in list view, and clamping limit between 1 and 30. It also describes the fields included in each view, which is useful context.

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, well-structured, and front-loaded with the two main views. The bullet-style view explanations and short Args section convey a lot of information without wasted words 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?

Given the absence of an output schema, the description adequately explains both the input parameters and the expected return fields for each view. The annotations cover safety and idempotency, and the description covers behavior, defaults, and constraints, so an agent has a complete picture for using this 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 coverage is 0%, but the description fully compensates by explaining the meaning, format, defaults, and valid values for all three parameters: date uses YYYY-MM-DD, view accepts 'report' or 'list', and limit is clamped to 1-30. This gives the agent everything needed to construct correct calls.

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 states the tool provides 'the daily intelligence report' and enumerates two distinct views, 'report' and 'list'. It names the resource, the action, and the available retrieval modes, making it easy for an agent to understand what this tool does and to distinguish it from sibling 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 clear internal guidance on when to use 'report' vs 'list' and explains defaults and the limit parameter. However, it does not explicitly contrast this tool with sibling tools like get_playbook or get_signal, nor does it state when this tool should be avoided.

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 annotations (readOnly, idempotent, non-destructive), the description discloses cache-first behavior with a ~10-minute market-hours refresh cycle, freshness semantics for each field (OI updates once each morning, day_volume is live session), and the critical data quirk that bid/ask/mid/spread are absent rather than NULL. The 'absent, not NULL' distinction and the explicit `as_of` mention are exactly the kind of behavioral context an agent cannot infer from 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 long but every sentence earns its place — the tool genuinely needs both modes, cache semantics, a data-exclusion caveat, and four parameters explained. Structure is strong: the differentiating lead, bulleted modes, the exclusion paragraph, and an Args block. It loses one point for the grammatically awkward opening ('the read the pool's session-frozen...') and overall density that slightly slows scanning.

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 is complete for a two-mode read tool: it covers what data is served, what is deliberately not served and why, cache/live behavior, the batch shortlist limit, and the temporal decision window. Since an output schema exists, the description need not enumerate return values, and it even hints at the `as_of` field in batch responses. Nothing an agent needs to select and invoke this tool correctly is missing.

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 schema description coverage at 0%, the description carries the full parameter-documentation burden and succeeds completely. Each parameter gets meaning: `contract` is an OCC ticker taken verbatim from the pool's `recommended_contract` and selects single-contract mode, `scan_date` is the pool date with a default of latest pool, `contracts` is a batch shortlist capped at 60, and `live` forces a fresh upstream fetch. Format, mode association, and constraints are all given where the schema gives only types and defaults.

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 names a specific verb and resource — reading FRESH (entry-day) liquidity — and immediately distinguishes it from the session-frozen pool read via `recommended_oi`/`recommended_volume`, which maps to the sibling get_pool. The two modes (single `contract` snapshot vs whole-pool batch) are spelled out with the exact fields returned (open interest, session volume, last trade, day range, underlying price, greeks), leaving no ambiguity about what this tool does.

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 when-to-use context: the ~10:00 ET decision window for batch mode, and the overnight-sweep timing explanation for why a fresh read is needed. It also provides mode-selection logic ('chosen by whether you pass a single `contract`'), cache-versus-live guidance (`live=true` to force a fresh fetch or read a contract NOT in today's pool), and a clear when-not ('Deliberately serves NO bid/ask/mid/spread'). Alternatives are implicit via the pool-read contrast rather than named siblings, but the routing guidance is fully actionable.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond annotations: it states the status view is deterministic and intentionally avoids hallucination about market open status, and it describes what each view returns. This gives the agent confidence in the tool's behavior and outputs.

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 and well-structured, with a short overview followed by bullet points for each view and an explicit Args section. Every sentence adds useful information, and the most important distinction (the two 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 minimal complexity with a single optional parameter and no output schema, but the description covers the purpose, both modes, their outputs, defaults, and the deterministic guarantee. Nothing essential is missing for an agent to select and invoke 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 the parameter documentation burden. It does so effectively by enumerating the only parameter 'view' with its two allowed values, the default 'status', and a distinct explanation of what each value returns. This fully compensates for the lack of schema-level parameter descriptions or enums.

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 explicitly identifies the tool as a market-calendar reference and details the two views: 'status' for US equity market open status plus next open/close, holiday, and early-close flags, and 'scan_dates' for data-availability calendar with per-date signal counts. This is specific and distinguishes the tool from sibling data-retrieval tools by naming the resource it references.

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 clearly implies when to use each view: use 'status' to check if the US equity market is open, and use 'scan_dates' to find which recent scan dates have GammaRips data. It does not explicitly name alternative sibling tools or state when not to use this tool, but the intended usage context is clear.

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 read-only, idempotent, and non-destructive; the description adds substantial behavioral context: versioned server-side content, a recommendation to re-fetch rather than cache, deterministic no-LLM field lookups, override semantics between `field` and `name`, and the leakage-classification safety rule that only `feature` columns are safe as selection inputs. This goes well beyond what annotations provide.

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 tool's essence and uses a compact bullet structure that maps cleanly to the branch logic. Every sentence contributes either a mode, an example, or a constraint; there is no filler.

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?

Despite having no output schema, the description explains what each invocation returns: field definitions with an `available_fields` list, markdown playbooks, a machine-readable data contract with leakage classifications, or a catalog with a pointer to the field dictionary. Valid name values are enumerated, making the tool fully callable without external assumptions.

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 thoroughly explains `name` with valid special values and concrete playbook names, and `field` with an example and the note that it overrides `name`. This fully compensates for 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 states a specific purpose: a versioned server-side methodology/reference tool that returns field definitions, playbook markdown, the data contract, or a catalog depending on arguments. It clearly differentiates this from data-access siblings like get_signal or get_pool by framing it as the methodological/dictionary 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 gives explicit arg-driven usage rules: use `field` for definitions, `name` for playbooks or the data contract, and neither for the catalog. It also enumerates valid playbook names and special values. It does not explicitly contrast with sibling tools, but the usage context is clear enough that an agent can select this tool confidently.

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 establish a safe read-only, idempotent profile, and the description adds substantial non-obvious behavior: anon calls to paid views return subscription_required, enriched is served from a leakage-safe view with outcome columns physically stripped, features lags by 1-2 trading days, the two rule eras are explicitly not one population, and recommended_spread_pct is permanently NULL. This is exactly the contextual depth that annotations alone cannot provide.

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 long, but every section earns its place: a bulleted view taxonomy up front, then tier and caveat paragraphs, then a compact Args block. The structure makes it scannable, and the density is justified for a 9-parameter, four-mode tool with auth gating.

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 no output schema, the description covers parameters, defaults, clamps, auth gating, null fields, data lag, and era differences, nearly everything needed to invoke it correctly. The only remaining gap is that return row shapes for the raw and features views are not enumerated the way enriched's ~21 decision columns and full-rows behavior are.

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 Args block carries the entire burden, and it fully delivers: every one of the 9 parameters gets a value domain, default, view scoping, and clamps (min_score 0-10 raw-only, limit 1-50/100/20 by view, fields as a strict projection, offset enriched-only pagination). This completely compensates for the empty schema descriptions.

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 defines get_pool as the GammaRips candidate pool and breaks it into four clearly distinct views (enriched, raw, features, preview), each with its own role and consumer. It differentiates from siblings inline, pointing to get_playbook for contract selection and get_liquidity for live re-checking, so an agent can tell exactly which resource this tool serves and how it differs.

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 when-to-use guidance: enriched is the daily candidate set the agent reasons over, features is the substrate for joining against query_outcomes, preview is named the free entry point, and raw is the pre-cut scan. It also names alternatives with conditions (get_playbook, get_liquidity) and states exclusions like view-scoped filters and the paid-tier requirement.

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 and idempotent annotations, the description discloses important behaviors: values are constant per scan_date, data lags the live pool by ~1-2 trading days, and the engine fail-closes when spot VIX exceeds VIX3M. This adds real decision-relevant context that annotations alone do not provide.

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 well organized: a front-loaded summary, a concise explanation of the safety rail, a data-lag caveat, then clear Args and Returns sections. Every sentence contributes useful information without redundancy or filler.

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 single-optional-parameter read-only lookup, the description is complete: it defines the input, defaults, output fields, timing semantics, and the fail-closed rule. An agent has everything needed to call it correctly and interpret the result.

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 provides only a nullable string with no description, but the description fully documents scan_date: its format (YYYY-MM-DD), its role as the selection point, and its default behavior (latest scan date carrying regime features). This fully compensates 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 states a specific verb and resource: it returns point-in-time market-regime context for a scan date, enumerating the exact fields (VIX close, VIX3M, SPY trend, 5-day VIX delta) and the regime safety rail. This makes it clearly distinguishable from sibling tools like get_liquidity or get_signal.

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 clear context for when the tool is appropriate: it is a leakage-safe, as-of-scan_date regime lookup that defaults to the latest available scan date, and it is tied to the engine's fail-closed regime check. It does not explicitly name alternatives or state when not to use it, but the intended use is well implied.

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 readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description goes well beyond this by disclosing fail-closed behavior for unknown earnings dates, leakage-safe point-in-time features, the error behavior when a ticker is missing from the pool, and the distinction between engine-applied rails and pool rows. This is rich, useful behavioral context.

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 structured with a clear opening, a bulleted breakdown of the two views, fail-closed warning, and a compact Args section. There is no filler; every sentence adds either a semantic detail, a default, or a behavioral constraint. Despite its length, it is dense and front-loaded with the most important information.

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 tool's two-view complexity and the presence of an output schema (which removes the need to describe return values), the description is remarkably complete. It covers defaults, parameter combinations, error behavior, edge cases (unknown earnings date), and the rationale for using the earnings view. An agent has everything needed to invoke the tool correctly across both views.

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 of explaining all six parameters. It does this thoroughly: each parameter is named, tied to a view, marked as required/optional, and given a format (e.g., YYYY-MM-DD, OCC ticker). It even clarifies derivations like 'both ticker and expiration are derived' from contract. This fully compensates for the absent schema descriptions.

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 distinguishes itself from sibling list-oriented tools by emphasizing it covers one ticker, and it clearly enumerates the two available 'view's. This is more than sufficient for an agent to understand what the tool does.

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 clearly indicates the tool is for a single ticker/contract deep dive and provides detailed per-view guidance, including when to pass 'ticker' vs 'contract' and how to interpret the earnings check. It references the pool's 'recommended_contract' and tells the user to check every candidate, which implies the screening/listing sibling (get_pool) is the alternative. However, it never explicitly names an alternative tool or states a when-not-to-use condition, so it falls just short of a 5.

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 read-only, idempotent, and non-destructive, and the description adds substantial behavioral context: returns are fractions, only closed windows are served, row-level surface output truncates oldest-first and reports that truncation, null aggregates mean 'not measured yet' rather than zero, and policy_version carries cohort-start semantics. This is exactly the kind of context that prevents misuse.

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 long but tightly organized: a front-loaded framing, nine scannable view bullets, and a complete Args list. Every paragraph adds necessary cautions or semantics, and repeated warnings address high-cost misinterpretations rather than padding the text.

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 nine view modes and 26 parameters, the description covers selection criteria, defaults, units, truncation behavior, null semantics, cohort disclaimers, and research-only boundaries. Since an output schema exists, the absence of detailed return-field documentation is acceptable; the description covers 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?

The input schema has 26 parameters and 0% description coverage, so the description carries the full burden. It defines every parameter in the Args section, including valid values for horizon, rule, and group_by, per-view applicability, limit ranges, defaults, and the nuanced behavior of policy_version. This fully compensates for the empty schema descriptions.

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 querying realized outcomes and receipts across nine distinct views. It distinguishes itself from strategy-performance reporting by emphasizing that pooled composites are a research surface, never a strategy track record. This gives an agent a precise mental model of what resource the tool operates on.

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 comes with an explicit use case and often a warning: use surface for exit design, harvest for touch probability, positions/performance for receipts, and exit_rule only for research. It also provides strong when-not guidance: never treat repudiated cohorts as track records, do not render null aggregates as 0.0, and do not confuse underlying-direction outcomes with option PnL.

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 and idempotent annotations, the description discloses important behavioral traits: no exit simulation/validation, reliance on RM-002/RM-004 boundary bars, first-crossing reporting, fallback to upstream minute fetch, and the thin tape caveat that missing bars are not evidence of no activity. This gives an agent realistic expectations about data quality and return semantics.

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 well-structured with front-loaded purpose, mode bullets, a critical data-quality caveat, and an organized Args list. Every section contributes to correct invocation or interpretation of results; there is no filler or redundant restating of the schema.

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 seven parameters and no schema-level descriptions, the description is remarkably complete. It covers mode selection, parameter defaults and constraints, ignored parameters, output expectations (bars, first-crossing sequence, OHLCV), and data reliability caveats. Since an output schema is reported to exist, the description does not need to enumerate return fields.

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?

Even though schema description coverage is 0%, the description's Args section fully compensates by explaining each parameter: contract format, date requirements, granularity modes, target_pct/stop_pct meaning relative to the 10:00 ET anchor, and from_date/to_date defaults. It also clarifies that date is ignored in day mode, which is not inferable from the schema alone.

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 resource (raw option price bars) and the operation (replay for a user's own entry/exit rule). It distinguishes itself from simulation/validation tools by explicitly stating this server does NOT simulate or validate exits. The two granularity modes further define its scope, making it unambiguous against sibling get_* 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 clear context for when to use each granularity mode: minute for a single session with a required date, and day for marking live or closed paper positions over a date range. It also flags limits such as the 120-day span and thin tape. It does not explicitly name alternative sibling tools or say when not to use this tool, so it stops short of a 5.

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