eia-energy-mcp-server

Name: eia-energy-mcp-server
Author: cyanheads

Server Details

Browse and query the EIA API v2 — electricity, petroleum, natural gas, coal, forecasts via MCP.

If you are the author of this connector, you can claim ownership with GitHub, an HTTP challenge, or a DNS record. Claimed connector authors can inspect health checks, view analytics, and manage their listing.

Status: Healthy
Last Tested: 2026-09-06 04:37
Transport: Streamable HTTP
URL
Repository: cyanheads/eia-energy-mcp-server
GitHub Stars: 2
Server Listing: @cyanheads/eia-energy-mcp-server

Available Tools

6 tools

eia_browse_routesBrowse EIA RoutesA

Read-only

Inspect

Lists child routes under a given path in the EIA dataset taxonomy. Start with no path to get the 14 top-level categories (electricity, petroleum, natural-gas, steo, aeo, ieo, seds, etc.), then drill into subcategories. Each result includes an isLeaf flag — leaf routes are queryable endpoints; non-leaf routes have children to browse. When isLeaf is true on the browsed path itself, switch to eia_describe_route.

ParametersJSON Schema

Name	Required	Description	Default
`path`	No	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.

Output Schema

ParametersJSON Schema

Name	Required	Description
`path`	No	The path that was browsed (empty string for root).
`error`	No	Present when the call failed. Absent on success.
`isLeaf`	No	True when the browsed path itself is a leaf route — no children to drill into; use eia_describe_route instead.
`children`	No	Child entries under the browsed path.

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true, and the description adds valuable context: the isLeaf flag, that leaf routes are queryable endpoints, and the normalization of slashes (in the parameter description). It does not mention error handling or empty results, but the core behavior is well disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences that are tightly packed with meaning: purpose, usage guidance, behavior, and routing to a sibling. No fluff, and the key information is front-loaded. This is exemplary conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With a present output schema and readOnly annotation, the description covers the essential browse flow, initial steps, and the switch to eia_describe_route. Minor gaps like invalid paths or empty results are not addressed, but they are not critical for a browse tool given the existing structured fields.

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

Parameters3/5

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

Schema description coverage is 100% for the 'path' parameter, including examples and slash normalization. The main description adds 'Start with no path' which slightly reinforces the omit-root behavior, but this is largely redundant. The schema already does the heavy lifting, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Lists child routes under a given path in the EIA dataset taxonomy.' It names the 14 top-level categories and explicitly contrasts with eia_describe_route, making the tool's unique role unambiguous even among siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit instructions: 'Start with no path to get the 14 top-level categories... then drill into subcategories.' It also gives a concrete conditional: 'When isLeaf is true on the browsed path itself, switch to eia_describe_route.' This tells the agent exactly when to use this tool and when to hand off.

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

eia_dataframe_describeDescribe EIA DataframesA

Read-onlyIdempotent

Inspect

List canvas dataframes (df_) materialized by eia_query_route calls that passed stage: true, with provenance, expiry, row count, and column schema. Nothing is staged until such a call runs, so an empty list on a fresh session means no query has staged yet, not that staging failed. Drops entries for dataframes the canvas no longer holds before responding, so the list is always current. Pass a specific name to inspect one dataframe; omit to list all active dataframes for this tenant. A name that is not staged comes back as found=false alongside the handles that are, never as an empty list. Listing is not use: only an eia_dataframe_query statement naming a dataframe extends its expiry, so a dataframe polled with this tool and never queried still lapses on schedule.

ParametersJSON Schema

Name	Required	Description	Default
`name`	No	df_<id> handle to describe a single dataframe. Omit to list all active dataframes.

Output Schema

ParametersJSON Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`found`	No	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.
`dataframes`	No	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.
`active_names`	No	Every df_<id> handle staged for this tenant, regardless of the requested scope. On a miss these are the handles that are still usable.
`requested_name`	No	Echo of the name input. Absent when no name was supplied.

TDQS

A4.9/5.0

Behavior5/5

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

