ferric-fred-mcp

get_observations

Read-onlyIdempotent

Retrieve FRED series observations as date/value pairs with optional filters for date range, units, aggregation, sort, and limit. Also supports ALFRED vintage data for point-in-time views.

Instructions

Fetch a FRED series' observations (date/value pairs, each with its ALFRED real-time period). Supports an optional date range, a units transform, aggregation to a lower frequency, sort order, and a result limit. For point-in-time/vintage (ALFRED) data, set realtime_start/realtime_end (both together; same date = the series as known on that day) and/or vintage_dates.

Input Schema

TableJSON Schema

Name	Required	Description
`end`	No	Latest observation date, `YYYY-MM-DD`.
`sort`	No	Sort order by date.
`limit`	No	Maximum number of observations to return.
`start`	No	Earliest observation date, `YYYY-MM-DD`.
`units`	No	Units transformation to apply.
`frequency`	No	Frequency to aggregate observations down to. FRED can only aggregate to a frequency coarser than the series' native one (e.g. a monthly series to quarterly or annual, never a coarser series to a finer one); asking for a finer or invalid frequency returns a FRED 400.
`series_id`	Yes	The FRED series id, e.g. `GNPCA` or `UNRATE`.
`aggregation`	No	Aggregation method — how observations are combined when aggregating to `frequency`. Requires `frequency`; supplying it without `frequency` is rejected (an invalid-params error), not silently ignored.
`realtime_end`	No	ALFRED: end of the real-time period, `YYYY-MM-DD`. Must be given together with `realtime_start`.
`vintage_dates`	No	ALFRED: specific revision dates to fetch, each `YYYY-MM-DD`. Each date selects that vintage of the series.
`realtime_start`	No	ALFRED: start of the real-time period, `YYYY-MM-DD` — the data as it was known then. Use the same value for `realtime_end` to snapshot the series as of one day (point-in-time). Must be given together with `realtime_end`.

Output Schema

TableJSON Schema

Name	Required	Description
`count`	Yes	The number of observations returned.
`series_id`	Yes	The series the observations belong to.
`observations`	Yes	The observations, in the requested sort order.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.3.11Aug 1, 2026
RemovedJul 20, 2026

Changed2 schema fields changedv0.3.9Jul 14, 2026

changedInput schema / properties / aggregation / description

Previous value: -"Aggregation method, used together with `frequency`."New value: +"Aggregation method — how observations are combined when aggregating to\n`frequency`. Requires `frequency`; on its own it is ignored."

changedInput schema / properties / frequency / description

Previous value: -"Frequency to aggregate observations down to."New value: +"Frequency to aggregate observations down to. FRED can only aggregate to a\nfrequency **coarser than** the series' native one (e.g. a monthly series to\nquarterly or annual, never a coarser series to a finer one); asking for a\nfiner or invalid frequency returns a FRED 400."

Changed7 schema fields changedv0.3.7Jul 7, 2026

addedInput schema / properties / realtime_end

