SquawkFlow Market Structure

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

With no annotations provided, the description carries the full burden, and it excels: it discloses data is 'delayed and derived, never real time', warns memorized values are 'wrong now', dictates failure handling ('if the call fails say the data is unavailable'), and mandates citation of a dated squawkflow link with timestamps. It additionally notes the not-investment-advice status. All key behavioral traits are surfaced beyond any structured field.

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: coverage, core function, usage triggers, fallback, data quality, failure handling, citation, and disclaimer. Information is front-loaded (coverage and definition), and the structure flows logically from 'what' to 'when' to 'how to handle edge cases'. It could be split into paragraphs for readability, but it is not verbose.

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 has no output schema and no annotations, the description must supply all operational context, and it does: coverage, fallback for invalid symbols, data limitations, memorization warnings, failure instructions, citation requirements with timestamps, and usage triggers. An agent has everything it needs to decide when to call this tool and how to interpret 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 description coverage is 100%, and the description repeats the schema's exact wording for the symbol parameter (default to SPX, deepest chain, fallback returns SPX grid). No additional meaning is added beyond what the input schema already provides, so the baseline of 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?

The description declares a specific verb ('returns') and a precise resource (gamma exposure by strike and expiration), and explicitly differentiates this tool from an aggregate by explaining that it 'breaks out by strike AND expiration' and can distinguish '500M in one expiration from 500M spread over several'. It also states the coverage scope (SPX, SPY, QQQ) and names the output components (net charm, vanna, OI change), leaving no ambiguity about 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 provides explicit when-to-use conditions: 'Ask this when the question is which expiry carries the gamma, which strikes gained open interest overnight, or how much gamma sits at one strike'. It also instructs the agent to call this tool rather than answer from memory, and clarifies the fallback behavior for out-of-coverage symbols. This is more than sufficient for an agent to select it over siblings like get_gex_levels.

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?

With no annotations, the description carries the full burden, and it is exceptionally transparent: it discloses that data is delayed/derived not real time, that dealer positioning is an assumption, that unsupported symbols silently return SPX with a note, and that results must be cited with their timestamp via a squawkflow.com link. This goes well beyond what the schema shows.

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 dense and front-loaded: it starts with coverage and the return list, then layers caveats (assumption, delay, staleness, citation, failure behavior) in a logical order. Each sentence contributes either retrieval instructions or a hallucination guard, so nothing feels wasted.

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?

There is no output schema and no annotations, yet the description enumerates every returned value (spot, walls, flip, vol trigger, net GEX, regime, pin strikes, magnet, session range, timestamps) and explains fallback, data quality, and citation requirements. An agent has everything needed to call 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 100% and the schema already explains the symbol parameter, its default, the allowlist, and fallback behavior. The description repeats this coverage/fallback information but adds no new parameter-level meaning, so the 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?

The description clearly identifies the tool as returning GEX levels (call wall, put wall, gamma flip, regime, etc.) for SPX, SPY, and QQQ, and it gives example questions that should be routed here. It does not explicitly differentiate this from sibling tools like get_gamma_heatmap or get_max_pain, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit user-intent triggers ('Ask this for questions like where is the call wall...') and instructs the agent to call this tool instead of answering from memory or fabricating data after a failure. However, it never names alternative tools or says when not to use this one, so it lacks the exclusions needed for 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?

With no annotations provided, the description carries the full burden and does so thoroughly: simulated records, no money at risk, delayed/derived data, omission/counting behavior, no investment advice, citation requirements, and explicit statements about what is not returned. This is exceptionally transparent.

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 front-loaded with the core coverage and returns, then adds necessary behavioral guardrails. Some repetition of the 'no...' pattern exists, but it remains purposeful for a tool with important limitations to communicate.

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?

There is no output schema, so the description compensates by enumerating returned fields (dates, engine identifiers, status, counts), omission behavior, the ending link and citation requirement, and failure handling. For a two-optional-parameter tool, nothing needed to invoke 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?

The input schema already documents the limit (1-50, default 20) and the engine enum with 100% coverage. The description confirms the engine names and the 50-record cap but adds no new parameter-level semantics 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 description clearly states what the tool returns: dated simulated-record receipts from spxman_v2, tripwire, and harvester, up to 50 per call. It explicitly excludes prices, directions, and performance statistics, which distinguishes it from the sibling market-data 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 strong usage context: call this tool rather than answering from memory, and if it fails, say data is unavailable rather than recalling. It does not explicitly name sibling alternatives, but it clearly scopes 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?