Beyond the readOnly and idempotent annotations, the description discloses that entries for dataframes no longer held by the canvas are dropped before responding, non-staged names return found=false rather than an empty list, and that polling does not extend expiry. These are critical stateful behaviors an agent must know.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is densely packed with zero verbosity: each sentence carries new information—purpose, staging prerequisite, parameter usage, error case, and expiry distinction. It is front-loaded with the core function and then layers essential nuances.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (listing/inspecting dataframes with provenance, expiry, schema) and its interaction with sibling tools, the description covers all operational aspects: staging prerequisite, staleness handling, error return semantics, and the expiry distinction from eia_dataframe_query. The presence of an output schema further reduces the need to explain return values, leaving no gap.

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

Parameters4/5

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

The schema already documents the name parameter at 100% coverage, and the description repeats the omit-to-list-all behavior. However, it adds meaningful semantics by explaining that a non-staged name returns found=false and that listing does not affect expiry, which goes beyond the schema definition.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (list/inspect) and resource (canvas dataframes), and clearly scopes the tool to dataframes materialized by eia_query_route with stage:true. It explicitly contrasts with eia_dataframe_query on the expiry behavior, distinguishing its role without ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit usage guidance: omit the name to list all, provide a name to inspect one, and explicitly states that listing does not extend expiry—only eia_dataframe_query does. It also clarifies that an empty list means no staging has occurred, not failure, which is essential context.

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

eia_dataframe_queryQuery EIA DataframesA

Read-onlyIdempotent

Inspect

Run a single-statement SELECT against canvas dataframes registered by eia_query_route calls that passed stage: true — a query that staged nothing leaves no table to select from. Standard DuckDB SQL — joins, aggregates, window functions, CTEs all supported. Reference dataframes by the df_ handles returned by eia_query_route or listed by eia_dataframe_describe. Read-only: writes, DDL, DROP, COPY, PRAGMA, ATTACH, and external-file table functions are rejected. System catalogs (information_schema, pg_catalog, sqlite_master, duckdb_*) are denied. EIA data values are VARCHAR — use CAST(col AS DOUBLE) for arithmetic and aggregation. Optional register_as chains results as a new dataframe with a fresh expiry. Every dataframe named in the statement has its expiry extended by the query.

ParametersJSON Schema

Name	Required	Description
`sql`	Yes	Single-statement SELECT against df_<id> tables. EIA data columns are VARCHAR — use CAST(col AS DOUBLE) for arithmetic. Example: SELECT period, CAST(value AS DOUBLE) AS val FROM df_XXXXX ORDER BY period
`preview`	No	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.
`row_limit`	No	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.
`register_as`	No	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.

Output Schema

ParametersJSON Schema

Name	Required	Description
`rows`	No	Materialized rows, bounded by preview / row_limit.
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Guidance when either cap bound the response — names the cap that applied and how to reach the rows it withheld.
`columns`	No	Column names in projection order.
`totalRows`	No	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.
`truncated`	No	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.
`expires_at`	No	ISO 8601 expiry for the newly registered dataframe, when applicable. Extended each time a later query references it.
`executedSql`	No	Echo of the SQL statement that was executed — confirms the exact query that ran.
`returnedRows`	No	Rows included in this response.
`registered_as`	No	Set when register_as was supplied and the new dataframe was materialized.

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already declare readOnlyHint and idempotentHint, and the description reinforces these by explicitly listing rejected operations. It adds behavior not in annotations: VARCHAR casting requirements, expiry extension for referenced dataframes, and the semantics of register_as (fresh expiry, name uniqueness). This goes beyond the annotation baseline, though it does not cover every edge case (e.g., performance or transaction behavior).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but efficient. It leads with the core purpose, then covers constraints, data type caveats, and optional chaining in a logical order. Every sentence conveys essential information without filler. It is longer than average, but the complexity of the tool justifies it — no word is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool of this complexity, the description covers all critical aspects: prerequisites, supported and rejected operations, data type handling, output truncation behavior, expiry semantics, and register_as usage. The output schema likely captures return format, so nothing critical is missing. This is a model of a complete tool description.

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

Parameters4/5

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

