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: -"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: -"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: -"Human-readable name."New value: +"Human-readable name. Falls back to the alias, then to the id, on the values EIA sends without one."

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": "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"
+]