Skip to main content
Glama

Flexreport Finance

by com.flexreportfinapi.mcp
OverviewDiscussionsAdmin

get_event_ontology

Read-only

The platform's event ONTOLOGY — what an event TYPE means for everything else. Call it FIRST on any real-time, single-company, or event-driven request; it is the map the other calls are planned from.

===> `situate(...)` composes this with the event web and the cache state and
hands you a plan — start there. Call this tool directly for the FULL card of an
event type, a relation card, a whole family, or the unfiltered graph, when the
plan did not cover what you need next.

===> REQUISITE for: any real-time / live-events request, any "what
happened / why / catch me up" question, and BEFORE aiming explore_data_catalogue or
generate_report_for_stock at a company whose situation is event-driven. Cheap,
synchronous, public, symbol-INDEPENDENT and cacheable — fetch once per event type
(or once unfiltered, ~230 KB) and reuse for the whole conversation.

Pass exactly ONE filter for a small card (~5-10 KB):
  event_type="eps_update"        one event type and the relations it entails
  relation="eod_stock_prices"    one table/view and the event types that entail it
  family="earnings"              every event type and relation in a family
No filter -> the whole class graph (21 event types, ~300 relations, 20 tools).
Web nodes from get_company_event_web carry the join keys verbatim: pass a node's
`type` as event_type, its `relation` as relation, its `family` as family.

An event_type card carries:
  about                    what the event is ABOUT: symbol | filer | strategy. A 13F
                           event is a FILER's action across N names — the symbol
                           you asked about is one of them.
  persisted_in             the durable table to read once the event has aged out
                           of the realtime cache (realtime_cache_ttl_hours, 12h) —
                           list_realtime_events returns [] after that; the data is
                           still there, in this relation.
  entails.<layer>          the relations WRITTEN by the same chain run (mined, with
                           run counts) plus every view above them (pg_depend),
                           bucketed base / silver / gold / dimension / analysis.
                           These are the tables that are FRESH because this event
                           fired — name them explicitly in explore queries.
  entails.realtime_events  event types that usually FOLLOW, each with rate,
                           median_lag_hours, lift, mode (trigger = dispatched by the
                           same chain, near-certain; sequence = world-ordered,
                           independently detected, probabilistic), certainty /
                           expected_within_hours when declared, and persisted_in.
  preceded_by              the inverse — what should ALREADY exist earlier in the web.
  episodes                 named world-order sequences (earnings, realtime_mover,
                           thirteen_f_cycle, news) with this event's position — the
                           whole shape of the situation from any one member.
  produced_by[].schedule   the workflow that publishes it, its cron, and
                           next_run_at (America/New_York).
  deepened_by              the tools that deepen this event once you have its payload.
  informs                  DOMAIN causality (news -> prices, earnings -> estimates):
                           what an analyst checks next. Declared and the WEAKEST
                           edge — never present it as lineage.
  evidence                 how many of these events the platform has seen.

A relation card carries: layer, family, cadence (update_frequency + prose),
derives_from / feeds (pg_depend), computed_from / computes (LLM and model writers),
refreshed_by[].schedule with next_run_at, read_by (the MCP tools that read it),
entailed_by (event types), informs.

THE FRESHNESS CHECK — the reason this tool exists: compare a web node's `at` with a
downstream relation's refreshed_by[].schedule[].next_run_at. If next_run_at is AFTER
the event, that relation does NOT reflect the event yet. Do not query it for the
reaction — use the intraday tools (detect_intraday_outlier_jumps,
get_aftermarket_data) or say the daily table lags.

Every edge carries `provenance` (mined | declared | pg_depend | static:tasks.py |
beat | catalogue | data_model), the same honesty axis as the web's `cause`: mined
and pg_depend are facts, declared is the platform's own judgment, informs is domain
intuition. Quote the grade when you lean on an edge. format="triples" returns raw
subject-predicate-object rows instead of cards. degraded=true means the table has
not been built yet, not that the type is unknown.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
familyNoOne family, e.g. "earnings" (a web node's `family`).
formatNocards (grouped, default) or triples (raw subject-predicate-object rows).cards
relationNoOne table/view, e.g. "eod_stock_prices" (a web node's `relation`).
event_typeNoOne event type, e.g. "eps_update" (a web node's `type`). Pass exactly one filter.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
as_ofNo
edgesNoSubject-predicate-object rows (triples format).
degradedNoTrue when the ontology table is not built yet, not that the type is unknown.
episodesNo
relationsNoRelation cards, keyed by table/view (cards format).
event_typesNoEvent-type cards, keyed by type (cards format).
realtime_cache_ttl_hoursNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Annotations only declare readOnlyHint=true, yet the description discloses cost/latency profile (cheap, synchronous, public, symbol-independent, cacheable, fetch once and reuse), response sizes (~5-10 KB per card, ~230 KB unfiltered), the `degraded=true` meaning, and the freshness/lag semantics that are the tool's whole rationale.

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?

Well front-loaded and sectioned with headers, but it is very long and the field-by-field enumeration of what an event_type/relation card carries duplicates content that a present output schema already covers. Much of it earns its place; a meaningful fraction does not.

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?

For a complex ontology tool with a rich return surface, the description covers selection, sequencing relative to `situate`, filter semantics, freshness caveats, and provenance grading. Even accounting for the existing output schema, an agent has everything needed to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% so the baseline is 3, but the description adds real value beyond the schema: the 'pass exactly ONE filter' constraint, expected card sizes per filter, and the mapping of web-node keys (`type`/`relation`/`family`) onto the parameters. The per-parameter examples largely restate the schema, keeping it from a 5.

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?

States a specific resource and its scope: 'the platform's event ONTOLOGY — what an event TYPE means for everything else.' It explicitly distinguishes itself from siblings by naming `situate(...)` as the composing entry point and describing when to call this one directly instead.

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?

Gives explicit when-to-use ('Call it FIRST on any real-time, single-company, or event-driven request'), names the alternative (`situate` composes this), and lists when-not/requisite conditions plus the freshness-check routing to `detect_intraday_outlier_jumps` / `get_aftermarket_data`. Nothing is left to inference.

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

All Flexreport Finance toolsInspect
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