eia-energy-mcp-server

Previous value: -"Keep only the facet values whose id, name, or alias contains this text, ignoring case (e.g. \"palo verde\" on plantCode). A plain substring match, not a pattern or a ranked search. Applied to every facet in the response, before values_offset and the cap. Leading and trailing whitespace is ignored. Omit to list every value."New value: +"Keep only the facet values whose id, name, or alias contains this text, ignoring case (e.g. \"palo verde\" on plantCode). On the balancing-authority facets of electricity routes (respondent, fromba, toba, parent, balancing_authority_code), a value also matches when its ISO/RTO acronym contains the text: \"ERCOT\" finds ERCO, \"CAISO\" finds CISO, \"SPP\" finds SWPP and SWPW. A plain substring match, not a pattern or a ranked search. Applied to every facet in the response, before values_offset and the cap. Leading and trailing whitespace is ignored. Omit to list every value."

Previous value: -"Measurement units (e.g. \"cents per kilowatt-hour\")."New value: +"Measurement units (e.g. \"cents per kilowatt-hour\"). An empty string means the route metadata names no unit for this column; the notice then names the eia_query_route row field that holds its unit when a row has one, and a column whose rows have no such field has no unit."

Previous value: -"Valid values for this facet dimension, starting at values_offset and capped at EIA_FACET_VALUE_CAP. With values_query, only the matching values, in upstream order."New value: +"Valid values for this facet dimension, starting at values_offset and capped at the window size this server sets. With values_query, only the matching values, in upstream order."

Previous value: -"Values of this facet whose id, name, or alias contains values_query — what values_offset indexes and values_truncated is measured against. One ID listed under two historical names counts twice. Present only when values_query is set."New value: +"Values of this facet whose id, name, or alias contains values_query — or, on a balancing-authority facet, whose ISO/RTO acronym does — what values_offset indexes and values_truncated is measured against. One ID listed under two historical names counts twice. Present only when values_query is set."

Previous value: -"Default-frequency date-range context, composed with guidance for exhausted facet windows, a values_query no value matched, unavailable facet values, or cached values served because their refresh failed."New value: +"Default-frequency date-range context, composed with the row field carrying the unit of each data column the route metadata gives no unit, the facet value lists EIA publishes partial, and guidance for exhausted facet windows, a values_query no value matched, unavailable facet values, or cached values served because their refresh failed."

Previous value: -"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, which is on unless the server sets CANVAS_PROVIDER_TYPE=none; without one nothing is staged whatever this is set to."New value: +"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 the staging row cap this server sets and registers the accumulated rows, starting at offset, 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 the server to have a canvas, which it does unless its operator turned it off; without one nothing is staged whatever this is set to."

Previous 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, the time limit of the call, or an upstream page that did not return) the offset to resume from; last, the inline page against total and next_offset — 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."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 — from offset 0 past the first page — and, while rows remain, 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 staging row cap this server sets, the time limit of the call, or an upstream page that did not return) the offset to resume from; last, the row range of the inline page (e.g. rows 21–30 of 55), whether it is the last page, and next_offset — 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 names the row range of the inline page, says when it is the last page, and names stage: true and eia_dataframe_query as the way to get SQL access to the matching rows — with offset 0 past the first page, since a stage starts at offset — and offset paging while rows remain; where this server has no canvas, it says staging is unavailable on this deployment and, while rows remain, names offset paging instead."

Previous value: -"Machine-readable failure mode. Declared by this tool: `upstream_invalid_response`: EIA returned an unusable response body or a missing route or data envelope. `upstream_unavailable`: EIA answered with a retryable HTTP service failure. `upstream_timeout`: EIA did not answer in time: one attempt passed 45 s, or the call passed its 56 s deadline across retries. Staging that runs out of time ends early instead, keeping the rows already staged. `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, named a month, day, or hour that does not exist in the period shape its frequency reads exactly (YYYY-MM-DD at daily or weekly, YYYY-MM-DDTHH at hourly, YYYY-MM-DDTHH±HH at local-hourly), or lacked its UTC offset at local-hourly frequency. `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`: EIA returned no rows and start selects a later period than end at the effective frequency (the range is inverted). `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."New value: +"Machine-readable failure mode. Declared by this tool: `upstream_invalid_response`: EIA returned an unusable response body or a missing route or data envelope. `upstream_unavailable`: EIA answered with a retryable HTTP service failure. `upstream_timeout`: EIA did not answer in time: one attempt passed 45 s, or the call passed its 56 s deadline across retries. Staging that runs out of time ends early instead, keeping the rows already staged. `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; named a month outside 01–12 or an hour that is not two digits; named a day its month lacks or an hour 24–99 that rolls the bound into another period at the chosen frequency (any such day or hour at daily, hourly, and local-hourly, and any such day at weekly and four-week-average); or lacked its UTC offset at local-hourly frequency. `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`: EIA returned no rows and start selects a later period than end at the effective frequency (the range is inverted). `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: -"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."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\", \"total_energy_series\", \"facet_values\"), which the next search retries."