The schema already provides detailed descriptions for all four parameters (100% coverage), so the baseline is 3. The description adds value by explaining how the sql parameter must reference df_<id> handles, giving an example, and clarifying the interplay between preview and register_as (lower preview when chaining). It also deepens register_as's meaning with reuse rules. This is more than the schema alone offers.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Run a single-statement SELECT against canvas dataframes'. It clearly distinguishes this from sibling tools by referencing dataframes registered by eia_query_route and listing them via eia_dataframe_describe, and implies it is the querying counterpart to those route-management tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states the prerequisite: dataframes must have been staged (stage: true) or there is nothing to select. It enumerates supported SQL features and lists rejected operations (writes, DDL, DROP, etc.), provides a concrete example, and explains when register_as should be used for chaining. This leaves an agent with no ambiguity about when and how to use the tool.

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

eia_describe_routeDescribe EIA RouteA

Read-only

Inspect

Returns metadata for a leaf route: available facets with their valid values, data column names and units, frequency options, and date range. Call this before eia_query_route to discover valid facet IDs, facet values, column IDs, and frequency codes. Each facet returns a capped window of its values with value_count and values_truncated alongside; pass facet and values_offset to page through the rest of one facet. A values_offset past the last value of a facet returns an empty window for it and a notice naming the count to page against. Facet values are fetched from separate EIA endpoints and merged — results are cached per-route for the process lifetime to minimize API calls.

ParametersJSON Schema

Name	Required	Description
`facet`	No	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.
`route`	Yes	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.
`values_offset`	No	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.

Output Schema

ParametersJSON Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`route`	No	The route path described.
`facets`	No	Filterable dimensions. Each facet has an ID and a window of its valid values. Restricted to one entry when the facet input is set.
`notice`	No	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.
`date_range`	No	Available date range for this route.
`description`	No	Human-readable description of the dataset.
`frequencies`	No	Valid frequency options for eia_query_route.
`data_columns`	No	Data columns available for this route.
`values_offset`	No	Index of the first facet value returned, echoing the requested offset.
`default_frequency`	No	Default frequency ID used when none is specified.
`default_date_format`	No	Period format for the default frequency (e.g. "YYYY-MM").

TDQS

A4.9/5.0

Behavior5/5

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

With readOnlyHint=true, the bar is lower, but the description still adds valuable behavioral context: it discloses that facet values are fetched from separate EIA endpoints and merged, that results are cached per-route for the process lifetime, and it explains the capped window with value_count and values_truncated plus the empty-window notice. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence earns its place: purpose, usage ordering, pagination mechanics, and caching. It is front-loaded with the core purpose and avoids redundancy. Despite being longer than average, it is tightly written with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (multiple parameters, pagination, merging behavior) and the existence of an output schema that defines return values, the description covers all aspects an agent needs: what the tool does, when to call it, how to paginate, and caching implications. Nothing essential is missing.

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

Parameters4/5

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

Schema coverage is 100% and each parameter already has a meaningful description. The tool description adds extra guidance beyond the schema, such as how to use facet and values_offset together to page through truncated results and what happens with offset past the end. This exceeds the baseline of 3 for full coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns metadata for a leaf route and enumerates exactly what that metadata includes (facets, columns, units, frequency, date range). It distinguishes itself from siblings by explicitly naming eia_query_route as its predecessor and implying that route discovery is done via eia_browse_routes/eia_search_routes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: 'Call this before eia_query_route to discover valid facet IDs...' It also explains pagination usage (pass facet and values_offset) and the behavior when paging past the last value. This effectively tells the agent how to sequence operations relative to siblings.

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

eia_query_routeQuery EIA Route DataA

Read-only

Inspect

Fetches data from a leaf route with optional facet filters, date range, frequency, and column selection. Use eia_describe_route first to discover valid facet IDs, facet values, column IDs, and frequency codes. Data values are strings in the response (EIA API returns all numeric values as strings, e.g. "9.13"); cast to DOUBLE in SQL when arithmetic is needed. Returns a preview inline and stages nothing by default — one upstream request, whatever total says. Pass stage: true to also page past the preview and stage the accumulated set as a DataCanvas table, then pass the returned dataset name to eia_dataframe_query for SQL. Every dataset a tenant stages lands in the same canvas, so tables from different routes cross-join by name with nothing to thread between calls.

