situate
Read-only
THE FIRST CALL. What is going on right now — for named companies, or for the whole market — from the backend's situation endpoints. Call it before any other flexreport tool on anything about a company, an event, or "now".
TWO SCOPES (each parameter's description says which it belongs to):
WITH symbols -> GET /situate-company, one call per symbol. For "catch me up on
X", "what happened at X / why", "how did X's quarter look", and BEFORE aiming
explore_data_catalogue, list_realtime_events or a report tool at a company. When
the question is about one event, pass it as `event_type` AND `card_types` (halves
the payload: the cards of every other present type are dropped):
situate(symbols=["OKTA"]) catch-up
situate(symbols=["MAR"], event_type="financials_release",
card_types=["financials_release"]) the 10-Q
Returns {"situations": {SYMBOL: situation}} (a symbol that failed carries
{"error"} instead):
present_types event types with a node in the window
web {nodes, edges}: the newest node per event type and per table
over window_days. Edges carry `cause`: same_chain_run (observed:
one chain run wrote both — a table linked this way to the event
REFLECTS it), lineage (declared), co_occurrence (temporal only,
never causation). `at` is a write time, not a business date.
Node `fetch` hints name the follow-up call; a signed_query_url
goes to get_signed_sql_drilldown verbatim.
cards event-type cards: persisted_in, sources, entails (tables written
by layer, and realtime events that follow with rate and lag),
preceded_by
relations table cards: layer, refreshed_by (schedule, next_run_at), and
read_by — THE TOOL THAT READS IT. Prefer the first tool there
over explore_data_catalogue (company_financials for the EDGAR
statements, get_company_snapshot, predict_earnings_move, ...).
entailed tables the events entail, routed to this company's EDGAR or FMP
side; edgar_filer / routed_out / source_routing say which side
(never query a routed_out table for it)
Then: a node still inside the 12h cache -> list_realtime_events(event_type,
tickers=[symbol]); older -> its card's persisted_in table. For a table that
refreshed for the event, call its read_by tool first, e.g.
company_financials(symbol, financial_type=<the table>, limit=5, line_items=[...]).
A table whose next_run_at is after the event still shows the prior period. An
empty web is not a quiet week: widen window_days.
NO symbols -> GET /situate-market. For "any earnings today?", "most significant
investor decks today", "which hedge funds exited?", "what's going on?". Name the
types yourself when you can (`event_types`, else `family`); otherwise pass the
user's words as `question`:
situate(event_types=["ir_publication"]) decks today: step 1 = decks
situate(family="earnings") the earnings episode in order
situate(question="what's going on?") a sweep: one entry per episode
Returns {shape, routed_from, order, types, event_types, market, ...}:
shape named_types | family | sweep (nothing named: no default family)
routed_from what decided the order: `by` = explicit | question | none
order up to 4 event types, in reading order
types[T] card (trimmed ontology card: persisted_in, followers, ...),
cache {count, newest_at, oldest_at, tickers — or members with
member_kind cik | strategy | singleton}, reports {fresh, stale,
report_date}
event_types the whole realtime corpus (type, family, description)
market exchange, is_open, session
degraded_sources realtime_cache / report_inventory when one was unreachable:
counts are then unknown, NOT zero
Then: list_realtime_events(event_type=T, tickers=[...]) in `order`, skipping a
type whose cache.count is 0 (the 12h cache is cold for it — say so; it is not
evidence nothing happened). Narrow every follow-up with tickers=[...] to the names
just seen. For the research on the names that stand out, take the types that carry
`reports` into list_available_reports(event_types=[...],
report_date=<types[T].reports.report_date>), then get_latest_report. A family with no realtime types returns `message` naming
its durable tables.
Skip this tool ONLY for pure enumeration (list_options), an explicit "get me the
existing report" (get_latest_report), or a metric-history question with no event
in it ("Micron EPS over 8 quarters" -> company_financials(symbol="MU", limit=8,
line_items=["epsDiluted"]); cross-company or non-statement history ->
explore_data_catalogue). get_company_event_web gives a company's raw graph;
get_event_ontology gives any full card.
Requires auth (your MCP client attaches the OAuth bearer automatically).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| family | No | NO symbols, no type named: one family whose episode is walked in order — earnings, news, market_movement, institutional_ownership, analyst_activity, strategy, prediction, insider. | |
| symbols | No | Tickers to situate, e.g. ["MAR"] (max 5; one backend call each, in parallel). Omit for the whole market. | |
| question | No | NO symbols: the user's words verbatim, keyword-routed to event types / a family only when neither event_types nor family is passed. Naming nothing is a market-wide sweep. Ignored with symbols. | |
| sections | No | WITH symbols: sections to return (default web, cards, relations, entailed). Add episodes for the episode definitions; informs_relations is the largest and least targeted. | |
| card_types | No | WITH symbols: return cards only for these event types instead of every type present; entailed and relations shrink with them. E.g. ["financials_release"] with event_type. | |
| event_type | No | WITH symbols: the realtime event type the question is about, e.g. "financials_release" for a 10-Q/10-K, "ir_publication" for a deck, "8k_release". Its card is returned even when it has no node in the window. Valid values: list_options("event_types"). | |
| event_types | No | NO symbols: the realtime event types the question is about, in the order named, e.g. ["ir_publication"] for decks, ["13f_exited"] for hedge-fund exits. Step 1 of the order is the first. Valid values: list_options("event_types"). | |
| top_tickers | No | NO symbols: members listed per event type from the realtime cache, newest first (default 10, max 50). | |
| window_days | No | WITH symbols: event-web look-back in days (default 14, max 90). | |
| include_keys | No | Fields kept inside each card. With symbols the default is persisted_in, sources, entails, preceded_by, layer, read_by, refreshed_by ([] = whole cards; keep read_by: it names the tool that reads each table). With no symbols the default is the trimmed market card. | |
| include_fetch | No | WITH symbols: keep each web node's `fetch` hint (the follow-up call and, on data updates, a signed_query_url for get_signed_sql_drilldown). false shrinks the web 2-4x. | |
| report_inventory | No | NO symbols: include fresh/stale report-plan counts per plan-earning type. |