Previous 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 — fuel, sector, and RTO respondent values, and the series and product values of daily and weekly petroleum and natural-gas routes (e.g. {\"series\": \"RNGWHHD\"} on natural-gas/pri/fut) — and on a resolved series ID, where it holds every facet EIA maps the ID to, values as EIA writes them (e.g. {\"sectorid\": \"RES\", \"stateid\": \"TX\"}). Pass directly as filters (e.g. eia_query_route(route=\"seds\", 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 ({\"seriesId\": ...}), Monthly Energy Review series results ({\"msn\": \"TETCBUS\"} on total-energy), and facet-value results — fuel, sector, and RTO balancing-authority values (found by name, EIA code, or ISO/RTO acronym: \"ERCOT\" gives {\"respondent\": \"ERCO\"} on electricity/rto/region-data), and the series and product values of daily and weekly petroleum and natural-gas routes (e.g. {\"series\": \"RNGWHHD\"} on natural-gas/pri/fut) — and on a resolved series ID, where it holds every facet EIA maps the ID to, values as EIA writes them (e.g. {\"sectorid\": \"RES\", \"stateid\": \"TX\"}). Pass directly as filters (e.g. eia_query_route(route=\"seds\", filters=filter_hint))."

Previous value: -"Total entries in the search index: routes, STEO and SEDS series names, and the facet values indexed at warm time, plus the facet values of every route described since the server started — so the count grows with describe calls."New value: +"Total entries in the search index: routes, STEO, SEDS, and Monthly Energy Review series names, and the facet values indexed at warm time, plus the facet values of every route described since the server started — so the count grows with describe calls."

Previous value: -"Rows to include in the immediate response. Defaults to row_limit; larger integers are clamped to 10000 with a notice. 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."New value: +"Rows to include in the immediate response. Default 25; a larger value returns at most row_limit and says so. 0 returns none, useful when chaining via register_as."

Removed value: -9007199254740991

Added value: +1

Previous value: -"integer"New value: +"number"

Previous value: -"Hard cap on rows materialized (default 1000; larger integers are clamped to 10000 with a notice). 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."New value: +"Hard cap on rows materialized. Default 1,000; a larger value returns at most 10,000 and says so. 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."

Removed value: -9007199254740991

Added value: +1

Previous value: -"integer"New value: +"number"

Previous 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."New value: +"Column names in projection order."

Previous 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."New value: +"Echo of the SQL statement that was executed — confirms the exact query that ran."

Previous value: -"Discloses requested/effective row_limit and preview when clamped, including on short or empty results. When row_limit, preview, or the 64,000-byte response budget ended the inline rows, names each bound and how to reach the rows it withheld (raise a bound below its ceiling, or page a register_as table with ORDER BY … LIMIT/OFFSET)."New value: +"Discloses requested/effective row_limit and preview when clamped, including on short or empty results. When row_limit or preview ended the inline rows, names each bound and how to reach the rows it withheld (raise a bound below its cap, or page a register_as table with LIMIT/OFFSET and no ORDER BY)."

Previous 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."New value: +"Rows included in this response. Below totalRows when preview ended the inline rows; the notice names how to reach the rest."

Previous 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."New value: +"Inline rows, bounded by preview and row_limit."

Previous value: -"Default-frequency date-range context, composed with guidance for exhausted facet windows, a values_query no value matched, or unavailable facet values."New value: +"Default-frequency date-range context, composed with guidance for exhausted facet windows, a values_query no value matched, unavailable facet values, or cached values served because their refresh failed."

Previous value: -100New value: +25

Previous value: -"Rows to fetch for the inline page (default 100; larger integers are clamped to 5000 with a notice). 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."New value: +"Rows per page. Default 25; a larger value returns at most 5,000 and says so. With stage: true, staging is not bounded by this — it pages past the page on its own."

Removed value: -9007199254740991

Added value: +1

Previous value: -"integer"New value: +"number"

Previous 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."New value: +"Facet filters applied to the query, when provided."

Previous value: -"Preview row count requested for this call."New value: +"Rows per page applied to this call — length, after any clamp."

Previous 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, the time limit of the call, 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."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, the time limit of the call, or an upstream page that did not return) the offset to resume from; last, the inline page against total and next_offset — 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: -"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."New value: +"Inline rows: the length rows from offset, fewer only at the end of the matching set. 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: -"Composed guidance for empty results or an offset past total, unmatched filter values in complete cached vocabularies, year-only bounds on effective monthly YYYY-MM data, and requested/effective length when clamped. Submitted filters and date bounds are preserved. A row withheld by the response byte budget is explained in canvas_preview_note."New value: +"Composed guidance for empty results or an offset past total, unmatched filter values in complete cached vocabularies, year-only bounds on effective monthly YYYY-MM data, and requested/effective length when clamped. Submitted filters and date bounds are preserved."

Previous 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."New value: +"Maximum results to return. Default 10; a larger value returns at most 30 and says so. truncated says whether more matches exist."

Removed value: -9007199254740991

Added value: +1

Previous value: -"integer"New value: +"number"

Previous value: -"Machine-readable failure mode. Declared by this tool: `upstream_invalid_response`: EIA returned an unusable response body or a missing route or data envelope. `upstream_unavailable`: EIA answered with a retryable HTTP service failure. `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."New value: +"Machine-readable failure mode. Declared by this tool: `upstream_invalid_response`: EIA returned an unusable response body or a missing route or data envelope. `upstream_unavailable`: EIA answered with a retryable HTTP service failure. `upstream_timeout`: EIA did not answer in time: one attempt passed 45 s, or the call passed its 56 s deadline across retries. `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, on the live fetch of the browsed path a cold call falls back to, or while re-fetching a path the warm could not fetch. `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, on the live fetch of the browsed path a cold call falls back to, or while re-fetching a path the warm could not fetch. Other values are possible when a failure originates below the handler."

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

Previous value: -"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."New value: +"Restrict the response to one facet by ID (e.g. \"stateid\"). Use with values_offset to page a facet whose values were truncated, or with values_query to find a value in it. Omit to get every facet."

Previous value: -"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."New value: +"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. With values_query, indexes the matching values."

Added value: +{
+  "description": "Keep only the facet values whose id, name, or alias contains this text, ignoring case (e.g. \"palo verde\" on plantCode). A plain substring match, not a pattern or a ranked search. Applied to every facet in the response, before values_offset and the cap. Leading and trailing whitespace is ignored. Omit to list every value.",
+  "minLength": 1,
+  "type": "string"
+}

Previous value: -"Machine-readable failure mode. Declared by this tool: `upstream_invalid_response`: EIA returned an unusable response body or a missing route or data envelope. `upstream_unavailable`: EIA answered with a retryable HTTP service failure. `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."New value: +"Machine-readable failure mode. Declared by this tool: `upstream_invalid_response`: EIA returned an unusable response body or a missing route or data envelope. `upstream_unavailable`: EIA answered with a retryable HTTP service failure. `upstream_timeout`: EIA did not answer the route metadata request or the route-tree build in time: one attempt passed 45 s, or the call passed its 56 s deadline across retries. A value list that times out is named in unavailable_facets instead. `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: -[
-  "upstream_invalid_response",
-  "upstream_unavailable",
-  "route_not_found",
-  "route_not_queryable",
-  "facet_not_found",
-  "facet_unavailable",
-  "rate_limited",
-  "upstream_unreachable"
-]New value: +[
+  "upstream_invalid_response",
+  "upstream_unavailable",
+  "upstream_timeout",
+  "route_not_found",
+  "route_not_queryable",
+  "facet_not_found",
+  "facet_unavailable",
+  "rate_limited",
+  "upstream_unreachable"
+]

Previous value: -"Total values this facet has upstream, independent of the returned window."New value: +"Total values this facet has upstream, independent of the returned window and of values_query."

Previous value: -"Valid values for this facet dimension, starting at values_offset and capped at EIA_FACET_VALUE_CAP."New value: +"Valid values for this facet dimension, starting at values_offset and capped at EIA_FACET_VALUE_CAP. With values_query, only the matching values, in upstream order."

Added value: +{
+  "description": "Values of this facet whose id, name, or alias contains values_query — what values_offset indexes and values_truncated is measured against. One ID listed under two historical names counts twice. Present only when values_query is set.",
+  "type": "number"
+}

Previous value: -"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."New value: +"True when values stops short of values_matched when values_query is set, otherwise of value_count. Call eia_describe_route again with this facet ID, the same values_query, and values_offset set to values_offset + values.length for the next page."

Previous value: -"Default-frequency date-range context, composed with guidance for exhausted facet windows or unavailable facet values."New value: +"Default-frequency date-range context, composed with guidance for exhausted facet windows, a values_query no value matched, or unavailable facet values."

Added value: +{
+  "description": "The values_query each facet was narrowed by, as matched after trimming. Absent when no values_query was sent.",
+  "type": "string"
+}

Previous value: -"Period end (same format as start)."New value: +"Period end, read the same way as start: a coarser end selects only its first period, so \"2020\" ends at 2020-01 at monthly — use \"2020-12\" to include the whole year. At hourly a date-only end covers its whole day."

Previous value: -"Period start in the route date format (e.g. \"2020-01\" for monthly, \"2020\" for annual). Format from eia_describe_route."New value: +"Period start in the route date format (e.g. \"2020-01\" for monthly, \"2020\" for annual). Format from eia_describe_route. EIA reads a bound as the period of the effective frequency containing its first day, so a coarser bound selects that one period (\"2020\" is 2020-01 at monthly, \"2020-Q4\" is 2020-10). At local-hourly every bound needs its hour and UTC offset (YYYY-MM-DDTHH±HH, e.g. \"2024-02-01T02-06\")."

Previous 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."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, the time limit of the call, 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: -"Machine-readable failure mode. Declared by this tool: `upstream_invalid_response`: EIA returned an unusable response body or a missing route or data envelope. `upstream_unavailable`: EIA answered with a retryable HTTP service failure. `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."New value: +"Machine-readable failure mode. Declared by this tool: `upstream_invalid_response`: EIA returned an unusable response body or a missing route or data envelope. `upstream_unavailable`: EIA answered with a retryable HTTP service failure. `upstream_timeout`: EIA did not answer in time: one attempt passed 45 s, or the call passed its 56 s deadline across retries. Staging that runs out of time ends early instead, keeping the rows already staged. `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, named a month, day, or hour that does not exist in the period shape its frequency reads exactly (YYYY-MM-DD at daily or weekly, YYYY-MM-DDTHH at hourly, YYYY-MM-DDTHH±HH at local-hourly), or lacked its UTC offset at local-hourly frequency. `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`: EIA returned no rows and start selects a later period than end at the effective frequency (the range is inverted). `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: -[
-  "upstream_invalid_response",
-  "upstream_unavailable",
-  "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"
-]New value: +[
+  "upstream_invalid_response",
+  "upstream_unavailable",
+  "upstream_timeout",
+  "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"
+]

Previous value: -"Free-text search terms to match against route names and descriptions. Leading and trailing whitespace is ignored."New value: +"Free-text search terms to match against route names and descriptions, or a legacy APIv1 series ID (e.g. \"PET.RWTC.W\": three or more dot-separated segments ending in a frequency code A, Q, M, W, D, H, HL, or 4; any case). Leading and trailing whitespace is ignored, and only the first 256 characters are searched."

Previous value: -"Query as searched — the submitted text with surrounding whitespace trimmed."New value: +"Query as searched — the submitted text with surrounding whitespace trimmed, cut to its first 256 characters."

Previous value: -"Machine-readable failure mode. Declared by this tool: `upstream_invalid_response`: EIA returned an unusable response body or a missing route or data envelope. `upstream_unavailable`: EIA answered with a retryable HTTP service failure. `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."New value: +"Machine-readable failure mode. Declared by this tool: `upstream_invalid_response`: EIA returned an unusable response body or a missing route or data envelope. `upstream_unavailable`: EIA answered with a retryable HTTP service failure. `upstream_timeout`: EIA did not answer in time while the first call after server start built the route tree. An index pass that times out does not fail the search; it is reported in indexGaps. `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."

Previous value: -[
-  "upstream_invalid_response",
-  "upstream_unavailable",
-  "rate_limited",
-  "upstream_unreachable"
-]New value: +[
+  "upstream_invalid_response",
+  "upstream_unavailable",
+  "upstream_timeout",
+  "rate_limited",
+  "upstream_unreachable"
+]

Previous value: -"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."New value: +"True when this answer was ranked against the complete warm-time corpus. False means part of it is missing (see indexGaps) — results may be short, and a better match may exist that was never scored. Facet values folded in by eia_describe_route are additional and never count toward completeness. A resolved series ID is answered by EIA, not ranked, so it does not depend on this."

Previous value: -"Discloses requested/effective limits when clamped, and guidance when no routes matched or more matches exist."New value: +"Discloses requested/effective limits when clamped and says when only the start of the query was searched; names a resolved series ID (saying so when EIA reports no rows for it), or says the lookup of a query shaped like one found nothing or failed (the results are then the text search); and gives guidance when no routes matched or more matches exist."

Added value: +{
+  "description": "Data column IDs the series reads (e.g. [\"price\"]). Present only on a resolved series ID; pass as eia_query_route columns.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Previous 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))."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 — fuel, sector, and RTO respondent values, and the series and product values of daily and weekly petroleum and natural-gas routes (e.g. {\"series\": \"RNGWHHD\"} on natural-gas/pri/fut) — and on a resolved series ID, where it holds every facet EIA maps the ID to, values as EIA writes them (e.g. {\"sectorid\": \"RES\", \"stateid\": \"TX\"}). Pass directly as filters (e.g. eia_query_route(route=\"seds\", filters=filter_hint))."

Added value: +{
+  "description": "Frequency ID the series is published at (e.g. \"weekly\", \"local-hourly\"). Present only on a resolved series ID; pass as eia_query_route frequency.",
+  "type": "string"
+}

Previous 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."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. A resolved series ID scores 0."

Previous value: -"Total entries in the search index (routes + STEO and SEDS series names + facet values)."New value: +"Total entries in the search index: routes, STEO and SEDS series names, and the facet values indexed at warm time, plus the facet values of every route described since the server started — so the count grows with describe calls."

Previous 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."New value: +"Route path to browse (e.g. \"electricity\", \"petroleum/pri\"). Omit for root. Whitespace and slashes are normalized, then one complete leading v2 segment is removed: \"/v2/electricity/retail-sales/\" resolves to \"electricity/retail-sales\", and \"/v2/\" to root. Full URLs and /data suffixes are not normalized."

Previous 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."New value: +"Machine-readable failure mode. Declared by this tool: `upstream_invalid_response`: EIA returned an unusable response body or a missing route or data envelope. `upstream_unavailable`: EIA answered with a retryable HTTP service failure. `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",
-  "rate_limited",
-  "upstream_unreachable"
-]New value: +[
+  "upstream_invalid_response",
+  "upstream_unavailable",
+  "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. The 64,000-byte response budget can end the inline rows sooner."New value: +"Rows to include in the immediate response. Defaults to row_limit; larger integers are clamped to 10000 with a notice. 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: -10000New value: +9007199254740991

Previous 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."New value: +"Hard cap on rows materialized (default 1000; larger integers are clamped to 10000 with a notice). 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: -10000New value: +9007199254740991

Previous value: -"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."New value: +"Machine-readable failure mode. Declared by this tool: `denied_function`: SQL calls a denied function, including engine settings, file reads, or SQL built from strings. `multi_statement`: SQL contains more than one statement. `sql_read_only`: SQL attempts a write, external file access, or another operation refused by the read-only gate. `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."

Previous value: -[
-  "canvas_unavailable",
-  "system_catalog_access",
-  "missing_table",
-  "non_select_statement",
-  "invalid_sql",
-  "register_as_clash"
-]New value: +[
+  "denied_function",
+  "multi_statement",
+  "sql_read_only",
+  "canvas_unavailable",
+  "system_catalog_access",
+  "missing_table",
+  "non_select_statement",
+  "invalid_sql",
+  "register_as_clash"
+]

Previous 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)."New value: +"Discloses requested/effective row_limit and preview when clamped, including on short or empty results. When row_limit, preview, or the 64,000-byte response budget ended the inline rows, names each bound and how to reach the rows it withheld (raise a bound below its ceiling, or page a register_as table with ORDER BY … LIMIT/OFFSET)."