Added value: +{
+  "description": "ALFRED: end of the real-time period, `YYYY-MM-DD`. Must be given together\nwith `realtime_start`.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedInput schema / properties / realtime_start

Added value: +{
+  "description": "ALFRED: start of the real-time period, `YYYY-MM-DD` — the data as it was\nknown then. Use the same value for `realtime_end` to snapshot the series\nas of one day (point-in-time). Must be given together with `realtime_end`.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedInput schema / properties / vintage_dates

Added value: +{
+  "description": "ALFRED: specific revision dates to fetch, each `YYYY-MM-DD`. Each date\nselects that vintage of the series.",
+  "items": {
+    "type": "string"
+  },
+  "type": [
+    "array",
+    "null"
+  ]
+}

changedOutput schema / $defs / Observation / description

Previous value: -"A single observation in a FRED series: a calendar date and its value.\n\nFRED transmits the value as a string and encodes a *missing* value as the\nsentinel `\".\"`, which maps to `None`. Any other value parses to `Some(f64)`;\na non-`\".\"` value that fails to parse is a deserialization error, not a\nsilent `None` (see ADR-0004 and ADR-0005).\n\nOn *serialization* the value is emitted as a JSON number or `null` — typed\nJSON for consumers, not FRED's stringly-typed `\".\"` wire format."New value: +"A single observation in a FRED series: a calendar date, its value, and the\nreal-time period that value was current for (ALFRED — ADR-0024).\n\nFRED transmits the value as a string and encodes a *missing* value as the\nsentinel `\".\"`, which maps to `None`. Any other value parses to `Some(f64)`;\na non-`\".\"` value that fails to parse is a deserialization error, not a\nsilent `None` (see ADR-0004 and ADR-0005).\n\n[`realtime_start`](Observation::realtime_start) /\n[`realtime_end`](Observation::realtime_end) bound the period the value was the\ncurrent one — the ALFRED dimension. For a plain latest query FRED returns\ntoday for both; a point-in-time or `vintage_dates` query returns the period\nthe archived value held.\n\nOn *serialization* the value is emitted as a JSON number or `null` — typed\nJSON for consumers, not FRED's stringly-typed `\".\"` wire format."

addedOutput schema / $defs / Observation / properties / realtime_end

Added value: +{
+  "description": "End of the real-time period this value was current for (ALFRED). Equal to\ntoday for a latest query; the archived vintage's end otherwise.",
+  "format": "date",
+  "type": "string"
+}

addedOutput schema / $defs / Observation / properties / realtime_start

Added value: +{
+  "description": "Start of the real-time period this value was current for (ALFRED). Equal\nto today for a latest query; the archived vintage's start otherwise.",
+  "format": "date",
+  "type": "string"
+}

changedOutput schema / $defs / Observation / required

Previous value: -[
-  "date",
-  "value"
-]New value: +[
+  "realtime_start",
+  "realtime_end",
+  "date",
+  "value"
+]

Changed1 schema field changedv0.3.6Jul 6, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$defs": {
+    "Observation": {
+      "description": "A single observation in a FRED series: a calendar date and its value.\n\nFRED transmits the value as a string and encodes a *missing* value as the\nsentinel `\".\"`, which maps to `None`. Any other value parses to `Some(f64)`;\na non-`\".\"` value that fails to parse is a deserialization error, not a\nsilent `None` (see ADR-0004 and ADR-0005).\n\nOn *serialization* the value is emitted as a JSON number or `null` — typed\nJSON for consumers, not FRED's stringly-typed `\".\"` wire format.",
+      "properties": {
+        "date": {
+          "description": "The observation date. FRED dates are calendar dates with no time or zone,\nwhich [`NaiveDate`] models exactly.",
+          "format": "date",
+          "type": "string"
+        },
+        "value": {
+          "description": "The observation value; `None` when FRED reports it as missing (`\".\"`).",
+          "format": "double",
+          "type": [
+            "number",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "date",
+        "value"
+      ],
+      "type": "object"
+    }
+  },
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "properties": {
+    "count": {
+      "description": "The number of observations returned.",
+      "format": "uint",
+      "minimum": 0,
+      "type": "integer"
+    },
+    "observations": {
+      "description": "The observations, in the requested sort order.",
+      "items": {
+        "$ref": "#/$defs/Observation"
+      },
+      "type": "array"
+    },
+    "series_id": {
+      "description": "The series the observations belong to.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "series_id",
+    "count",
+    "observations"
+  ],
+  "type": "object"
+}

First observedv0.3.2Jul 6, 2026

TDQS

A4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context about ALFRED point-in-time/vintage behavior and the constraint that realtime_start/realtime_end be used together, going beyond the annotations without contradicting them.

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

Conciseness5/5

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

Two sentences front-load the core purpose, then efficiently summarize optional capabilities and the special ALFRED case. Every sentence earns its place with no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter read-only tool with an output schema, the description covers the primary function, optional transforms, and the critical ALFRED usage nuance. Parameter-level constraints live in the schema, so the description does not need to repeat them; the only notable gap is lack of sibling-tool differentiation.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already explains every parameter (units enums, aggregation method, realtime constraints, etc.). The description restates some high-level capabilities and adds a compound hint for realtime_start/realtime_end, but it does not materially add meaning beyond the rich schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description uses a specific verb ('Fetch') and clearly identifies the resource ('a FRED series' observations') with output described as date/value pairs plus ALFRED real-time periods. It is unambiguous but does not explicitly distinguish itself from sibling tools like get_series_data or get_series_vintagedates, so it misses the top score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context for when to use the tool (fetching observations with optional date range, units, aggregation, sort, limit) and gives explicit ALFRED guidance: realtime_start/realtime_end must be set together, and same date gives a point-in-time snapshot. It does not name alternative tools or state exclusions, so it stops short of a 5.

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