ferric-fred-mcp

get_release_tables

Read-onlyIdempotent

Fetch a FRED release's table tree as JSON, showing nested sections, tables, and series rows. Optionally include observation values or scope to a specific element subtree.

Instructions

Fetch a FRED release's table tree — the nested layout (sections, tables, and the series rows beneath them) it uses to present its series. Optionally scope to the subtree rooted at one element id, and optionally fold each series row's observation value (at observation_date, or FRED's latest) into the tree via include_observation_values. Returns the tree as structured JSON, with each element's children nested under it. Note: element_id takes precedence over release_id — FRED resolves the element by its own id, so an element from another release yields that release's subtree. Note: each returned row's observation_date is FRED's display label (e.g. "Jun 2026"), not an ISO YYYY-MM-DD date like the inputs — it is not round-trippable back into any date parameter.

Input Schema

TableJSON Schema

Name	Required	Description
`element_id`	No	Return only the subtree rooted at this element id (omit for the whole tree). Takes precedence over `release_id`: FRED resolves the element by its own id, so if it belongs to a different release you get that release's subtree and `release_id` is effectively ignored. Pass an element that belongs to `release_id`.
`release_id`	Yes	The FRED release id, e.g. 10 (Consumer Price Index).
`observation_date`	No	Observation value as of this date, `YYYY-MM-DD`. Implies `include_observation_values`.
`include_observation_values`	No	Fold each series row's observation value into the tree (structure-only otherwise). FRED returns its latest value unless `observation_date` is set.

Output Schema

TableJSON Schema

Name	Required	Description
`name`	Yes	The name of the requested element, when a subtree was requested.
`roots`	Yes	The root elements of the tree, ordered by element id. (FRED's redundant top-level `release_id` — a string, unlike the numeric one on each element — is dropped; the caller already knows it.) On the wire FRED names this `elements` (a flattened object keyed by id); we read that, keep only the tree's true roots, and re-serialize as a `roots` array (see `roots_from_map`).
`element_id`	Yes	The id of the requested element, when a subtree was requested.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedJul 20, 2026

changedOutput schema / $defs / ReleaseTableElement / properties / observation_date / description

Previous value: -"FRED's formatted label for the [`observation_value`](ReleaseTableElement::observation_value)\ndate, e.g. `\"Jun 2023\"` or `\"2023\"` — a display string keyed to the\nseries' frequency, **not** an ISO date (unlike the request's\n`observation_date`). `None` when values weren't requested or the element\ncarries no series."New value: +"FRED's formatted label for the [`observation_value`](ReleaseTableElement::observation_value)\ndate, e.g. `\"Jun 2023\"` or `\"2023\"` — a human-readable **display string**\nkeyed to the series' frequency, **not** an ISO `YYYY-MM-DD` date (unlike\nevery date *input*, including the request's `observation_date`). It is\ntherefore **not round-trippable**: it cannot be parsed deterministically\nor fed back into any date parameter. `None` when values weren't requested\nor the element carries no series."

Changed2 schema fields changedv0.3.9Jul 14, 2026

changedInput schema / properties / element_id / description

Previous value: -"Return only the subtree rooted at this element id (omit for the whole\ntree)."New value: +"Return only the subtree rooted at this element id (omit for the whole\ntree). Takes precedence over `release_id`: FRED resolves the element by its\nown id, so if it belongs to a different release you get *that* release's\nsubtree and `release_id` is effectively ignored. Pass an element that\nbelongs to `release_id`."

changedOutput schema / properties / roots / description

Previous value: -"The root elements of the tree, ordered by element id. (FRED's redundant\ntop-level `release_id` — a string, unlike the numeric one on each\nelement — is dropped; the caller already knows it.)\n\nOn the wire FRED names this `elements` (an object keyed by id); we read\nthat but re-serialize as a `roots` array, matching this field and the\nflattened shape."New value: +"The root elements of the tree, ordered by element id. (FRED's redundant\ntop-level `release_id` — a string, unlike the numeric one on each\nelement — is dropped; the caller already knows it.)\n\nOn the wire FRED names this `elements` (a flattened object keyed by id);\nwe read that, keep only the tree's true roots, and re-serialize as a\n`roots` array (see `roots_from_map`)."

Changed5 schema fields changedv0.3.7Jul 7, 2026

addedInput schema / properties / include_observation_values

Added value: +{
+  "description": "Fold each series row's observation value into the tree (structure-only\notherwise). FRED returns its latest value unless `observation_date` is set.",
+  "type": [
+    "boolean",
+    "null"
+  ]
+}

addedInput schema / properties / observation_date

Added value: +{
+  "description": "Observation value as of this date, `YYYY-MM-DD`. Implies\n`include_observation_values`.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / $defs / ReleaseTableElement / properties / observation_date

Added value: +{
+  "default": null,
+  "description": "FRED's formatted label for the [`observation_value`](ReleaseTableElement::observation_value)\ndate, e.g. `\"Jun 2023\"` or `\"2023\"` — a display string keyed to the\nseries' frequency, **not** an ISO date (unlike the request's\n`observation_date`). `None` when values weren't requested or the element\ncarries no series.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / $defs / ReleaseTableElement / properties / observation_value

Added value: +{
+  "default": null,
+  "description": "The element's observation value at the request's `observation_date` (or\nFRED's latest), present only when the request set\n[`include_observation_values`](crate::ReleaseTablesRequest::include_observation_values).\n`None` for a structural (non-`series`) element, when values weren't\nrequested, or when FRED reports the value as missing (`\".\"`) — mirroring\n[`Observation`](crate::Observation)'s value handling.",
+  "format": "double",
+  "type": [
+    "number",
+    "null"
+  ]
+}

changedOutput schema / $defs / ReleaseTableElement / required

Previous value: -[
-  "element_id",
-  "release_id",
-  "parent_id",
-  "series_id",
-  "type",
-  "name",
-  "line",
-  "level",
-  "children"
-]New value: +[
+  "element_id",
+  "release_id",
+  "parent_id",
+  "series_id",
+  "type",
+  "name",
+  "line",
+  "level",
+  "observation_value",
+  "observation_date",
+  "children"
+]

Changed1 schema field changedv0.3.6Jul 6, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$defs": {
+    "ReleaseElementId": {
+      "description": "A FRED release-table element identifier — the numeric id of a node in a\nrelease's table tree (a section, table, or series row; see\n`fred/release/tables`).\n\nA `Copy` newtype over `u32`, mirroring [`ReleaseId`]; `#[serde(transparent)]`\ncarries it as the bare integer FRED sends (ADR-0005). `Ord` lets the table\ndeserializer order its roots deterministically by id.",
+      "format": "uint32",
+      "minimum": 0,
+      "type": "integer"
+    },
+    "ReleaseId": {
+      "description": "A FRED release identifier — the numeric id of a data release (a publication\nsuch as \"Gross Domestic Product\").\n\nA `Copy` newtype over `u32`, mirroring [`CategoryId`]; `#[serde(transparent)]`\ncarries it as the bare integer FRED sends (ADR-0005).",
+      "format": "uint32",
+      "minimum": 0,
+      "type": "integer"
+    },
+    "ReleaseTableElement": {
+      "description": "A node in a release's table tree: a section, a table, or a series row. Nodes\nnest via [`children`](ReleaseTableElement::children) to arbitrary depth.",
+      "properties": {
+        "children": {
+          "default": [],
+          "description": "The child elements nested beneath this one (empty for a leaf).",
+          "items": {
+            "$ref": "#/$defs/ReleaseTableElement"
+          },
+          "type": "array"
+        },
+        "element_id": {
+          "$ref": "#/$defs/ReleaseElementId",
+          "description": "This element's id."
+        },
+        "level": {
+          "description": "The element's depth as FRED reports it (`\"0\"` at the top). Mirrors the\nnesting of [`children`](ReleaseTableElement::children).",
+          "type": "string"
+        },
+        "line": {
+          "default": null,
+          "description": "The element's line number within its table, when FRED provides one.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "name": {
+          "description": "Human-readable label, e.g. `\"CPI for U.S. City Average\"`.",
+          "type": "string"
+        },
+        "parent_id": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/ReleaseElementId"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "The parent element's id, absent for a root."
+        },
+        "release_id": {
+          "$ref": "#/$defs/ReleaseId",
+          "description": "The release this element belongs to."
+        },
+        "series_id": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/SeriesId"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "The series this element points to, for a `series`-type row. Absent for\nstructural elements (sections/tables), where FRED sends `null` or `\"\"`."
+        },
+        "type": {
+          "description": "The element kind, e.g. `\"section\"`, `\"table\"`, or `\"series\"`. Kept as a\nstring (its vocabulary is open-ended and thinly documented; ADR-0017).",
+          "type": "string"
+        }
+      },
+      "required": [
+        "element_id",
+        "release_id",
+        "parent_id",
+        "series_id",
+        "type",
+        "name",
+        "line",
+        "level",
+        "children"
+      ],
+      "type": "object"
+    },
+    "SeriesId": {
+      "description": "A FRED series identifier, e.g. `GNPCA` or `UNRATE`.\n\nA newtype over `String` so a series id can't be silently swapped for another\nkind of identifier or an arbitrary string (see ADR-0005). Construction does\nno validation for now — FRED rejects malformed ids — but the newtype gives\nus a place to add it later without changing call sites.",
+      "type": "string"
+    }
+  },
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "properties": {
+    "element_id": {
+      "anyOf": [
+        {
+          "$ref": "#/$defs/ReleaseElementId"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "description": "The id of the requested element, when a subtree was requested."
+    },
+    "name": {
+      "default": null,
+      "description": "The name of the requested element, when a subtree was requested.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "roots": {
+      "description": "The root elements of the tree, ordered by element id. (FRED's redundant\ntop-level `release_id` — a string, unlike the numeric one on each\nelement — is dropped; the caller already knows it.)\n\nOn the wire FRED names this `elements` (an object keyed by id); we read\nthat but re-serialize as a `roots` array, matching this field and the\nflattened shape.",
+      "items": {
+        "$ref": "#/$defs/ReleaseTableElement"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "name",
+    "element_id",
+    "roots"
+  ],
+  "type": "object"
+}

First observedv0.3.2Jul 6, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Beyond the annotations (readOnlyHint, idempotentHint, non-destructive), the description adds valuable behavioral details: element_id overrides release_id, returned observation_date is a display label not ISO, and the date is not round-trippable. This fully informs the agent of non-obvious behavior.

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?

The description is concise yet comprehensive, using a few well-structured sentences. It front-loads the primary purpose, then covers options and caveats without unnecessary words. The two notes are placed appropriately.

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?

Given the tool's complexity (hierarchical tree, optional subtrees, observation inclusion, date caveat), the description fully covers what an agent needs to invoke it correctly. The output schema exists, so return value details are not required.

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

Parameters5/5

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

With 100% schema coverage, the baseline is 3. The description adds significant extra meaning: element_id precedence and cross-release behavior, release_id example, observation_date format and implication, and include_observation_values default logic. This greatly aids correct parameter usage.

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 description clearly states 'Fetch a FRED release's table tree' with a specific verb and resource, and elaborates on the nested layout. It distinguishes itself from sibling tools like get_release_series by focusing on the hierarchical tree structure.

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?

The description explains optional scoping and observation value inclusion, and provides important notes about element_id precedence and date format. However, it does not explicitly contrast with sibling tools or state when not to use.

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