Previous 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."New value: +"Leaf route path (e.g. \"electricity/retail-sales\", \"steo\"). Discoverable via eia_browse_routes or eia_search_routes. Whitespace and slashes are normalized, then one complete leading v2 segment is removed: \"/v2/electricity/retail-sales/\" resolves to \"electricity/retail-sales\". Full URLs and /data suffixes are not normalized."

Previous value: -"Available date range for this route."New value: +"Route metadata date range in the default-frequency context, not a bound across all frequencies."

Previous value: -"Latest available period."New value: +"Metadata end period for the default frequency; another frequency may extend later."

Previous value: -"Earliest available period."New value: +"Metadata start period for the default frequency; another frequency may extend earlier."

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. `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."New value: +"Machine-readable failure mode. Declared by this tool: `upstream_invalid_response`: EIA returned an unusable response body or a missing route or data envelope. `upstream_unavailable`: EIA answered with a retryable HTTP service failure. `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",
-  "facet_unavailable",
-  "rate_limited",
-  "upstream_unreachable"
-]New value: +[
+  "upstream_invalid_response",
+  "upstream_unavailable",
+  "route_not_found",
+  "route_not_queryable",
+  "facet_not_found",
+  "facet_unavailable",
+  "rate_limited",
+  "upstream_unreachable"
+]

