eia-energy-mcp-server

Previous value: -"Machine-readable failure mode. Declared by this tool: `route_not_found`: Path does not exist in the EIA taxonomy. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `route_not_found`: Path does not exist in the EIA taxonomy. `rate_limited`: EIA rate limit hit (OVER_RATE_LIMIT) while building the route tree on the first call after server start, or on the live fetch of the browsed path a cold call falls back to. `upstream_unreachable`: EIA could not be reached (connection refused or reset, DNS failure) while building the route tree on the first call after server start, or on the live fetch of the browsed path a cold call falls back to. Other values are possible when a failure originates below the handler."

Previous value: -[
-  "route_not_found"
-]New value: +[
+  "route_not_found",
+  "rate_limited",
+  "upstream_unreachable"
+]

Previous value: -"Rows to include in the immediate response. Defaults to row_limit. Set lower when chaining via register_as and only a sample is needed inline."New value: +"Rows to include in the immediate response. Defaults to row_limit. Set lower when chaining via register_as and only a sample is needed inline. The 64,000-byte response budget can end the inline rows sooner."

Previous value: -"Hard cap on rows materialized in the response (default 1000, max 10000). Rows past the cap are dropped without being counted — the response then carries truncated: true and a totalRows equal to the cap rather than a true total. Pass register_as to materialize the whole result instead and get an exact count."New value: +"Hard cap on rows materialized (default 1000, max 10000). Rows past the cap are dropped without being counted — the response then carries truncated: true and a totalRows equal to the cap rather than a true total. Pass register_as to materialize the whole result instead and get an exact count. Of the rows materialized, only as many go inline as fit the 64,000-byte response budget."

Previous value: -"Column names in projection order."New value: +"Column names in projection order. When no row is inline and the names pass 32,000 bytes, the list ends early with an entry counting the columns left out."

Previous value: -"Echo of the SQL statement that was executed — confirms the exact query that ran."New value: +"Echo of the SQL statement that was executed — confirms the exact query that ran. A statement past 4,000 bytes is echoed cut, ending with a marker that gives its full size; the whole statement ran."

Previous value: -"Guidance when either cap bound the response — names the cap that applied and how to reach the rows it withheld."New value: +"Guidance when row_limit, preview, or the 64,000-byte response budget ended the inline rows — names each bound that applied and how to reach the rows it withheld (raise the cap, or page a register_as table with ORDER BY … LIMIT/OFFSET)."

Previous value: -"Rows included in this response."New value: +"Rows included in this response. Below totalRows when preview or the response budget ended the inline rows; the notice names how to page the rest."

Previous value: -"Materialized rows, bounded by preview / row_limit."New value: +"Inline rows, bounded by preview, row_limit, and a 64,000-byte budget on each response surface — whole rows only; a row too large for the budget alone is withheld."

Previous value: -"Machine-readable failure mode. Declared by this tool: `route_not_found`: Route does not exist in the EIA taxonomy. `route_not_queryable`: Route is a category node with sub-routes, not a queryable leaf. `facet_not_found`: The facet input names an ID the route does not expose. `rate_limited`: EIA rate limit hit during facet fan-out. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `route_not_found`: Route does not exist in the EIA taxonomy. `route_not_queryable`: Route is a category node with sub-routes, not a queryable leaf. `facet_not_found`: The facet input names an ID the route does not expose. `facet_unavailable`: The facet input names a facet whose value list EIA did not return after retries. `rate_limited`: EIA rate limit hit on the route metadata request, or on the value list the facet input names. `upstream_unreachable`: EIA could not be reached (connection refused or reset, DNS failure) on the route metadata request or the route-tree build. A value list the facet input names fails as facet_unavailable instead. Other values are possible when a failure originates below the handler."

Previous value: -[
-  "route_not_found",
-  "route_not_queryable",
-  "facet_not_found",
-  "rate_limited"
-]New value: +[
+  "route_not_found",
+  "route_not_queryable",
+  "facet_not_found",
+  "facet_unavailable",
+  "rate_limited",
+  "upstream_unreachable"
+]

Previous value: -"Filterable dimensions. Each facet has an ID and a window of its valid values. Restricted to one entry when the facet input is set."New value: +"Filterable dimensions. Each facet has an ID and a window of its valid values. Restricted to one entry when the facet input is set. A facet named in unavailable_facets is left out."

Previous value: -"Guidance when values_offset lands past the last value of one or more facets — names each emptied facet, its value_count, and its last valid offset. Absent when every facet returned values."New value: +"Guidance when values_offset lands past the last value of one or more facets — naming each emptied facet, its value_count, and its last valid offset — or when EIA did not return the value list of a facet named in unavailable_facets. Absent when neither applies."