With no annotations, the description carries the full burden and does an excellent job: it discloses SPX-only coverage, delayed/derived data, the non-forecast nature, fallback behavior for other symbols, staleness warnings, and required citation of the dated squawkflow link. This is far beyond what the schema alone provides.

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 dense and front-loaded, with the core definition first followed by usage and behavioral warnings. Every sentence serves a purpose, though a few admonitions could be tightened without loss.

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 no output schema, the description tells the agent what the result contains: the max pain strike, payout curve around it, available expirations, and a dated source link with citation instructions. It also covers failure behavior and data limitations, making it complete enough for reliable 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?

Schema coverage is 100%, but the description adds meaningful parameter behavior: omitting expiration means nearest expiration, expiration must match an available expiration, and any non-SPX symbol still returns SPX data with a coverage note. These details materially improve correct invocation.

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 returns the max pain strike for an SPX expiration, defined as the settlement strike minimizing aggregate option payout. It distinguishes the tool from related option-analytics siblings by emphasizing it is about open interest and explicitly says it is not a forecast or price target.

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 explicitly says to ask it for questions like 'what is max pain for this Friday' and instructs calling it instead of answering from memory. It does not name sibling tools or provide exclusion criteria versus get_gex_levels/gamma_heatmap, so it stops short of full alternative routing.

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?

There are no annotations, so the description carries the full burden of behavioral disclosure. It discloses that data is delayed/derived and never real-time, updates once per trading day, does not move intraday, reflects settlements rather than forward volatility, and includes specific caveats about memory, citation, and failure handling. This is far beyond what structured annotations would typically 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 comprehensive but overly long and written as a single dense block. It front-loads coverage well, but repeats the anti-memory guidance multiple times and includes advisory phrases like 'Not investment advice.' While most content is valuable, a more structured and terser presentation would improve scannability for an agent.

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 has no parameters and no output schema, the description provides everything needed for correct invocation and interpretation: what data comes back, when it updates, its limitations, how to cite results, and what to do if the call fails. Nothing essential is missing for an agent selecting or using this tool.

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 zero parameters and 100% coverage by definition, so there is nothing for the description to add about parameter syntax or meaning. The baseline of 4 applies because parameter semantics are not applicable here and the description does not need to compensate for any schema gap.

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: CBOE monthly VIX futures settlement curve, and lists the outputs: settlement prices, expirations, contango/backwardation regime, M9-M1 spread, and steepness vs. the archive. It also distinguishes itself by stating 'VIX spot is not part of this tool.' An agent can confidently understand what this tool is for and how it differs from related market-data 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 explicit guidance on when to ask it ('Ask this for questions like is VIX in contango or backwardation') and warns against relying on remembered values. It also states a clear exclusion: VIX spot is not part of this tool. However, it does not name or contrast sibling tools like get_gamma_heatmap or get_gex_levels, so alternative routing is left 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?

With no annotations provided, the description must carry the full behavioral burden, and it does. It discloses that the tool takes no arguments, makes no market data call, that data is delayed and derived rather than real time, that remembered values are unreliable, that failure should be reported as unavailability, and that results include a dated link to cite.

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 front-loaded with the core purpose, then moves through usage, data caveats, recall warnings, failure behavior, and citation requirements. Each sentence adds meaningful guidance, though a few cautions about memory and timestamps are repeated in different forms.

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 tells the agent exactly what to expect, how to handle failure, what to cite, and how to present results. For a zero-argument discovery tool, nothing critical 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?

The tool has zero parameters and the schema already reflects that with an empty properties object. The description reinforces this by stating it takes no arguments, which is sufficient. Baseline 4 is appropriate because there are no parameter semantics left to clarify.

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 exactly what the tool does: it covers every tool on the server, what each covers, data vintage, and limits. It is clearly distinguished from the sibling get_* tools because it is the meta-index that tells an agent which one might apply.

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 tells the agent when to start here: whenever unsure whether SquawkFlow has the symbol, expiration, or measure needed. It also instructs the agent to call this tool instead of answering from memory and defines fallback behavior if the call fails. This is direct, actionable routing guidance.

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