ParametersJSON Schema

Name	Required	Description
`end`	No	Period end (same format as start).
`sort`	No	Result ordering.
`route`	Yes	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.
`stage`	No	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.
`start`	No	Period start in the route date format (e.g. "2020-01" for monthly, "2020" for annual). Format from eia_describe_route.
`length`	No	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.
`offset`	No	Row offset into the matching set (default 0). An offset at or beyond total returns zero rows.
`columns`	No	Data column IDs to return (reduces payload). Defaults to all. IDs discoverable via eia_describe_route.
`filters`	No	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.
`frequency`	No	Aggregation frequency ID (e.g. "monthly", "annual"). Defaults to route default. Valid IDs from eia_describe_route.

Output Schema

ParametersJSON Schema

Name	Required	Description
`data`	No	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.
`error`	No	Present when the call failed. Absent on success.
`route`	No	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.
`total`	No	Total matching rows in the EIA dataset for this query (may exceed returned rows when pagination or spillover applies).
`notice`	No	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).
`dataset`	No	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.
`frequency`	No	Frequency of the returned data.
`appliedEnd`	No	Echo of the end period as applied, when an end was provided.
`totalCount`	No	Total matching rows in the EIA dataset.
`appliedSort`	No	Echo of the result ordering as applied, when a sort was provided — the ordering that decided which rows a capped stage holds.
`date_format`	No	Period format for the returned data (e.g. "YYYY-MM").
`appliedStart`	No	Echo of the start period as applied, when a start was provided.
`appliedLength`	No	Preview row count requested for this call.
`appliedOffset`	No	Row offset applied to the query — the cause when a page comes back empty.
`returnedCount`	No	Rows in this response. When returnedCount < totalCount, use offset or canvas for the rest.
`appliedColumns`	No	Echo of the column projection as applied, when columns were provided.
`appliedFilters`	No	Facet filters applied to the query, when provided.
`effectiveRoute`	No	The route path that was queried.
`returned_count`	No	Number of rows in this response. When returned_count < total, use offset pagination or DataCanvas for the rest.
`appliedFrequency`	No	Echo of the frequency as applied, when a frequency was provided.
`truncation_warning`	No	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).
`canvas_preview_note`	No	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.

TDQS

A4.9/5.0

Behavior5/5

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

The description discloses that data values are strings and need casting in SQL, that one upstream request is made by default, and that stage:true pages past the preview and incurs extra latency. It explains the staging side effect and requirement of a canvas. This goes well beyond the readOnlyHint annotation, providing complete transparency about side effects and performance.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact yet information-dense. It front-loads the core purpose, then covers prerequisites, data type quirk, default vs. staging behavior, and integration with downstream tools. Every sentence earns its place with no redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 10 parameters, nested objects, and an output schema, the description covers all necessary context: prerequisites, behavior for preview and staging, latency implications, data type handling, and routing to eia_dataframe_query. The output schema is present, so return-value explanation is not needed. Nothing an agent needs to invoke correctly is missing.

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

Parameters4/5

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

Schema coverage is 100% with detailed parameter descriptions (e.g., route slash stripping, stage behavior, filters keyed by facet ID). The description adds a useful note about data values being strings (relevant to numeric columns) and emphasizes the need to consult eia_describe_route for valid parameter values, but these are not parameter-specific over and above the schema. Since the schema already carries the heavy lifting, a 4 is appropriate for the marginal added context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool fetches data from a leaf route with optional facet filters, date range, frequency, and column selection. It distinguishes itself from siblings by mentioning 'leaf route' and the preview/staging behavior, which is distinct from route discovery (browse/search) and route metadata (describe) tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly instructs to 'Use eia_describe_route first to discover valid facet IDs, facet values, column IDs, and frequency codes.' It also explains when to use stage:true ('turn it on when moving to analysis, not while exploring') and directs the user to pass the staged dataset name to eia_dataframe_query for SQL, providing clear routing among siblings.

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

eia_search_routesSearch EIA RoutesA

Read-only

Inspect

