Skip to main content
Glama

Kaleidoscope MCP (SEC & financial data)

Macro Series (FRED data — ALFRED vintages, honest first-print vs revised values for backtests)

macro_series
Read-onlyIdempotent

Point-in-time historical values for a FRED macro series — backed by ALFRED vintages so a query at as_of=2020-05-15 for UNRATE returns the first-print value (14.7) not the later revision (14.8). The honest PIT macro reader.

Why this is the right shape: every other macro source returns 'current best value' which silently puts revised data into a backtest of a strategy that ran on first-print data — lookahead bias. ALFRED vintages let you ask 'what did everyone see on day X' and get the truth.

Inputs:

  • series_id (required) — FRED id, e.g. UNRATE, CPILFESL, DGS10, VIXCLS, NFCI. See covered list below.

  • start / end — YYYY-MM-DD bounds on obs_date (observation period). start default is as_of - 1 year; end defaults to as_of.

  • as_of — YYYY-MM-DD vintage cutoff (default today). Returns latest vintage ≤ this date per obs_date. 0 rows is a valid answer — means the print hadn't been released by as_of (e.g. UNRATE for 2020-04-01 obs at as_of='2020-05-01' = empty; the April report was released 2020-05-08).

  • limit — max rows returned (default 500, max 5000 — full daily series can be large).

as_of_effective = MAX(realtime_start) among the returned rows — the true currency of the data at as_of. If no rows: as_of_effective echoes as_of with a no_data_before_as_of: true flag (the 'print not yet released' signal).

Coverage (44 series total, daily refresh):

  • 24 ALFRED-true vintages (revision-prone, reconstruct first-print vs revised exactly): CPILFESL, PAYEMS, UNRATE, INDPRO, CFNAIMA3, UMCSENT, ICSA, GACDFSA066MSFRBPHI (Philly Fed mfg), GACDISA066MSFRBNY (Empire Manufacturing), BAML credit indices (BAMLC0A0CM, BAMLC0A1CAAA, BAMLC0A3CA, BAMLC0A4CBBB, BAMLH0A0HYM2, BAMLH0A1HYBB, BAMLH0A3HYC), DCOILWTICO (WTI), DTWEXBGS (USD broad index), ECBDFR, THREEFYTP10 (Adrian-Crump term premium), some intl rates (IRSTCB01JPM156N, IRSTCI01AUM156N, IRSTCI01GBM156N), TEDRATE.

  • 20 final_synth series (daily/weekly market series — non-revised so synthesized first-knowable date as obs_date + 1 business day): Treasury yields (DGS1MO, DGS3MO, DGS6MO, DGS1-DGS30), DFF (Fed Funds), DFII10 (10Y TIPS), T10Y2Y / T10Y3M / T10YIE (curve + breakeven), VIXCLS, NFCI (Chicago Fed NFCI), STLFSI4 (St. Louis Fed Financial Stress), USEPUINDXD (EPU index).

Important caveat on final_synth: for the 2 recomputed weekly indices (NFCI, STLFSI4), final_synth means intermediate revisions are NOT represented — final values only. For market-priced series (yields, VIX, FX, oil), the synthesized date is correct because those don't get revised.

Smoke goldens (FRED team 2026-06-14, verified live): UNRATE 2020-04-01 first-print 14.7 at as_of='2020-05-15' (realtime_start=2020-05-08); UNRATE 2020-04-01 at as_of='2020-05-01' returns 0 rows (April report released 2020-05-08, so not yet knowable). Pair with macro_calendar for 'when does the next print drop.'

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "series_id": "<series_id>"
    },
    "name": "macro_series"
  }
}

Input Schema

NameRequiredDescriptionDefault
endNoUpper bound on obs_date YYYY-MM-DD (default as_of).
as_ofNoVintage cutoff date YYYY-MM-DD (default today). The PIT key — selects the vintage of value that was current at this date.
limitNoMax rows returned (default 500, max 5000).
startNoLower bound on obs_date YYYY-MM-DD (default as_of - 1 year).
series_idYesFRED series id (e.g. UNRATE, CPILFESL, DGS10). See covered list in the description.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare read-only, idempotent, non-destructive and closed-world, so the safety profile is covered; the description adds substantial non-obvious behavior on top: the as_of_effective = MAX(realtime_start) rule, the no_data_before_as_of flag on empty results, the limit ceiling of 5000, and the final_synth caveat that intermediate revisions for NFCI/STLFSI4 are not represented. It stops short of describing row/field shape beyond the vintage metadata, which is the one remaining gap.

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 core claim and bolded section headers for Inputs, Coverage and caveats, so it scans well despite its length. It is on the long side and repeats the zero-row case twice (the as_of bullet and the smoke goldens), and the 'Why this is the right shape' framing is mildly editorial, but nearly every block carries operational 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?

No output schema exists, so the description carries the return-value burden itself and does so: per-obs_date latest vintage selection, as_of_effective semantics, and the explicit empty-result flag. Combined with the covered-series list and the final_synth revision caveat, an agent has enough to call this correctly and interpret edge-case results without guessing.

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; the description still adds meaning the schema lacks — which concrete series_ids are actually covered (44 enumerated, split by vintage fidelity), what as_of does to per-obs_date selection, and the default start = as_of - 1 year interaction. The coverage taxonomy in particular is information an agent cannot get from the schema at all.

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 verb and resource — point-in-time historical values for a FRED macro series — and immediately pins the distinguishing mechanism (ALFRED vintages, first-print vs revised) with a concrete UNRATE 14.7/14.8 example. An agent can tell this apart from a generic macro-data fetch without opening the 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?

Explicitly frames the when-to-use case (backtests needing first-print data) against the alternative behavior it replaces ('every other macro source returns current best value'), and routes to the sibling for a different question: 'Pair with macro_calendar for when does the next print drop.' It also pre-empts a likely misinterpretation by stating that 0 rows is a valid answer with the release-date reasoning.

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