DC Hub — Data Center & Energy Intelligence

Get Retirement Headroom

get_retirement_headroom

Read-onlyIdempotent

Find near-term grid injection headroom from scheduled power plant retirements, returning nearest substations and queue pressure.

Instructions

Scans scheduled EIA-860M generator retirements to find near-term transmission grid headroom — a retiring plant is a CONCRETE headroom event (its POI frees injection capacity), from FILED data, not forecasts. Returns _entity=retirement_headroom_results: retiring generators inside your horizon (name, MW, fuel, prime mover, retirement_date), representative_point, nearest substations with distance_km + count within 25 km, county-level queue_pressure (competing in-progress MW), iso_context (the generator's own EIA balancing-authority code), and a pre-filled site_evaluation_handoff (analyze_site + get_water_risk args, capacity_mw = YOUR target load). Answers "where is grid capacity about to free up", "which retiring plants open injection headroom near me". Try: get_retirement_headroom target_mw=50 horizon_months=18 region_iso=MISO — "50 MW opening near a substation inside 18 months, sidestepping the 4-7yr mega-queue." Honesty: meta.caveat flags that filed dates are subject to ISO reliability reviews (RMR extensions). Use to find WHERE capacity opens next; for what's already queued use get_refined_queue; for one site use analyze_site.

Input Schema

TableJSON Schema

Name	Required	Description
`limit`	No	Max results to return (1-500; default varies by tool)
`target_mw`	Yes	Minimum required headroom in megawatts (MW) — filters to retiring generators at/above this size. Also passed through as the handoff's analyze_site capacity_mw (the DC you are siting).
`region_iso`	No	Optional target region or ISO (e.g., 'MISO', 'PJM', 'ERCOT', 'SPP', 'CAISO', 'NYISO', 'ISONE'). Matches the generator's own EIA balancing-authority code — real market boundaries, not state lines. Comma-separated for a union.
`fuel_filter`	No	Optional filter for retiring fuel categories, substring-matched (e.g., 'Coal', 'Natural Gas', 'Petroleum').
`horizon_months`	Yes	Time horizon in months to look ahead for planned retirements, 1-120 (e.g., 12, 18, 36).

Output Schema

TableJSON Schema

Name	Required	Description
`quota`	No	Caller quota state (remaining calls, tier) when available.
`_entity`	No	Payload class discriminator (e.g. facility\|market\|iso_grid\|queue_results\|deal\|report\|response) — branch on this before parsing the rest.
`citation`	No	Machine-readable citation: how to attribute DC Hub (dchub.cloud) for this payload. Normally an OBJECT {source, url, license, cite_as, retrieved_at}; a bare string is accepted and carries the attribution line itself.
`provenance`	No	Collection-level provenance block: {source, method, as_of, verification_counts, cite_url_template, license, cite_as}. Quote the verification level when citing.
`_front_door`	No	In-band front-door hint (first workflow-entry tool of a session): call plan_query(intent) first for the ordered multi-step plan.
`_return_loop`	No	Suggested next-session delta call (get_changes since=24h) so you pull only what changed.
`site_evaluation_handoff`	No	Pre-built follow-up calls (analyze_site / get_water_risk args) when the payload carries coordinates — an array of {tool, parameters, why} entries.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedAug 30, 2026

removedInput schema / $schema

Removed value: -"http://json-schema.org/draft-07/schema#"

removedOutput schema / $schema

Removed value: -"http://json-schema.org/draft-07/schema#"

Changed5 schema fields changedv2.3.20Aug 14, 2026

removedOutput schema / properties / citation / additionalProperties
```
Removed value: -{}
```

addedOutput schema / properties / citation / anyOf

Added value: +[
+  {
+    "additionalProperties": {},
+    "properties": {},
+    "type": "object"
+  },
+  {
+    "type": "string"
+  }
+]

changedOutput schema / properties / citation / description

Previous value: -"Machine-readable citation: how to attribute DC Hub (dchub.cloud) for this payload."New value: +"Machine-readable citation: how to attribute DC Hub (dchub.cloud) for this payload. Normally an OBJECT {source, url, license, cite_as, retrieved_at}; a bare string is accepted and carries the attribution line itself."

removedOutput schema / properties / citation / properties
```
Removed value: -{}
```
removedOutput schema / properties / citation / type
```
Removed value: -"object"
```

Changed4 schema fields changedv2.3.12Jul 28, 2026

changedInput schema / properties / horizon_months / description

Previous value: -"Time horizon to look ahead for planned retirements (e.g., 12, 18, 36)."New value: +"Time horizon in months to look ahead for planned retirements, 1-120 (e.g., 12, 18, 36)."

changedInput schema / properties / horizon_months / maximum
```
Previous value: -9007199254740991New value: +120
```
changedInput schema / properties / horizon_months / minimum
```
Previous value: --9007199254740991New value: +1
```

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "description": "DC Hub envelope: structuredContent mirrors the JSON payload in content[0].text — tool-specific data fields ride at the top level alongside these envelope keys.",
+  "properties": {
+    "_entity": {
+      "description": "Payload class discriminator (e.g. facility|market|iso_grid|queue_results|deal|report|response) — branch on this before parsing the rest.",
+      "type": "string"
+    },
+    "_front_door": {
+      "additionalProperties": {},
+      "description": "In-band front-door hint (first workflow-entry tool of a session): call plan_query(intent) first for the ordered multi-step plan.",
+      "properties": {},
+      "type": "object"
+    },
+    "_return_loop": {
+      "additionalProperties": {},
+      "description": "Suggested next-session delta call (get_changes since=24h) so you pull only what changed.",
+      "properties": {},
+      "type": "object"
+    },
+    "citation": {
+      "additionalProperties": {},
+      "description": "Machine-readable citation: how to attribute DC Hub (dchub.cloud) for this payload.",
+      "properties": {},
+      "type": "object"
+    },
+    "provenance": {
+      "additionalProperties": {},
+      "description": "Collection-level provenance block: {source, method, as_of, verification_counts, cite_url_template, license, cite_as}. Quote the verification level when citing.",
+      "properties": {},
+      "type": "object"
+    },
+    "quota": {
+      "additionalProperties": {},
+      "description": "Caller quota state (remaining calls, tier) when available.",
+      "properties": {},
+      "type": "object"
+    },
+    "site_evaluation_handoff": {
+      "anyOf": [
+        {
+          "items": {
+            "additionalProperties": {},
+            "properties": {},
+            "type": "object"
+          },
+          "type": "array"
+        },
+        {
+          "additionalProperties": {},
+          "properties": {},
+          "type": "object"
+        }
+      ],
+      "description": "Pre-built follow-up calls (analyze_site / get_water_risk args) when the payload carries coordinates — an array of {tool, parameters, why} entries."
+    }
+  },
+  "type": "object"
+}

