DEV Community: FirmTape

How much does the volatility model move a GEX terminal's numbers? We swapped it and measured

FirmTape — Thu, 27 Aug 2026 21:31:32 +0000

Every published gamma-exposure construction — including the one Cboe's own research uses — prices gamma the same way: Black-Scholes, one implied vol per contract, inverted from the quote mid. The literature offers upgrades: fit an arbitrage-free smile (SVI), or replace the lognormal with a Gram-Charlier expansion whose skew and kurtosis supposedly matter most at 0DTE. No paper measures what switching the model does to the number a terminal actually ships. So we did: the production machinery runs verbatim — same book, same dealer weights, same root finder — with only the vol input swapped, over 14 sessions including the two worst flip days in our archive.

What moves:

swap	zero-gamma flip (median)	net gamma at spot
SVI slice fit	2.5 pts	4.4%
Gram-Charlier	8.3 pts	13%
higher moments alone	3.9 pts	~10%
one-tick mid ambiguity (worst case)	0.27 pts	0.9%

Three readings. First, the model systematic is real: a defensible-but-different vol model moves the flip 2–3 points and aggregate gamma 5–13%. Nobody quotes that error bar; ours is now in the terminal tooltip. Second, the upgrades are not upgrades: the SVI refit makes frame-to-frame flip stability worse on 10 of 14 sessions (on 2024-08-05 the p95 frame jump goes 69 → 380 points — fit-parameter chatter is its own noise source), and half its displacement is just collapsing call and put IVs into one smile. Third, the Gram-Charlier story inverts at the aggregate: its corrections are smallest in the last 30 minutes — exactly where the theory says Black-Scholes is most wrong — because near expiry the book's gamma concentrates at the money, where every model that prices the straddle agrees.

There is no minute-level exchange truth for gamma, so none of this says which model is right — it says how much the answer depends on the choice. Per-contract Black-Scholes stays.

What changed instead: the flip's real defect was never the vol model but a discontinuous root selector, so as of this week the terminal's flip is a smoothed, tracked estimator (p95 frame jump 17.6 → 4.5 points) and ships with a crossing standard error drawn as a band. A root deserves an error bar, not a different model.

Full study: How much does the vol model move GEX?

How accurately can complex option trades be signed? First grading against exchange truth

FirmTape — Thu, 27 Aug 2026 21:30:33 +0000

To build a dealer book from the options tape you must decide, print by print, who bought. For simple orders the quote rule does that. But on the day we measured, 40.2% of all SPX option prints were legs of multi-leg packages — and on those legs the quote rule is invalid by construction: an exchange fills a spread at a net price and allocates it across legs by convention, so a leg can print anywhere inside (or outside) its own market regardless of who initiated.

Our terminal signs the package: legs printing on the same millisecond are reassembled into their parent order, the package's net price is compared to a net bid/ask derived from the leg quotes, and the quote rule is applied at that level. The idea is not unique to us. What has never existed — for ours or anyone's scheme — is an accuracy number.

The truth set. Cboe publishes a free trade-by-trade sample: 3% of executions, each carrying the side, the capacity (customer / market maker / firm), the trade type, and an id linking legs of one complex execution. That is per-leg ground truth. Joined to our tape: 12,422 complex legs carry a verdict.

The number:

rule, graded on customer legs	per print	volume-weighted
package signer, as shipped	80.4%	79.1%
excluding legged-in contras (unrecoverable in principle)	87.9%	84.7%
single-leg quote rule on the same legs	75.1%	75.1%
coin flip	50%	50%

Iron condors grade at 88%, strangles at 91%. Even the legged-in category — which Cboe itself declines to attribute — comes out at 69% rather than the coin flip we budgeted.

The mirror check. A rule that claims to find the customer should be reliably wrong about the market maker on the other side. It is: on legs where the sampled participant is a market maker, the rule agrees with that side only 10.9% of the time.

The semantics finding. Against time-priority truth the rule fails (16.9% vs true liquidity removers) while scoring 90.4% against auction initiators. Both make sense at once only one way: the package quote rule identifies the side that paid the spread against the derived net mid, not the side that arrived second. For a customer-versus-dealer book, that is not a bug — it is the reason the rule works.

One truth day, binomial SE ~0.7pp; the signer abstains on ~45% of complex volume rather than guessing. Full study: How accurate is complex-trade signing?

What is SPX option flow actually made of? A fifth still trades on a physical floor

FirmTape — Thu, 27 Aug 2026 21:29:33 +0000

Every print on the SPX options tape carries an OPRA condition code naming the pipe it came through: electronic book, complex order book, price-improvement auction, a multi-leg order legging into the simple book, or a human being on the trading floor in Chicago. Nobody appears to have published the composition for SPX — the one product where the answer is unusual. So we tabulated five years of it, every code mapped, cancels excluded, zero unmapped residual.

The near book, by year (share of volume):

channel	2022	2024	2026
electronic simple book	34.2%	34.8%	26.0%
complex book + complex auctions	36.1%	39.1%	44.7%
physical floor	20.8%	19.8%	20.6%
AIM price-improvement auctions	2.9%	2.9%	6.7%

