Skip to main content
Glama
gridcarbon

gridcarbon-mcp

Official
by gridcarbon
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Get a carbon intensity time series for a zone

get_intensity_history
Read-onlyIdempotent

Pull interval-by-interval carbon intensity data for one zone over a chosen time window, enabling analysis of grid emissions trends, cleanest and dirtiest hours, and shifts across days.

Instructions

Return the interval-by-interval carbon intensity history for ONE zone over a time window.

Use it for "how has the German grid varied today", "what was the cleanest hour in France yesterday", "is Ireland's grid dirtier at breakfast than at midday".

Data contract (read this before you report any number to a user):

  • Unit is gCO2eq/kWh (grams of CO2-equivalent per kilowatt-hour of electricity consumed). LOWER IS CLEANER. There is no upper bound; roughly <100 is very clean, ~100-300 is moderate, >400 is fossil-heavy.

  • "ts" is the START of the reporting interval, in UTC (ISO-8601, "Z" suffix). A value with ts=2026-08-26T01:00:00Z and a 60-minute resolution covers 01:00-02:00 UTC.

  • "latest" means NEWEST PUBLISHED, NOT "now". European zones typically run 2-4 hours behind real time; US (EIA) zones run 11-28 hours behind. Every reading carries "age_minutes" and "age_human" -- state that age when you report the value. Saying "the current carbon intensity in Texas is X" about a 20-hour-old number is wrong.

  • GB values come from NESO and use OPERATIONAL (combustion-only) emission factors, not the IPCC AR5 lifecycle factors used for the other 44 zones. GB numbers are systematically lower and MUST NOT be compared or ranked against other zones.

  • Coverage starts 2026-08-21T00:00:00Z; there is no data before that date.

  • Attribution is a licence condition. If you surface these values to an end user, credit: ENTSO-E Transparency Platform / U.S. Energy Information Administration (EIA) / NESO Carbon Intensity API. EIA does not endorse this service or any use of it.

Window semantics:

  • The window is HALF-OPEN: [from, to). A point at exactly 'to' is excluded.

  • Default window is the last 24 hours. 'hours' is a shorthand for that.

  • Every point's ts is the START of its interval, in UTC. Resolution is 60 minutes for all zones except GB, which is 30.

  • There is no data before 2026-08-21T00:00:00Z, and none for intervals the upstream source has not published yet, so a window that reaches into the last few hours (or, for US zones, the last day) will simply have fewer points. Missing points are gaps, not zeros — never interpolate them.

Args:

  • zone (string, required): e.g. "DE", "FR", "US-CAISO", "GB".

  • from (string, optional): inclusive ISO-8601 UTC start.

  • to (string, optional): exclusive ISO-8601 UTC end.

  • hours (integer 1-2160, optional): last N hours ending now; ignored when 'from' is set.

  • max_points (integer, default 200): trim to the most recent N points for readability.

  • include_points (boolean, default true): false returns summary statistics only.

  • response_format ("markdown" | "json", default "markdown").