Addedv2.3.8Jul 14, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already establish read-only, idempotent, non-destructive behavior, and the description adds meaningful context: it uses FILED data rather than forecasts, includes a meta.caveat about ISO reliability reviews and RMR extensions, and discloses that target_mw is passed through into the site_evaluation_handoff as capacity_mw. This goes beyond what annotations alone convey.

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

Conciseness4/5

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

The description is dense and front-loaded with the core purpose, then covers outputs, caveats, and sibling routing. Some promotional phrasing ('sidestepping the 4-7yr mega-queue') is non-essential, but overall the length is justified by the tool's complexity and the value of the example and exclusions.

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?

The tool is complex, but the description covers the data source, horizon, result contents, substation proximity logic, queue pressure, ISO context, handoff behavior, caveat, and how to choose among siblings. With an output schema present, nothing needed for correct invocation is missing.

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

Parameters4/5

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

The input schema already documents all parameters at 100% coverage, so the baseline is 3. The description adds real value on top by explaining that target_mw also becomes the handoff's capacity_mw, that region_iso matches the generator's EIA balancing-authority code rather than state lines, and that fuel_filter is substring-matched.

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

Purpose5/5

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

The description states a specific verb and resource: scanning scheduled EIA-860M generator retirements to find transmission grid headroom. It explicitly answers the tool's use cases ('where is grid capacity about to free up') and distinguishes itself from siblings like get_refined_queue and analyze_site.

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

Usage Guidelines5/5

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

The description gives both a clear when-to-use directive ('Use to find WHERE capacity opens next') and explicit alternatives ('for what's already queued use get_refined_queue; for one site use analyze_site'). It also includes a concrete parameterized example with target_mw, horizon_months, and region_iso values.

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

Deploy Server