Added value: +{
+  "description": "Facet IDs whose value lists EIA did not return after retries, left out of facets. Each ID still filters eia_query_route — only its values are missing. Call eia_describe_route again to re-fetch these lists alone. Absent when every facet is in facets.",
+  "items": {
+    "description": "Facet ID whose value list EIA did not return.",
+    "type": "string"
+  },
+  "type": "array"
+}

Previous value: -"Data column IDs to return (reduces payload). Defaults to all. IDs discoverable via eia_describe_route."New value: +"Data column IDs to return (reduces payload). Defaults to all. IDs discoverable via eia_describe_route data_columns[].id. Every row also carries period and each facet ID whatever this lists, so naming those here is unnecessary and they are dropped from the request."

Previous value: -"Facet filters keyed by facet ID (e.g. { \"stateid\": \"TX\", \"sectorid\": [\"RES\", \"COM\"] }). Use the facets[].id values returned by eia_describe_route as keys here."New value: +"Facet filters keyed by facet ID (e.g. { \"stateid\": \"TX\", \"sectorid\": [\"RES\", \"COM\"] }). Use the facets[].id values returned by eia_describe_route as keys here. Every value travels in the request URI, which EIA caps at about 8 KB — a few hundred values across all filters; split a longer list across calls."

Previous value: -"Rows in the inline preview (default 100, max 5000 per EIA limit). With stage: true, staging is not bounded by this — it pages past the preview on its own."New value: +"Rows to fetch for the inline page (default 100, max 5000 per EIA limit). Every fetched row is used, but the response carries only as many as fit a 64,000-byte budget per surface — wide routes end the page early, said so in canvas_preview_note, with next_offset naming where to continue. With stage: true, staging is not bounded by this — it pages past the preview on its own."

Previous value: -"Echo of the column projection as applied, when columns were provided."New value: +"Echo of the column projection as sent to EIA, when columns named at least one data column — period and facet IDs, which every row carries anyway, are not part of it."

Previous value: -"Facet filters applied to the query, when provided."New value: +"Facet filters applied to the query, when provided. Past 4,000 bytes the echo keeps the leading values and adds a \"…\" entry counting those not echoed per facet — every value was still applied."

Previous value: -"Human-readable note when total exceeds the inline preview. On a stage: true call it names how many rows actually reached the canvas table, and where in the matching set those rows sit whenever the stage does not start at row 1; when staging also stopped short of total (the EIA_CANVAS_MAX_ROWS cap, or an upstream page that did not return), it says so and gives the offset to resume from. Where staging was not requested it places the inline page against total and names stage: true as the way to get SQL access to the rest; where no canvas is configured at all, staging is unavailable, so it names offset paging and CANVAS_PROVIDER_TYPE=duckdb instead."New value: +"Human-readable note, present whenever dataset is set or staging failed, and otherwise when total exceeds the inline rows. On a stage: true call it opens with the stage outcome: the staged row count and dataset name, naming eia_dataframe_describe for the staged column names (quoting one rename when staging renamed a column) and then eia_dataframe_query for SQL — or, when the canvas failed, that no dataframe was created (dataset is then absent), with the retry and offset paging. Next, where in the matching set the staged rows sit whenever the stage does not start at row 1, and when staging stopped short of total (the EIA_CANVAS_MAX_ROWS cap, or an upstream page that did not return) the offset to resume from; last, the inline page against total and next_offset — saying when the 64,000-byte response budget rather than length ended the page, or that a single row too large for the budget was withheld and offset + 1 steps past it — and, after a registered stage, that the inline rows page with stage left off, since another stage: true call stages a new table. Where staging was not requested it places the inline page against total and names stage: true and eia_dataframe_query as the way to get SQL access to the rest; where no canvas is configured at all, staging is unavailable, so it names offset paging and CANVAS_PROVIDER_TYPE=duckdb instead."

Previous value: -"Preview rows. All numeric values are strings per the EIA API (e.g. \"9.13\"). Cast to DOUBLE in SQL for arithmetic: CAST(value AS DOUBLE). Per-column units appear as {col}-units fields inline in each row. Keys are dynamic column IDs from the EIA route."New value: +"Inline rows: the first length rows from offset, ended early when the next whole row would push either response surface past the 64,000-byte budget. All numeric values are strings per the EIA API (e.g. \"9.13\"). Cast to DOUBLE in SQL for arithmetic: CAST(value AS DOUBLE). Per-column units appear as {col}-units fields inline in each row. Keys are dynamic column IDs from the EIA route."

Previous value: -"df_<id> table handle for the registered dataset — pass directly to eia_dataframe_query SQL (SELECT ... FROM df_<id>). Present only on a stage: true call against a deployment with a canvas configured; absent otherwise, since nothing was staged. Every dataset a tenant stages shares one canvas, so handles from different routes join directly."New value: +"df_<id> handle for the staged rows — eia_dataframe_describe lists its column names; eia_dataframe_query runs SQL over it (SELECT … FROM df_<id>). Present only when a stage: true call registered a table on a deployment with a canvas configured; absent otherwise, since nothing was staged. Every dataset a tenant stages shares one canvas, so handles from different routes join directly."