Fuzzy text search across route names, descriptions, and category labels. Resolves natural-language queries like "electricity retail sales by state" or "natural gas imports" to matching route paths. Multi-term queries are also matched term by term, so combining a commodity, a metric, and a sector — "electricity price residential", "coal generation industrial sector" — reaches the route carrying that data even when no single entry reads like the whole phrase. STEO series names are indexed so queries like "ethanol net imports" or "crude oil production forecast" also resolve, and so are facet values, so a fuel type or sector term like "wind" or "anthracite coal" resolves to the route that exposes it, with filter_hint carrying the filter to pass on. Results include isLeaf so you know whether to browse further or query directly. Results with score > 0.72 are weak matches — try a more specific query or use eia_browse_routes to explore the taxonomy. The first call after server start waits 24-30s while the index warms, and at most 45s; every later call returns in milliseconds. Check indexComplete before reading anything into a short or empty result set.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No	Maximum results to return (default 10, max 30).
`query`	Yes	Free-text search terms to match against route names and descriptions.

Output Schema

ParametersJSON Schema

Name	Required	Description
`cap`	No	The limit that was applied.
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Number of results returned.
`notice`	No	Recovery hint when no routes matched — suggests alternative queries or using eia_browse_routes.
`results`	No	Ranked matches, best first.
`indexGaps`	No	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").
`truncated`	No	True when matches were capped at limit; more may exist.
`totalIndexed`	No	Total entries in the search index (routes + STEO series names + facet values).
`indexComplete`	No	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.
`effectiveQuery`	No	Query as submitted to the Fuse.js index.

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description's job is to add context — and it adds a lot: first-call warm-up latency of 24-30s (up to 45s) vs. milliseconds on later calls, the indexComplete check, result semantics (isLeaf, filter_hint carrying filters), and the weak-match threshold. This is non-obvious behavioral disclosure that no annotation or schema could convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but efficient — purpose is front-loaded and each subsequent clause adds value (matching behavior, facet handling, result fields, latency, indexComplete). The operational warm-up note is valuable rather than padding. It runs a bit long but no sentence is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values needn't be spelled out, and the description covers optimization/search-navigation guidance, result semantics (isLeaf, filter_hint, score threshold), and a critical operational quirk (warm-up latency, indexComplete). Nothing an agent needs to call this correctly is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the schema documents both query and limit (default 10, max 30) — baseline 3. The description goes beyond this by clarifying query semantics: fuzzy matching, term-by-term multi-term matching, STEO series indexing, and facet-value resolution. It meaningfully enriches how the query parameter behaves in ways the schema cannot express.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — 'Fuzzy text search across route names, descriptions, and category labels' — and explains the resolution goal (natural-language queries → matching route paths). This clearly differentiates it from siblings like eia_browse_routes (browse taxonomy) and eia_query_route (direct query), which the sibling list makes relevant.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent to eia_browse_routes when results are weak (score > 0.72), and distinguishes browsing further vs. querying directly via isLeaf. It doesn't enumerate every sibling differentiation (e.g., when to use eia_query_route vs. this for an exact known path), but the key exclusion condition and alternative are stated clearly.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

6 tool updatesAug 25, 2026

Changedeia_browse_routes6 fields changed

changedInput schema / $schema

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

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

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

addedOutput schema / anyOf

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

addedOutput schema / properties / 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"
+}

removedOutput schema / required

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

Changedeia_dataframe_describe6 fields changed

changedInput schema / $schema

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

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

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

addedOutput schema / anyOf

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

addedOutput schema / properties / 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"
+}

removedOutput schema / required

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

Changedeia_dataframe_query6 fields changed

changedInput schema / $schema

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

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

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

addedOutput schema / anyOf

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

addedOutput schema / properties / 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"
+}

removedOutput schema / required

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

Changedeia_describe_route6 fields changed

changedInput schema / $schema

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

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

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

addedOutput schema / anyOf

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

addedOutput schema / properties / 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"
+}

removedOutput schema / required

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

Changedeia_query_route6 fields changed

changedInput schema / $schema

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

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

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

addedOutput schema / anyOf

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