Three readings:

1. The floor is not dying. A steady fifth of the near book trades by open outcry, five years running — independently matching the one recent academic estimate (Galati, Hendershott, Khan, Riordan: over 20% of U.S. options floor volume, "almost exclusively" S&P 500 index options). The dominant floor code is the proprietary-product multi-leg print: big structures negotiated by humans.

2. The complex book keeps eating the simple book. 36% → 45%, while simple electronic fell to 26%. If your dealer book signs legs individually, nearly half the tape is mis-handled by construction.

3. The auction slice is retail, and it doubled. Cboe's free trade-by-trade sample carries each participant's capacity. Joined to our tape: the initiator of an AIM auction is a Customer 97.8% of the time, the contra is a market maker 95.6% of the time, and 100% of initiating volume is ≤10 contracts — the mechanism's size cap, visible in the data. Small-lot auction internalization is the closest thing SPX has to a printed retail label — and on the 0DTE expiry it reached almost 10% of volume this year.

One more composition fact from the signed book: at the close, dealers end up net LONG gamma on 83% of sessions — the crowd's structural habit is selling same-day optionality into the close.

Full series, channel map and honesty section: What is SPX flow made of?

How fast do dealers hedge SPX 0DTE flow? We measured it: 2-3 minutes

FirmTape — Thu, 27 Aug 2026 21:28:29 +0000

Every dealer-positioning story assumes the same mechanism: customers force option delta onto dealers, dealers hedge it in the underlying, the hedge moves the index. The premise is stated everywhere and measured almost nowhere — the canonical footprint study (Hu 2014) is equities, pre-0DTE, daily grain. So we measured it on SPX 0DTE directly: when a customer imbalance lands this minute, how many minutes until the index has absorbed the hedge?

Setup. 1,088 SPX sessions (2022–2026) at one-minute grain. The dealer's option-delta inventory is a published series on our terminal; its minute change, negated, is the delta dealers must hedge that minute. Regress forward index returns at 1–30 minute horizons on that imbalance, with day and minute-of-day fixed effects, reversal controls, and the imbalance's absolute size as a magnitude control. Day-clustered errors; last 40 sessions held out.

Answer: two to three minutes.

horizon	coef, bp per 1σ	t
1 min	+0.038	+4.4
2 min	+0.050	+4.2
3 min	+0.048	+3.5
5 min	+0.021	+1.2

The footprint is front-loaded exactly as a hedging story requires — strongest in the first two minutes, statistically gone by the fifth. On the held-out 40 sessions the sign is right at all seven horizons tested.

The placebo is the point. Rerun everything with one change: every minute's imbalance keeps its exact magnitude and gets a coin-flip sign. The placebo predicts nothing, at any horizon, in either sample. The information is not in how much traded — it is in which way the signing engine says it traded. Random signs kill the result; the tape-signed book carries it.

What this is not: 0.04bp per standard deviation is not a trading edge after any spread. It is a measurement of the hedging machine's latency — and, as far as we can find, the first published figure of its kind for SPX.

Full study with the reproduce recipe (it runs entirely off our free public session files): How fast do dealers hedge?

Does open interest pin the index or widen its range? A decomposition over 1,084 SPX sessions

FirmTape — Thu, 27 Aug 2026 09:02:57 +0000

Two published claims about what option open interest does to the underlying point in opposite directions. Golez and Jackwerth (JFE 2012): the index is pulled toward strikes on expiration days - pinning. Elms (2025, SSRN 6564078): in the 0DTE era, high ATM open interest comes with ~16% wider daily ranges - amplification. Our earlier replication on SPX open interest (not a SPY proxy) found Elms's significant cell reverses sign: high ATM 0DTE OI, narrower ranges.

The new result is that both stories are true at once, and the univariate framing was hiding it. Put the total 0DTE book into the same regression as the ATM concentration and the two carry opposite signs simultaneously, on 1,084 sessions:

component	elasticity of forward range	t	sign by year 2022-2026
ATM concentration (+/-0.5% of the open)	-0.28	-7.3	negative 5 of 5
total 0DTE book size	+0.17	+4.3	positive 5 of 5

Where the book sits, the range narrows. How big the book is, the range widens. Univariately the two components nearly cancel (total OI alone: t -1.5) - which is how a blended measure like Elms's SPY proxy can print either sign depending on the mix. His amplification and our reversal stop contradicting each other: they are two halves of one decomposition, and per-strike SPX open interest is what separates them.

