SquawkFlow Market Structure

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

Annotations declare read-only/idempotent/non-destructive, and the description adds substantial behavior beyond that: risk-neutral prices are not forecasts, the straddle is a cross-check rather than an independent estimate, each source carries its own date, data is delayed and derived (never real time), every result carries one dated squawkflow.com citation even on failure, and a failure protocol (report last good reading with its as-of time). No contradictions with 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 trigger conditions are front-loaded well, but the paragraph is long and repeats itself: the memory warning appears twice ('any number you already remember... is wrong now' and 'call this tool rather than answering from memory'), and the citation rule is restated in two separate sentences. Roughly a quarter of the text could be cut without losing 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?

An output schema exists, so return-field detail is unnecessary; what remains—coverage areas, exclusions, sourcing/date caveats, failure handling and citation obligation—is all covered. Nothing an agent needs to call this zero-parameter 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?

Zero parameters, so the baseline is 4; nothing about parameters needs explaining and the description correctly spends no words on them.

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 concrete trigger questions (first post-election SPX session, which VX window includes Nov 3, where the dated election-week schedule lives) and enumerates what the response covers (SPX event premium with both readings, dated VX comparison, GDELT ratio, exchange calendar). It is clearly distinguishable from siblings, though the tool name alone ('election_market_context') would not convey this and there's no single crisp verb+resource sentence.

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?

Explicit when-to-use triggers are given, an explicit 'Not for' list excludes election outcomes, venue prices and polling arithmetic, and two alternatives are routed by condition ('For a settlement probability at a selected level use get_implied_odds; for the whole futures curve use get_vix_term_structure').

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 openWorldHint, yet the description adds substantial behavioral detail beyond them: unresolved ids return nothing rather than composed text, long pages are truncated with a note, data is delayed and derived, and every result ends with a dated citation even on failure. This is exactly the extra context annotations cannot carry.

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?

Front-loaded with the use-when and not-for guidance, which is good, but the tail repeats the same anti-hallucination instruction twice ('a number you already remember ... is wrong now' and 'never a recalled number') and restates the citation rule across several sentences. Length is partly justified by the citation contract, but there is real 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?

With one parameter, an output schema, and rich annotations, the description still supplies the pieces the agent cannot derive structurally: id formats, failure semantics, truncation, data staleness, and the mandatory citation/timestamp discipline. Nothing needed to call or interpret the result 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?

Schema coverage is 100%, so the baseline is 3, but the description goes further by enumerating the id namespaces (page:, session:, glossary:, learn:, institution:) and confirming a squawkflow.com URL is accepted. That is meaningfully more than the schema's single example, though it does not cover parsing/validation behavior.

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?

States a specific verb and resource: read one published page's text by id, returning markdown verbatim plus a canonical URL to cite. It is clearly differentiated from the sibling `search` (which produces the ids this tool consumes) and from the market-figure tools it explicitly excludes.

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?

Names the trigger condition ('when you have an id from search and want the page text itself') and provides an explicit 'Not for' block covering arbitrary web pages and current market figures, which routes the agent to the right sibling tool. Alternatives are stated rather than left 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?

Goes well beyond the annotations: three non-collapsed dates, null lag with published reason, amendments appended as new records, unreadable filings counted on every answer, ~45-day disclosure lag, window applied before the row cap with coverage reported, and a mandatory dated citation. That is exactly the operational context annotations (readOnly/idempotent/openWorld) cannot convey.

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?

Core content is front-loaded and tight for the first half, but the closing block repeats the citation/timestamp instruction three times and drags in language about 'a wall, a flip, a regime or a settlement' and 'levels' that does not belong to a disclosures tool. Roughly a third of the text is boilerplate that dilutes the signal.

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?