addedOutput schema / properties / 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"
+}

removedOutput schema / required

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

Changedeia_search_routes6 fields changed

changedInput schema / $schema

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

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

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

addedOutput schema / anyOf

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

addedOutput schema / properties / 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"
+}

removedOutput schema / required

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

3 tool updatesAug 6, 2026

Changedeia_browse_routes1 field changed

changedInput schema / properties / path / description

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

Changedeia_describe_route1 field changed

changedInput schema / properties / route / description

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

Changedeia_query_route7 fields changed

changedInput schema / properties / length / description

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

changedInput schema / properties / route / description

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

addedInput schema / properties / stage

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"
+}

changedOutput schema / properties / canvas_preview_note / description

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

changedOutput schema / properties / dataset / description

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

changedOutput schema / properties / route / description

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

changedOutput schema / properties / truncation_warning / description

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

1 tool updateAug 6, 2026

Changedeia_query_route2 fields changed

changedOutput schema / properties / canvas_preview_note / description

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

changedOutput schema / properties / truncation_warning / description

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

1 tool updateAug 6, 2026
- Changedeia_describe_route1 field changed
  - changedOutput schema / properties / facets / items / properties / values / items / properties / name / description
```
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."
```

2 tool updatesAug 6, 2026

Changedeia_dataframe_query5 fields changed

changedInput schema / properties / row_limit / description

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

changedOutput schema / properties / notice / description

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

changedOutput schema / properties / totalRows / description

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

addedOutput schema / properties / truncated

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"
+}

changedOutput schema / required

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

Changedeia_describe_route1 field changed

addedOutput schema / properties / notice

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"
+}

1 tool updateAug 6, 2026

Changedeia_query_route3 fields changed

addedOutput schema / properties / appliedSort

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"
+}

changedOutput schema / properties / canvas_preview_note / description

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

changedOutput schema / properties / truncation_warning / description

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

1 tool updateAug 1, 2026

Changedeia_search_routes1 field changed

changedOutput schema / properties / results / items / properties / score / description

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

1 tool updateJul 31, 2026

Changedeia_search_routes3 fields changed

addedOutput schema / properties / indexComplete

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"
+}

addedOutput schema / properties / indexGaps

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"
+}

changedOutput schema / required

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

2 tool updatesJul 31, 2026

Changedeia_dataframe_describe7 fields changed

addedOutput schema / properties / active_names

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"
+}

changedOutput schema / properties / dataframes / description

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

changedOutput schema / properties / dataframes / items / properties / expires_at / description

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

changedOutput schema / properties / dataframes / items / required

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

addedOutput schema / properties / found

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"
+}

addedOutput schema / properties / requested_name

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

changedOutput schema / required

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

Changedeia_dataframe_query3 fields changed

changedInput schema / properties / register_as / description

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

addedInput schema / properties / register_as / minLength
```
Added value: +1
```

changedOutput schema / properties / expires_at / description

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

2 tool updatesJul 31, 2026

Changedeia_describe_route9 fields changed

addedInput schema / properties / facet

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"
+}

addedInput schema / properties / values_offset

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"
+}

changedOutput schema / properties / facets / description

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

addedOutput schema / properties / facets / items / properties / value_count

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

changedOutput schema / properties / facets / items / properties / values / description

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

addedOutput schema / properties / facets / items / properties / values_truncated

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"
+}

changedOutput schema / properties / facets / items / required

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

addedOutput schema / properties / values_offset

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

changedOutput schema / required

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

Changedeia_search_routes2 fields changed

changedOutput schema / properties / results / items / properties / filter_hint / description

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

changedOutput schema / properties / totalIndexed / description

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

2 tool updatesJul 31, 2026

Changedeia_query_route10 fields changed

removedInput schema / properties / canvas_id

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

changedInput schema / properties / length / description

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

changedInput schema / properties / offset / description

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

addedOutput schema / properties / appliedLength

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

addedOutput schema / properties / appliedOffset

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

removedOutput schema / properties / canvas_id

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

changedOutput schema / properties / canvas_preview_note / description

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

changedOutput schema / properties / dataset / description

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

changedOutput schema / properties / notice / description

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

