Return the most recently published carbon intensity for ONE electricity zone.

Answers questions like "how clean is the German grid right now", "should I run this batch job in Ireland or leave it", "what is the CO2 per kWh in Texas".

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.

Args:

• zone (string, required): Zone code such as "DE", "FR", "US-ERCOT", "IT-NORD", "GB". Case-insensitive; unambiguous names like "Texas" or "Portugal" also resolve. Unknown zones return an error listing near matches — do NOT fall back to a neighbouring country.

• response_format ("markdown" | "json", default "markdown"): text rendering.

Returns (structured): { "reading": { "zone": "DE", "zone_name": "Germany-Luxembourg", "source": "entsoe", "resolution_min": 60, "ts": "2026-08-26T01:00:00Z", // START of the interval, UTC "gco2eq_kwh": 371.4, "unit": "gCO2eq/kWh", "method": "computed:v1", "age_minutes": 107, "age_human": "1h 47m ago", "freshness": "normal", // fresh | normal | stale | very_stale "operational_factors_only": false, "warning": "..." // present only when something could mislead }, "as_of_statement": "As of 2026-08-26 01:00 UTC ... was 371.4 gCO2eq/kWh.", "unit": "gCO2eq/kWh", "interpretation": "371.4 gCO2eq/kWh is fossil-heavy.", "warnings": [] }

How to report the answer: Quote or paraphrase "as_of_statement". Always include the timestamp or the age. Never say "currently" or "right now" about a reading whose freshness is "stale" or "very_stale", and never about any US zone without naming the time it refers to.

Examples:

• "How clean is France's grid?" -> zone="FR"

• "Carbon intensity in Texas" -> zone="US-ERCOT" (freshness will be ~1 day old; say so)

• Don't use for: comparing several zones (use compare_zones), or for a time series (use get_intensity_history).

Errors:

• Unknown zone -> "Unknown zone "XX". ... Call list_zones ..." with suggestions.

• Network/timeout -> a message saying the API is unreachable. Do not invent a value.

• A covered zone with no published data yet returns "No published data for yet."

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.

List every electricity zone gridcarbon covers, with its upstream data source, its reporting resolution, and whether its numbers are comparable with the rest.

Call this whenever you are not certain a zone code exists. The data tools reject unknown codes on purpose — there is no sensible fallback, and substituting a neighbouring country's grid would be a fabrication.

Coverage is 45 zones: continental Europe + Nordics + Ireland (ENTSO-E), 10 US balancing authorities plus a Lower-48 aggregate (EIA), and Great Britain (NESO). There is NO coverage of Canada, Australia, Japan, China, India, Latin America or Africa.

This tool returns no measurements itself, but the values the other tools return follow one contract: the unit is gCO2eq/kWh and LOWER IS CLEANER; each value's "ts" is the START of its reporting interval in UTC; and "latest" means NEWEST PUBLISHED, NOT "now" — see typical_lag_hours below and always quote the timestamp with the number.

Two things this list tells you that matter for correctness:

• factor_basis: "lifecycle" for 44 zones (IPCC AR5, includes construction and fuel supply chain) versus "operational" for GB (combustion only). 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.

• typical_lag_hours: how far behind real time that source normally publishes. US zones are routinely ~1 day behind. This is normal, not an outage — but it means a US value must never be described as "right now".

Args:

• source ("entsoe" | "eia" | "uk-neso", optional): filter by upstream provider.

• search (string, optional): case-insensitive substring over zone code and name.

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

Returns (structured): { "count": 45, "total_covered": 45, "zones": [ { "zone": "DE", "name": "Germany-Luxembourg", "source": "entsoe", "resolution_min": 60, "factor_basis": "lifecycle", "typical_lag_hours": 4, "comparable_with_others": true }, { "zone": "GB", "name": "Great Britain", "source": "uk-neso", "resolution_min": 30, "factor_basis": "operational", "typical_lag_hours": 2, "comparable_with_others": false } ], "history_starts_at": "2026-08-21T00:00:00Z", "notes": [...] }

Examples:

• "Which US grids do you cover?" -> source="eia"

• "Do you have Italy?" -> search="italy" (returns the 7 Italian bidding zones)

• "Is Japan supported?" -> search="japan" returns zero rows; say it is not covered.

Rank several electricity zones (or all 45) by their most recently published carbon intensity, cleanest first by default.

Use it for "where should I run this training job", "is Sweden cleaner than Poland right now", "what are the five cleanest grids you cover".

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.

Great Britain — the one thing that makes this tool easy to get wrong: GB's numbers come from NESO and use OPERATIONAL (combustion-only) factors. The other 44 zones use IPCC AR5 LIFECYCLE factors, which also count plant construction and fuel supply chains. GB therefore looks cleaner than like-for-like. GB is EXCLUDED from the ranking by default and returned in "excluded_from_ranking" WITH its value and the reason, so you can still report it — just report it separately, never as "GB is the cleanest of these". Passing include_gb_in_ranking=true ranks it anyway and flags every affected row; only do that if the user has been told why the numbers differ.

Comparing different moments: Each zone's newest published interval has its own timestamp. European zones run 2-4h behind, US zones 11-28h behind, so a Europe-vs-US ranking compares observations taken up to a day apart. "observation_times.age_gap_minutes" reports that spread and a warning is added when it exceeds 6 hours. Say so when it applies.

Args:

• zones (string[], optional): zone codes to rank. Omit to rank all covered zones.

• order ("cleanest_first" | "dirtiest_first", default "cleanest_first").

• limit (integer 1-45, default 45): cap on ranked rows.

• include_gb_in_ranking (boolean, default false): see above.

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

Returns (structured): { "unit": "gCO2eq/kWh", "order": "cleanest_first", "comparison_basis": "IPCC AR5 lifecycle factors (GB excluded: operational factors)", "ranked_count": 3, "omitted_by_limit": 0, "ranked": [ { "rank": 1, "zone": "FR", "zone_name": "France", "gco2eq_kwh": 48.3, "ts": "2026-08-26T00:00:00Z", "age_minutes": 168, "age_human": "2h 48m ago", "freshness": "normal", "band": "very clean", "comparable": true, "method": "computed:v1" } ], "cleanest": { ... }, "dirtiest": { ... }, "spread_gco2eq_kwh": 356.1, "excluded_from_ranking": [ { "zone": "GB", "zone_name": "Great Britain", "gco2eq_kwh": 114, "ts": "2026-08-26T01:30:00Z", "age_human": "1h 18m ago", "reason": "GB uses operational (combustion-only) factors ... not comparable ..." } ], "observation_times": { "newest_ts": "...", "oldest_ts": "...", "age_gap_minutes": 90 }, "headline": "Of 3 zone(s) ranked, FR is cleanest at 48.3 gCO2eq/kWh ...", "warnings": [ ... ] }

Unknown zone codes are returned in "excluded_from_ranking" with reason "unknown zone code" instead of failing the whole call — surface them to the user, do not substitute a neighbour.

Examples:

• "Germany, France or Spain — which is cleanest?" -> zones=["DE","FR","ES"]

• "Five cleanest grids you cover" -> omit zones, limit=5

• "Dirtiest US grid today" -> zones=["US-ERCOT","US-PJM","US-MISO","US-SPP","US-SOCO", "US-CAISO","US-ISONE","US-NYISO","US-BPA","US-TVA"], order="dirtiest_first", limit=1

• Don't use for: one zone (get_carbon_intensity) or a time series (get_intensity_history).