An output schema exists, so return values need no explanation, and coverage, lag, amendment, and citation behavior are all covered. The only weakness is the misdirected market-data boilerplate (walls, regimes, levels), which could momentarily mislead an agent about what this tool returns.

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 baseline is 3. The description still adds value by clarifying that the since window is applied to the public disclosure date before the row cap and that the answer reports whether the window reached further back than the read — behavior the schema hints at but does not fully state.

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 trigger ('what a member of Congress disclosed buying or selling, or who disclosed trading a ticker') and names the exact data sources (House Clerk PTRs, Senate eFD). It also explicitly routes 13F work to get_filing_receipt, so an agent can separate it from siblings without opening a 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?

Gives an explicit 'Use this when' trigger, an explicit 'Not for:' exclusion list (rationale, timing, performance, rankings, committee links), and names the alternative tool for institutional filings. The since/public-disclosure-date caveat further constrains correct usage.

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?

Goes well beyond readOnly/idempotent annotations: 45-day filing lag, long-only US equity and option scope, absence of shorts/cash/bonds/non-US, cohort being a chosen list rather than a census, delayed derived data, and a mandatory dated citation on both success and failure. A no-filing quarter returning an answer rather than an error is exactly the kind of behavior an agent cannot infer from 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 relevant content (trigger, returns, coverage, exclusions, limits) is well front-loaded, but a large trailing block is boilerplate copied from a market-level tool: 'a wall, a flip, a regime or a settlement', 'never present a level, wall or regime without its timestamp', plus a repeated citation rule. None of that earns its place in a 13F receipt tool and it dilutes the operative guidance.

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?

Covers scope, cohort limits, data lag, failure behavior, and citation obligations; an output schema exists so return-shape explanation is optional rather than required. What is missing is anything about ordering, pagination, or truncation when limit caps holdings rows — though 'largest reported value first' in the schema partially covers ordering.

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% and the schema already documents limit (1-50, largest value first), manager slug semantics including the 'outside the cohort returns the cohort' fallback, and YYYY-qN quarter format. The description only restates 'omit the manager to list the published cohort', adding little beyond the schema, so baseline 3 applies.

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?

States a specific verb and resource ('returns the reported positions... accession number, period of report, acceptance date, revision history') and a precise trigger ('what an institutional manager reported holding in a quarter'). It also differentiates itself from the nearest sibling by name ('congressional filings (get_congressional_disclosures)' and the real-time/performance tools it is not).

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?

Explicit 'Use this when...' plus an explicit 'Not for:' exclusion list (current holdings, price, performance, returns, rankings, congressional filings) with the alternative named. The empty-quarter case is clarified as a valid answer rather than an error, which removes a common misroute.

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?

Goes well past the annotations (readOnly/idempotent/openWorld already cover the safety profile) by disclosing the five-minute cache, the SPX/SPY/QQQ coverage ceiling, the six-expiration render limit vs. full row totals, the reason-code behavior when the exposure block is missing, and the non-error fallback that returns the SPX grid for an out-of-coverage symbol. It also flags charm/vanna as model projections in delta dollars rather than gamma dollars, which prevents a real unit-mismatch 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?

It front-loads a use-case clause rather than the one-line identity of the tool, so the definition of what the heatmap actually is arrives second. Several compliance paragraphs (memory, citation, no-trade-advice) restate the same instruction more than once, which inflates length without adding distinct 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?

With an output schema present, return structure needn't be described, and the description covers everything else an agent needs: coverage, cache freshness, display limits, model-vs-measurement caveats, degradation behavior, and the mandatory dated citation. Nothing required to call or interpret it 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?

Schema coverage is 100% and the single parameter's description already carries the default and fallback rules, so the schema does most of the work. The description reinforces this with the coverage list and the SPX-default rationale ('deepest chain and the richest grid'), adding a little meaning beyond the schema but not much that is new.

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?

Defines a specific resource (dealer gamma broken out by strike AND expiration, plus vanna/charm) and states the distinguishing axis versus an aggregate in one line: 'An aggregate cannot tell 500M in one expiration from 500M spread over several.' It also names the alternatives it is not (get_gex_levels, get_gamma_matrix, get_oi_change), so an agent can route without opening siblings' schemas.

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?