changedOutput schema / required

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

Changedeia_search_routes1 field changed

changedOutput schema / properties / results / items / properties / score / description

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

2 tool updatesJun 13, 2026

Changedeia_dataframe_query2 fields changed

addedOutput schema / properties / executedSql

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

changedOutput schema / required

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

Changedeia_query_route4 fields changed

addedOutput schema / properties / appliedColumns

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

addedOutput schema / properties / appliedEnd

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

addedOutput schema / properties / appliedFrequency

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

addedOutput schema / properties / appliedStart

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

1 tool updateJun 13, 2026

Changedeia_search_routes4 fields changed

addedOutput schema / properties / cap

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

addedOutput schema / properties / shown

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

addedOutput schema / properties / truncated

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

changedOutput schema / required

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

1 tool updateJun 4, 2026

Changedeia_query_route4 fields changed

addedOutput schema / properties / notice

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

addedOutput schema / properties / returned_count

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

addedOutput schema / properties / total

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

changedOutput schema / required

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

3 tool updatesMay 30, 2026

Changedeia_dataframe_query8 fields changed

addedOutput schema / properties / notice

Added value: +{
+  "description": "Guidance when results are capped — shows how many rows were omitted.",
+  "type": "string"
+}

addedOutput schema / properties / returnedRows

Added value: +{
+  "description": "Rows included in this response.",
+  "type": "number"
+}

removedOutput schema / properties / row_count

Removed value: -{
-  "description": "Total rows the query produced (may exceed rows.length when capped).",
-  "type": "number"
-}

addedOutput schema / properties / rows / items / description

Added value: +"A result row with dynamic keys matching the SQL projection columns."

addedOutput schema / properties / rows / items / properties
```
Added value: +{}
```
removedOutput schema / properties / rows / items / propertyNames
```
Removed value: -{
-  "type": "string"
-}
```

addedOutput schema / properties / totalRows

Added value: +{
+  "description": "Total rows the query produced (may exceed rows.length when capped by row_limit).",
+  "type": "number"
+}

changedOutput schema / required

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

Changedeia_query_route7 fields changed

addedOutput schema / properties / appliedFilters

Added value: +{
+  "additionalProperties": {
+    "anyOf": [
+      {
+        "type": "string"
+      },
+      {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      }
+    ]
+  },
+  "description": "Facet filters applied to the query, when provided.",
+  "propertyNames": {
+    "type": "string"
+  },
+  "type": "object"
+}

addedOutput schema / properties / effectiveRoute

Added value: +{
+  "description": "The route path that was queried.",
+  "type": "string"
+}

addedOutput schema / properties / returnedCount

Added value: +{
+  "description": "Rows in this response. When returnedCount < totalCount, use offset or canvas for the rest.",
+  "type": "number"
+}

removedOutput schema / properties / returned_count

Removed value: -{
-  "description": "Rows in this response. When returned_count < total, use offset or canvas for the rest.",
-  "type": "number"
-}

removedOutput schema / properties / total

Removed value: -{
-  "description": "Total matching rows in the EIA dataset.",
-  "type": "number"
-}

addedOutput schema / properties / totalCount

Added value: +{
+  "description": "Total matching rows in the EIA dataset.",
+  "type": "number"
+}

changedOutput schema / required

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

Changedeia_search_routes5 fields changed

addedOutput schema / properties / effectiveQuery

Added value: +{
+  "description": "Query as submitted to the Fuse.js index.",
+  "type": "string"
+}

addedOutput schema / properties / notice

Added value: +{
+  "description": "Recovery hint when no routes matched — suggests alternative queries or using eia_browse_routes.",
+  "type": "string"
+}

addedOutput schema / properties / totalIndexed

Added value: +{
+  "description": "Total entries in the search index (routes + STEO series names).",
+  "type": "number"
+}

removedOutput schema / properties / total_indexed

Removed value: -{
-  "description": "Total entries in the search index (routes + STEO series names).",
-  "type": "number"
-}

changedOutput schema / required

Previous value: -[
-  "results",
-  "total_indexed"
-]New value: +[
+  "results",
+  "effectiveQuery",
+  "totalIndexed"
+]

Frequently Asked Questions

Claiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.

Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
- GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user, then choose Claim with GitHub. An organization namespace such as io.github.acme/server also needs that organization to have installed the Glama AI GitHub App and approved its permissions, because GitHub discloses organization membership only to apps it has installed. Use HTTP or DNS when it has not.
- HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
- DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.

The HTTP ownership file has this structure:

{
  "$schema": "https://glama.ai/mcp/schemas/connector.json",
  "claim": "glama_claim_..."
}

Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.

If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.

For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.

Discussions

No comments yet. Be the first to start the discussion!

Related MCP Connectors

Eia A
io.github.pipeworx-io
EIA MCP — US Energy Information Administration API v2
Government Data Energy Open Data
362
econdata A
io.github.pipeworx-io
Econdata MCP — wraps BLS (Bureau of Labor Statistics) public API v2
Government Data Open Data Research & Data
352
DOE Energy Information A
com.olyport
Energy data from EIA: electricity, fuel prices, and renewables
Energy Open Data Government Data
42
worlduank A
io.github.pipeworx-io
World Bank MCP — wraps the World Bank Data API v2 (free, no auth)
Government Data Open Data Research & Data
372

Related MCP Servers

MCP Energy Server
Government Data Open Data Research & Data
ebarros23
A
license
Not graded
quality
Not graded
maintenance
Provides access to comprehensive U.S. and international energy data from the EIA API, including electricity, natural gas, petroleum, coal, renewables, CO2 emissions, and energy forecasts.
Updated 10 months ago (2025-11-10 12:40 UTC)
-
EIA MCP Server
Government Data Open Data Energy
asharanims611
F
license
Not graded
quality
C
maintenance
A FastMCP server that wraps the U.S. Energy Information Administration Open Data API v2, enabling natural-language queries for electricity, petroleum, and other energy statistics via tools like discover_eia_route and get_eia_data.
Updated a month ago (2026-08-11 07:33 UTC)
-
mcp-server-eia
Energy Government Data Open Data
GSA-TTS
F
license
A
quality
C
maintenance
An MCP server that exposes the U.S. Energy Information Administration (EIA) Open Data API, enabling LLMs to browse and query energy data across 17 datasets with generic, composable tools.
Updated a month ago (2026-08-07 18:06 UTC)
4
-
eia-energy-data-mcp
Energy Government Data Open Data
franklan-pm
A
license
Not graded
quality
C
maintenance
An MCP server that wraps the U.S. Energy Information Administration's Open Data API, enabling assistants to fetch live energy data via natural language. It provides tools for querying series, browsing data routes, filtering facets, and running custom queries.
Updated 24 days ago (2026-08-13 15:46 UTC)
MIT

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.7/5.0

Disambiguation5/5

Each tool serves a clearly distinct function: taxonomy browsing, fuzzy search, route metadata discovery, data retrieval, dataframe inspection, and SQL querying. There is no overlap between the route-focused and dataframe-focused tools, and even the two describe/query pairs are separated by target (route vs. dataframe).

Naming Consistency4/5

All tools share the eia_ prefix and use descriptive verbs, but there's a minor inconsistency: route tools mix plural (browse_routes, search_routes) and singular (describe_route, query_route) forms, while dataframe tools place 'dataframe' before the verb (eia_dataframe_describe, eia_dataframe_query). This is readable and predictable overall, with only slight deviation from a uniform pattern.

Tool Count5/5

With 6 tools, the server is well-scoped for its purpose. It covers discovery, metadata, data access, and SQL analysis without unnecessary bloat or missing essentials. The number fits comfortably within the ideal range for a domain-specific data server.

Completeness5/5

The tool chain is complete for the domain: browse/search to locate routes, describe to get facet/column metadata, query to fetch data, and optionally stage to query with SQL. Dataframe management includes listing and querying, with automatic expiry, so there are no dead ends in the typical workflow. It's a read-only API, but that's appropriate for the energy data use case.

Server Details

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Frequently Asked Questions

Discussions

Related MCP Connectors

Related MCP Servers

Glama MCP Gateway

Resources