Returns (structured): { "zone": "DE", "zone_name": "Germany-Luxembourg", "source": "entsoe", "resolution_min": 60, "unit": "gCO2eq/kWh", "from": "2026-08-25T18:00:00Z", "to": "2026-08-26T00:00:00Z", "count": 6, // points the API returned for the window "server_truncated": false, // TRUE means the window is INCOMPLETE, see below "points_returned": 6, "points_omitted_for_brevity": 0, "summary": { "min": 356.5, "max": 380.7, "mean": 363.6, "first": {...}, "last": {...}, "cleanest": {"ts": "...", "gco2eq_kwh": 356.5}, "dirtiest": {"ts": "...", "gco2eq_kwh": 380.7}, "change_from_first_to_last_pct": -5.3 }, "points": [ { "ts": "2026-08-25T18:00:00Z", "gco2eq_kwh": 380.7, "method": "computed:v1" } ], "operational_factors_only": false, "warnings": [] }

Truncation — do not ignore this: The API caps a response at 5000 points. When it does, "server_truncated" is true and the series you received is only PART of the requested window. Never present a truncated series as a complete picture, and never compute a daily/weekly average from one. Narrow the window and call again instead.

Examples:

  • "Chart France's grid over the last two days" -> zone="FR", hours=48

  • "Cleanest hour in Spain yesterday" -> zone="ES", from/to spanning that UTC day, then read summary.cleanest

  • "Average intensity last week" -> hours=168, include_points=false

  • Don't use for: a single current value (get_carbon_intensity) or cross-zone ranking (compare_zones).

Errors:

  • Unknown zone -> error with near matches; call list_zones.

  • Unparseable from/to -> error naming the offending field.

  • Empty window -> a message saying no intervals were published in that range.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
toNoWindow end, EXCLUSIVE — the window is half-open [from, to). ISO-8601 UTC, e.g. '2026-08-25T18:00:00Z'. Local times and offsets are not accepted. Omit for "up to now".
fromNoWindow start, INCLUSIVE. ISO-8601 UTC, e.g. '2026-08-25T18:00:00Z'. Local times and offsets are not accepted. Omit to use 'hours' or the default last 24h. Nothing exists before 2026-08-21T00:00:00Z.
zoneYesZone code, e.g. 'DE' (Germany-Luxembourg), 'FR' (France), 'US-ERCOT' (Texas), 'IT-NORD', 'GB'. Case-insensitive and '_' is accepted for '-'. An unambiguous country/region name such as 'Texas' or 'Portugal' also resolves. Call list_zones if you are unsure — never substitute a neighbouring zone that is not covered.
hoursNoConvenience alternative to from/to: the last N hours ending now. Ignored if 'from' is given. Example: hours=48 for the last two days.
max_pointsNoCap on how many interval points are included in the response, to keep it readable. If the window holds more, the MOST RECENT max_points are returned and the response says how many were omitted. Summary statistics are always computed over the WHOLE window, never over the trimmed subset.
include_pointsNoSet false to get only the summary statistics (min/max/mean/cleanest/dirtiest) without the individual intervals. Useful for long windows.
response_formatNoOutput format for the text content. 'markdown' is compact and human-readable; 'json' returns the full structured payload as text. Structured data is always returned alongside either way.markdown

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
toYes
fromYes
unitYes
zoneYes
countYesPoints the API returned for the window.
pointsYes
sourceNo
summaryNo
warningsYes
zone_nameNo
resolution_minNo
points_returnedYes
server_truncatedYesTrue if the API hit its 5000-point cap and the window is INCOMPLETE.
server_truncation_noteNo
operational_factors_onlyYes
points_omitted_for_brevityYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.2

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context: the unit meaning (gCO2eq/kWh, lower is cleaner), the distinction between 'latest' (newest published) and 'now', the GB operational-factor caveat, the data-start boundary, the half-open window semantics, truncation behavior (server_truncated true means incomplete), and the rule never to interpolate missing points. This goes far beyond the annotations and is essential for correct interpretation.

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 long, but every section is purposeful and well factored: a one-sentence purpose, examples, data contract, window semantics, args, return structure, truncation warning, and errors. It is front-loaded with the core purpose and examples, and the headings make it scannable. While it could be trimmed, no sentence is redundant; given the tool's complexity (7 parameters, return contract, error cases), the length is justified. This is strong structure, though not as lean as a two-sentence description.

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, the description is exceptionally complete. It covers parameter usage, return structure with a concrete JSON example, window semantics, truncation handling, error messages, attribution licensing, and even the caveat about missing points. It also explains the summary statistics and how to use them, and notes that max_points trimming does not affect summary statistics. The output schema is provided, but the description adds operational context (like server_truncated) that is not in the schema. Nothing an agent needs to call this tool correctly is omitted.

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?

The input schema has 100% description coverage, documenting each parameter's format, defaults, and constraints (e.g., 'EXCLUSIVE' for 'to', 'Ignored if from is given' for 'hours'). The description does not add meaning beyond what the schema already provides for the parameters themselves; it reiterates the same semantics. The only incremental value is clarifying the default window and the 'hours' shorthand, but those are also mentioned in the schema ('hours' description mentions 'the last N hours'). With full schema coverage, a baseline of 3 is appropriate.

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: 'Return the interval-by-interval carbon intensity history for ONE zone over a time window.' It explicitly scopes to a single zone, distinguishing it from cross-zone tools, and provides concise example queries ('how has the German grid varied today') that anchor the purpose. This is unambiguous and immediately differentiates the tool from siblings like compare_zones.

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 explicitly states when to use the tool via example intents ('what was the cleanest hour in France yesterday') and then explicitly lists exclusions: 'Don't use for: a single current value (get_carbon_intensity) or cross-zone ranking (compare_zones).' It names the sibling alternatives and the conditions that disqualify them, leaving no ambiguity about routing.

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

Deploy Server

Other Tools