Under the Hood
How Agentic Market Explainer works
Every stock move gets a headline. Almost none of them get a real answer. You open a chatbot, ask why your position is down 8%, and it gives you a plausible-sounding paragraph pulled from training data that’s months old, with no idea what the price, volume, or news actually did today. We built this tool because that isn’t good enough for a retail trader trying to make a real decision. Agentic Market Explainer pulls the actual price, volatility, options activity, and news before it says a single word about why a stock moved. It doesn’t guess. It looks, and it shows its work, so when you read the answer, you know exactly which numbers it came from.
Deterministic first
Live price, volatility, and a statistical significance check run in plain code before any reasoning happens, so no tokens get spent explaining a routine, unremarkable move.
Agentic when it counts
Only once a move actually looks unusual does the reasoning layer switch on, deciding for itself which evidence, news, options, macro, or earnings, is worth pulling next.
Built on MCP
Every data source is a discrete, swappable MCP (Model Context Protocol) tool, an open, ever-extendable standard, so new capabilities plug in without redesigning the reasoning loop.
Pipeline
1. Pull price & volatility, always, no LLM call
Every query starts the same way: latest price, multi-horizon % change, and realized volatility are fetched deterministically in code, before the LLM is ever invoked.
2. Statistical significance gate
Only if the move exceeds roughly 2× the stock's own realized volatility does the app fan out further. A normal 1% drift on a high-beta name doesn't trigger the same investigation as a genuine outlier.
3. Parallel evidence fan-out
News and options data are fetched in parallel, spliced into the conversation as if the model had called them itself, with zero extra LLM round trips for this step.
4. The LLM decides what else is needed
Reasoning is handled by Claude Haiku, chosen for its balance of speed, cost, and quality in this kind of tool-use loop. A tool-use loop (max 7 turns) reasons about whether anything conditional is still missing, macro context, sector comparison, earnings/FOMC proximity, and calls only the tools that are genuinely relevant.
5. Synthesize, with a hard grounding rule
The model returns a single JSON contract: ranked hypotheses, confidence levels, and citations. Every number must trace back to a real tool result. Missing data says “Data unavailable” instead of being invented.
MCP Tools
get_price_dataprice.pyLatest price, multi-horizon % change, and annualized realized volatility. Finnhub quote first for the live tick, yfinance always for the historical series (and as the price fallback).
get_options_dataoptions.pyATM implied volatility, IV rank, put/call ratio, and skew from the nearest options chain.
get_options_positioningoptions.pyDeeper 2–4 week positioning: max pain, call/put open-interest walls, IV term-structure trend, and unusual volume-vs-open-interest activity.
get_newsnews.pyRecent headlines for the ticker over a configurable lookback window. Finnhub first, yfinance fallback.
get_macromacro.pyMarket-wide indicators (VIX, S&P level), fetched once and shared, not duplicated per ticker. FRED first, yfinance VIX fallback.
get_eventsevents.pyUpcoming earnings date (yfinance) and next FOMC meeting date (hardcoded calendar), for proximity context.
get_analyst_sentimentanalyst.pyWall Street consensus rating and price targets, and how many analysts cover the name.
get_sector_comparisonsector.pyCompares the stock's multi-horizon moves against its sector ETF's moves, to separate stock-specific news from a sector-wide drift.
FAQs
Is this financial advice?
No. This is an informational and educational tool that describes recent price action. It does not predict future moves or recommend buying, selling, or holding anything. Always verify important numbers against a primary source and consult a licensed financial advisor before acting.
Where does the data come from?
Every number comes from a live API call inside one of the MCP tools: Finnhub for live quotes and news (with yfinance fallback), FRED for macro (yfinance ^VIX fallback), and yfinance for history, options chains, analyst consensus, earnings dates, and sector classification. Every tool degrades gracefully — if a source fails, it falls through to the next rather than erroring out the whole query.
Why didn't it look at news or options for my query?
Because the move didn't clear the significance bar. Every horizon is scored on two axes: a relative ratio against the stock's own realized volatility, and an absolute magnitude floor. A routine 0.5% drift fails both and gets a short, cheap answer — that's a latency and cost optimization, not a coverage gap.
Can the AI make up numbers?
It's structurally discouraged: the final answer must be delivered through a JSON contract where every number traces back to a real tool result already in the conversation, and price/volatility are computed in plain code before the model is invoked. It can still misread a headline — verify anything you act on.
What's the difference between this and a normal chatbot?
A general chatbot answers a “why did this stock move” question from stale training data and a confident guess. This app pulls real, current price, volatility, options, and news data before the model reasons about anything, and forces the answer into a contract where every figure is traceable.
Does this work for non-US stocks?
Best support is US-listed equities and ETFs. Non-US tickers may resolve with sparse or missing data, or not at all — treat results outside US markets as unreliable for now.
Limitations
- US-market only. Price, options, news, and macro sources are all oriented around US-listed equities and ETFs; non-US tickers aren't reliably supported and thinly-covered US names may come back with sparse evidence.
- No intraday tick data or Level 2 order book. Options positioning and price moves are summarized, not tick-by-tick.
- The significance gate means small, “boring” moves intentionally get a shallow investigation. This is a deliberate cost/latency tradeoff, not a coverage gap to fix.
- Like any LLM system, outputs can be incomplete, out of date, or simply wrong. Every claim should be checked against a primary source before you act on it.
On the Roadmap
Crypto & FX coverage
Extend beyond equities/ETFs to major crypto and FX pairs.
Multi-ticker comparisons
Ask about two tickers at once (“AAPL vs MSFT this week”) in a single run.
Persistent query history
Save past investigations across sessions instead of resetting on refresh.