Previous value: -"Machine-readable failure mode. Declared by this tool: `route_not_found`: Route does not exist in the EIA taxonomy. `route_not_queryable`: Route is a category node with sub-routes, not a queryable leaf. `invalid_facet`: An unknown facet key was used in filters. `invalid_column`: An unknown data column ID was passed in columns. `invalid_frequency`: An unknown frequency code was passed. `invalid_sort`: A sort entry named a column the route does not sort by. `invalid_period`: start or end was not in a period format the route accepts. `no_data`: Date range is inverted (start is after end). `rate_limited`: EIA rate limit hit (OVER_RATE_LIMIT). Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `route_not_found`: Route does not exist in the EIA taxonomy. `route_not_queryable`: Route is a category node with sub-routes, not a queryable leaf. `invalid_facet`: An unknown facet key was used in filters. `invalid_column`: An unknown data column ID was passed in columns. `invalid_frequency`: An unknown frequency code was passed. `invalid_sort`: A sort entry named a column the route does not sort by. `invalid_period`: start or end was not in a period format the route accepts. `uri_too_long`: The request URI passed the EIA limit of about 8 KB (HTTP 414) — typically a filter list of several hundred values. `no_data`: Date range is inverted (start is after end). `rate_limited`: EIA rate limit hit (OVER_RATE_LIMIT). `upstream_unreachable`: EIA could not be reached (connection refused or reset, DNS failure) on the data request, the route metadata request, or the route-tree build. Other values are possible when a failure originates below the handler."

Previous value: -[
-  "route_not_found",
-  "route_not_queryable",
-  "invalid_facet",
-  "invalid_column",
-  "invalid_frequency",
-  "invalid_sort",
-  "invalid_period",
-  "no_data",
-  "rate_limited"
-]New value: +[
+  "route_not_found",
+  "route_not_queryable",
+  "invalid_facet",
+  "invalid_column",
+  "invalid_frequency",
+  "invalid_sort",
+  "invalid_period",
+  "uri_too_long",
+  "no_data",
+  "rate_limited",
+  "upstream_unreachable"
+]

Added value: +{
+  "description": "Offset that continues right after the rows in data (offset + returned_count) — pass it as offset for the next page, with no gap or overlap. Present whenever rows remain past this page; absent on the last page.",
+  "type": "number"
+}

Previous value: -"Informational message when the response carries no rows — either zero rows matched the filters (broaden the query) or offset paged past the last row (reduce offset below total)."New value: +"Informational message when EIA returned no rows — either zero rows matched the filters (broaden the query) or offset paged past the last row (reduce offset below total). A page left empty because its first row alone exceeds the response budget carries no notice; canvas_preview_note names the offset that skips it."

Previous value: -"Rows in this response. When returnedCount < totalCount, use offset or canvas for the rest."New value: +"Rows in this response. When returnedCount < totalCount, continue at next_offset or stage the rest."

Previous value: -"Number of rows in this response. When returned_count < total, use offset pagination or DataCanvas for the rest."New value: +"Number of rows in data. When returned_count < total, continue at next_offset or stage the rest for SQL."

Previous value: -"Maximum results to return (default 10, max 30)."New value: +"Maximum results to return (default 10). One call returns at most 30; a larger limit is served at 30, and truncated says whether more matches exist."

Previous value: -30New value: +100

Previous value: -"Free-text search terms to match against route names and descriptions."New value: +"Free-text search terms to match against route names and descriptions. Leading and trailing whitespace is ignored."

Previous value: -"The limit that was applied."New value: +"Most results this call could return — limit, or 30 when limit was larger."

Previous value: -"Query as submitted to the Fuse.js index."New value: +"Query as searched — the submitted text with surrounding whitespace trimmed."

Previous value: -"Machine-readable failure mode."New value: +"Machine-readable failure mode. Declared by this tool: `rate_limited`: EIA rate limit hit (OVER_RATE_LIMIT) while building the route tree on the first call after server start. `upstream_unreachable`: EIA could not be reached (connection refused or reset, DNS failure) while building the route tree on the first call after server start. Other values are possible when a failure originates below the handler."

Added value: +[
+  "rate_limited",
+  "upstream_unreachable"
+]

Previous value: -"Present only when indexComplete is false: route paths whose metadata could not be fetched (call eia_browse_routes on one to re-fetch it) and index passes that did not land (\"steo_series\", \"facet_values\")."New value: +"Present only when indexComplete is false: route paths whose metadata could not be fetched (call eia_browse_routes on one to re-fetch it) and index passes that did not land (\"steo_series\", \"seds_series\", \"facet_values\"), which the next search retries."

Previous value: -"Recovery hint when no routes matched — suggests alternative queries or using eia_browse_routes."New value: +"Present when no routes matched, or when more matches exist than were returned — says how to narrow or widen the search."

Previous value: -"Pre-built filter for eia_query_route when a specific facet value is required. Present on STEO series and facet-value results — pass directly as filters (e.g. eia_query_route(route=\"steo\", filters=filter_hint))."New value: +"Pre-built filter for eia_query_route when a specific facet value is required. Present on STEO and SEDS series results and facet-value results — pass directly as filters (e.g. eia_query_route(route=\"seds\", filters=filter_hint))."

Previous value: -"Total entries in the search index (routes + STEO series names + facet values)."New value: +"Total entries in the search index (routes + STEO and SEDS series names + facet values)."

Previous value: -"True when matches were capped at limit; more may exist."New value: +"True when more matches exist past the ones returned; false when these are all."

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Added value: +false

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "path",
+      "children",
+      "isLeaf"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `route_not_found`: Path does not exist in the EIA taxonomy. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "route_not_found"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

Removed value: -[
-  "path",
-  "children",
-  "isLeaf"
-]

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Added value: +false

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "active_names",
+      "dataframes"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `canvas_unavailable`: DataCanvas service is not configured for this deployment. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "canvas_unavailable"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

Removed value: -[
-  "active_names",
-  "dataframes"
-]

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Added value: +false

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "columns",
+      "rows",
+      "totalRows",
+      "returnedRows",
+      "truncated",
+      "executedSql"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `canvas_unavailable`: DataCanvas service is not configured for this deployment. `system_catalog_access`: SQL references a denied system catalog (information_schema, pg_catalog, sqlite_master, duckdb_*). `missing_table`: SQL references a df_<id> table that is not staged — mistyped, already dropped, or past its expiry. `non_select_statement`: The statement is not a single read-only SELECT — writes, DDL, DROP, COPY, PRAGMA, and ATTACH are rejected. `invalid_sql`: DuckDB could not parse or bind the statement — a syntax error, or a column or alias that does not exist on the referenced dataframe. `register_as_clash`: register_as names a dataframe that is already staged for this tenant. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "canvas_unavailable",
+            "system_catalog_access",
+            "missing_table",
+            "non_select_statement",
+            "invalid_sql",
+            "register_as_clash"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

Removed value: -[
-  "columns",
-  "rows",
-  "totalRows",
-  "returnedRows",
-  "truncated",
-  "executedSql"
-]

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Added value: +false

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "route",
+      "description",
+      "facets",
+      "values_offset",
+      "data_columns",
+      "frequencies",
+      "date_range",
+      "default_frequency",
+      "default_date_format"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `route_not_found`: Route does not exist in the EIA taxonomy. `route_not_queryable`: Route is a category node with sub-routes, not a queryable leaf. `facet_not_found`: The facet input names an ID the route does not expose. `rate_limited`: EIA rate limit hit during facet fan-out. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "route_not_found",
+            "route_not_queryable",
+            "facet_not_found",
+            "rate_limited"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

Removed value: -[
-  "route",
-  "description",
-  "facets",
-  "values_offset",
-  "data_columns",
-  "frequencies",
-  "date_range",
-  "default_frequency",
-  "default_date_format"
-]

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Added value: +false

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "route",
+      "data",
+      "total",
+      "returned_count",
+      "frequency",
+      "date_format",
+      "effectiveRoute",
+      "totalCount",
+      "returnedCount",
+      "appliedOffset",
+      "appliedLength"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `route_not_found`: Route does not exist in the EIA taxonomy. `route_not_queryable`: Route is a category node with sub-routes, not a queryable leaf. `invalid_facet`: An unknown facet key was used in filters. `invalid_column`: An unknown data column ID was passed in columns. `invalid_frequency`: An unknown frequency code was passed. `invalid_sort`: A sort entry named a column the route does not sort by. `invalid_period`: start or end was not in a period format the route accepts. `no_data`: Date range is inverted (start is after end). `rate_limited`: EIA rate limit hit (OVER_RATE_LIMIT). Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "route_not_found",
+            "route_not_queryable",
+            "invalid_facet",
+            "invalid_column",
+            "invalid_frequency",
+            "invalid_sort",
+            "invalid_period",
+            "no_data",
+            "rate_limited"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

Removed value: -[
-  "route",
-  "data",
-  "total",
-  "returned_count",
-  "frequency",
-  "date_format",
-  "effectiveRoute",
-  "totalCount",
-  "returnedCount",
-  "appliedOffset",
-  "appliedLength"
-]

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Added value: +false

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "results",
+      "effectiveQuery",
+      "totalIndexed",
+      "indexComplete",
+      "truncated",
+      "shown",
+      "cap"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode.",
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

Removed value: -[
-  "results",
-  "effectiveQuery",
-  "totalIndexed",
-  "indexComplete",
-  "truncated",
-  "shown",
-  "cap"
-]

