Skip to main content
Glama

list_available_reports

Read-only

List the symbols with a report plan SAVED on or after report_date (default: TODAY) — the real-time research get_latest_report can render right now, and whether each renders in seconds or needs a rebuild.

A plan is saved the moment a material event publishes for a symbol (eps_update,
eps_release, 8k_release, financials_release, ir_publication, transcript_update) and
nightly for company_update. This tool is the INVENTORY of those plans — it does not
build or return a report. Returns `plans`, newest plan first:
  {"plans": [{"symbol": "NVDA", "event_type": "eps_release",
              "planned_at": "<iso>",   # when the plan was built
              "queued_at": "<iso>",    # the report inputs (the event) it was built from
              "fresh": true,           # see below
              "source": "redis"}, ...]}  # redis = built within 3 days, s3 = older durable copy
`fresh` applies the SAME rule get_latest_report (/get-cached-reports) applies:
  fresh: true  -> get_latest_report([ticker]) renders this plan into the user's
                  template in ~10-20 s (it comes back under `rendering`). These are
                  the names to pull.
  fresh: false -> a newer event landed after the plan; get_latest_report returns the
                  stale cached PDF, and only generate_report_for_stock(ticker) — a full
                  rebuild, ~10 min — refreshes it. Say so before the user waits on it.
  not listed   -> no plan IN THE WINDOW. An empty result does not mean there is no
                  research — it means nothing was planned in the window. Widen
                  `report_date` before concluding a symbol has no plan; only then is
                  a first build a full ~10 min run (or `onboard_symbol` if the ticker
                  is not covered).

TWO WAYS IN:
  1) Event-first — list_realtime_events(event_type=...) shows what just published; call
     this with event_types=[<that type>] to confirm which of those symbols have a plan
     and which are fresh, then get_latest_report(symbols=[...]) for the ones the user
     wants. (An event in the 12h cache with no plan here means the plan is still being
     built — check again in a minute.)
  2) Research-first — skip the events step: call this with no filter for every symbol
     planned TODAY, grouped by the event that triggered it. Plans stay renderable for 7
     days, so pass report_date="YYYY-MM-DD" (e.g. 3 days back) when the user wants the
     running inventory rather than today's, or when today's list comes back thin.

PICKING THE MOST PERTINENT PLANS ("pull the most relevant reports today", "what's worth
reading right now"): the list is an inventory, not a ranking — a nightly company_update
plan sits next to a transcript that just landed. Rank by the EVENT, not by the plan:
  a) FILTER on what published — list_realtime_events for the material types
     (transcript_update, 8k_release, ir_publication, eps_release / eps_update,
     financials_release) and for the tape (biggest_mover, biggest_loser,
     biggest_gainer). A symbol on BOTH lists — a filing or call AND a move — is
     the strongest candidate.
  b) ANALYZE the content — read the event payloads (what the 8-K discloses, what the
     call said, what the deck guides to) and keep the ones that change something;
     `situate(question=...)` and get_event_ontology say what each type means.
  c) CONFIRM with intraday price action — detect_intraday_outlier_jumps(tickers=[...])
     (and get_aftermarket_data after the close) shows whether the market treated it
     as significant; a print with no reaction ranks below a mover with a filing.
  d) MATCH to plans — call this tool with event_types=[<the types from a>] and keep
     the candidates that appear, preferring `fresh: true`; `queued_at` should be the
     event you just read.
  e) PULL the winners — get_latest_report(symbols=[...]) for the few that survived,
     not the whole list: the fresh ones render in seconds; a stale one comes back as
     its cached PDF. Tell the user which is which, and offer generate_report_for_stock
     rebuilds (~10 min each) only if they want to wait.

Not `get_latest_report`: that PULLS the reports for named tickers (renders the fresh
plans, serves the cached PDF for the rest). This tool answers "for which symbols could
I get a fresh report?" — by event, across the universe — before anything is pulled. Not
`generate_research_report`: that is the broad, topical, or multi-company writeup;
the plans listed here are single-symbol, event-anchored reports.

Synchronous, cheap (500/hour). Requires auth (your MCP client attaches the OAuth
bearer automatically).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
event_typesNoPlan-earning event types to list: eps_update, eps_release, 8k_release, financials_release, ir_publication, transcript_update, company_update. Any other type is a 422. Omit for every type.
report_dateNoLower bound on when the plan was built, YYYY-MM-DD (default today). Earlier dates widen the window and cost more; plans stay renderable for 7 days. A malformed date is a 422.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
plansYesSaved report plans in the window, newest first. Empty means nothing was planned in the window.

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?

Beyond the readOnlyHint annotation, it discloses that it does not build/return reports, rate limit (500/hour), synchronous behavior, auth requirement, the meaning of an empty result, the redis-vs-s3 source distinction, and the fresh/stale render semantics. This is well past what the annotation alone conveys.

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?

Purpose is front-loaded and the body is organized under clear headers (TWO WAYS IN, PICKING THE MOST PERTINENT PLANS). It is on the verbose side with some redundancy in the workflow narrative, but nearly every sentence carries routing or behavioral information.

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?

Covers auth, rate limits, error conditions, the empty-result edge case, and the full decision flow from event to plan to pull, despite an output schema already existing. An agent has everything needed to call it correctly and interpret the response.

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 schema documents both params, but the description adds meaningful semantics: report_date is a lower bound defaulting to today, earlier dates widen the window and cost more, and plans stay renderable for 7 days. It also enumerates the valid event_types and the 422 failure mode.

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?

The opening sentence states a specific verb and resource — 'List the symbols with a report plan SAVED on or after report_date' — and immediately scopes it as an inventory that does not build or return a report. It explicitly differentiates from the two nearest siblings, get_latest_report and generate_research_report.

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?

Provides two named entry paths (event-first vs research-first), tells the agent when to widen report_date, when to use list_realtime_events first, and when generate_report_for_stock is the correct follow-up. Explicit exclusions ('Not get_latest_report... Not generate_research_report') remove ambiguity about alternatives.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources