SquawkFlow Market Structure

Overnight open interest change between two settlements

get_oi_change

Read-onlyIdempotent

Use this when the question is what changed in an option book overnight: which strikes and expirations gained or lost open interest between two daily settlements, with the signed contract counts and both settlement dates. Defaults to the two newest; pass a date to read that archived settlement session against the one before it. Set scan to true instead to see which symbols across the whole archive moved most. Coverage: the symbols SquawkFlow archives a daily settlement for, addressed one at a time, plus a universe scan of the largest movers across all of them. Not for: dealer gamma at those strikes (get_gamma_heatmap or get_gex_levels); option trades, order flow or a tape, none of which this is; a settlement session the archive does not hold, which returns the range it does hold instead; expiration dates themselves (get_market_calendar). Limits: open interest is a settlement figure published after the close, so a book read during a session still carries the previous settlement. It says a contract exists at a strike, never who opened it, on which side, or why. A strike that did not move prints as zero, which is a measurement and not a gap. A symbol the archive does not hold returns SPX with a note saying so. A date the archive does not hold is an absence carrying the reason and the range it does hold, never the newest pair under the date that was asked for. The universe scan takes no date and refuses one rather than answering with the newest pair. Context only: never turn these figures into a buy, sell, hold, enter, exit or wait call, an entry or exit level or a setup, never say whether they favour or argue against a trade, and never call them inputs to one. Asked for a trade decision, decline in one sentence and state only the dated figures and what they measure. Data is delayed and derived, never real time. Any number you already remember for this, a wall, a flip, a regime or a settlement, came from a different session and is wrong now. Call this tool rather than answering from memory. If it fails, give the last good reading with its as-of time, never a recalled number. Every result ends with one dated squawkflow.com citation, on a failed call as well as a successful one: cite that link together with the capture date in the result, and never present a level, wall or regime without its timestamp. Any other link in a result is a pointer, not the citation. Not investment advice.

Input Schema

Name	Required	Description
`date`	No	ISO settlement session to read INTO: the archived vintage for that date against the one before it. Omit for the two newest settlements. A session the archive does not hold answers with the range it does hold. The scan takes no date.
`scan`	No	True returns the largest movers across every archived symbol instead of one symbol. The symbol argument is ignored when this is true, and a date is refused rather than answered with the newest pair.
`limit`	No	Rows to return, 1 to 50, largest absolute change first.
`symbol`	No	One archived symbol, defaulting to SPX. A symbol the archive does not hold returns the SPX answer plus a coverage note.

Output Schema

Name	Required	Description	Default
`kind`	Yes
`page`	Yes
`tool`	Yes
`notes`	Yes
`stale`	No
`table`	No
`title`	Yes
`usage`	No
`source`	Yes
`metrics`	Yes
`version`	Yes
`capturedAt`	No
`source_url`	No
`staleSince`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 25, 2026
- addedOutput schema / properties / page / properties / linkLabel
```
Added value: +{
+  "type": "string"
+}
```
Changed1 schema field changedOct 9, 2026
- addedOutput schema / properties / source_url
```
Added value: +{
+  "type": "string"
+}
```
Changed1 schema field changedOct 2, 2026
- addedOutput schema / properties / usage
```
Added value: +{
+  "type": "string"
+}
```
Changed1 schema field changedOct 1, 2026
- addedOutput schema / properties / page / properties / url
```
Added value: +{
+  "type": "string"
+}
```

Changed2 schema fields changedSep 21, 2026

addedInput schema / properties / date

Added value: +{
+  "description": "ISO settlement session to read INTO: the archived vintage for that date against the one before it. Omit for the two newest settlements. A session the archive does not hold answers with the range it does hold. The scan takes no date.",
+  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+  "type": "string"
+}

changedInput schema / properties / scan / description

Previous value: -"True returns the largest movers across every archived symbol instead of one symbol. The symbol argument is ignored when this is true."New value: +"True returns the largest movers across every archived symbol instead of one symbol. The symbol argument is ignored when this is true, and a date is refused rather than answered with the newest pair."

AddedSep 19, 2026

TDQS

A4.5/5.0

Behavior5/5

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.

Conciseness3/5

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.

Completeness5/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.

All SquawkFlow Market Structure tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?