Explore the EIA dataset tree, or fetch a leaf dataset's metadata.

Behavior depends on the node type at route:

• Intermediate node -> returns {"type": "routes", "routes": [...]}, each item being a selectable child route id + name/description.

• Leaf dataset -> returns {"type": "dataset", ...} with the available frequencies, facets (facet ids to filter on), valid data columns, and the startPeriod/endPeriod date coverage. Feed these into eia_get_data.

Start with route="" to discover datasets, then drill down. This is the primary discovery tool; call it before eia_get_data to learn the valid columns, facet ids, and frequency for a dataset.

List the facet ids you can filter a dataset by.

Returns {"route": ..., "facets": [{"id", "description"}, ...]}. Pass a facet id to eia_get_facet_options to enumerate its valid values, then use those values in the facets argument of eia_get_data.

List the valid option values (ids) for one facet of a dataset.

Returns {"route", "facet_id", "total", "options": [...]}. Use the returned ids as values in the facets argument of eia_get_data, e.g. facets={"stateid": ["CA", "NY"]}.

Query rows from an EIA dataset with filtering, sorting, and paging.

Returns a structured payload: { "route", "frequency", "description", "total": , "offset", "length", "returned": , "has_more": , "next_offset": <int | None>, "data": [ {row}, ... ], "warnings": [ ... ] # present only when relevant }

Workflow: use eia_browse_routes to find the route, its valid data_columns, frequencies, and facet ids; use eia_get_facet_options for valid facet values; then call this tool. If data columns are wrong the API may return empty rows, so verify columns against the metadata.