Opens with concrete triggering questions (which expiry carries the gamma, where 0DTE concentrates, the charm ramp into the close) and closes with an explicit 'Not for:' list mapping each excluded use to the correct sibling tool. When-to-use, when-not-to-use and alternatives are all present.

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?

Goes well beyond the annotations: discloses that results come from a cached grid with stated age, are never rebuilt on request because a cold build is fourteen chain pulls, and that sector tiles are measured from a window around spot so a sector total differs from the SPX total, and that no gamma regime exists for sector ETFs. Also flags delayed/derived data and failure behavior (return last good reading with as-of time).

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?

Front-loaded with purpose, scope and alternatives before the caveats, and most sentences carry distinct facts (build cost, measurement window, citation rule, staleness). It is long and the guardrail prose repeats itself somewhat around citations and trade-decision refusals, keeping it off a 5.

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 an output schema present, rich annotations and zero parameters, the description supplies everything else an agent needs: measurement semantics, staleness handling, failure behavior and citation requirements. Nothing needed to call it 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?

Zero parameters gives a baseline of 4, and the description still adds meaning by explaining that the symbol set is a fixed grid and 'not a parameter,' which justifies the empty schema and prevents an agent from trying to pass symbols.

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?

States a specific verb and resource plus exact scope: 'where dealer gamma sits across the sectors,' one grid of eleven SPDR sector ETFs plus the SPX, SPY and QQQ index row, all from one build/capture clock. It explicitly distinguishes itself from get_gex_levels (one index in depth) and get_gamma_heatmap (by strike and expiration), so an agent can route correctly without opening schemas.

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?

Gives explicit when-to-use ('when the question is where dealer gamma sits across the sectors rather than in one index') and named when-not alternatives plus a third exclusion (sector performance/rotation not published). The selection condition and the alternatives are stated outright, nothing left 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?

Goes well beyond the readOnly/idempotent annotations: it discloses the SPX/SPY/QQQ allowlist and the graceful fallback (out-of-coverage symbol returns the SPX answer with a note, not an error), that frontExpiry is a second independent set of levels that must be cited with its expiry and can return a stated reason instead of levels when the book is thin, that data is delayed/derived, and that every result including failures carries one dated citation. No contradiction with readOnlyHint=true or destructiveHint=false.

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?

Well front-loaded — purpose and trigger come first, coverage and limits later — but the block is long and repeats itself: the anti-trade-decision instruction appears twice ('Context only: never turn these figures into...' and 'Asked for a trade decision, decline in one sentence'), and the return-value inventory duplicates an output schema that already exists. Several compliance sentences earn their place; the duplication does not.

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 read-only data tool with an output schema, this covers everything an agent needs: coverage set, fallback behavior, expiry-mode caveats, reproducibility limits on the dated change point (penalty-dependent, SPX only), stale-memory and failure-handling policy, and citation requirements. Nothing needed to call it 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?

Schema coverage is already 100%, so the baseline is 3; the description adds real meaning on top — it frames frontExpiry as answering 'does today's book agree with the full book', warns that it costs a chain-budget recompute rather than the cheap call, and explains the second-level-set semantics. Symbol semantics (allowlist plus non-error fallback) are reinforced rather than merely restated.

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?

Names the exact quantities returned (call wall, put wall, zero gamma flip, Swing Line, positive/negative gamma regime) and the resource domain, plus the aliases GEX / gamma exposure / dealer gamma. It is immediately distinguishable from get_gamma_heatmap, get_gamma_matrix, get_oi_change and get_session_record, each named explicitly.

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?

