Eia

Eia Petroleum

eia_petroleum

Read-onlyIdempotent

Get EIA petroleum time series data for a specific product (gasoline, diesel, crude, stocks, supply, production, imports). Returns prices or volumes by period with regional breakdowns. Requires free EIA API key.supply, production, and imports. Simplified interface to common EIA petroleum series.

Input Schema

Name	Required	Description
`end`	No	End date (optional)
`area`	No	Retail prices only: "US" (default, national average), "all" (every region EIA reports), or an EIA area code such as "R10" (East Coast) or "SCA" (California).
`grade`	No	Gasoline grade, for product "gasoline" only: "regular" (default — the national headline price), "midgrade", "premium", or "all" (all grades combined).
`start`	No	Start date (optional)
`_apiKey`	Yes	EIA API key
`product`	Yes	Product type: "gasoline" (retail pump price), "diesel" (retail pump price), "crude" (WTI spot), "stocks", "supply", "production", "imports"
`frequency`	No	Frequency: "weekly", "monthly", "annual" (optional; retail prices default to weekly)

Output Schema

Name	Required	Description
`data`	Yes	Time series data points (max 100 returned)
`count`	Yes	Number of records returned
`total`	Yes	Total number of records available
`product`	Yes	Petroleum product type requested
`truncated`	Yes	True if more than 100 records available
`description`	Yes	Series description from EIA API

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedNov 2, 2026

changedInput schema / examples

Previous value: -[
-  {
-    "_apiKey": "your-eia-api-key",
-    "product": "gasoline"
-  },
-  {
-    "_apiKey": "your-eia-api-key",
-    "frequency": "weekly",
-    "product": "crude",
-    "start": "2023-01-01"
-  }
-]New value: +[
+  {
+    "product": "gasoline"
+  },
+  {
+    "frequency": "weekly",
+    "product": "crude",
+    "start": "2023-01-01"
+  }
+]

addedInput schema / properties / area

Added value: +{
+  "description": "Retail prices only: \"US\" (default, national average), \"all\" (every region EIA reports), or an EIA area code such as \"R10\" (East Coast) or \"SCA\" (California).",
+  "type": "string"
+}

changedInput schema / properties / frequency / description

Previous value: -"Frequency: \"weekly\", \"monthly\", \"annual\" (optional, defaults vary by product)"New value: +"Frequency: \"weekly\", \"monthly\", \"annual\" (optional; retail prices default to weekly)"

addedInput schema / properties / grade

Added value: +{
+  "description": "Gasoline grade, for product \"gasoline\" only: \"regular\" (default — the national headline price), \"midgrade\", \"premium\", or \"all\" (all grades combined).",
+  "enum": [
+    "regular",
+    "midgrade",
+    "premium",
+    "all"
+  ],
+  "type": "string"
+}

changedInput schema / properties / product / description

Previous value: -"Product type: \"gasoline\", \"diesel\", \"crude\", \"stocks\", \"supply\", \"production\", \"imports\""New value: +"Product type: \"gasoline\" (retail pump price), \"diesel\" (retail pump price), \"crude\" (WTI spot), \"stocks\", \"supply\", \"production\", \"imports\""

Changed1 schema field changedMay 8, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "count": {
+      "description": "Number of records returned",
+      "type": "number"
+    },
+    "data": {
+      "description": "Time series data points (max 100 returned)",
+      "items": {
+        "properties": {
+          "area": {
+            "description": "Geographic area name",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "description": {
+            "description": "Series description",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "period": {
+            "description": "Time period (e.g., date or year)",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "process": {
+            "description": "Process or measurement type",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "product": {
+            "description": "Product type",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "units": {
+            "description": "Unit of measurement",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "value": {
+            "description": "Numeric value for the period",
+            "type": [
+              "number",
+              "null"
+            ]
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "description": {
+      "description": "Series description from EIA API",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "product": {
+      "description": "Petroleum product type requested",
+      "type": "string"
+    },
+    "total": {
+      "description": "Total number of records available",
+      "type": "number"
+    },
+    "truncated": {
+      "description": "True if more than 100 records available",
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "product",
+    "total",
+    "description",
+    "count",
+    "data",
+    "truncated"
+  ],
+  "type": "object"
+}

Changed1 schema field changedMay 6, 2026

addedInput schema / examples

Added value: +[
+  {
+    "_apiKey": "your-eia-api-key",
+    "product": "gasoline"
+  },
+  {
+    "_apiKey": "your-eia-api-key",
+    "frequency": "weekly",
+    "product": "crude",
+    "start": "2023-01-01"
+  }
+]

First observedApr 22, 2026

TDQS

B3.4/5.0

Behavior3/5

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds a genuinely useful auth requirement ('Requires free EIA API key') and the shape of returned data, but says nothing about rate limits, pagination, or how missing periods are handled on an open-world upstream source.

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

Conciseness3/5

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

The opening sentence is front-loaded and useful, but the text contains a garbled duplicated fragment ('Requires free EIA API key.supply, production, and imports') and the product list is repeated from the schema. Size is small, but the corruption hurts readability.

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 an output schema present and 100% schema coverage, the description only needs to frame the purpose, the auth requirement, and what the data represents — all of which it does. Only the moment-to-moment operational details (rate limits, error behavior from the upstream EIA API) are absent.

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%, so product values, area codes, grade enum, and frequency defaults are all fully documented in the schema. The description only restates the product list and regional breakdowns, adding no syntax or default behavior beyond what the schema already provides; baseline 3 applies.

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

Purpose4/5

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

States a specific verb and resource ('Get EIA petroleum time series data for a specific product') plus the return shape ('prices or volumes by period with regional breakdowns'). It also notes it is a 'Simplified interface to common EIA petroleum series', which implicitly separates it from eia_series, but no sibling is named explicitly.

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

Usage Guidelines3/5

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

Usage context is implied by 'specific product' and 'common EIA petroleum series', suggesting eia_series is the escape hatch for non-common series, but the description never says when to prefer this over eia_series, eia_natural_gas, or us_fuel_price. No explicit exclusions or prerequisites beyond the API key.

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

All Eia tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.