Server definition

Hash: sha256:4b170051f28ee5f1df21666994968d6a6b8b392853f641e3d9775850b8467f68
What it is: What a remote MCP server returned when asked what it offers: 6 tools

The blob, as servednamed by its sha256

{
  "instructions": "Use the `eia_*` tools for U.S. Energy Information Administration (EIA) API v2 energy data. Requires an `EIA_API_KEY`. Routes use path identifiers (e.g. `electricity`, `petroleum/pri`); leading, trailing, and doubled slashes are stripped, so an EIA-doc spelling resolves the same way. Workflow: `eia_search_routes` or `eia_browse_routes` to find a leaf route → `eia_describe_route` for its facets and columns → `eia_query_route` with facet-ID filters. Facet values come only from describe, not route metadata, so describe before querying. Values arrive as strings. `eia_query_route` returns a preview and stages nothing by default; pass `stage: true` to also stage the matching rows as a DataCanvas table named by the `dataset` field, queried via SQL with `eia_dataframe_query`. Every dataset a tenant stages shares one canvas, so tables from different routes cross-join by name. The dataframe tools are listed only where a canvas is configured.",
  "tools": [
    {
      "description": "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.",
      "inputSchema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "additionalProperties": false,
        "properties": {
          "path": {
            "description": "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.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "name": "eia_browse_routes",
      "outputSchema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "additionalProperties": false,
        "anyOf": [
          {
            "not": {
              "required": [
                "error"
              ]
            },
            "required": [
              "path",
              "children",
              "isLeaf"
            ]
          },
          {
            "required": [
              "error"
            ]
          }
        ],
        "properties": {
          "children": {
            "description": "Child entries under the browsed path.",
            "items": {
              "additionalProperties": false,
              "description": "A child route entry.",
              "properties": {
                "description": {
                  "description": "Route description.",
                  "type": "string"
                },
                "id": {
                  "description": "Route segment ID.",
                  "type": "string"
                },
                "isLeaf": {
                  "description": "True when this child is a queryable leaf route with data.",
                  "type": "boolean"
                },
                "name": {
                  "description": "Human-readable name.",
                  "type": "string"
                },
                "route": {
                  "description": "Full route path usable in eia_describe_route or eia_query_route.",
                  "type": "string"
                }
              },
              "required": [
                "id",
                "name",
                "description",
                "route",
                "isLeaf"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "error": {
            "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"
          },
          "isLeaf": {
            "description": "True when the browsed path itself is a leaf route — no children to drill into; use eia_describe_route instead.",
            "type": "boolean"
          },
          "path": {
            "description": "The path that was browsed (empty string for root).",
            "type": "string"
          }
        },
        "type": "object"
      }
    },
    {
      "description": "List canvas dataframes (df_<id>) 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.",
      "inputSchema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "additionalProperties": false,
        "properties": {
          "name": {
            "description": "df_<id> handle to describe a single dataframe. Omit to list all active dataframes.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "name": "eia_dataframe_describe",
      "outputSchema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "additionalProperties": false,
        "anyOf": [
          {
            "not": {
              "required": [
                "error"
              ]
            },
            "required": [
              "active_names",
              "dataframes"
            ]
          },
          {
            "required": [
              "error"
            ]
          }
        ],
        "properties": {
          "active_names": {
            "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"
          },
          "dataframes": {
            "description": "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.",
            "items": {
              "additionalProperties": false,
              "description": "A canvas dataframe entry.",
              "properties": {
                "column_schema": {
                  "description": "Column schema (all EIA data columns are VARCHAR and nullable).",
                  "items": {
                    "additionalProperties": false,
                    "description": "A column in the dataframe schema.",
                    "properties": {
                      "name": {
                        "description": "Column name.",
                        "type": "string"
                      },
                      "nullable": {
                        "description": "Whether the column permits NULL.",
                        "type": "boolean"
                      },
                      "type": {
                        "description": "DuckDB column type (VARCHAR for EIA data values).",
                        "type": "string"
                      }
                    },
                    "required": [
                      "name",
                      "type",
                      "nullable"
                    ],
                    "type": "object"
                  },
                  "type": "array"
                },
                "created_at": {
                  "description": "ISO 8601 creation timestamp.",
                  "type": "string"
                },
                "expires_at": {
                  "description": "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.",
                  "type": "string"
                },
                "max_rows": {
                  "description": "Materialization cap that produced truncated, when applicable.",
                  "type": "number"
                },
                "name": {
                  "description": "Canvas table name (df_<id>).",
                  "type": "string"
                },
                "query_params": {
                  "additionalProperties": {},
                  "description": "Input parameters the source tool was called with.",
                  "propertyNames": {
                    "type": "string"
                  },
                  "type": "object"
                },
                "row_count": {
                  "description": "Rows materialized in the dataframe.",
                  "type": "number"
                },
                "source_tool": {
                  "description": "Tool that produced this dataframe.",
                  "type": "string"
                },
                "truncated": {
                  "description": "True when the EIA upstream had more rows than were registered.",
                  "type": "boolean"
                }
              },
              "required": [
                "name",
                "source_tool",
                "query_params",
                "created_at",
                "row_count",
                "truncated",
                "column_schema"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "error": {
            "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"
          },
          "found": {
            "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"
          },
          "requested_name": {
            "description": "Echo of the name input. Absent when no name was supplied.",
            "type": "string"
          }
        },
        "type": "object"
      }
    },
    {
      "description": "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_<id> 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.",
      "inputSchema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "additionalProperties": false,
        "properties": {
          "preview": {
            "description": "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.",
            "maximum": 10000,
            "minimum": 0,
            "type": "integer"
          },
          "register_as": {
            "description": "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.",
            "minLength": 1,
            "type": "string"
          },
          "row_limit": {
            "default": 1000,
            "description": "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.",
            "maximum": 10000,
            "minimum": 1,
            "type": "integer"
          },
          "sql": {
            "description": "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",
            "minLength": 1,
            "type": "string"
          }
        },
        "required": [
          "sql"
        ],
        "type": "object"
      },
      "name": "eia_dataframe_query",
      "outputSchema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "additionalProperties": false,
        "anyOf": [
          {
            "not": {
              "required": [
                "error"
              ]
            },
            "required": [
              "columns",
              "rows",
              "totalRows",
              "returnedRows",
              "truncated",
              "executedSql"
            ]
          },
          {
            "required": [
              "error"
            ]
          }
        ],
        "properties": {
          "columns": {
            "description": "Column names in projection order.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "error": {
            "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"
          },
          "executedSql": {
            "description": "Echo of the SQL statement that was executed — confirms the exact query that ran.",
            "type": "string"
          },
          "expires_at": {
            "description": "ISO 8601 expiry for the newly registered dataframe, when applicable. Extended each time a later query references it.",
            "type": "string"
          },
          "notice": {
            "description": "Guidance when either cap bound the response — names the cap that applied and how to reach the rows it withheld.",
            "type": "string"
          },
          "registered_as": {
            "description": "Set when register_as was supplied and the new dataframe was materialized.",
            "type": "string"
          },
          "returnedRows": {
            "description": "Rows included in this response.",
            "type": "number"
          },
          "rows": {
            "description": "Materialized rows, bounded by preview / row_limit.",
            "items": {
              "additionalProperties": {},
              "description": "A result row with dynamic keys matching the SQL projection columns.",
              "properties": {},
              "type": "object"
            },
            "type": "array"
          },
          "totalRows": {
            "description": "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.",
            "type": "number"
          },
          "truncated": {
            "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"
          }
        },
        "type": "object"
      }
    },
    {
      "description": "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.",
      "inputSchema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "additionalProperties": false,
        "properties": {
          "facet": {
            "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"
          },
          "route": {
            "description": "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.",
            "minLength": 1,
            "type": "string"
          },
          "values_offset": {
            "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"
          }
        },
        "required": [
          "route"
        ],
        "type": "object"
      },
      "name": "eia_describe_route",
      "outputSchema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "additionalProperties": false,
        "anyOf": [
          {
            "not": {
              "required": [
                "error"
              ]
            },
            "required": [
              "route",
              "description",
              "facets",
              "values_offset",
              "data_columns",
              "frequencies",
              "date_range",
              "default_frequency",
              "default_date_format"
            ]
          },
          {
            "required": [
              "error"
            ]
          }
        ],
        "properties": {
          "data_columns": {
            "description": "Data columns available for this route.",
            "items": {
              "additionalProperties": false,
              "description": "A data column available for this route.",
              "properties": {
                "alias": {
                  "description": "Human-readable column alias.",
                  "type": "string"
                },
                "id": {
                  "description": "Column ID — use in the columns parameter of eia_query_route.",
                  "type": "string"
                },
                "units": {
                  "description": "Measurement units (e.g. \"cents per kilowatt-hour\").",
                  "type": "string"
                }
              },
              "required": [
                "id",
                "alias",
                "units"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "date_range": {
            "additionalProperties": false,
            "description": "Available date range for this route.",
            "properties": {
              "end": {
                "description": "Latest available period.",
                "type": "string"
              },
              "start": {
                "description": "Earliest available period.",
                "type": "string"
              }
            },
            "required": [
              "start",
              "end"
            ],
            "type": "object"
          },
          "default_date_format": {
            "description": "Period format for the default frequency (e.g. \"YYYY-MM\").",
            "type": "string"
          },
          "default_frequency": {
            "description": "Default frequency ID used when none is specified.",
            "type": "string"
          },
          "description": {
            "description": "Human-readable description of the dataset.",
            "type": "string"
          },
          "error": {
            "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"
          },
          "facets": {
            "description": "Filterable dimensions. Each facet has an ID and a window of its valid values. Restricted to one entry when the facet input is set.",
            "items": {
              "additionalProperties": false,
              "description": "A filterable dimension for this route.",
              "properties": {
                "description": {
                  "description": "Facet description.",
                  "type": "string"
                },
                "id": {
                  "description": "Facet ID — use as key in the filters parameter of eia_query_route (e.g. filters: { \"stateid\": \"TX\" }).",
                  "type": "string"
                },
                "value_count": {
                  "description": "Total values this facet has upstream, independent of the returned window.",
                  "type": "number"
                },
                "values": {
                  "description": "Valid values for this facet dimension, starting at values_offset and capped at EIA_FACET_VALUE_CAP.",
                  "items": {
                    "additionalProperties": false,
                    "description": "A valid facet value.",
                    "properties": {
                      "alias": {
                        "description": "Short alias, when provided by EIA.",
                        "type": "string"
                      },
                      "id": {
                        "description": "Facet value ID — use as filter value.",
                        "type": "string"
                      },
                      "name": {
                        "description": "Human-readable name. Falls back to the alias, then to the id, on the values EIA sends without one.",
                        "type": "string"
                      }
                    },
                    "required": [
                      "id",
                      "name"
                    ],
                    "type": "object"
                  },
                  "type": "array"
                },
                "values_truncated": {
                  "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"
                }
              },
              "required": [
                "id",
                "description",
                "values",
                "value_count",
                "values_truncated"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "frequencies": {
            "description": "Valid frequency options for eia_query_route.",
            "items": {
              "additionalProperties": false,
              "description": "A frequency option for eia_query_route.",
              "properties": {
                "description": {
                  "description": "Human-readable description.",
                  "type": "string"
                },
                "format": {
                  "description": "Period format string (e.g. \"YYYY-MM\", \"YYYY\").",
                  "type": "string"
                },
                "id": {
                  "description": "Frequency ID (e.g. \"monthly\", \"annual\").",
                  "type": "string"
                },
                "query": {
                  "description": "API query value for this frequency.",
                  "type": "string"
                }
              },
              "required": [
                "id",
                "description",
                "query",
                "format"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "notice": {
            "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"
          },
          "route": {
            "description": "The route path described.",
            "type": "string"
          },
          "values_offset": {
            "description": "Index of the first facet value returned, echoing the requested offset.",
            "type": "number"
          }
        },
        "type": "object"
      }
    },
    {
      "description": "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.",
      "inputSchema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "additionalProperties": false,
        "properties": {
          "columns": {
            "description": "Data column IDs to return (reduces payload). Defaults to all. IDs discoverable via eia_describe_route.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "end": {
            "description": "Period end (same format as start).",
            "type": "string"
          },
          "filters": {
            "additionalProperties": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                }
              ]
            },
            "description": "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.",
            "propertyNames": {
              "type": "string"
            },
            "type": "object"
          },
          "frequency": {
            "description": "Aggregation frequency ID (e.g. \"monthly\", \"annual\"). Defaults to route default. Valid IDs from eia_describe_route.",
            "type": "string"
          },
          "length": {
            "default": 100,
            "description": "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.",
            "maximum": 5000,
            "minimum": 1,
            "type": "integer"
          },
          "offset": {
            "default": 0,
            "description": "Row offset into the matching set (default 0). An offset at or beyond total returns zero rows.",
            "maximum": 9007199254740991,
            "minimum": 0,
            "type": "integer"
          },
          "route": {
            "description": "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.",
            "minLength": 1,
            "type": "string"
          },
          "sort": {
            "description": "Result ordering.",
            "items": {
              "description": "A sort criterion.",
              "properties": {
                "column": {
                  "description": "Column ID to sort by.",
                  "type": "string"
                },
                "direction": {
                  "description": "Sort direction.",
                  "enum": [
                    "asc",
                    "desc"
                  ],
                  "type": "string"
                }
              },
              "required": [
                "column",
                "direction"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "stage": {
            "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"
          },
          "start": {
            "description": "Period start in the route date format (e.g. \"2020-01\" for monthly, \"2020\" for annual). Format from eia_describe_route.",
            "type": "string"
          }
        },
        "required": [
          "route"
        ],
        "type": "object"
      },
      "name": "eia_query_route",
      "outputSchema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "additionalProperties": false,
        "anyOf": [
          {
            "not": {
              "required": [
                "error"
              ]
            },
            "required": [
              "route",
              "data",
              "total",
              "returned_count",
              "frequency",
              "date_format",
              "effectiveRoute",
              "totalCount",
              "returnedCount",
              "appliedOffset",
              "appliedLength"
            ]
          },
          {
            "required": [
              "error"
            ]
          }
        ],
        "properties": {
          "appliedColumns": {
            "description": "Echo of the column projection as applied, when columns were provided.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "appliedEnd": {
            "description": "Echo of the end period as applied, when an end was provided.",
            "type": "string"
          },
          "appliedFilters": {
            "additionalProperties": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                }
              ]
            },
            "description": "Facet filters applied to the query, when provided.",
            "propertyNames": {
              "type": "string"
            },
            "type": "object"
          },
          "appliedFrequency": {
            "description": "Echo of the frequency as applied, when a frequency was provided.",
            "type": "string"
          },
          "appliedLength": {
            "description": "Preview row count requested for this call.",
            "type": "number"
          },
          "appliedOffset": {
            "description": "Row offset applied to the query — the cause when a page comes back empty.",
            "type": "number"
          },
          "appliedSort": {
            "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"
          },
          "appliedStart": {
            "description": "Echo of the start period as applied, when a start was provided.",
            "type": "string"
          },
          "canvas_preview_note": {
            "description": "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.",
            "type": "string"
          },
          "data": {
            "description": "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.",
            "items": {
              "additionalProperties": {},
              "description": "A single data row with dynamic column keys.",
              "properties": {},
              "type": "object"
            },
            "type": "array"
          },
          "dataset": {
            "description": "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.",
            "type": "string"
          },
          "date_format": {
            "description": "Period format for the returned data (e.g. \"YYYY-MM\").",
            "type": "string"
          },
          "effectiveRoute": {
            "description": "The route path that was queried.",
            "type": "string"
          },
          "error": {
            "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"
          },
          "frequency": {
            "description": "Frequency of the returned data.",
            "type": "string"
          },
          "notice": {
            "description": "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).",
            "type": "string"
          },
          "returnedCount": {
            "description": "Rows in this response. When returnedCount < totalCount, use offset or canvas for the rest.",
            "type": "number"
          },
          "returned_count": {
            "description": "Number of rows in this response. When returned_count < total, use offset pagination or DataCanvas for the rest.",
            "type": "number"
          },
          "route": {
            "description": "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.",
            "type": "string"
          },
          "total": {
            "description": "Total matching rows in the EIA dataset for this query (may exceed returned rows when pagination or spillover applies).",
            "type": "number"
          },
          "totalCount": {
            "description": "Total matching rows in the EIA dataset.",
            "type": "number"
          },
          "truncation_warning": {
            "description": "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).",
            "type": "string"
          }
        },
        "type": "object"
      }
    },
    {
      "description": "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.",
      "inputSchema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "additionalProperties": false,
        "properties": {
          "limit": {
            "default": 10,
            "description": "Maximum results to return (default 10, max 30).",
            "maximum": 30,
            "minimum": 1,
            "type": "integer"
          },
          "query": {
            "description": "Free-text search terms to match against route names and descriptions.",
            "minLength": 1,
            "type": "string"
          }
        },
        "required": [
          "query"
        ],
        "type": "object"
      },
      "name": "eia_search_routes",
      "outputSchema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "additionalProperties": false,
        "anyOf": [
          {
            "not": {
              "required": [
                "error"
              ]
            },
            "required": [
              "results",
              "effectiveQuery",
              "totalIndexed",
              "indexComplete",
              "truncated",
              "shown",
              "cap"
            ]
          },
          {
            "required": [
              "error"
            ]
          }
        ],
        "properties": {
          "cap": {
            "description": "The limit that was applied.",
            "type": "number"
          },
          "effectiveQuery": {
            "description": "Query as submitted to the Fuse.js index.",
            "type": "string"
          },
          "error": {
            "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"
          },
          "indexComplete": {
            "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"
          },
          "indexGaps": {
            "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"
          },
          "notice": {
            "description": "Recovery hint when no routes matched — suggests alternative queries or using eia_browse_routes.",
            "type": "string"
          },
          "results": {
            "description": "Ranked matches, best first.",
            "items": {
              "additionalProperties": false,
              "description": "A search result entry.",
              "properties": {
                "description": {
                  "description": "Route description.",
                  "type": "string"
                },
                "filter_hint": {
                  "additionalProperties": {
                    "type": "string"
                  },
                  "description": "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)).",
                  "propertyNames": {
                    "type": "string"
                  },
                  "type": "object"
                },
                "isLeaf": {
                  "description": "True when the route is a queryable leaf; false when it has sub-routes to browse.",
                  "type": "boolean"
                },
                "name": {
                  "description": "Human-readable route name.",
                  "type": "string"
                },
                "route": {
                  "description": "Route path — usable directly in eia_describe_route or eia_query_route.",
                  "type": "string"
                },
                "score": {
                  "description": "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.",
                  "type": "number"
                }
              },
              "required": [
                "route",
                "name",
                "description",
                "score",
                "isLeaf"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "shown": {
            "description": "Number of results returned.",
            "type": "number"
          },
          "totalIndexed": {
            "description": "Total entries in the search index (routes + STEO series names + facet values).",
            "type": "number"
          },
          "truncated": {
            "description": "True when matches were capped at limit; more may exist.",
            "type": "boolean"
          }
        },
        "type": "object"
      }
    }
  ]
}

Verify it yourself

curl -s https://api.teppi.xyz/v1/evidence/sha256:4b170051f28ee5f1df21666994968d6a6b8b392853f641e3d9775850b8467f68 | sha256sum