Previous value: -"Route path to browse (e.g. \"electricity\", \"petroleum/pri\"). Omit for root."New value: +"Route path to browse (e.g. \"electricity\", \"petroleum/pri\"). Omit for root. Leading, trailing, and doubled slashes are stripped, so an EIA-doc spelling like \"/electricity/retail-sales/\" resolves to the same route."

Previous value: -"Leaf route path (e.g. \"electricity/retail-sales\", \"steo\"). Discoverable via eia_browse_routes or eia_search_routes."New value: +"Leaf route path (e.g. \"electricity/retail-sales\", \"steo\"). Discoverable via eia_browse_routes or eia_search_routes. Leading, trailing, and doubled slashes are stripped, so an EIA-doc spelling like \"/electricity/retail-sales/\" resolves to the same route."

Previous value: -"Rows in the inline preview (default 100, max 5000 per EIA limit). Canvas staging is not bounded by this — it pages past the preview on its own."New value: +"Rows in the inline preview (default 100, max 5000 per EIA limit). With stage: true, staging is not bounded by this — it pages past the preview on its own."

Previous value: -"Leaf route path (e.g. \"electricity/retail-sales\", \"steo\"). Discoverable via eia_browse_routes or eia_search_routes."New value: +"Leaf route path (e.g. \"electricity/retail-sales\", \"steo\"). Discoverable via eia_browse_routes or eia_search_routes. Leading, trailing, and doubled slashes are stripped, so an EIA-doc spelling like \"/electricity/retail-sales/\" resolves to the same route."

Added value: +{
+  "default": false,
+  "description": "Stage the matching rows as a DataCanvas table for SQL (default false). Off, the call makes one upstream request and returns the preview alone. On, the service pages past the preview up to EIA_CANVAS_MAX_ROWS and registers the accumulated rows, returning the handle in dataset — several extra upstream requests and seconds of latency on a large route, so turn it on when moving to analysis, not while exploring. Requires a canvas (CANVAS_PROVIDER_TYPE=duckdb); without one nothing is staged whatever this is set to.",
+  "type": "boolean"
+}

Previous value: -"Human-readable note when total exceeds the inline preview. With a canvas configured it names how many rows actually reached the canvas table, and where in the matching set those rows sit whenever the stage does not start at row 1; when staging also stopped short of total (the EIA_CANVAS_MAX_ROWS cap, or an upstream page that did not return), it says so and gives the offset to resume from. With no canvas configured nothing is staged, so it places the inline page against total and names offset paging and CANVAS_PROVIDER_TYPE=duckdb as the ways to reach the rest."New value: +"Human-readable note when total exceeds the inline preview. On a stage: true call it names how many rows actually reached the canvas table, and where in the matching set those rows sit whenever the stage does not start at row 1; when staging also stopped short of total (the EIA_CANVAS_MAX_ROWS cap, or an upstream page that did not return), it says so and gives the offset to resume from. Where staging was not requested it places the inline page against total and names stage: true as the way to get SQL access to the rest; where no canvas is configured at all, staging is unavailable, so it names offset paging and CANVAS_PROVIDER_TYPE=duckdb instead."

Previous value: -"df_<id> table handle for the registered dataset — pass directly to eia_dataframe_query SQL (SELECT ... FROM df_<id>). Every dataset a tenant stages shares one canvas, so handles from different routes join directly."New value: +"df_<id> table handle for the registered dataset — pass directly to eia_dataframe_query SQL (SELECT ... FROM df_<id>). Present only on a stage: true call against a deployment with a canvas configured; absent otherwise, since nothing was staged. Every dataset a tenant stages shares one canvas, so handles from different routes join directly."

Previous value: -"The route path queried."New value: +"The route path queried, in canonical spelling — any leading, trailing, or doubled slashes the input carried are stripped. Reusable verbatim in a follow-up call."

Previous value: -"Upstream advisories forwarded verbatim from EIA's warnings[], joined with '; ' when more than one applies. These describe the inline page — EIA's \"incomplete return\" entry fires whenever the requested length is under total, at any size — not a 5,000-row ceiling on this response. Absent when the response already accounts for the gap the advisory names (the staged table reaches the last row, notice explains the empty page, or canvas_preview_note places the inline page against total where no canvas is configured)."New value: +"Upstream advisories forwarded verbatim from EIA's warnings[], joined with '; ' when more than one applies. These describe the inline page — EIA's \"incomplete return\" entry fires whenever the requested length is under total, at any size — not a 5,000-row ceiling on this response. Absent when the response already accounts for the gap the advisory names (the staged table reaches the last row, notice explains the empty page, or canvas_preview_note places the inline page against total because nothing was staged)."