Previous 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."New value: +"Default-frequency date-range context, composed with guidance for exhausted facet windows or unavailable facet values."

Previous 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."New value: +"Rows to fetch for the inline page (default 100; larger integers are clamped to 5000 with a notice). 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: -5000New value: +9007199254740991

Previous 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."New value: +"Leaf route path (e.g. \"electricity/retail-sales\", \"steo\"). Discoverable via eia_browse_routes or eia_search_routes. Whitespace and slashes are normalized, then one complete leading v2 segment is removed: \"/v2/electricity/retail-sales/\" resolves to \"electricity/retail-sales\". Full URLs and /data suffixes are not normalized."

Previous value: -"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."New value: +"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, which is on unless the server sets CANVAS_PROVIDER_TYPE=none; without one nothing is staged whatever this is set to."

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. `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."New value: +"Machine-readable failure mode. Declared by this tool: `upstream_invalid_response`: EIA returned an unusable response body or a missing route or data envelope. `upstream_unavailable`: EIA answered with a retryable HTTP service failure. `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",
-  "uri_too_long",
-  "no_data",
-  "rate_limited",
-  "upstream_unreachable"
-]New value: +[
+  "upstream_invalid_response",
+  "upstream_unavailable",
+  "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"
+]

Previous 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."New value: +"Composed guidance for empty results or an offset past total, unmatched filter values in complete cached vocabularies, year-only bounds on effective monthly YYYY-MM data, and requested/effective length when clamped. Submitted filters and date bounds are preserved. A row withheld by the response byte budget is explained in canvas_preview_note."

Previous 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."New value: +"The canonical route path queried: whitespace/slashes normalized and one complete leading v2 segment removed. Reusable verbatim in a follow-up call."

Previous value: -100New value: +9007199254740991

Previous 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."New value: +"Machine-readable failure mode. Declared by this tool: `upstream_invalid_response`: EIA returned an unusable response body or a missing route or data envelope. `upstream_unavailable`: EIA answered with a retryable HTTP service failure. `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."

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

Previous value: -"Present when no routes matched, or when more matches exist than were returned — says how to narrow or widen the search."New value: +"Discloses requested/effective limits when clamped, and guidance when no routes matched or more matches exist."

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."