Opens with an explicit trigger ('Use this when the question is where the call wall... sits right now'), then gives a 'Not for:' block routing four sibling capabilities elsewhere, plus a clear condition for setting frontExpiry ('today's book rather than the whole chain'). Both when-to-use and when-not-to-use are stated.

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 only declare readOnly/idempotent/non-destructive; the description adds what annotations cannot: SPX/SPY/QQQ-only coverage, one expiration per call, a 90-day settlement horizon, delayed/derived data, and the failure contract (absence with the reason named when publication rules or method agreement fail). It also defines the numbers as risk-neutral, not frequencies, which is the key interpretive caveat.

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?

Front-loaded well: purpose and examples come first, exclusions and limits after. But the tail is bloated and repetitive — the no-trade-advice rule is restated three different ways across several sentences, and the citation/timestamp mandate runs long, pushing length well past what the routing and computation details require.

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?

An output schema exists, so return values need not be re-explained, yet the description still orients the agent to what comes back and how to treat a null. Combined with coverage limits, failure semantics, and the interpretation caveat, an agent has everything needed to call and report results 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 100%, so baseline is 3; the description earns a lift by adding constraints the schema omits — symbol coverage limits (SPX/SPY/QQQ only) and the rule that only expirations settling within 90 days are servable, which directly constrains the `expiration` parameter beyond its ISO-format description.

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?

States a specific computation (market-implied probability a level is exceeded by an expiration) and grounds it with two concrete examples (SPX above 7700 by Friday, QQQ below 740 next week). It also enumerates the returned artifacts (priced probability above/below, cross-check, ladder, implied distribution with median/quartiles/band), which no sibling offers.

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?

Opens with an explicit 'Use this when...' trigger and then names four exclusion zones with the sibling to use instead (get_gex_levels / get_gamma_heatmap for walls, get_max_pain for OI concentration, get_market_calendar for expiration dates). The agent can route without opening any schema.

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 cover read-only/idempotent/open-world, but the description adds substantial context beyond them: a 50-record per-call cap, omission and counting of unknown/undated records, delayed-and-derived data provenance, failure behavior (return last good reading with its as-of time), and a mandatory citation ending every result including failed ones.

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 and scope are front-loaded, but the text is roughly 300 words with heavy repetition: the no-price/no-direction/no-outcome point is made three times in different phrasings ('not for any measurement', 'receipts carry no price', 'never a level, wall or regime'). Several guardrail sentences could collapse into one.

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?

An output schema exists, yet the description still usefully names the returned fields (absolute session dates, engine identifiers, resolved/ungraded status, counts) and pre-empts the most likely misread — that the counts say whether a record was graded, not what the grade was. Failure handling and citation obligations are also covered.

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% and both params are already documented with defaults, bounds and enum values. The description restates the 50-record cap and lists the engine identifiers, but adds no new semantic detail (e.g. what ordering means across engines or how counts relate to the limit). Baseline 3 is correct.

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 opening sentence names a specific resource and the exact question it answers: which dated simulated records the Lab holds and whether they were graded. It also names the sibling it is not (get_session_record for published levels) and excludes measurement/commentary outright, so an agent can route without opening the 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?

Explicit when-to-use (dated record inventory + grading existence), explicit when-not-to-use (outcome measurement, prices, directions, session levels), and an explicit alternative (get_session_record). It even prescribes the agent's behavior when asked for a trade decision: decline in one sentence and restate the dated figures.

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 cover safety (readOnly, idempotent, non-destructive), and the description adds substantive behavior beyond them: no date is rule-computed, undocumented dates return 'not published', half sessions are omitted entirely, the closure table has a bounded year span, and the 'next session' is a derived field bounded by that span. It also discloses delayed/derived data and mandates citing the dated link even on failure.

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 opening sentence and the Limits block are well front-loaded and earn their place, but the trailing citation/hallucination boilerplate ('Any number you already remember for this...', 'Not investment advice') is repeated server-wide policy that dilutes the tool-specific content. Roughly a third of the text is boilerplate an agent would see on every sibling.

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 an output schema present, return shape need not be explained, and the description still covers the hard parts of this domain: coverage scope, bounded closure-table span, derived-vs-published distinction, half-session caveat, and failure behavior. Nothing an agent needs to call this correctly or interpret gaps 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?

Schema coverage is 100% and the single 'date' parameter already documents the ISO pattern, the as-of meaning, and the today-by-default behavior. The description restates the same as-of/default semantics ('Answered as of today on the exchange clock, or as of any date you pass') without adding new constraints, so this sits at the baseline for fully documented schemas.

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?

States a specific resource precisely: exchange sessions, next session, monthly/quarterly/VIX expirations, and upcoming holidays, all answered as of a date. It explicitly separates itself from siblings ('not for ... get_session_record ... get_max_pain'), so an agent can route without opening any 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?

Opens with the selecting condition ('Use this when the question is a date') and then enumerates exclusions with named alternatives: economic releases and earnings (not published here), market hours, prior-session publishings (get_session_record), max pain strike (get_max_pain). Both when-to-use and when-not-to-use are explicit.

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/non-destructive, and the description adds what they cannot: data is delayed and derived, results include a payout curve and availableExpirations, a non-SPX symbol degrades to a coverage note rather than an error, and failures should be reported with the last good as-of time. It also states the interpretive boundary (not a forecast, not a price target).

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?

Usage and exclusions are correctly front-loaded, but the second half drifts into policy boilerplate: repeated disclaimers about trade decisions, memory, and citation format consume substantial space without helping select or invoke the tool. The signal is strong but the size is inflated.

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 an output schema and full parameter documentation, the description still covers everything an agent needs: coverage limits, single-expiration constraint, return contents, degradation behavior on other symbols, and failure handling. Nothing about calling it correctly is left ambiguous.

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% and both parameters are documented in-schema, including the ISO pattern and the omit-for-nearest behavior, so the baseline is 3. The description adds little parameter-level detail beyond repeating the symbol fallback and 'one expiration per call', both of which the schema already conveys.

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?

Names a specific metric and resource ('settlement strike that minimises the aggregate option payout for one expiration') plus scope ('Coverage: SPX only. One expiration per call'). It explicitly disambiguates from get_gex_levels, get_gamma_heatmap and get_oi_change, so an agent can pick it without opening schemas.

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?

Gives trigger phrasing ('when the question is what max pain is for an expiration, or where the pain point sits for this Friday') and an explicit 'Not for:' list routing to the correct siblings for gamma, OI change and expiration dates. The alternative-for-alternative routing is unusually complete.

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 cover read-only/idempotent safety, yet the description adds substantial behavioural detail the annotations cannot: OI is a post-close settlement figure so an intraday read carries the previous settlement; unmoved strikes print zero rather than gap; an unheld symbol falls back to SPX with a note; an unheld date returns an absence with the range held. It also discloses refusal semantics for scan+date and the citation requirement, with nothing contradicting readOnlyHint.

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 use case is correctly front-loaded, but the paragraph is long and includes repeated policy statements — two separate sentences on citing the dated link, two on never converting figures into a trade call, and a 'Not for' bullet that is actually a fallback behaviour (unheld settlement date). The guardrails are useful, but several restate the same point and could be consolidated.

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 an output schema present, the description need not explain return shape, and it focuses instead on the things an agent cannot infer: settlement timing, zero-vs-gap semantics, fallback and refusal behaviour, and citation obligations. Nothing needed to call the tool correctly in either mode 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?

Schema description coverage is 100% and the four parameter descriptions already carry the date-vs-vintage, scan, symbol-fallback and limit semantics, so the baseline is 3. The description mostly restates those same rules narratively (defaults to two newest, scan ignores symbol/refuses date) rather than adding format or edge-case meaning beyond the 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 opening sentence names a specific verb and resource — what gained or lost open interest between two daily settlements, with signed contract counts and both dates — so the agent knows exactly what the tool returns. It is explicitly differentiated from named siblings (get_gamma_heatmap, get_gex_levels, get_market_calendar) and from option trades/order flow, which no other schema field could convey.

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 states the default behaviour (two newest settlements), how to switch modes (pass a date for an archived vintage vs. the one before it; set scan=true for the whole-archive movers view), and adds an explicit 'Not for:' list routing to the correct alternatives. The conditions that select each mode are spelled out rather than 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?

Goes well beyond the readOnly/idempotent annotations: it discloses the Tuesday-as-of / Friday-publication lag, defines net as an arithmetic difference rather than sentiment, states that markets with different multipliers are never aggregated, and specifies failure handling (return last good reading with as-of time, never a recalled number) and citation obligations. That is substantive operational context an agent cannot get from the 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?

Purpose and coverage are correctly front-loaded, but the body runs long with repetition ('not a market feed' / 'Data is delayed and derived, never real time', and a triple 'never ... never ... never' policy block). The compliance and citation material earns its place, but the same constraint is asserted two or three times.

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?

Covers the universe of published pages, the temporal semantics of the data, cross-market aggregation limits, and the output contract, with return values left to the existing output schema. Nothing an agent needs to call this 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?

Schema coverage is 100% and the contract parameter's omit-to-list behaviour is already documented in the schema, so the description's restatement adds little. The weeks parameter (1-52, oldest first) is never mentioned in the description, leaving the schema to carry it; baseline 3 is appropriate.

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?

States the precise resource (index futures positioning by trader classification, enumerating dealers, asset managers, leveraged funds, other/nonreportables) and the exact output shape (long, short, spreading, net plus week history). It also contrasts itself with get_gex_levels and with commodity futures, so the agent can distinguish it from siblings without opening a 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?

Gives an explicit trigger ('Use this when the question is how index futures positioning is distributed...'), explicit exclusions ('Not for: options positioning or dealer gamma (get_gex_levels); commodity futures...; any reading of the session in progress'), and a fallback behaviour (omit contract to list pages). The alternative tool is named with the condition that selects 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?

Well beyond the readOnly/idempotent annotations: discloses that weekends/holidays return a distinct 'not a session' answer versus a missing record, that open/close/high/low are vendor-derived and withheld, that data is delayed, that results carry a dated citation even on failure, and what to do if the call fails. These are non-obvious behavioral traits an agent could not infer from annotations or schema.

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 and scope are correctly front-loaded, but the description is unusually long and reiterates the trading-advice prohibition across several sentences ('never turn these figures into...', 'never say whether they favour...', 'Asked for a trade decision, decline...'). Much of it earns its place as compliance context, yet the safety language could be tightened without losing meaning.

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 a single optional parameter and an output schema, the description covers everything an agent needs: coverage boundaries, what the record contains, absent fields, failure handling, and citation requirements. Nothing material is missing for correct invocation and interpretation.

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% and the schema already explains the ISO date format, the omit-for-latest default, and unlisted-date behavior. The description adds interpretive meaning: the published index defines the entire valid coverage, and a non-session date is a different answer from a missing record — useful semantics the schema does not fully spell out.

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 condition and resource: the dated SquawkFlow record for one session, listing exactly what it contains (published levels, verdicts, capture coverage, move from prior session, settled/open status). It explicitly contrasts itself with get_gex_levels as 'the dated tool on this server', so an agent can distinguish it from siblings without opening schemas.

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?

Gives explicit when-to-use ('pass a date to ask about a past session'), when-not ('the current reading (get_gex_levels)', cross-session rates, forward statements), and names the alternative tool. It also pre-empts the trade-decision use case with a prescribed decline response.

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 vastly expands upon the sparse annotations by detailing critical operational behaviors: the data is delayed/derived, it does not describe future volatility, and it mandates specific citation practices (dated squawkflow.com citation on every result). This level of detail is crucial for a low-certainty market data tool.

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 definition is extremely verbose, making conciseness low. While nearly every sentence serves a critical safety or scoping function, the sheer density of rules (e.g., rules on advice, historical recollection, citation formats) makes it poorly structured for an agent seeking a quick utility overview.

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 complexity of the financial instrument (VIX futures) and the mandatory safety/disclaimer constraints, the description is maximally complete. An agent cannot safely or accurately invoke this tool without reading the entire passage.

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 is empty (0 parameters), meaning the description cannot explain parameter meaning. However, since 0 parameters means 100% schema coverage, the baseline score is high, and the description provides necessary context on *what* is returned (regime, M9-M1 spread, etc.) to the agent.

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 purpose is exceptionally clear: to provide the VIX futures term structure (contango/backwardation, steepness, front month settlements). It specifies the scope as the 'Official monthly VIX futures settlement curve,' providing precise financial context.

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 guidelines are comprehensive, addressing not only when to use it ('when the question is whether VIX is in contango') but also explicitly what it is not for (VIX spot, weekly futures) and how to handle external prompts (decline trade advice in one sentence).

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/non-destructive, and the description layers on what annotations cannot: it makes no market data call, the same body is readable as a resource without spending a tool call, data is delayed and derived rather than real time, and it mandates citation plus timestamp discipline even on a failed call. It also specifies failure behavior (return the last good reading with its as-of time, never a recalled number).

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 purpose, exclusion and alternative are front-loaded, which is good, but the tail becomes policy boilerplate: the citation/timestamp rule is restated across several sentences ('cite that link together with the capture date', 'never present a level, wall or regime without its timestamp', 'never a recalled number'), and 'Not investment advice' is ancillary. Useful content, but it would be tighter with the citation and failure rules consolidated.

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 zero-arg, read-only catalog tool with an output schema, the description covers everything an agent needs: what is returned (tools, coverage, data age, boundaries), how to avoid spending a call (resource), fallback behavior on failure, and the citation obligation. Return-value structure is correctly left to the output schema.

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 tool takes zero parameters and the empty schema is self-evident, so the description only needs to confirm 'Takes no arguments'. That is a clean baseline-4 case with nothing further required.

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?

States a specific verb and resource: it returns the coverage catalog of every tool on the server, with data vintage and limits. It explicitly distinguishes itself from the data-returning siblings by saying 'Not for: any market figure' and 'This returns descriptions, not data', so an agent can tell it apart from get_gamma_heatmap, get_implied_odds and the rest.

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?

Gives explicit trigger conditions ('when you are not sure whether SquawkFlow has the symbol, the date, the expiration or the measure you need'), an explicit exclusion ('Not for: any market figure'), and names an alternative access path (the sf://catalog resource) plus the redirect instruction to call the tool it names instead.

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/openWorld annotations, it discloses that coverage comes from the site's published index rather than the API (so it costs market-data endpoints nothing), that unpublished pages are un-findable and ids are never invented, that ranking is plain lexical match, and that data is delayed/derived. It also specifies failure behavior (return last good reading with as-of time, cite on failure too) – unusually rich disclosure.

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 and usage are front-loaded and the sentences are dense with distinct information (coverage, limits, ranking, citation rule). It is long and the citation/investment-advice tail is somewhat repetitive of earlier points, costing it a point, but almost every clause carries selection or behavior value.

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 search tool with an output schema, it covers what an agent needs: scope, return fields, handoff to fetch, exclusion of market data, freshness constraints, citation requirements, and failure handling. Nothing material for correct invocation 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?

Schema description coverage is 100% and both parameters are documented in the schema (including the ISO-date behavior and the 1–20 limit), so the description adds little beyond them. Baseline 3 applies; the 'pass an id to fetch' note concerns result usage, not the input parameters.

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?

States a specific verb+resource (search the pages SquawkFlow publishes) and enumerates the page types returned (glossary, methodology, calendars, filing pages, dated session records) plus the return shape (ids, titles, canonical URLs). It explicitly distinguishes itself from the sibling market-data tools that return numbers.

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?

Gives explicit when-to-use ('when you want the page that answers a question, or a citable link rather than a number'), the handoff to fetch ('pass an id to fetch'), and an explicit not-for clause ('market figures of any kind... call the tool that publishes it'). Both sides of the routing decision are named.

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