Previous value: -"Human-readable note when total exceeds the inline preview — names how many rows actually reached the canvas table, and where in the matching set those rows sit whenever the stage does not start at row 1. When staging also stopped short of total (the EIA_CANVAS_MAX_ROWS cap, or an upstream page that did not return), it says so and gives the offset to resume from."New value: +"Human-readable note when total exceeds the inline preview. With a canvas configured it names how many rows actually reached the canvas table, and where in the matching set those rows sit whenever the stage does not start at row 1; when staging also stopped short of total (the EIA_CANVAS_MAX_ROWS cap, or an upstream page that did not return), it says so and gives the offset to resume from. With no canvas configured nothing is staged, so it places the inline page against total and names offset paging and CANVAS_PROVIDER_TYPE=duckdb as the ways to reach the rest."

Previous value: -"Upstream advisories forwarded verbatim from EIA's warnings[], joined with '; ' when more than one applies. These describe the inline page — EIA's \"incomplete return\" entry fires whenever the requested length is under total, at any size — not a 5,000-row ceiling on this response. Absent when the response already accounts for the gap the advisory names (the staged table reaches the last row, or notice explains the empty page)."New value: +"Upstream advisories forwarded verbatim from EIA's warnings[], joined with '; ' when more than one applies. These describe the inline page — EIA's \"incomplete return\" entry fires whenever the requested length is under total, at any size — not a 5,000-row ceiling on this response. Absent when the response already accounts for the gap the advisory names (the staged table reaches the last row, notice explains the empty page, or canvas_preview_note places the inline page against total where no canvas is configured)."

Previous value: -"Human-readable name."New value: +"Human-readable name. Falls back to the alias, then to the id, on the values EIA sends without one."

Previous value: -"Hard cap on rows materialized in the response (default 1000, max 10000)."New value: +"Hard cap on rows materialized in the response (default 1000, max 10000). Rows past the cap are dropped without being counted — the response then carries truncated: true and a totalRows equal to the cap rather than a true total. Pass register_as to materialize the whole result instead and get an exact count."

Previous value: -"Guidance when results are capped — shows how many rows were omitted."New value: +"Guidance when either cap bound the response — names the cap that applied and how to reach the rows it withheld."

Previous value: -"Total rows the query produced (may exceed rows.length when capped by row_limit)."New value: +"Rows the query materialized. Exact when truncated is false — including on the register_as path, which stages and counts the whole result past row_limit. Equal to row_limit when truncated is true: a floor on the real match count, not a total."

Added value: +{
+  "description": "True when row_limit cut the result: more rows matched than the cap and the remainder was dropped without being counted. False when every matching row was materialized, including on the register_as path, which counts the new dataframe exactly.",
+  "type": "boolean"
+}

Previous value: -[
-  "columns",
-  "rows",
-  "totalRows",
-  "returnedRows",
-  "executedSql"
-]New value: +[
+  "columns",
+  "rows",
+  "totalRows",
+  "returnedRows",
+  "truncated",
+  "executedSql"
+]

Added value: +{
+  "description": "Guidance when values_offset lands past the last value of one or more facets — names each emptied facet, its value_count, and its last valid offset. Absent when every facet returned values.",
+  "type": "string"
+}

