download_dataset
Read-only
Read one of Flexreport's versioned daily data feeds by date — the feeds and what each holds come from list_options("data_feeds"). Use it over explore_data_catalogue when one of those feeds answers the ask for a date or date range. RATE-LIMITED TO 3 CALLS PER WEEK per user (all datasets together, failed calls included): make ONE call with the narrowest dates, never test-fire it, never re-call because a result was trimmed, and never poll it from a dashboard — fetch once and embed the rows.
list_options("data_feeds") lists the feeds — free, no rate limit — each as
{dataset, description, returns, date_field, event_types}: `returns` is "rows" or
"download_links" (presigned URLs), `date_field` is the column the dates filter on,
and `event_types` the valid filter values (null = unsupported). This tool checks
`dataset` and `event_types` against that list before spending a download call. For
open-ended analysis ("why did X move") keep to explore_data_catalogue.
Sizing — always pass explicit ET dates, the narrowest that answer the request, and
widen only when the user asks ("this month", "since launch"): the week ahead for
forward-looking predictions; the most recent completed date for "how did it do"; one
business day for documents (nightly files land after the 22:00 ET build, so before
then the latest complete day is the previous business day). A range with nothing
published returns no rows, not an error.
Shaping, applied here to the one response:
- Every row carries `published_at`, the UTC time its file version was published —
quote the result's `published_at` as the data's as-of.
- Document feeds (rows with `document_url` + `page_number`) come back ONE ROW PER
DOCUMENT (page columns dropped, `pages_with_text` added); include_page_text=true
returns the page rows with their full `content`.
- `download_links` feeds return links valid 12 HOURS: hand each `url` to the user as
a link, never store it or inline the file.
Returns {dataset, start_date, end_date, bulk_download, latest_file_version, shape,
rows, row_count, truncated, published_at, notes}. `notes` lists what was left out
(pages collapsed, symbols filtered, rows truncated) — tell the user in one line.
Requires auth (your MCP client attaches the OAuth bearer automatically). Also counts
once against the plan's daily request quota.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dataset | Yes | A `dataset` from list_options("data_feeds") (free, no rate limit). | |
| symbols | No | Keep only these tickers, e.g. ["SNOW"]. Applied to the response here (the feed itself has no symbol filter); not possible for `download_links` feeds. | |
| end_date | No | Last date, inclusive, YYYY-MM-DD. Omit for start_date alone (one day). | |
| max_rows | No | Cap on rows returned (after filtering and collapsing); the result then carries row_count and truncated: true. | |
| start_date | Yes | First date, inclusive, YYYY-MM-DD, on the feed's `date_field` (ET). Pick the narrowest window that answers the request. | |
| event_types | No | Narrow to these event types, from the feed's `event_types` in list_options("data_feeds"). Omit for all; ignored by feeds whose `event_types` is null. | |
| bulk_download | No | True ignores the dates and returns EVERY published date. Only when the user explicitly asks for full history. | |
| document_urls | No | Document feeds only: keep only these documents (their `document_url`), e.g. to read one deck's pages. | |
| include_page_text | No | Document feeds (one row per page) only. False (default) = one row per document, no text. True = one row per page with its full `content` — only when the user wants the text, and narrowed with symbols / document_urls. | |
| latest_file_version | No | True (default) = newest file version per date. False = every version ever published — only for point-in-time / backtest questions ("what did the model say Monday morning?"). |