Details that matter: the outcome is the forward range read from minute 30 (open interest is yesterday's EOD book - predetermined), controls include the trailing move, the previous session's range and the overnight gap, and year fixed effects change nothing. This is a cross-sectional association with named controls, not an experiment.

Full write-up with the original seven pre-specified tests and the free reproduction path: https://firmtape.com/research/does-open-interest-pin-the-index

All finished sessions replay free at https://firmtape.com/sessions

How accurate is the SPX "expected move"? A calibration over 1,088 sessions and 82,000 readings

FirmTape — Thu, 27 Aug 2026 09:01:29 +0000

Every 0DTE dashboard quotes an "expected move" - the one-sigma range to the close implied by ATM volatility. Folklore says the straddle overstates the move most days. As far as we can find, nobody has published the number: when the screen says +/-X points to the close, how often does the close land inside?

We measured it on 82,378 five-minute readings over 1,088 SPX sessions (2022-04-14 to 2026-08-26). At every frame: ATM IV interpolated at spot, EM = S * sigma * sqrt(tau to 16:00), then the fact - did the close land within EM of that reading's spot? Shares are day-clustered; readings with under 15 minutes left are excluded from the headline.

Conservative by four points, everywhere

threshold	theory	measured
inside 1.0 x EM	68.3%	72.4% +/- 0.9
inside 0.8 x EM (straddle breakeven)	57.5%	62.0% +/- 0.9
inside 0.5 x EM	38.3%	42.4% +/- 0.8

The folklore is right in sign and modest in size: the quote overstates the delivered close-move by ~4 percentage points of coverage. The four points sit at every threshold - a level of implied vol, not a fat-tail premium. And it is remarkably uniform: coverage runs 71-74% at every hour of the session and in every year 2022-2026. Nothing has drifted as 0DTE volume grew.

One observation the naive story does not predict

Cut by the dealer-gamma state at that minute and the gradient runs backwards from intuition: coverage is HIGHER in the short-gamma tail (74.5% at gamma percentile <= 20 vs 71.0% at >= 80). Implied vol prices short-gamma days even more conservatively than the extra movement they deliver to the close. Two to three standard errors - an observation to check, not a result to lean on.

Caveats named in full (minute closes, close-calibration not range-calibration, overnight excluded) plus a complete reproduce recipe from the public per-session files - per-strike IVs and spot are all you need, no paid data: https://firmtape.com/research/how-accurate-is-the-expected-move

All finished sessions replay free at https://firmtape.com/sessions

Update: the variance test (2026-08-28). Coverage asks how often the close lands inside; it does not ask whether the quote is the right SIZE. We added the standard checks from the vol-forecasting literature. Result: E[z^2] = 1.034 +/- 0.062 - the expected move is an essentially unbiased VARIANCE forecast, roughly uniform across the day - and under the QLIKE loss it decisively beats a trailing-realized-vol benchmark (1.50 vs 2.05, t -4.2). So "conservative by four points of coverage" is not overpricing: the variance is priced right, and more closes land inside +/-1 EM than the lognormal predicts anyway. Both can be true only if the move distribution is leptokurtic versus the lognormal - more mass in the middle AND fatter far tails at the same variance. The sharper one-liner: right variance, wrong shape. Sizing against the expected move as a one-sigma is honest; treating the 28% outside as lognormal tails is not. Full numbers in the addendum on the study page above.

Does 0DTE options trading raise volatility? We measured a published +9% claim on 1,083 SPX sessions

FirmTape — Thu, 27 Aug 2026 08:59:55 +0000

Whether 0DTE options destabilise the index is a live three-way academic dispute. Brogaard, Han and Won (SSRN 4426358): a one-sd increase in the 0DTE volume share raises underlying volatility by ~9% of its mean. Dim, Eraker and Vilkov (SSRN 4692190): 0DTE positioning does not propagate volatility. Adams, Dim, Eraker, Fontaine, Ornthanalai and Vilkov (SSRN 5641974): 0DTE intermediation lowers volatility by 60-90 annualised bps.

We measured the association on 1,083 SPX sessions of the mature regime (2022-04-14 to 2026-08-20), on the same per-print SPXW tape our terminal runs on. One row per session: realised vol from 390 one-minute returns, and the 0DTE share of the near book's volume (mean 66%, sd 7 points). Controls: previous day's log vol, year and day-of-week fixed effects.

The raises-volatility claim does not survive

Same-day: one sd of 0DTE share corresponds to +0.6% of mean volatility (t +0.3) against the published +9%. Yearly signs alternate (+0.1, -0.3, +1.4, -0.9, +1.5 in t-stats) - no year is significant. And the share does not lead volatility either: t -0.9 on next-day vol given today's.

The one robust fact runs the other way

Reverse the arrow and the panel produces a stable number: after a volatile session the 0DTE share falls (-0.14 sd per log-unit of vol, t -4.3). Decomposing the ratio: both volume legs mean-revert after a vol shock, but the 0DTE leg retreats roughly twice as hard as the rest of the book (-0.047, t -3.6, vs -0.026, t -2.2). The folklore says volatility spikes attract 0DTE speculation; the tape says 0DTE flow steps away the next day, disproportionately.

What we cannot test, honestly: the dampening claim rests on the staggered Tue/Thu SPXW listings of April-May 2022 as a natural experiment, and our archive starts 2022-04-14 - days before the first new listing, so there is no pre-period. We refute the plus sign; we neither confirm nor refute the minus.

Full tables and caveats (the share's denominator is the ~21-expiry near book, not the whole chain): https://firmtape.com/research/does-0dte-trading-raise-volatility

All finished sessions replay free at https://firmtape.com/sessions

Is intraday momentum still alive? We measured it on 1,085 SPX sessions of the 0DTE era

FirmTape — Thu, 27 Aug 2026 08:58:32 +0000

Two peer-reviewed papers say the last half hour of the US session continues the day's direction. Gao, Han, Li and Zhou ("Market intraday momentum", JFE 2018) found it on SPY 1993-2013; Baltussen, Da, Lammers and Martens (JFE 2021) widened it to sixty futures markets over 1974-2020 and attributed it to gamma-hedging demand. Both samples end before 0DTE options became half the SPX tape.

We retested on 1,085 SPX sessions, 2022-04-14 to 2026-08-20, one observation per day: the rest-of-day return (open to 30 minutes before the close) against the last-30-minute return.

The unconditional effect is gone

sample	days	slope	t
2022	175	+0.009	+0.4
2023	250	+0.002	+0.1
2024	252	-0.016	-0.7
2025	249	+0.016	+1.0
2026	159	-0.012	-0.6
all	1,085	+0.006 +/- 0.009	+0.6

Flat overall, flat in every single year, signs alternating. Anyone still trading "the last half hour continues the day" on the index is trading a sample that ended before the market they are in existed.

The one place it still shows

The hedging-demand mechanism makes a sharper prediction than either paper could test: continuation should live where dealers are short gamma. Conditioning on a tape-signed 0DTE dealer book read at 15:30, the slope adds +0.055 (t +3.1) on short-gamma closes, and the public open-interest convention book sees none of it. The interaction is positive in all five years - but short closes are only 15% of sessions, the magnitude swings by an order of magnitude, and the final-40-session holdout rests on four short days. Five-for-five on sign is worth reporting; it is not worth a position.

Full tables, the named caveats, and a recipe to rebuild everything from the public per-session files (spot minutes, the aggressor-signed volume grid, per-strike IVs) are in the full post: https://firmtape.com/research/is-intraday-momentum-still-alive

All 1,000+ finished sessions are free to replay at https://firmtape.com/sessions

We replicated a published 0DTE options paper to four decimals. One unit-scale bug reverses its headline result — confirmed by the author

FirmTape — Wed, 26 Aug 2026 22:05:47 +0000

This is the short version of the full write-up, which carries every table: Replicating Vilkov (2026) on 0DTE trading rules.

Grigory Vilkov's "0DTE Trading Rules: Tail Risk, Implementation, and Tactical Timing" (SSRN 4641356) is a rare thing in the trading literature: the author shipped the code and the data panels behind his tables, MIT-licensed. So instead of comparing numbers to a memory, we could re-implement his construction independently and feed his own panel through it.

Step 1: the replication is exact. All seven option structures, both cost tiers, reproduce his published P&L table to four decimal places. No ambiguity about what the code does.

Step 2: the reproduction exposed a units bug. The panel stores the P&L column in percent of spot (reth_und = (payoff - mid) * 100) but the bid-ask spread column as a fraction of spot. The cost code subtracts one from the other directly:

pnl_ba = reth_und - half_spread_cost   # percent minus fraction: cost charged at 1/100
pnl_ba_fee05 = pnl_ba - 0.005          # the flat 0.5bp fee term was correctly scaled

The half-spread was charged at one hundredth of its true size — about 0.022bp instead of 2.2bp. Rescale it and change nothing else: every unconditional structure in the paper goes negative. The best one (put ratio spread) has a mean gross edge of +0.0251% of spot per day, and the spread you cross to get it costs 0.0343%.

Step 3: the ML layer makes it worse, not better. The paper's conditional layer trains a classifier whose target is y = 1[PNL_net > 0] — the cost sits inside the training label, not just in the evaluation. Re-pricing the author's shipped predictions at the corrected cost takes the headline conditional Sharpe from +1.55 to +0.33. Rebuilding the labels with the corrected cost and retraining takes it to −0.70. Two-thirds of the published result was cost arithmetic; most of the rest was a model that had learned from mislabelled days.

Step 4: we emailed the author before publishing. His reply, within two days, quoted with permission:

Thank you for this. You have read the units correctly, the finding stands, and it is more consequential than the charitable version you offered me. Please publish it.

He reran the corrected code on the private, longer sample behind the paper — the bug is there too — and pushed the fix upstream (commit 85a447c) with a KNOWN-ISSUES.md and a unit-scale assert module, so this class of error now fails loudly. The paper's headline conditional result reverses sign: put ratio spread +0.93 published → −0.75 corrected, and no strategy or basket survives net of costs. His framing of what survives is worth quoting too: the gross directional signal is real; what died is the claim that crossing the quoted spread leaves any of it for the trader.

Takeaways for anyone who ships research code:

Mixed scales in one dataframe are a landmine. reth_und in percent next to bas in fractions, in the same table, with no suffix on either name.
Assert units at boundaries. The fix that made this permanent is not the * 100 — it's the guard that checks a cost series is on a plausible scale before it touches P&L.
A metric bug can contaminate your labels. If your training target is derived from the quantity your bug distorts, retraining after the fix is part of the correction. Re-evaluating alone understates the damage.
Ship your data. This error was findable, and fixable, only because the author published everything. That is the norm this literature needs — his response shows how it should be done.

The full post — with the corrected tables, the delta decomposition showing the result is not hidden index beta, the author's complete response, and a 46-session out-of-sample run on our own SPXW tick tape — is at https://firmtape.com/research/vilkov-0dte-rules-replication.

A paywall where the trim is the product

FirmTape — Tue, 25 Aug 2026 16:13:16 +0000

I sell one thing: a live data stream. Everything that has already finished is free, forever, and that free archive is the evidence the paid stream is measured honestly.

Last week I added a third thing between them — a public page showing today's numbers, deliberately late. It sounds like a small feature. It is actually the most dangerous kind of code in the codebase, because it reads the paid file and publishes part of it, and every bug in it is a bug that gives away the product.

Here is what I got right, what I got wrong, and the two bugs that only showed up in production.

The line: give away timeliness, not a new category

The temptation with a "free tier" is to publish a crippled version of everything. That is hard to explain and harder to defend, because every field becomes a negotiation.

The rule I landed on: the free page introduces no new category of number. Every field on it is already free elsewhere on the site the next morning. What it adds is when — and when is exactly what is metered.

So the paid product keeps the things that are actually different in kind: the per-strike ladder, the second-order series, the internal disagreement between three different ways of computing the same thing, and the path through the day. Not trimmed to a teaser. Absent.

That framing turned out to be worth more than the trim itself. It fits in one sentence, it survives contact with a pricing page, and it never invites "why is this field free and that one not".

One function decides, and everything else is presentation

The route that serves this page loads a payload and hands it to exactly one function. That function returns a plain object or null. Nothing else on the request path sees the payload.

This is not tidiness. My codebase already has a comment recording what happens when two routes serve one payload under two policies: someone finds the other spelling and walks through it. In my case a request path could be normalised after it had been checked, so //data/live.json and /data/LIVE.json both missed the rule that guarded /data/live.json and were then resolved into the very file the rule protected. Two parsers of one string will eventually disagree.

So: one canonicaliser, run once per request, consumed by both the gate and the file read. And one trim, called by one route. The new page is a third door into that file, and it is the reason I wrote the trim as a pure function with its own test file before wiring anything up.

Measure the delay against the stream, not the clock

The obvious implementation of "fifteen minutes behind" is: take the reading from now() - 15min.

Do not do that.

Consider what happens when your writer stalls. Wall-clock arithmetic keeps marching, the newest data stops moving, and the effective delay shrinks toward zero — you begin publishing the freshest thing you have at the exact moment your pipeline is unhealthy and nobody is watching.

Measure against the data instead:

// the newest reading at least DELAY_MIN older than the newest reading we hold
const newest = toMin(frames[frames.length - 1].t);
let chosen = null;
for (const f of frames) if (newest - toMin(f.t) >= DELAY_MIN) chosen = f;
if (!chosen) return null;    // the whole session so far is inside the window

Now a stall makes the page older, never fresher. That is the direction a paywall should fail in. As a bonus the function needs no clock at all, which makes it trivially testable — the test suite hands it a synthetic payload and asserts the delay holds, including the stalled case.

The bug that would have given it away

My payload carries the same levels twice, in two shapes. There is a five-minute series, and there are session-level scalars.

For a finished day the scalars are the right answer — they are the published level set, the same numbers the archive page prints, and reading them means the two pages can never quote the same day differently.

For a day in progress the scalars mean "as of the most recent rebuild". Current. Undelayed. Publishing them would have handed over live values while the page's own timestamp claimed a fifteen-minute delay.

Two of my seven fields existed only as scalars. The lazy version of this function would have mixed sources — series where available, scalars where not — and the page would have been simultaneously delayed and not, with no visible symptom.

The fix was to read a live day entirely from the series, and accept that this means the whole row belongs to one moment rather than being a composite. That is also what makes the timestamp on the page true.

The test that pins it sets the scalars to absurd sentinel values:

levels: { flip: 1, cr0: 2, ps0: 3 },   // never publishable while live

and then asserts no live reading ever returns 1, 2 or 3. If someone later "simplifies" the function by falling back to the scalars, that test fails loudly instead of the paywall failing quietly.

Say "at least", because your delay composes

I shipped the page saying "15 minutes behind the live stream".

Then I measured it in production, cache-busted, and the reading was twenty-two minutes old.

Nothing was broken. My function controls the gap to the newest reading in the payload — and the payload has a lag of its own, because the frames are published behind the real-time tail. The two lags compose, and I had only ever reasoned about mine.

The timestamp on the page was never wrong. The sentence next to it was: it made a wall-clock promise the code cannot keep. The page now says "at least 15 minutes", which is true at both ends.

If you publish a delayed anything, this generalises: the stamp is the claim, the delay is a floor, and stating a floor as an equality is a promise your dependencies have not agreed to.

What I would take to the next one

Write the trim before the route. A pure function with a test file, then wire it. The test file becomes the paywall's regression suite rather than coverage-for-its-own-sake, and the two assertions that matter — never fresher than the delay, never reads the live source — are the ones you would otherwise verify by staring.

Pass the gate's own signal in, do not recompute it. My trim takes "is this day still being written" as an argument, from the same helper the paywall uses. Two implementations of "is this live" is the same class of bug as two parsers of a path.

Sentinel values beat mocks for "this must never be published". A magic 1 that shows up in output is unmistakable; a mock that returns plausible data hides exactly the bug you were testing for.

Look at it in production before you believe the copy. Both of my real bugs — the composed delay, and a page linking the new URL from a footnote nobody read — were invisible from the code and obvious from one curl and one log line.

This is from FirmTape, which rebuilds SPX dealer positioning from the options tape. The page in question is /now; the research section is where the measurements live, and most of them are null results.

Your MCP server is invisible to ChatGPT unless it has these two tools

FirmTape — Tue, 25 Aug 2026 16:11:29 +0000

My MCP server had nine working tools. Claude used all of them. ChatGPT could list the server and could not use a single one.

The reason is short: ChatGPT reaches an MCP server through exactly two tool names, search and fetch, and ignores the rest of the table. In deep research that pair is not a convenience layer over your tools — it is the interface. A server without them is listable and useless.

Here is what I learned building them for a server that was already in production with a different shape.

The contract

Both tools answer with plain text. Not structuredContent, not an outputSchema — the connector reads content[0].text and expects a documented JSON envelope inside it.

search(query) returns:

{"results": [{"id": "...", "title": "...", "url": "https://...", "text": "snippet"}]}

fetch(id) returns one document, not wrapped in a list:

{"id": "...", "title": "...", "text": "the full text", "url": "https://...", "metadata": {}}

If your existing tools declare outputSchema and answer with structuredContent — mine did, and it is the better shape for every other client — leave those alone and make these two the exception. They are the only tools in my table that are text-only, and there is a comment in the source saying why so nobody "fixes" it later.

Rule one: every id must round-trip

search hands out ids. fetch receives them. If a model can be handed an id it cannot resolve, you have built a dead end that costs a round trip to discover.

The failure mode I avoided by accident and then almost re-introduced: using titles as ids. A model will hand you back something close to the title, and now you are doing fuzzy matching in your resolver.

Namespace them instead:

`session:${day}`     // a dated record
`page:${path}`       // a document on the site

Two prefixes, both trivially parseable, both impossible to produce by paraphrase.

Rule two: tolerant on input, strict on output

Models do not reliably hand back the id they were given. Mine gets handed citation URLs, bare dates, and paths with and without a leading slash — all meaning something perfectly clear. Refusing them is technically correct and practically a wasted turn.

function resolveRef(raw) {
  let s = raw.trim();
  if (s.startsWith("session:")) s = s.slice(8);
  else if (s.startsWith("page:")) s = s.slice(5);

  // a URL from a citation, with or without the scheme
  const url = s.match(/^(?:https?:\/\/)?(?:www\.)?example\.com(\/[^\s]*)?$/i);
  if (url) s = url[1] || "/";

  if (/^\d{4}-\d{2}-\d{2}$/.test(s)) return { kind: "record", day: s };
  const rec = s.match(/^\/(?:record)\/(\d{4}-\d{2}-\d{2})\/?$/);
  if (rec) return { kind: "record", day: rec[1] };

  const path = ("/" + s.replace(/^\/+/, "")).split(/[?#]/)[0].replace(/\/+$/, "") || "/";
  return { kind: "page", path };
}

Strict on the way out, though. fetch on a site is an HTTP client you are handing to a language model, and the thing it must never become is a way to reach the routes that execute work. My denylist is my own robots.txt Disallow list restated in code — not because robots.txt is a security boundary, but because the two lists answer the same question and having one derive from the other means they cannot drift.

Dates as people type them

If your corpus is time-series, half the queries carry a date, and none of them are ISO.

2026-08-24
August 24, 2026
24 Aug 2026
August 2026        <- means every record in that month

The one non-obvious rule: a named day must win over the month containing it. Parse "24 August 2026" with a month-and-year pattern and you will also match "August 2026" inside it and drag in the whole month. Compute exact days first; only if there are none, fall back to month expansion.

And return only dates you actually hold. A weekend is silently not a trading day, and the honest answer to "what happened on Saturday" is an empty result, not an error.

Read your catalogue from your own site

The first version of my search had a hardcoded list of pages. That was wrong within a day: I published a new article and it was unfindable until I redeployed the server.

Now the catalogue is fetched from the site itself, from two sources, because neither is enough alone:

llms.txt is maintained as one line per page — - [Title](url): description — so it carries good titles and real blurbs. But it is a curated file. Mine named five of eleven pages in one section.
sitemap.xml names every public URL and tells you nothing about any of them.

So: parse llms.txt first, then let the sitemap fill the gaps with a title derived from the slug. Edge-cache both. Now anything I publish is searchable without touching the server.

Ranking: "right now" is not "the latest"

This one shipped broken and I only caught it because I tested with a real question.

The query was "where is the SPX gamma flip right now". My scorer put the page that answers exactly that in fifth place, under three dated records. The words that separate the two intents — "right now" versus "latest" — are precisely the ones a keyword scorer treats as noise.

Keyword scoring cannot fix this. Split by intent instead:

const wantsNow    = /\b(now|currently|at the moment|live)\b/i.test(q) || /\btoday\b/i.test(q);
const wantsLatest = /\b(latest|newest|recent|yesterday|last)\b/i.test(q);

Present tense hoists the live page. Most-recent hoists the newest finished records. yesterday belongs with the second group deliberately: it is a finished day, and "now" is a moment.

If your server has one URL that answers the present tense, make sure a present-tense query returns it first. Everything else is a rounding error next to getting that wrong.

Do not put a long cache on the page whose value is freshness

I gave fetch a fifteen-minute edge cache for the pages it retrieves. Sensible for documentation that changes on deploy. Wrong for the one page that updates through the day: its own content is already delayed, and a fifteen-minute cache on top of that would hand an assistant a state half an hour old.

Cache by path, not globally:

cf: { cacheTtl: path === "/live" ? 60 : 900, cacheEverything: true }

Keep your real tools

search and fetch are a document interface. They return prose. My other tools return typed numbers with an outputSchema, which is strictly better for any client that can call them.

So both exist, and the descriptions say so — the generic pair carries a line telling a capable client to prefer the specific tools, and the server instructions repeat it. ChatGPT gets an interface it can use. Everything else gets the good one.

Worth knowing before you start

Adding a custom MCP connector in ChatGPT lives under Settings → Plugins → Developer mode, and that toggle is flagged "elevated risk" because it permits unverified connectors. That is a real decision for whoever owns the account, not a checkbox to breeze past — and it is worth telling your users where it is, because "Connectors" is not where it used to be.

None of this is hard. It is about a hundred and fifty lines. But no amount of good tool design substitutes for the two names, and I spent a while assuming a well-built server would be discovered on its merits.

I build FirmTape — SPX dealer positioning rebuilt from the options tape, with a public research section where most of the posts are null results. The MCP server is at https://firmtape.com/mcp if you want to see the shape described above in something that is actually running.

I measured which AI crawlers actually fetch my site. The answer changed what I built next.

FirmTape — Tue, 25 Aug 2026 15:55:27 +0000

Cloudflare Web Analytics told me chatgpt.com was one of my largest referrers. That is the sum total of what it could tell me, because Web Analytics is a client-side beacon: it fires from a browser running JavaScript. Every crawler on earth is invisible to it by construction.

So when I shipped a page specifically for AI assistants to read, I had no way to answer the only question that mattered — did any of them come?

I added about a hundred lines of server-side counting to find out. The result was not what I expected, and it made me throw away part of the work I had just done.

Three hats, not one

The naive version of this is a counter that increments on "is this a bot". That number is useless, and it took me one iteration to see why: an AI agent hits your site wearing one of three completely different hats.

Index. A crawler walking on its own schedule, building a corpus. OAI-SearchBot, PerplexityBot, Claude-SearchBot. This says you are reachable.

On-behalf. A person asked a question a second ago, and the assistant is fetching your page right now to answer it. ChatGPT-User, Perplexity-User, Claude-User. This says you are being cited. This is the number.

Training. Corpus collection for model training. GPTBot, ClaudeBot, Google-Extended. Neither of the above.

All three of OpenAI's agents carry the string "OpenAI" in the wild, and a matcher that collapses them produces a number that looks like data and answers nothing. Order matters when you match, too — test chatgpt-user before gptbot, or a naive substring search folds them together.

// UA substring -> [canonical name, hat]. First hit wins, so the more specific
// spelling comes first.
const AGENTS = [
  ["oai-searchbot",    ["OAI-SearchBot", "index"]],
  ["chatgpt-user",     ["ChatGPT-User",  "on-behalf"]],
  ["gptbot",           ["GPTBot",        "training"]],
  ["perplexity-user",  ["Perplexity-User", "on-behalf"]],
  ["perplexitybot",    ["PerplexityBot", "index"]],
  ["claude-user",      ["Claude-User",   "on-behalf"]],
  ["claude-searchbot", ["Claude-SearchBot", "index"]],
  ["claudebot",        ["ClaudeBot",     "training"]],
  ["googlebot",        ["Googlebot",     "index"]],
  ["bingbot",          ["Bingbot",       "index"]],
];

function classify(ua) {
  const s = String(ua || "").toLowerCase();
  for (const [needle, hit] of AGENTS) {
    if (s.includes(needle)) return { name: hit[0], hat: hit[1] };
  }
  return null;   // a person, or something that does not say
}

There is a fourth number worth having, and it is not a crawler at all. ChatGPT stamps the links it renders with utm_source=chatgpt.com. Counting those gives you the click-through: a human who saw a citation and decided it was worth opening.

Read together, the four are a funnel. Index arrives first. On-behalf follows once your page is actually retrievable. Clicks follow once a person decides the citation was worth a tap.

Keeping it cheap and keeping it private

Two constraints shaped the implementation more than anything else.

It is fed by strangers. The traffic this measures is exactly the traffic you do not control. A crawler walking my archive is a thousand page requests. So: aggregate in memory, keyed by day and path, and persist on a debounced flush rather than per request. If you mirror to a paid key-value store, mirror the accumulated day — one write every thirty seconds while anything is arriving, none when it is not. A crawler flood and an idle afternoon then cost exactly the same. Bound the number of distinct paths per agent per day too, or a single deep crawl grows one key per URL forever.

It should not become surveillance. There is no reason for this instrument to hold anything about a person. Mine records which known agent matched, which path, and the date. No IP, no account, no session, no user-agent string kept verbatim, nothing from the query string except that one attribution parameter. Counts roll off after sixty days. That is enough to answer "did OpenAI fetch this page yet" and not enough to answer anything about anyone.

If you have a privacy policy that says page views are counted by your analytics provider and stops there — mine did — that sentence stopped being the whole truth the moment this landed. Update it.

Two bugs worth stealing

The shutdown flush that never ran. My server registered signal handlers at module load: process.on(sig, () => process.exit(0)). My counter registered its own flush handler later, from inside the listen() callback. Node runs listeners in registration order, the first one calls process.exit(0), and the second never fires. A deploy is a SIGTERM, and a deploy is precisely when someone is watching the last few hours of data. The fix is not a second handler — it is to flush inside the one that already owns shutdown.

Load-or-reset. open() read a file and, if the file was missing, left whatever was already in memory. A second call silently inherited the first one's counts. "Load whatever survived" has to mean empty when nothing did, or the persisted file stops being the record it claims to be. A test caught this, not a code review.

The finding

Half an hour after it shipped, this is what the counter said:

  THE FUNNEL
  reachable   (index bots)           9
  cited now   (on-behalf)           15   <- a person was answered from us
  training                           0

  BY AGENT
  ChatGPT-User          on-behalf       15
      /research/level-hold-rates                   1
      /research/what-monthly-expiration...         1
      /learn                                       1
      /about                                       1
      /mcp                                         1
      /                                            1
      /sessions                                    1
      ... five session pages, four research posts

  Googlebot             index            9
      ... eight archive pages and /pricing

  CLICK-THROUGHS
    (nothing yet)

Three things jumped out.

ChatGPT-User outnumbered Googlebot. Fifteen on-behalf fetches to nine index crawls, on a site with a rounding error's worth of search traffic. People are asking assistants questions and the assistants are reading my pages to answer. Not skimming a title — pulling research posts, the explainer index, the docs page.

The page I built for them was never fetched. I had shipped, that same morning, a URL that answers the single most common question about this subject in plain server-rendered HTML. It appears nowhere in that list. Neither does OAI-SearchBot, which had not visited at all.

Nobody clicked. Fifteen reads, zero click-throughs.

What that actually means

The middle finding is the one that changed my plans, and it took a minute to understand.

The assistant fetched / and /sessions. My new page was linked from the navigation of both, and named in a sentence on one of them. It did not go.

In search mode, an assistant opens what its index returned. It does not browse — it does not follow links out of a page it just read. So a page that is hours old and indexed nowhere is unreachable no matter how prominently you link it internally. Every internal link I had added that morning was, for this purpose, worthless.

And it gets more pointed. / was fetched — and / was a JavaScript application shell whose HTML carried no numbers at all. The most-fetched URL on the site was answering the question with nothing.

So I moved the answer to where the fetch already lands: the current reading now renders into the shell's HTML as a <noscript> block. Not a hidden div served only to crawlers — the same bytes for everyone, and a genuine fallback, because without JavaScript that page really is blank. That is the line between a fallback and cloaking, and it is worth staying on the right side of it.

What I would tell you to do

Count the three hats separately. One "bot hits" number will not tell you whether you are indexed or whether you are being cited, and those need different responses.

Check whether your most-fetched URL actually answers anything. If it is a JS app shell, an assistant is spending a fetch on your site and leaving with nothing. That is the cheapest fix available and I would not have found it without the data.

Do not assume internal links help here. They help humans and they help traditional crawlers. They appear not to help an assistant that only opens search results.

Watch the click-through row. Fifteen reads and zero clicks is one afternoon on one small site and I would not generalise from it. But it is the number that separates "we are in the answer" from "we get the visit", and if you are not counting it you will not notice which one you have.

The honest caveat on all of this: it is roughly thirty minutes of data from a single site in a niche, and some of those fetches were me testing. It is not a study. It is an instrument that took an afternoon to build and immediately told me something I had got wrong — which is the only real argument for building it.

The site is FirmTape, which rebuilds SPX dealer positioning from the options tape. If you want the flavour of what the assistants were pulling: how often dealer-gamma levels hold, measured across a thousand sessions, and what monthly expiration does to the book. Most of what is published there is a null result, which is its own kind of fun.