Added value: +{
+  "description": "Echo of the result ordering as applied, when a sort was provided — the ordering that decided which rows a capped stage holds.",
+  "items": {
+    "additionalProperties": false,
+    "description": "A sort criterion as applied.",
+    "properties": {
+      "column": {
+        "description": "Column ID sorted by.",
+        "type": "string"
+      },
+      "direction": {
+        "description": "Sort direction.",
+        "enum": [
+          "asc",
+          "desc"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "column",
+      "direction"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

Previous value: -"Human-readable note when total exceeds the inline preview — names how many rows actually reached the canvas table and, when staging stopped short of total (the EIA_CANVAS_MAX_ROWS cap, or an upstream page that did not return), says so and gives the offset to resume from."New value: +"Human-readable note when total exceeds the inline preview — names how many rows actually reached the canvas table, and where in the matching set those rows sit whenever the stage does not start at row 1. When staging also stopped short of total (the EIA_CANVAS_MAX_ROWS cap, or an upstream page that did not return), it says so and gives the offset to resume from."

Previous value: -"Forwarded from EIA's warnings[] when the API warns of truncated results near the 5,000 per-page limit."New value: +"Upstream advisories forwarded verbatim from EIA's warnings[], joined with '; ' when more than one applies. These describe the inline page — EIA's \"incomplete return\" entry fires whenever the requested length is under total, at any size — not a 5,000-row ceiling on this response. Absent when the response already accounts for the gap the advisory names (the staged table reaches the last row, or notice explains the empty page)."

Previous value: -"Fuzzy match score: 0 = exact, 1 = no match. Lower is better; above 0.9 the match is unreliable."New value: +"Match score: 0 = exact, 1 = no match. Lower is better; above 0.72 the match is unreliable. On a multi-term query it is the better of the whole-phrase score and a per-term score that penalizes each query term the entry does not carry."

Added value: +{
+  "description": "True when this answer was ranked against the complete corpus. False means part of it is missing (see indexGaps) — results may be short, and a better match may exist that was never scored.",
+  "type": "boolean"
+}

Added value: +{
+  "description": "Present only when indexComplete is false: route paths whose metadata could not be fetched (call eia_browse_routes on one to re-fetch it) and index passes that did not land (\"steo_series\", \"facet_values\").",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Previous value: -[
-  "results",
-  "effectiveQuery",
-  "totalIndexed",
-  "truncated",
-  "shown",
-  "cap"
-]New value: +[
+  "results",
+  "effectiveQuery",
+  "totalIndexed",
+  "indexComplete",
+  "truncated",
+  "shown",
+  "cap"
+]

Added value: +{
+  "description": "Every df_<id> handle staged for this tenant, regardless of the requested scope. On a miss these are the handles that are still usable.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Previous value: -"Active dataframes for this tenant, newest first. Empty when none are registered."New value: +"Dataframes matching the requested scope, newest first. Empty when nothing is staged, or when a supplied name does not resolve — read found and active_names to tell those apart."

Previous value: -"ISO 8601 expiry timestamp (sliding TTL)."New value: +"ISO 8601 expiry, extended each time an eia_dataframe_query statement references this dataframe. Reading it here does not extend it. Absent when the dataframe carries no expiry of its own and follows the canvas lifecycle."

Previous value: -[
-  "name",
-  "source_tool",
-  "query_params",
-  "created_at",
-  "expires_at",
-  "row_count",
-  "truncated",
-  "column_schema"
-]New value: +[
+  "name",
+  "source_tool",
+  "query_params",
+  "created_at",
+  "row_count",
+  "truncated",
+  "column_schema"
+]

Added value: +{
+  "description": "True when the requested name is staged, false when it is not. Absent when no name was supplied — an unscoped list has nothing to resolve.",
+  "type": "boolean"
+}

Added value: +{
+  "description": "Echo of the name input. Absent when no name was supplied.",
+  "type": "string"
+}

Previous value: -[
-  "dataframes"
-]New value: +[
+  "active_names",
+  "dataframes"
+]

Previous value: -"When set, persist the result as a new dataframe with a fresh TTL. Use to chain analyses without re-running upstream queries. Conflicts with an existing name throw Conflict."New value: +"When set, persist the result as a new dataframe with a fresh expiry. Use to chain analyses without re-running upstream queries. The name must be unused — reusing a staged name is rejected, and the fix is a different name, not dropping the existing dataframe. eia_dataframe_describe lists the names already taken."

Added value: +1

Previous value: -"ISO 8601 expiry for the newly registered dataframe, when applicable."New value: +"ISO 8601 expiry for the newly registered dataframe, when applicable. Extended each time a later query references it."

Added value: +{
+  "description": "Restrict the response to one facet by ID (e.g. \"stateid\"). Use with values_offset to page a facet whose values were truncated. Omit to get every facet.",
+  "minLength": 1,
+  "type": "string"
+}

Added value: +{
+  "default": 0,
+  "description": "Index of the first facet value to return, applied to every facet in the response. Use the value named in a truncation hint to continue past the cap.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}

Previous value: -"Filterable dimensions. Each facet has an ID and a set of valid values."New value: +"Filterable dimensions. Each facet has an ID and a window of its valid values. Restricted to one entry when the facet input is set."

Added value: +{
+  "description": "Total values this facet has upstream, independent of the returned window.",
+  "type": "number"
+}

Previous value: -"Valid values for this facet dimension."New value: +"Valid values for this facet dimension, starting at values_offset and capped at EIA_FACET_VALUE_CAP."

Added value: +{
+  "description": "True when values stops short of value_count. Call eia_describe_route again with this facet ID and values_offset set to values_offset + values.length for the next page.",
+  "type": "boolean"
+}

Previous value: -[
-  "id",
-  "description",
-  "values"
-]New value: +[
+  "id",
+  "description",
+  "values",
+  "value_count",
+  "values_truncated"
+]

Added value: +{
+  "description": "Index of the first facet value returned, echoing the requested offset.",
+  "type": "number"
+}

Previous value: -[
-  "route",
-  "description",
-  "facets",
-  "data_columns",
-  "frequencies",
-  "date_range",
-  "default_frequency",
-  "default_date_format"
-]New value: +[
+  "route",
+  "description",
+  "facets",
+  "values_offset",
+  "data_columns",
+  "frequencies",
+  "date_range",
+  "default_frequency",
+  "default_date_format"
+]

Previous value: -"Pre-built filter for eia_query_route when a specific facet value is required. Present on STEO series results — pass directly as filters (e.g. eia_query_route(route=\"steo\", filters=filter_hint))."New value: +"Pre-built filter for eia_query_route when a specific facet value is required. Present on STEO series and facet-value results — pass directly as filters (e.g. eia_query_route(route=\"steo\", filters=filter_hint))."

Previous value: -"Total entries in the search index (routes + STEO series names)."New value: +"Total entries in the search index (routes + STEO series names + facet values)."

Removed value: -{
-  "description": "DataCanvas ID to register results into. Omit on first call — a new canvas is minted and returned. Pass the returned canvas_id on subsequent calls to accumulate multiple route results into one canvas for cross-route SQL joins.",
-  "type": "string"
-}

Previous value: -"Rows to fetch per request (default 100, max 5000 per EIA limit)."New value: +"Rows in the inline preview (default 100, max 5000 per EIA limit). Canvas staging is not bounded by this — it pages past the preview on its own."

Previous value: -"Pagination offset (default 0)."New value: +"Row offset into the matching set (default 0). An offset at or beyond total returns zero rows."

Added value: +{
+  "description": "Preview row count requested for this call.",
+  "type": "number"
+}

Added value: +{
+  "description": "Row offset applied to the query — the cause when a page comes back empty.",
+  "type": "number"
+}

Removed value: -{
-  "description": "Canvas workspace ID — present when spillover occurred or canvas_id was supplied. Pass to subsequent eia_query_route calls to accumulate datasets.",
-  "type": "string"
-}

Previous value: -"Human-readable note when total > returned rows, describing how to access the full dataset via canvas SQL."New value: +"Human-readable note when total exceeds the inline preview — names how many rows actually reached the canvas table and, when staging stopped short of total (the EIA_CANVAS_MAX_ROWS cap, or an upstream page that did not return), says so and gives the offset to resume from."

Previous value: -"df_<id> table handle for the registered dataset — pass directly to eia_dataframe_query SQL (SELECT ... FROM df_<id>)."New value: +"df_<id> table handle for the registered dataset — pass directly to eia_dataframe_query SQL (SELECT ... FROM df_<id>). Every dataset a tenant stages shares one canvas, so handles from different routes join directly."

Previous value: -"Informational message when zero rows matched the filters — guidance for broadening the query."New value: +"Informational message when the response carries no rows — either zero rows matched the filters (broaden the query) or offset paged past the last row (reduce offset below total)."

Previous value: -[
-  "route",
-  "data",
-  "total",
-  "returned_count",
-  "frequency",
-  "date_format",
-  "effectiveRoute",
-  "totalCount",
-  "returnedCount"
-]New value: +[
+  "route",
+  "data",
+  "total",
+  "returned_count",
+  "frequency",
+  "date_format",
+  "effectiveRoute",
+  "totalCount",
+  "returnedCount",
+  "appliedOffset",
+  "appliedLength"
+]

Previous value: -"Fuzzy match score: 0 = exact, 1 = no match. Lower is better."New value: +"Fuzzy match score: 0 = exact, 1 = no match. Lower is better; above 0.9 the match is unreliable."

Added value: +{
+  "description": "Echo of the SQL statement that was executed — confirms the exact query that ran.",
+  "type": "string"
+}

Previous value: -[
-  "columns",
-  "rows",
-  "totalRows",
-  "returnedRows"
-]New value: +[
+  "columns",
+  "rows",
+  "totalRows",
+  "returnedRows",
+  "executedSql"
+]

Added value: +{
+  "description": "Echo of the column projection as applied, when columns were provided.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Added value: +{
+  "description": "Echo of the end period as applied, when an end was provided.",
+  "type": "string"
+}

Added value: +{
+  "description": "Echo of the frequency as applied, when a frequency was provided.",
+  "type": "string"
+}

Added value: +{
+  "description": "Echo of the start period as applied, when a start was provided.",
+  "type": "string"
+}

Added value: +{
+  "description": "The limit that was applied.",
+  "type": "number"
+}

Added value: +{
+  "description": "Number of results returned.",
+  "type": "number"
+}

Added value: +{
+  "description": "True when matches were capped at limit; more may exist.",
+  "type": "boolean"
+}

Previous value: -[
-  "results",
-  "effectiveQuery",
-  "totalIndexed"
-]New value: +[
+  "results",
+  "effectiveQuery",
+  "totalIndexed",
+  "truncated",
+  "shown",
+  "cap"
+]

Added value: +{
+  "description": "Informational message when zero rows matched the filters — guidance for broadening the query.",
+  "type": "string"
+}

Added value: +{
+  "description": "Number of rows in this response. When returned_count < total, use offset pagination or DataCanvas for the rest.",
+  "type": "number"
+}

Added value: +{
+  "description": "Total matching rows in the EIA dataset for this query (may exceed returned rows when pagination or spillover applies).",
+  "type": "number"
+}

Previous value: -[
-  "route",
-  "data",
-  "frequency",
-  "date_format",
-  "effectiveRoute",
-  "totalCount",
-  "returnedCount"
-]New value: +[
+  "route",
+  "data",
+  "total",
+  "returned_count",
+  "frequency",
+  "date_format",
+  "effectiveRoute",
+  "totalCount",
+  "returnedCount"
+]