Skip to main content
Glama

Flexreport Finance

by com.flexreportfinapi.mcp
OverviewDiscussionsAdmin

situate

Read-only

THE FIRST CALL. What is going on right now — for the market, or for the named symbols — and a ready-made PLAN of the tool calls that answer the user's question. Call it before any other flexreport tool on anything about a company, an event, or "now".

===> Call this FIRST for: "catch me up on X", "what happened / why", "anything
before earnings?", "any earnings / 8-Ks / 13F moves / movers today?", "how is X
trading", and BEFORE aiming explore_data_catalogue, list_realtime_events or a
report tool at a company. Pass the user's question verbatim in `question`: it is
matched by keyword (never an LLM) against EVERY realtime event type — decks/
presentations -> ir_publication, 8-Ks, transcripts, upgrades, gainers/losers, 13F
exits, baskets, predictions, ... — and the plan STARTS at the type the user named.
A question naming only a family ("any earnings today?") walks that family's episode;
one naming neither ("what's going on?") sweeps every episode. Synchronous, public.
  situate(symbols=["OKTA"], question="catch me up on OKTA")   one or more names (max 5)
  situate(question="any earnings events today?")             no symbols = the market
  situate(question="most significant investor decks today")  step 1 = ir_publication

It reads the company event web (what HAPPENED to this company), the event ontology
(what that KIND of event entails, what follows it and how soon, where its payload
lives after the 12h realtime cache, when each table next refreshes) and market
status, and composes them into ONE response:
  market          exchange, is_open, session
  symbols[S]      web (newest 12 nodes; full graph via get_company_event_web),
                  newest_event, episode (the DOMINANT episode in the window — its
                  anchor and each member arrived | pending | overdue with rate and
                  expected_by), cache.present / cache.expired (inferred from node
                  age vs the TTL), freshness[] (per relation: last_refresh_at,
                  next_run_at, reflects_newest_event), cards (trimmed ontology
                  cards), deepen (tools the ontology says deepen this event)
  universe        (no symbols) shape (named_types | family | sweep), asked_types,
                  the plan order and cards, and event_types: the WHOLE realtime
                  corpus (type, family, one-line description) so you never guess
  plan[]          ORDERED tool calls: {step, tool, args, why, auth, sync, optional,
                  provenance, fallback}. `tool` is an exact tool name and `args`
                  are valid for it — pass them through unchanged.
  skip[]          calls that would return nothing or waste a job (an event type
                  that aged out of the cache, a 10-minute report) — DO NOT make these.
  suggest[]       calls to make ONLY IF their `when` arises after the plan has run
                  (explore_data_catalogue lives here, never in plan[]: it is a
                  multi-minute job, and "the user wants more than the 12h cache
                  holds" is the situation that earns it).
  guidance[]      situation-scoped rules: which tables have NOT refreshed since the
                  event, which followers are overdue, filer-scoped 13F nodes.

HOW TO EXECUTE:
  1. Run plan[] in order. `sync=false` steps return a task_id — poll
     get_task_status.
  2. Never make a call that appears in skip[]; quote its `why` if the user asks.
     Make a suggest[] call only when its `when` is true — an empty realtime list
     is NOT that condition; say the cache is cold instead.
  3. Read guidance[] before writing: an "overdue" follower is "not recorded yet",
     not "did not happen"; a relation with reflects_newest_event=false shows the
     PRIOR period, never the reaction.
  4. Go beyond the plan only for what it did not cover — then get_company_event_web
     (full graph, wider window) and get_event_ontology (full card / relation /
     family) tell you what to call next.
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 growth over 8 quarters" -> explore_data_catalogue).

degraded=true means a source was unavailable (ontology not built, a web errored);
the plan still runs on what remains — follow it, and say what was unknown.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
symbolsNoTickers to situate (max 5; extras are dropped). Omit for the whole market.
questionNoThe user's question VERBATIM; keyword-matched to the realtime event types it names, which decides where the plan starts.
window_daysNoEvent-web look-back in days (backend default 7, max 90).

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
planYesORDERED tool calls to execute as-is.
skipYesCalls that would return nothing or waste a job — do not make them.
as_ofYes
scopeYessymbol (symbols were named) or universe (the market).
marketYes
suggestYesCalls to make only if their `when` arises.
symbolsNoPer-symbol blocks (symbol scope only).
degradedYesTrue when a source was unavailable; guidance[] says which.
guidanceYesSituation-scoped rules to read before writing.
universeNoMarket-wide block (universe scope only).
ontology_as_ofNo
realtime_cache_ttl_hoursYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only carry readOnlyHint=true, and the description adds a great deal beyond that: synchronous execution, keyword (never LLM) matching, cache TTL/expiry semantics, sync=false returning a task_id to poll, and degraded=true meaning a source was unavailable. It also defines the operational contract of plan/skip/suggest/guidance, which the annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the single most important routing fact ('THE FIRST CALL') and organized under clear headers with inline examples. It is long and dense, and some prose re-describes output fields that the output schema already defines, but for a meta-tool of this complexity nearly every sentence carries operational weight.

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?

An output schema exists, yet the description supplies the interpretation layer an agent actually needs: what plan[], skip[], suggest[], and guidance[] mean, how to read an 'overdue' follower, and the degraded path. Nothing required to call it or act on its response is missing.

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 meaning with worked invocations showing no-symbols = whole market and how a question naming a family vs. a specific type changes plan order. It reinforces that question must be passed verbatim, which matters for the keyword matcher.

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?

Opening line states a specific verb and resource: it reports what is happening now for the market or named symbols AND returns a ready-made plan of tool calls. It explicitly distinguishes itself from siblings (explore_data_catalogue, list_realtime_events, report tools) and brands itself as 'THE FIRST CALL', so an agent can route to it without opening a schema.

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 triggers ('catch me up', 'anything before earnings?') and explicit exclusions ('Skip this tool ONLY for pure enumeration (list_options), an explicit get_latest_report, or a metric-history question'). It names the alternative tool for each exclusion, leaving nothing 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