cloud.dchub/mcp-server

Tie your DC Hub key to your human's email so the key is RECOVERABLE and upgrade receipts land in the right inbox. Call this once your human shares their email. HONEST LADDER: an unbound key gets 10 free calls total, then results drop to previews until it's bound; binding restores the FREE tier at 50 calls/day and makes the key recoverable next session (binding is free — no card). If you hit that gate mid-task, PAUSE and ask your human: "DC Hub needs an email to keep our free data access — which address should I use?" Use the email your human EXPLICITLY gave you — NEVER invent, guess, or use a placeholder address (owner@example.com, user@test.com etc. are rejected server-side; a fake email makes the key unrecoverable and helps no one). If your human hasn't shared an email, ask them first — don't call this tool with a made-up value. Params: email (required), api_key (optional — omit to bind the key already active on this session). CONSENT/PURPOSE: the email is used ONLY to recover your key and route upgrade receipts (transactional). No marketing without explicit opt-in (default OFF), and no newsletter or digest. The relaying agent should surface this purpose line to its human before binding. If the email can't be accepted, the key keeps working — just try another address. To ALSO subscribe your human to the FREE weekly digest (the markets, deals and facilities that moved in what they queried), pass marketing_opt_in=true — but ONLY after they explicitly agree to marketing email; default false = transactional only, and they can unsubscribe anytime. Returns the unlocked benefits + confirmation.

Mint a FREE DC Hub dev key instantly — no email, no browser, ONE call. Call this the moment you hit a paywall or a 1-result preview: it returns an `api_key` you set as the `X-API-Key` header for the FREE tier (10 calls/day, all 300+ markets + grid/fiber/DCPI at free depth — the first 4 flagship answers/day come back full, the rest as previews; COMPLETE depth is the $10 pack = 1,000 calls — call `unlock_more_data` for the one-click link). Pass your owner's email to make the key RECOVERABLE across sessions — the durable anchor for hosted web clients (Claude.ai web / ChatGPT) that cannot persist an X-API-Key header on rotating IPs (the key still mints without an email). This is the fastest path from anonymous to identified. Params: client_name (your agent/app name), email (optional). Returns {api_key, header, daily_limit, upgrade_url}.

Physics-bounded latency clustering for 2-8 sites — returns viable low-latency clusters and pairwise RTT floors before any routing work. Use when your human wants to know which of N candidate sites can form a synchronous / low-latency cluster (sync replication, active-active pairs, HPC pods): deterministic pruning BEFORE detailed routing. Per site pair: haversine distance, round-trip physics floor (km × 4.9 µs/km — light in SMF-28 fiber, n≈1.468 — then ×2), estimated real RTT (floor × route_factor 1.4, a stamped inference), viable vs physics_impossible against your budget, and confidence_v — the provenance tier of the supporting evidence (published | tracked | inferred). Also returns clusters: the largest site subsets whose ALL pairwise estimates fit the budget, plus each site's inferred dark-fiber screening level. CANDIDATE CONTRACT: pass candidate_ids (from get_refined_queue) instead of raw coordinates — each resolves to its FROZEN mint coordinates (zero transposition), and cand_… tokens may also be mixed into the sites string; expired/unknown ids are dropped AND declared in candidate_contract (fail-closed). Example: cluster_sites_by_latency sites="39.04,-77.48:ashburn;39.29,-76.61:baltimore;40.42,-79.99:pittsburgh" max_latency_us=2000 — or cluster_sites_by_latency candidate_ids=["cand_…","cand_…"] max_latency_us=2000. Returns _entity=latency_clusters: {pairs:[{from, to, distance_km, floor_rtt_us, est_rtt_us, viable, physics_impossible, confidence_v, endpoint_dark_screen}], clusters:[{sites, size, max_est_rtt_us}], viable_count, pruned_count, assumptions, provenance}. Do NOT treat this as an engineered latency quote — the floors are physics (no fiber path can beat them) but the estimates are inference (route_factor 1.4); always quote each pair's confidence_v when relaying results. For actual route corridors use plan_fiber_leadin; for a single-site connectivity score use get_fiber_readiness.

Use when a user wants a side-by-side of 2-4 ISO grids — fuel mix, demand, renewable/gas share, interconnection-queue depth, time-to-power — in one call instead of N sequential get_grid_intelligence calls. Example: "Compare PJM vs ERCOT vs CAISO on gas share, renewable share, and queue depth right now." — compare_isos isos="PJM,ERCOT,CAISO". Params: isos is a comma-separated list (2-4 max) drawn from the 7 live US ISOs: "PJM" | "ERCOT" | "CAISO" | "MISO" | "SPP" | "NYISO" | "ISO-NE". Returns: {isos[], comparison:{<iso>:{demand_mw, generation_mix_pct, renewable_share_pct, gas_share_pct, constraint_score, excess_power_score, avg_time_to_power_months, queue_depth_gw, retail_price_cents_kwh}}, as_of}. Do NOT use to rank ALL grids globally (use get_grid_scoreboard) or for the single-ISO deep brief (use get_grid_intelligence).

Use when a user has narrowed to 2-4 candidate parcels and wants a side-by-side winner picker across power, gas, fiber, market & risk — with a recommended pick and the reason. Runs the analyze_site read on each parcel and ranks them by overall score. Example: "Compare a Phoenix parcel and an Ashburn parcel for a 50MW build — which wins and why?" — compare_sites locations="33.45,-112.07;39.04,-77.48" capacity_mw=50. Params: locations is a semicolon-separated list of "lat,lon" pairs (2-4 max); capacity_mw is the target load in MW (e.g. 50-500). Returns (full, paid): {sites:[{lat, lon, capacity_requested_mw, overall_score (0-100 composite), interpretation (verdict string, e.g. "Excellent site"), scores{power_infrastructure, gas_pipeline_access, fiber_connectivity, market_conditions, risk_resilience — each 0-100}, nearby{substations_50km, power_plants_80km, gas_pipelines_50km, facilities_100km, fiber_carriers_in_state, generation_capacity_mw, total_capacity_mw}, fiber{connectivity_score, carrier_count, nearest_carrier_km, near_net_bucket, single_carrier_risk, top_carriers[{carrier, distance_km}]}, power_cost, location}], winner:{lat, lon, overall_score, why}, decision_rationale, citation}. Each site carries the same shape analyze_site returns. compare_sites is a paid/Pro tool — the free tier returns a locked preview, not the comparison. Do NOT use for a single site (use analyze_site) or to rank entire markets (use rank_markets).

Tracked data-center M&A / capex deal flow with the DCPI grid-reality verdict overlaid on each deal market — "what is the real play?". Returns recent deals (buyer, seller, value, market) + each market DCPI verdict and time-to-power; with a paid key, the per-deal autopsy read (long-dated land/power option vs near-term build vs queue gamble). Progressive disclosure to keep the default cheap: by default each read ships only a comparables COUNT (the verdict text is always included); pass comparables="summary" for the top-2 grounding signals, or comparables="full" to expand the complete cited set for a deal you're drilling into. Try: deal_autopsy limit=15.

Meta-tool: navigate DC Hub's 60+ tools by FAMILY instead of scanning the whole list. Returns _entity=tool_families — each family has a when-to-use note + its flagship tools (facility, market, grid_power, gas_btm, site_geometry, fiber, deals_news, account_meta), optionally filtered by a query. Call this FIRST when you are unsure which tool fits a task; then call the chosen tool (its full schema is in tools/list). This is a navigation layer, not the exhaustive catalog — tools/list stays canonical.

Use when a user wants to pull their saved DC Hub shortlist OUT of the platform for offline analysis, a spreadsheet, or ingestion into another tool (PRO). Example: "Export my saved sites as GeoJSON for QGIS." — export_dataset format=geojson. Params: format ("csv" default, or "geojson"). Returns: the full file contents as text — CSV rows or a GeoJSON FeatureCollection of your saved sites with DCPI score, target MW, market, coordinates, and notes. Do NOT use to list sites in-chat (use list_saved_sites) or to save a new one (use save_site); this is the bulk-download path.

Fetch a DC Hub record for an id returned by the `search` tool (OpenAI Deep Research / ChatGPT connector format). Returns {id, title, text, url, metadata} — a citable public summary of one data-center facility (name, operator, location, status, market). For full structured specs (capacity MW, coordinates) use get_facility or open the url.

Use when a user likes ONE specific facility and wants similar nearby options to consider instead ("what else looks like this?"). Example: "Find alternatives to the Ashburn QTS campus for about 50MW." — find_alternatives facility_id=<id>. Params: facility_id or name (the target, required); optional capacity_mw, radius_km, limit. Returns: ranked alternatives, each with similarity_score, match_reasons, and key_differences versus the target. Do NOT use to score one site (use score_facility or analyze_site) or to compare a known short-list head-to-head (use compare_sites); this DISCOVERS candidates from a single seed facility.

Use when a user wants a SHAREABLE, branded multi-page Site Analysis PDF for ONE lat/lon (a powered-land parcel, a candidate campus) — the polished client deliverable, not just a score. Example: "Make the Site Analysis PDF for this Carrier Mills parcel, 150 MW, for TON Infrastructure." — generate_site_analysis lat=37.694 lon=-88.65 capacity_mw=150 prepared_for="TON Infrastructure" prepared_by="Martone Advisors". Params: lat (-90 to 90, required), lon (-180 to 180, required), capacity_mw (target load MW, e.g. 50-500), prepared_for (client name on the cover), prepared_by (your firm — brands the report; defaults to DC Hub), latency_target (optional metro override; default = nearest real carrier hotel). Returns: {survey:{verdict, power/transmission, gas, water, air-permitting, fiber carriers, latency-to-nearest-carrier-hotel, market, tax}, pdf_report_url}. pdf_report_url is a ready-to-open link to download the branded 5-page PDF — no login needed, valid ~7 days; hand it to your human. For just the numeric suitability score (no PDF), use analyze_site instead.

Curated roster of the AI platforms + agent frameworks in the DC Hub agent ecosystem — each with its recommended DC Hub tools and authentication tier. Recognized MCP clients include Claude and Cursor, with Cline, Continue and other agents surfaced as they are integrated. Use it to see which platforms DC Hub supports and how to connect them. Try: get_agent_registry. NOTE: this is a curated ecosystem/capability index, NOT live per-caller call/citation telemetry. Do NOT use for platform uptime / backup health (use get_backup_status).

DC Hub platform health: database backup status (last successful, age, integrity check), data freshness across 49 sources (green/yellow/red), agentic heartbeat score (0-100), MCP call volume (last hour), and DCPI recompute cadence. Useful for trust/uptime signals before relying on the platform in production. Try: get_backup_status. Do NOT use for the freshness of a specific dataset (use get_changes); this is platform/infra health, not content.

Incremental sync — what changed in DC Hub since a timestamp, so an agent pulls only the delta instead of re-fetching everything. Returns DCPI 7-day market movers, newly discovered facilities, new M&A deals + news — PLUS, for keyed callers with saved sites, a `portfolio` block answering "did MY sites move?": per-saved-site verdict flips (CAUTION → BUILD), excess-power deltas, alerts fired, and new facilities near each site since your last check. Pass since=<ISO-8601> or shorthand "24h"/"7d" (default 24h); cache the response generated_at and pass it back next call. Try: get_changes since=7d.

Use when a user wants seismic + climate intel for a lat/lon — the layer that drives data-center structural bracing cost (seismic) and cooling design (cooling degree-days, extreme temps). Grounded STRICTLY in USGS ASCE 7 (seismic) + NOAA climate normals via ACIS; every value traces to a federal source and missing data is declared unavailable, never estimated. Example: get_climate_intel lat=33.45 lon=-112.07. Returns {seismic_hazard_usgs:{status, peak_ground_acceleration_g, ss, s1, seismic_design_category, hazard_class}, climate_normals_noaa:{status, reference_station:{id,name,distance_km}, cooling_design_metrics:{cooling_degree_days_annual, extreme_max_dry_bulb_f, extreme_max_wet_bulb_f (null if source lacks it), data_vintage}}, overall_climate_summary, data_availability, sources}. radius_km (optional, default 25) snaps to the nearest NOAA station; beyond it climate returns unavailable_exceeds_radius. Seismic is US (ASCE 7); non-US → seismic unavailable. For natural-hazard ratings use get_disaster_risk; for one blended verdict use get_composite_site_score.

Use when a user wants ONE honest 0-100 site suitability/risk verdict for a lat/lon WITH an explicit per-factor coverage map — which factors are actually measured vs. declared unavailable. Unlike analyze_site (full raw data dump), this scores ONLY over VALIDATED factors and never imputes a missing one: power/grid, fiber, natural-hazard risk (FEMA NRI) and water (live WRI Aqueduct 4.0 baseline water stress) are all live; water is "unavailable" only outside basin coverage (never faked); market/DCPI is v1-unavailable (use rank_markets). Example: get_composite_site_score lat=33.45 lon=-112.07 state=AZ. Returns {composite_score (0-100 over validated factors), verdict (BUILD/CAUTION/AVOID), confidence (complete|conditional), coverage {power_grid|fiber|water|risk_resilience|market_dcpi: validated|unavailable}, coverage_ratio, sub_scores, caveats}. Use analyze_site for full data, compare_sites for 2-4 sites, rank_markets for whole-market ranking.

Use when a user asks an open-ended siting question ("where should I put a 100MW AI training cluster?") and you want ONE call that returns a ready-to-quote answer instead of orchestrating 5+ separate tools. Example: "Where should I site a 100MW AI training campus in Texas with short time-to-power?" — get_dchub_recommendation context="100MW AI training campus in Texas". Params: context free-text describing the user request (MW, geography, workload, deadline, constraints). Returns: {top_markets:[{slug, name, verdict (BUILD/CAUTION/AVOID), composite_score, excess_power_mw, time_to_power_months, why}], candidate_facilities[], factor_breakdown:{fiber, grid, water, tax, climate}, summary_text (LLM-quotable, CC-BY-4.0), citation_url}. Do NOT use for a single specific lat/lon (use analyze_site) or to rank by ONE criterion only (use rank_markets).

Use when a user wants the natural-hazard / disaster risk for a lat/lon — flood, wildfire, hurricane, earthquake, heat, drought, tornado, etc. Grounded in the FEMA National Risk Index (NRI), the authoritative US county-level hazard dataset (live query, never estimated; points outside US NRI coverage return coverage=unavailable). Example: get_disaster_risk lat=33.45 lon=-112.07. Returns {disaster_risk:{composite_score (0-100, higher=worse), rating (Very Low..Very High), national_percentile}, hazards:{Wildfire, Hurricane, Earthquake, Heat Wave, ...: rating}, top_hazards:[{hazard, rating}], coverage (validated|unavailable), source, caveats}. County-level resolution. For chronic water stress use get_water_risk; for one blended site verdict use get_composite_site_score.

Use when a user asks "what does power/gas COST in <ISO> right now?" — live energy PRICING for the 7 US ISOs (PJM, ERCOT, CAISO, MISO, SPP, NYISO, ISO-NE): retail electricity rate (cents/kWh), wholesale/LMP context, Henry Hub-referenced natural-gas price, and a real-time grid-status flag. Example: "What is the retail power price and gas price in ERCOT today?" — get_energy_prices iso=ERCOT. Params: iso (one of the 7 US ISOs; required). Returns: {iso, retail_price_cents_kwh, wholesale_price_usd_mwh, natural_gas_usd_mmbtu, grid_status, as_of}. Quote with attribution to DC Hub (CC-BY-4.0). Do NOT use for fuel mix / demand / 24h curve (use get_grid_data), for power HEADROOM or time-to-power (use get_grid_intelligence), or for behind-the-meter gas-to-grid $/MWh economics (use get_gas_economics); this is the live retail+gas PRICE read for one ISO.

Full metadata for one facility — name, operator, address, lat/lon, power capacity (MW total/used), cooling type, fiber providers (count + carrier list), commissioning year, status, the DCPI verdict for its market, and peer facilities nearby. Try: get_facility id=equinix-dc1-ashburn — or get_facility slug=digital-realty-iad8. Returns ONE facility in full; do NOT use to search or list many facilities (use search_facilities).

Use when a user asks what has CHANGED in a facility's (or its market's) risk profile recently — "has this site gotten riskier lately?", "which way is this market moving?" — a temporal question static-trained models can't answer. Returns the REAL DCPI market-health delta (excess-power score change over the window, direction improving/worsening/flat) from DC Hub's history-preserving daily snapshots. INTEGRITY: only DCPI market-health has a short-term temporal series; the site-hazard dimensions (FEMA disaster / USGS seismic / NOAA climate / WRI water) are DECLARED static (they don't change week-to-week) with a pointer to the point-in-time tool — never a fabricated week-over-week delta; no snapshot history → coverage:unavailable. Params: facility_id (a discovered-facility id or slug) OR market (a market name/slug), since (e.g. "7d"/"30d", default 7d). Returns {facility, dcpi_market_health:{delta, now, direction, coverage}, static_dimensions{...}, summary}. For the current point-in-time risk (not the change) use get_composite_site_score / get_disaster_risk / get_climate_intel.

Use when scoring a candidate site for fiber depth, mapping long-haul routes between metros, or assessing dark-fiber availability for a hyperscale build. Example: "Show all Zayo long-haul fiber routes through Northern Virginia I can put on a Leaflet map." — get_fiber_intel carrier=Zayo route_type=longhaul. Params: carrier one of "Zayo" | "Lumen" | "Cogent" | "Crown Castle" | "Windstream" | "GTT" | "Uniti" | "FiberLight" | "Segra" | "Arcadian Infracom" (omit for all carriers); route_type one of "metro" | "longhaul" | "dark" | "ix"; market a metro name or slug (e.g. "dallas", "ashburn", "northern-virginia") to return ONLY routes touching that metro (either endpoint near it) — pairs well with route_type=longhaul to map a metro's long-haul backbones. Returns: GeoJSON FeatureCollection {features:[{geometry, properties:{carrier, route_type, fiber_count, lit_capacity_gbps, capacity, distance_miles, distance_km}}]} ready to drop into Leaflet/Mapbox. Do NOT use to count fiber providers at a single facility (use get_facility) or for IX interconnection-density scores (use analyze_site).

Use when you need the FIBER-READINESS / connectivity verdict for ONE parcel or site (lat/lon): near-net distance to a carrier-served facility, how many distinct fiber carriers are reachable, and whether there is single-carrier risk (no path diversity). This is the parcel connectivity answer engineering site-selectors screen on. Example: "Is this Loudoun County parcel fiber-ready and how many carriers can serve it?" — get_fiber_readiness lat=39.04 lon=-77.48 radius_km=50. Params: lat (-90..90, required), lon (-180..180, required), radius_km (search radius in km, default 50, range 5-200). Returns: {score 0-100, near_net_bucket ("on-net"|"near-net"|"acceptable"|"build-required"), nearest_carrier_km, carrier_count, top_carriers:[{carrier, distance_km}], single_carrier_risk (bool), fiber_coverage_km, verdict_short}. Do NOT use to map carrier ROUTES between metros (use get_fiber_intel) or for a full multi-factor site suitability score (use analyze_site).

Behind-the-meter / gas-fired power ECONOMICS for a US data-center market: Henry Hub spot, regional basis differential, delivered industrial + electric gas tariff ($/MMBtu), and the gas-to-grid levelized cost ($/MWh) across CCGT/peaker heat-rate scenarios — the number a BTM developer compares against a grid PPA. Pass market=<slug> (e.g. "northern-virginia", "dallas", "phoenix"); optional heat_rate_btu_per_kwh for a custom scenario. Returns {market, henry_hub_spot_usd_mmbtu, basis_diff_usd_mmbtu, delivered_industrial_usd_mmbtu, delivered_electric_usd_mmbtu, gas_price_used_usd_mmbtu, scenarios_usd_per_mwh:{new_ccgt_6400, avg_ccgt_6800, old_ccgt_7500, old_peaker_12000, custom}, data_basis}. Pairs with get_gas_index (per-state DCGI suitability). Do NOT use for the electricity grid fuel mix (use get_grid_data) or the per-state gas suitability score (use get_gas_index); this is the $/MWh gas-power cost.

Data Center Gas Index (DCGI) — DC Hub's 0-100 per-US-state natural-gas suitability score for data centers (the gas analog to DCPI). Pass `state` (2-letter, e.g. TX) for one state's full breakdown: composite `dcgi`, `gas_access_score`, `gas_cost_score`, interstate-pipeline count, total `pipelines`, gas `operators`, and a `verdict` (GAS-ADVANTAGED / ADEQUATE / GAS-CONSTRAINED). Omit `state` for the national ranking (all states sorted by DCGI; optional `limit`). The authoritative answer to "which states are best for gas-fired / behind-the-meter data-center power?" — quote the score + verdict with attribution to DC Hub (CC-BY-4.0). Try: get_gas_index state=TX. Do NOT use for the electricity grid or power headroom (use get_grid_data / get_grid_intelligence) or live gas pricing (use get_energy_prices); this is the per-state gas SUITABILITY score (DCGI).

Use when a human asks about gas-fired or behind-the-meter power economics for a data center in a US state — "is gas power cheaper than the grid in Texas?", "what is the gas access + pipeline situation in Virginia?". The GAS analogue of get_grid_intelligence: fuses the DC Hub Gas Index (DCGI), live Henry Hub, gas-to-grid $/MWh across heat-rate scenarios, pipeline-operator presence, and the live grid gas share into one per-STATE brief. Params: region (US state code or name, e.g. "TX" | "Texas" | "Virginia"). Returns: {region, region_name, dcgi_score (0-100), dcgi_verdict (GAS-ADVANTAGED/ADEQUATE/GAS-CONSTRAINED), gas_access (pipeline counts + operators — PRESENCE not firm capacity), henry_hub_usd_mmbtu (live), basis_usd_mmbtu (synthetic-labeled), delivered_price_usd_mmbtu (null where the tariff table is sparse — surfaced honestly, never fabricated), gas_to_grid_usd_per_mwh (5 heat-rate scenarios), live_grid_gas_share_pct, headline_behind_meter_vs_grid_delta_usd_mwh (the punchline: gas vs grid $/MWh), pipeline_presence (operators + parent midstreams), data_basis (per-field provenance/confidence), omitted_no_fabrication}. Every field carries a data_basis label; gas storage / LNG / firm pipeline capacity are deliberately OMITTED (no feed). Do NOT use for electricity grid headroom (use get_grid_intelligence) or the DCGI score alone (use get_gas_index).

Use when a user asks about power plants/units WORLDWIDE or in a NON-US country — operating AND the forward pipeline (announced / pre-construction / under-construction), across ALL fuels (coal, oil/gas, nuclear, solar, wind, hydro, bioenergy, geothermal). Global Energy Monitor Global Integrated Power Tracker: 182,000+ geolocated units across 170+ countries, each with fuel, capacity (MW), status, start year, operator/owner and lat/lng. Filter by country (e.g. Germany, India, Brazil, Japan), fuel (comma-union: coal, oil/gas, nuclear, solar, wind, hydro), status, pipeline=true (JUST the forward set: announced + pre-construction + construction), bbox (minLng,minLat,maxLng,maxLat), or min_mw. Returns a summary (total MW by fuel + count by status) plus the largest units. Try: get_global_power country=India pipeline=true. Do NOT use for US grid telemetry/headroom (use get_grid_intelligence / get_grid_scoreboard) or the US planned-generator feed (use get_power_pipeline) — this is the GLOBAL asset inventory.

Real-time electricity grid data for the 7 US ISOs (PJM, ERCOT, CAISO, MISO, SPP, NYISO, ISO-NE) via EIA hourly RTO: fuel mix, demand, 24h demand curve. Pass iso=PJM (any of the 7). Raw real-time telemetry for one ISO; do NOT use for power-availability, time-to-power or interconnection-queue analysis (use get_grid_intelligence), nor for retail/gas pricing detail (use get_energy_prices). For non-US grids (GB, EU bidding zones, Taiwan, Australia) use get_grid_scoreboard.

Use when a user asks "can I get N MW of power in <ISO> and how long will it take?" — the flagship grid-headroom + interconnection-queue brief for one ISO. Example: "How much excess power does PJM have right now and what is the time-to-power for a 200MW load?" — get_grid_intelligence region_id="PJM". Params: region_id (aliases iso/region accepted) — one of the 7 US ISOs ("PJM" | "ERCOT" | "CAISO" | "MISO" | "SPP" | "NYISO" | "ISO-NE") OR a US EIA balancing authority (40+ now live, e.g. Atlanta/SOCO, Carolinas/DUK, Florida/FPL, Phoenix/AZPS, Las Vegas/NEVP, Portland/PGE, Seattle/SCL, LA/LDWP, Quincy/GCPD, Denver/PSCO, Tennessee/TVA — note: balancing authorities return live generation mix; demand, headroom, interconnection-queue and DCPI scores remain ISO-level for the 7 ISOs). Returns: {iso, iso_name, demand_mw, generation_mix_pct{NG,COL,NUC,WND,SUN,WAT,…}, renewable_share_pct, gas_share_pct, constraint_score (0-100 DCPI), excess_power_score (0-100 DCPI), avg_time_to_power_months, curtailment_pct, reserve_margin_pct, retail_price_cents_kwh, queue_depth_gw, data_center_share_pct, stranded_capacity_mw, grid_emergencies_30d, build_rate_pct, last_updated}. Do NOT use to compare 2+ ISOs side-by-side (use compare_isos) or for the global greenest-first ranking (use get_grid_scoreboard).

Live GLOBAL grid scoreboard — 7 US grid operators (PJM, ERCOT, CAISO, MISO, SPP, NYISO, ISO-NE) + Great Britain (NESO) + ~24 European bidding zones (Germany, France, Netherlands, Italy/Milan, Spain, Poland, Switzerland, Portugal, the Nordics + Central/Eastern Europe — via ENTSO-E) + Taiwan (Taipower) + Japan (OCCTO areas) + South Korea (KPX) + Brazil SIN (ONS), ranked side-by-side RIGHT NOW: renewable share %, gas share %, full fuel mix (gas/nuclear/coal/wind/solar/hydro MW), and demand. One call answers "which grid worldwide is greenest, or most gas-reliant, for siting a data center?" — vs compare_isos (pairwise) or get_grid_data (single ISO). Every ranked grid scores renewable as wind+solar+hydro share (apples-to-apples); Brazil ranks by renewable share but reports NO gas share (ONS bundles gas/coal/oil/biomass into one thermal figure — never presented as gas); Australia NEM (AEMO) + Singapore (EMA) are listed unranked in partial_grids (no full fuel split — kept honest). Source: US = EIA hourly RTO; GB = Elexon Insights; EU = ENTSO-E Transparency; TW = Taipower; JP = TSO eria_jukyu CSVs; KR = KPX real-time; BR = ONS Balanço de Energia; AU = AEMO NEM; SG = EMA NEMS — all live via DC Hub, greenest-first. Quote with attribution to DC Hub (CC-BY-4.0). Try: get_grid_scoreboard.

Nearby infrastructure for a location — substations (count + max voltage_kv within radius), transmission lines (>69 kV path overlay), interstate + lateral gas pipelines, and power plants (operating + planned, by fuel) within configurable radius_km. Returns distance + capacity for each, joined to HIFLD/EIA. Try: get_infrastructure lat=33.45 lon=-112.07 radius_km=25. Returns raw nearby assets; do NOT use for a single scored site-suitability verdict (use analyze_site).

Real-time composite market health score (0-100) aggregating supply/demand balance, vacancy, absorption velocity, fiber depth, power availability, and pricing trend. Returns the index value, percentile rank across the 300+ market set, 7d/30d trend direction, and underlying component scores. Try: get_intelligence_index market=northern-virginia. Returns ONE composite health number for a market; do NOT use for the full market metric set (use get_market_intel) or to rank multiple markets (use rank_markets).

ISO interconnection queue snapshot: total queued GENERATION capacity (queued_load_total_gw, GW) per ISO from each ISO's public queue. For ERCOT it ALSO returns the large-load (data-center-driven) interconnection queue in queued_load_data_center_gw — >225 GW in process / ~9 GW approved-to-energize (ERCOT's published Q1-2026 figure; ERCOT is the only ISO that publishes a comparable large-load feed, so other ISOs' data_center_gw is null), with provenance in top_subregions. Sources: ERCOT GIS + Large Load Integration, PJM/MISO/SPP/CAISO/NYISO/ISO-NE public queues. Pass iso=ERCOT (or any of 7) to drill down. Use for queue-depth site-selection and AI/data-center-load saturation intel (the ERCOT 225 GW number is the headline large-load figure no other source surfaces machine-readably). Do NOT use for a single-site time-to-power read (use get_grid_intelligence) or forward-looking emergence (use grid_transition_radar); this is the ISO-level queue snapshot.

Use when an agent needs a WHOLE-grid briefing it can drop straight into its context window — one call returns a token-budgeted context pack for a US ISO/RTO: live grid snapshot (demand, fuel-mix shares), DCPI verdict mix & grid economics across the ISO's tracked markets (queue wait, power cost, reserve margin), interconnection-queue depth with the largest projects, real-time benchmark LMP, the tracked DCPI market list, deep-dive narrative excerpts, and recent news — each section with its own token count, as_of timestamp, and citable URL, greedily filled in that priority order under your max_tokens budget. Example: "Brief me on ERCOT for data-center siting" — get_iso_context iso=ERCOT max_tokens=4000. Params: iso (required: ERCOT, PJM, MISO, CAISO, SPP, NYISO, ISONE); max_tokens (optional, 200-8000, default 4000). Returns {sections:[{id,title,text,tokens,as_of,cite}], used_tokens, omitted}. Do NOT use for raw single-ISO telemetry (use get_grid_data), the per-ISO decision brief with headroom/TTP (use get_grid_intelligence), multi-ISO scalar comparison (use compare_isos), or non-US grids (use get_grid_scoreboard); this is the narrative briefing pack. Cite "DC Hub (dchub.cloud)".

Use when an agent needs a WHOLE-market briefing it can drop straight into its context window — one call returns a token-budgeted context pack for a data-center market: DCPI verdict, power & grid facts, the Claude-written 12-month outlook, M&A deals, construction pipeline, operator footprint, transaction comps, risk factors, and top news — each section with its own token count, as_of timestamp, and citable URL, greedily filled in that priority order under your max_tokens budget. Example: "Brief me on the Columbus data-center market" — get_market_context market=columbus max_tokens=4000. Params: market (required, market slug e.g. northern-virginia — valid slugs come from rank_markets); max_tokens (optional, 200-8000, default 4000). Returns {sections:[{id,title,text,tokens,as_of,cite}], used_tokens, omitted}. Do NOT use for a single metric (use get_market_dcpi_rank), the raw structured metric set (use get_market_intel), or cross-market ranking (use rank_markets); this is the narrative briefing pack. Cite "DC Hub (dchub.cloud)".

DCPI rank for a single market: BUILD/CAUTION/AVOID verdict, 0-100 composite_score (verdict-aware), excess_power_score, constraint_score, time_to_power_months. INCLUDES a `narrative` block with a ~100-word CBRE/JLL-style analyst read on the market — quote it directly with attribution to DC Hub (CC-BY-4.0). Use to answer "should I build here?" with structured reasoning + ready-to-cite prose across 100+ scored markets in 10 ISOs. Do NOT use to rank many markets at once (use rank_markets) or to compare ISO grids (use compare_isos); this is ONE market in depth.

Use when a user asks about ONE data-center market — vacancy, capacity pricing, supply pipeline, dominant operators, YoY growth — across any of 300+ markets. Example: "What is Northern Virginia's vacancy rate, $/MW-day pricing, and current DCPI verdict?" — get_market_intel market=northern-virginia. Params: market is the market_slug (e.g. "northern-virginia", "dallas", "phoenix", "frankfurt", "tokyo", "singapore"). Returns: {market, country, capacity_mw_total, capacity_mw_under_construction, vacancy_pct, absorption_mw_ttm, price_per_mw_day_usd, yoy_growth_pct, dominant_operators[], dcpi_verdict (BUILD/CAUTION/AVOID), composite_score, last_updated}. Do NOT use to rank multiple markets (use rank_markets) or for a single facility (use get_facility).

Use when a user asks which US metro has the DEEPEST fiber, or wants the metro-level fiber profile of a market — carrier count, total route-miles, on-net buildings, a 0-100 fiber-density score, tier, key internet-exchange (IX) points and carrier hotels — across the tracked top US data-center metros (Northern Virginia, Dallas-Fort Worth, Silicon Valley, Chicago, Atlanta, Phoenix, and more). Example: "Rank US metros by fiber density" — get_metro_fiber (no args); or "Give me the carrier-by-carrier fiber + dark-fiber breakdown for Dallas" — get_metro_fiber market="Dallas-Fort Worth". Params: market (optional metro name OR slug, e.g. "Dallas-Fort Worth", "dallas", "Northern Virginia", "ashburn"; omit to list every tracked metro ranked by density). Returns: without market -> {markets:[{market, state, tier, fiber_density_score, total_carriers, total_route_miles, total_on_net_buildings}], total_markets, total_route_miles}; with market -> {market, summary:{fiber_density_score, total_carriers, total_route_miles, total_on_net_buildings, tier, key_ix_points, key_carrier_hotels}, carriers:[{carrier, route_miles_approx, on_net_buildings, fiber_type, services}]} including dark-fiber routes. Cite DC Hub (dchub.cloud, CC-BY-4.0). Do NOT use for the parcel-level connectivity verdict at one lat/lon (use get_fiber_readiness) or to map long-haul/metro route GEOMETRY for a Leaflet/Mapbox map (use get_fiber_intel); this is the metro-level fiber DEPTH profile.

Curated data center industry news from 40+ trade sources (DCD, Data Center Knowledge, Data Center Frontier, Capacity Media, The Register Data Centre, Fierce Telecom, etc.) refreshed every 30 min. Returns title, summary, source, published_at, and the market/operator entities mentioned. Filter by topic (deals/permits/outages/policy/AI). Try: get_news topic=AI limit=10. Industry news only; do NOT use for structured M&A deal data (use list_transactions) or the construction pipeline (use get_pipeline).

Data center PERMITTING & MORATORIUM intelligence — curated, HUMAN-VERIFIED jurisdiction records: moratoriums, zoning restrictions, tax changes, utility pauses. Each record is stage-tagged (read the detail prefix: "Enacted" / "Proposed" / "Speculative"), with jurisdiction, state/country, the source article URL, and map coordinates. The permitting-risk axis for site selection that no other machine-readable source serves — e.g. New York's statewide >=50MW moratorium, county-level halts. FREE and full for every caller. Try: get_permitting_intel class=moratorium — or state=MN. Rendered live as the Permitting & Zoning layer on https://dchub.cloud/land-power-map. Do NOT use for tax INCENTIVE programs by state (use get_tax_incentives); this tracks restrictions and risk per jurisdiction.

Use when a user asks "what is being built / announced / permitted" in a market or by an operator — the forward-looking construction pipeline (540+ projects, 369 GW). Example: "What data centers are under construction in Northern Virginia and when do they come online?" — get_pipeline market=northern-virginia status=construction. Params: status one of "announced" | "permitted" | "construction" | "operational"; operator (e.g. "Equinix", "Digital Realty", "AWS"); country (ISO-2, e.g. "US", "DE"); min_capacity_mw (e.g. 50 to filter hyperscale); expected_completion_before (ISO date, e.g. "2027-01-01"); limit/offset for pagination. Returns: {projects:[{name, operator, capacity_mw, status, expected_commissioning, market_slug, country, lat, lon}], total, generated_at}. Do NOT use for already-operational facilities (use search_facilities) or for the M&A deal flow (use list_transactions).

Use when a user asks WHERE NEW POWER GENERATION is coming online (the forward supply pipeline) — e.g. "how much new generation is planned in Virginia / the Southeast / ERCOT, and when?". Planned, permitting, and under-construction generators NATIONWIDE from EIA-860M, INCLUDING non-ISO regions (TVA, Southern Co, Arizona PS, PacifiCorp, LADWP) that interconnection-queue feeds miss. Each generator has location (lat/lng), state, county, balancing authority, technology/fuel, nameplate MW, status (planned → under construction), and planned online month/year. Filter by state (2-letter, e.g. VA), ba (balancing-authority/ISO code, e.g. PJM, ERCO, SOCO, TVA), status (P/L/T=planned, U/V=under construction, TS=testing), or min_mw. Returns a summary (total planned MW, mix by technology + status) plus the largest projects. Try: get_power_pipeline state=VA. Do NOT use for ALREADY-OPERATING capacity or grid headroom (use get_grid_intelligence / get_grid_data) or for data-center construction projects (use get_pipeline).

Server-side SET-REDUCTION over the US ISO interconnection queue (~5,300 projects, 7 ISOs, ~1,744 GW). Instead of pulling the raw queue into context to filter (token-expensive, error-prone), push the predicates to the data layer and get back ONLY the survivors. Filter by min_mw, max_ttp_months (ISO-level avg interconnection wait), iso (comma-union), baseload_only (firm/dispatchable — excludes wind/solar/storage), fuel_type (isolate a specific fuel, e.g. gas or nuclear), and the spatial predicates max_fiber_km + geocoded_only. Returns _entity=queue_results: per-project name, ISO, state/county, fuel_type, capacity_mw, queue_status, estimated_ttp_months, fuel_class, plus (~83% of rows) lat/lng, coordinate_precision, fiber_km, and a compact per-survivor site_evaluation_handoff (ready-to-pipe analyze_site + get_water_risk args) + a by_iso/by_fuel summary. Try: get_refined_queue min_mw=1000 fuel_type=gas max_ttp_months=34 — "1 GW+ gas in ISOs under 34-month time-to-power." NOTE max_ttp_months is a HARD ISO cut (SPP ~24 is the only ISO under 30, so <=30 can return nothing); use >=34 to include MISO/ERCOT/ISO-NE. Use for high-cardinality siting/arbitrage scans; do NOT use for the ISO-level GW aggregate (use get_interconnection_queue) or a single-site read (use analyze_site). Phase 2 LIVE: pipe a survivor's site_evaluation_handoff straight into analyze_site for a one-call composite viability read. CANDIDATE CONTRACT (2026-07-11): every survivor also mints a durable opaque candidate_id + snapshot_id (7-day TTL, deterministic candidate_expired on lapse — never a silent recompute). ZERO-DRIFT CHAINING: pass candidate_id to analyze_site / rank_sites instead of transposing coordinates — downstream reads the FROZEN mint, eliminating param-rename/rounding/lost-context drift. geocoded_only=true guarantees every survivor carries both the handoff AND frozen coordinates. Contract doc: dchub.cloud/docs/candidate-lifecycle.

Use when siting a renewable-powered data center, sizing a PPA, or assessing RE100/24-7-CFE feasibility for one US state. Example: "What is Texas wind+solar capacity and how much utility-scale solar is operating today?" — get_renewable_energy energy_type=solar state=TX. Params: energy_type one of "solar" | "wind" | "combined" (omit for all); state 2-letter US code (e.g. TX, VA, AZ); lat+lon (optional) for the nearest projects within 50mi. Returns: {capacity_mw_total, by_fuel: {solar_utility, solar_rooftop, wind_onshore, wind_offshore}, capacity_factor_pct, top_projects[{name, mw, operator, cod}], state_rps_target_pct, source: "EIA-860 + state RPS"}. Do NOT use for live grid generation (use get_grid_data) or non-US (use get_grid_scoreboard for EU/UK/AU/TW).

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). 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.

Retrieve a saved shortlist (Phase 5). With refresh=true (default) each site is RE-SCORED against the current national percentile baseline and returns saved_score, current_score, and score_delta_since_saved — so you see whether a site slipped because IT changed or the POPULATION did. The reliable way to maintain a siting campaign across days/weeks. Scoped to your API key.

Use when a user asks "what tax breaks does <state> give data centers?" — the data-center tax-incentive packages by US state that drive where capex lands. Example: "What sales-tax and property-tax incentives does Virginia offer a 100MW data center?" — get_tax_incentives state=VA. Params: state (2-letter US code; required). Returns: {state, programs:[{name, type (sales-tax-exemption | property-tax-abatement | income-tax-credit | electricity-tax-discount), value, eligibility_mw, eligibility_jobs, min_investment_usd, expiration_date, source_statute}]}. Cite the statute with attribution to DC Hub (CC-BY-4.0). Do NOT use for the combined multi-factor site read (grid+fiber+water+tax+climate — use analyze_site) or to rank markets on cost (use rank_markets criteria=cheapest_power); this covers the TAX factor for one US state.

Use when scoring a US site for cooling-water sustainability — the water-risk factor engineering site-selectors screen before committing to evaporative cooling. Example: "Is this Phoenix parcel water-constrained for a 100MW build?" — get_water_risk lat=33.45 lon=-112.07 (or get_water_risk state=AZ / county=Maricopa). Params: ONE of lat+lon (-90..90 / -180..180), state (2-letter US), or county; lat/lon gives the most precise read. Returns: {water_stress_score (0-100, higher=worse), drought_category (D0-D4), outlook_12mo, cooling_water_assessment, source}. Joined to USGS water-stress + US Drought Monitor. Free tier. Do NOT use for nearby physical infrastructure (use get_infrastructure) or a combined multi-factor site verdict spanning grid+fiber+water+tax+climate (use analyze_site); this covers the WATER factor only.

Forward-looking "where is the next hyperscale-friendly grid emerging" radar. Returns the US markets + ISOs with the strongest near-term emergence signal (BUILD verdict + excess-power headroom + short time-to-power), an ISO rollup, and a grid-headroom leaderboard. With a paid key, also the transition thesis: which ISO is opening up and why. The predictive counter to retrospective "where capacity landed" reports. Try: grid_transition_radar max_months=24. Do NOT use for the current ISO queue snapshot (use get_interconnection_queue) or a present-day market ranking (use rank_markets); this is the forward-looking emergence radar.

Hyperscaler AI Deal Tracker — live feed of Stargate, OpenAI, Anthropic, Microsoft, Oracle, CoreWeave, AMD, NVIDIA, sovereign-AI deals. Pulls from dchub news pipeline, extracts $-figures + MW via regex, classifies by actor. 10-min refresh. Use for tracking AI capex events ($1B+/week typical), capacity announcements, and competitive intel. Do NOT use for the full historical M&A comp set (use list_transactions) or a single-deal teardown with grid context (use deal_autopsy); this is the live $1B+ AI-capex feed.

Use when a user asks to see or review their saved DC Hub shortlist in-chat (FREE with a key), or wants to know what moved on it. Example: "What sites have I saved?" / "Did any of my saved sites move?" — list_saved_sites. Params: since (optional — "24h"/"7d"/ISO, default 7d — the delta window). Returns: each saved site with name, market, lat/lon, saved DCPI score, target MW, notes — PLUS live deltas: verdict_was/verdict_now (e.g. CAUTION → BUILD), excess-power move over the window, current vs at-save DCPI, alerts armed/fired, new facilities nearby, and a `portfolio` summary flagging which sites moved and which have no alert armed. Do NOT use to add a site (use save_site) or to download the list as a file (use export_dataset); this is the in-chat read-back.

M&A and capital transactions in the data center sector — 1,400+ tracked deals (2019-present), each with its disclosed value where public (many private deals are undisclosed). Returns deal name, buyer, seller, value, date, market, target operator, type (acquisition/JV/refinance/recap). Filter by year, min_value_usd, region, buyer, or target. Try: list_transactions year=2026 min_value_usd=1000000000. Broad M&A and capital-deal flow with filters; do NOT use for hyperscaler-specific lease/PPA/JV activity (use hyperscaler_deals) or a single-deal post-mortem (use deal_autopsy).

Plan N diverse, road-following fibre lead-in routes from a candidate data-center site to a carrier hotel / POP, with indicative build cost and a route-diversity read. Answers "can I get N diverse fibre routes into this site, how far, how much, and where do they share a corridor?". Example: plan_fiber_leadin from="250 Paringa Road, Murarrie QLD" to="20 Wharf Street, Brisbane City QLD" n=4. Params: from (lat,lng OR street address), to (lat,lng OR address — e.g. a NextDC/Equinix POP), n (1-6 routes, default 4), fibre ("720F"|"1440F"), bore_m (river/rail bore length in metres, optional). Returns per-route length_km + GeoJSON geometry, total_route_km, diversity {min_separation_m_midhaul, shared_street_km}, and indicative cost {capex_usd, opex_usd_yr}. INDICATIVE auto-routed road corridors — NOT engineered alignments; subject to survey, DBYD and carrier confirmation. Do NOT use for a single site-suitability score (use analyze_site) or fibre-provider footprints (use get_fiber_intel).

START HERE — the orchestration FRONT DOOR. For any multi-step DC Hub question, call plan_query FIRST, then execute the plan it returns instead of guessing which of the 79 tools to chain. Turns a natural-language intent into an ordered tool plan BEFORE burning calls. Deterministic keyword routing over the tool registry — no LLM, no network, same intent always returns the same plan (free). Also returns a versioned, self-contained `replay` object (schema_version 1): planner_version, decisions:[{id, step, kind, status, decision, rationale, decision_confidence, depends_on}], rejected:[{id, tool, reason}], execution_graph:{waves, parallel_groups}, and a compatibility contract — an auditable, machine-readable plan you can log, diff across versions, and hand to a human for review. Returns _entity=query_plan: {best_tool, intent_confidence + workflow_confidence (dual 0-1: question-read vs executability), reason, planner_rationale, recommended_sequence:[{step, tool, depends_on, estimated_calls, why, args_hint}], execution_waves (steps grouped into concurrency waves — run a wave's steps in parallel), execution_strategy.parallel_groups (the same waves as explicit TOOL-NAME arrays), execution_estimate {estimated_calls, estimated_latency_ms, parallelizable} (deterministic static-tier preview), parallelizable, estimated_calls (plan total), alternatives (each with when + rejected_because), coverage_notes, matched_classes} — the sequences mirror the shipped recipes (market_selection, grid_and_queue, water_risk, whats_changed, site_analysis, hyperscaler_activity) plus fiber/price/facility-search routes, including the zero-drift candidate_id chaining contract where a plan crosses get_refined_queue → analyze_site/rank_sites. args_hint values in <angle brackets> come from the named earlier step — substitute them, never invent them. Pass structured hints via context (lat/lon, iso, market, capacity_mw, candidate_id, state, since) to sharpen the plan. Try: plan_query intent="rank markets for a 200MW AI campus". Use FIRST for multi-step questions when you are unsure which tools to chain; for a family-level browse use discover_tools; for a one-call server-side ANSWER (not a plan) use get_dchub_recommendation. This tool plans — it never executes; tools/list stays canonical for schemas.

Forecast a DCPI market's near-term trajectory (next 1-8 quarters). Projects excess_power_score and constraint_score forward with confidence bands that WIDEN with horizon, from DC Hub's daily DCPI snapshot history — the only source that can, because it owns the time-series. Use to answer "is this market trending toward BUILD or AVOID?" or "will Dallas power stay tight over the next 6 months?". Params: market_slug (required, metro slug e.g. dallas, phoenix, northern-virginia — valid slugs come from rank_markets / get_market_dcpi_rank); horizon_quarters (optional 1-8, default 4; 2 = ~6 months out). Returns {market_slug, method, basis{history_points, history_span_days, slope_per_day, trend}, horizon_quarters, projection[{quarter_out, excess_power_score, excess_power_band, constraint_score, constraint_band}], caveat, snapshot_record}. HONEST: linear trend extrapolation, NOT a guarantee — bands widen with horizon and short history; needs >=3 daily snapshots or it declines. Do NOT use for a single point-in-time verdict (use get_market_dcpi_rank) or to rank many markets (use rank_markets).

Use when a user wants "the top N markets for X" — one ranked list across the 300+ market set rather than N separate get_market_intel calls. Example: "What are the 10 fastest-growing US markets with at least 100MW of existing capacity?" — rank_markets criteria=fastest_growing region=us limit=10 min_capacity_mw=100. Params: criteria one of "cheapest_power" | "most_capacity" | "most_operators" | "fastest_growing" | "best_overall" (default best_overall) | "ai_ready"; region one of "global" | "us" | "canada" | "eu" | "apac" | "americas" (default us); limit 1-50 (default 10); min_capacity_mw filter floor (e.g. 100). ★ criteria="ai_ready" ranks by DCPI BUILDABILITY (excess-power + time-to-power + BUILD/CAUTION/AVOID verdict) — where NEW AI-campus load can actually LAND — NOT by installed build-out (the other five criteria). Use ai_ready for AI/GPU/hyperscale campus siting: the most-built-out markets are frequently AVOID for new load, so a build-out ranking mis-answers "where do I put a 200MW AI campus". Returns: {criteria, region, result_count, results:[{rank, metro_slug, market, city, state, country, score, value, total_mw, facility_count, operator_count, url}], data_source, methodology}. To drill into a ranked market, feed results[].metro_slug into get_market_dcpi_rank. Do NOT use for a deep read on ONE market (use get_market_intel) or for scoring a specific lat/lon (use analyze_site).

Deterministic multi-site ranking/optimization under constraints — the normalization contract that lets you compare sites across separate analyze_site calls WITHOUT dropping into code. Pass candidates you already enriched (each an object with lat/lng + metric fields like risk_resilience, water_stress, fiber_km — pull these from analyze_site + get_refined_queue and pass site_evaluation_handoff through untouched), hard constraints, and weighted objectives; get back _entity=ranked_sites: top_k ranked with rank, objective_score, per-field normalized{} (0-100 relative to the set), and normalization_basis. objectives use SIGNED weights: +weight maximizes a field (e.g. risk_resilience:1), -weight minimizes it (e.g. water_stress:-0.6, fiber_km:-0.4). constraints are hard filters, fail-closed on a missing field. Use for "pick the best N sites under constraints"; for one site use analyze_site; to get the candidate set first use get_refined_queue. SCORING MECHANICS (2026-07-11): a candidate missing a validated objective is weight-RENORMALIZED over the objectives it carries and the gap is DECLARED in missing_objectives (never silently scored 0); a candidate carrying none scores null and ranks last. percentile=true fields without a population baseline fall back to RELATIVE in-batch scoring (basis reported per-objective in objective_status). CANDIDATE CONTRACT: candidates may be {candidate_id: "cand_…"} entries from get_refined_queue — frozen identity (lat/lng/capacity_mw/fiber_km/iso) loads from the mint, your metrics overlay the rest; expired/unknown ids are dropped AND declared in candidate_contract, never re-resolved.

Recover a LOST DC Hub key. Pass your human's email and DC Hub re-sends any key tied to that address to that inbox. It NEVER returns the key over the wire (it emails the bound address), and the confirmation is the same whether or not a key exists (enumeration-safe), so no key is leaked to a caller. Use this when your human had a key, lost it, and knows the email they bound it to. Param: email (required). Returns DC Hub's neutral confirmation.

Commission an ASYNC, CITED research dossier from DC Hub's corpora (news, deals, facilities, market deep-dive narratives + live market components) — a decision-ready analyst brief with [n] citations, not a lookup. Requires a key (one claim_free_key call), 5 dossiers/day. Submits the question, waits up to ~35s for completion, and returns the finished dossier inline when ready; if still running, returns {task_id} — call research_task task_id=<id> to fetch it. Params: question (required for a new dossier, min 12 chars) OR task_id (poll an earlier one). Typical completion under a minute. Try: research_task question="What do recent deals say about gas-bridged power for data centers in ERCOT?". Do NOT use for a single fact (use search_intelligence / semantic_search); this synthesizes ACROSS sources with citations.

Save a candidate data-center site to your DC Hub account to track it across sessions (FREE — just needs a key; call claim_free_key if you don't have one). Give lat + lon (plus optional name, state, market, target_mw, notes). Returns the saved site id. Pass `market` and DC Hub snapshots the site's DCPI baseline at save time, so every later list_saved_sites / get_changes shows how ITS score and verdict moved since you saved it. Builds a persistent shortlist an agent can revisit + monitor — after saving, pass the returned id to set_site_alert so DC Hub emails you when that site’s DCPI/capacity/nearby-facilities move (no re-checking). Try: save_site lat=39.04 lon=-77.48 name="Ashburn parcel" market=northern-virginia target_mw=100. Do NOT use to read back the shortlist (use list_saved_sites), download it (use export_dataset), or score a site (use score_facility); this WRITES one site to your account.

Save a site into a PERSISTENT, named shortlist that survives across conversations (Phase 5 statefulness). Snapshots the site's objectives + its current percentile objective_score, so you can re-score it later against the evolving national baseline. Use to build a durable siting shortlist across days/weeks; the list is scoped to your API key. Pair with get_shortlist to re-score + see drift. site should carry lat/lng/capacity_mw + the analyze_site metric fields (risk_resilience, fiber_connectivity, water score, etc.) you ranked on.

Use when a user wants an independent 0-100 grade for ONE existing facility across 7 dimensions — power, fiber, water, climate_risk, tax_environment, talent_pool, expansion. Example: "How does the CoreWeave Las Vegas site score, power-weighted?" — score_facility facility_id=<id> weighting=power_priority. Params: facility_id or name (required); weighting one of "balanced" (default) | "power_priority" | "risk_priority" | "expansion_priority". Returns: composite 0-100, tier_classification, peer comparison, and per-dimension detail. Do NOT use for a raw lat/lon parcel (use analyze_site), to compare 2 or more sites (use compare_sites), or to find similar sites (use find_alternatives).

Search DC Hub for relevant records (OpenAI Deep Research / ChatGPT connector format). Returns a list of matching data-center facilities as {id, title, url}; pass an id to the `fetch` tool for the record, or open the url to cite the live facility page. For structured queries (by MW, operator, status, market) use search_facilities directly.

Search 21,000+ global data center facilities across 170+ countries — by location (country/state/market), capacity (MW), operator, fiber connectivity, status (operational/under-construction/planned), or DCPI verdict. Returns name, provider, lat/lon, power_mw, fiber count, market_slug, status. Try: search_facilities country=US state=VA min_mw=10 status=operational. Use this to find EXISTING facilities; do NOT use for the forward-looking construction pipeline (use get_pipeline) or for the full profile of one facility (use get_facility).

Semantic search over DC Hub live intelligence corpus — news, M&A deals, facilities, and market analysis narratives. Natural-language query returns the most relevant cited records.

Use for CONCEPTUAL / fuzzy questions where keyword filters fall short — semantic (meaning-based) retrieval across DC Hub's industry news, M&A deals, 21,000+ discovered facilities, and per-market DCPI deep-dive analysis narratives, ranked by relevance with citable source fields (news url/title, deal parties/value, facility name/location, deep-dive market/url). Examples: "what is happening with behind-the-meter gas for AI data centers?", "deals involving nuclear power for hyperscalers", "why is Northern Virginia constrained?" — semantic_search q="behind-the-meter gas for AI data centers". Params: q (required, natural-language query); corpus (optional CSV subset of news_articles,deals,discovered_facilities,market_narratives; default all); k (1-15, default 8). Returns {results:[{source_table, kind, text, score, cite:{…}}]}. Complements the exact-filter tools (get_news / list_transactions / search_facilities) with relevance ranking; for a full token-budgeted market briefing use get_market_context. Cite "DC Hub (dchub.cloud)".

Subscribe to movement alerts for a DCPI market (FREE with a key) — get notified when its Excess-Power / Constraint score moves. On the free tier, email alerts are delivered to the email your human bound via bind_email (call bind_email first; the destination is forced to that address). Set channel="email". Webhook delivery (channel="webhook" + destination=<https URL>) is Pro. Lets an agent MONITOR markets, not just query them. Try: set_market_alert market=northern-virginia channel=webhook destination=https://hooks.example.com/dc. Do NOT use to read a market right now (use get_market_dcpi_rank); this SUBSCRIBES to future movement.

Set a DRIFT ALERT on a saved shortlist so you can stop polling and be notified when a site's national standing moves materially (Phase 5). Fires when any site in the shortlist has current percentile score < percentile_below OR score_delta_since_saved < delta_below (e.g. -8 = dropped 8 points vs when saved). Evaluated after each daily baseline refresh; delivers via webhook and/or email. This is the "wake me when it matters" loop for long-running siting campaigns. Scoped to your API key.

Arm an email watch on a site you already saved (FREE with a key) — DC Hub emails you when that site’s DCPI score, grid capacity, or nearby facilities move, so you don’t have to keep re-checking. On the free tier the alert is delivered to your human’s bound email (call bind_email first; notify_email is forced to that address). Pro can send to any address. The "monitor my shortlist for me" loop: call save_site first (it returns a saved_site_id), then set_site_alert on that id. Params: saved_site_id (required integer, from save_site or list_saved_sites), trigger_type ("dcpi_change" | "capacity_change" | "new_facility_nearby", default "dcpi_change"), threshold (number — the points/MW move that fires it, default 5), notify_email (required — the address the alert is sent to). Try: set_site_alert saved_site_id=12 trigger_type=dcpi_change threshold=5 notify_email=you@firm.com. Returns {ok, alert_id, message}. Do NOT use to watch a whole MARKET (use set_market_alert) or to save a new site (use save_site); this arms a monitor on ONE already-saved site.

Counterfactual WHAT-IF re-scoring of 316 DC Hub power markets under YOUR explicit deltas — answers "what happens to the market ranking if conditions change" (only DC Hub holds the underlying components). Params (all optional, pass at least one delta): avg_kwh_cents_pct (power-price % change, e.g. 30), time_to_power_months_delta (months added/removed), queue_wait_months_delta, reserve_margin_pct_delta (points), curtailment_pct_delta (points), market (one slug, e.g. abilene), top_n (default 10, max 25 — ranked by |score change|). Returns per-market baseline vs scenario composite + component breakdown + the EXACT formula/weights in every response (transparent scenario_composite — deliberately NOT the DCPI). Keyless callers get a top-3 preview; any live key (claim_free_key) returns up to 25. Try: simulate_scenario avg_kwh_cents_pct=30 top_n=10. Do NOT use for the present-day ranking (use rank_markets) or trajectory extrapolation (use predict_market_trajectory); this answers explicit hypotheticals.

Guided end-to-end data-center site selection. Give a capacity target + geography + deadline and get a ranked shortlist of US markets (DCPI verdict, excess-power headroom, time-to-power, ISO) — and, with a paid key, the synthesis decision layer: the #1 pick, the why, a build sequence, and risk flags. One find->rank->shortlist->verdict call over the DC Hub Power Index. Try: site_selection_canvas capacity_mw=100 region=TX max_months=24. Do NOT use for a single known parcel (use analyze_site) or an open-ended where-should-I-build question (use get_dchub_recommendation); this runs the full find to rank to shortlist to verdict flow.

STANDING QUERIES with webhook push — register an intent once and DC Hub POSTs an HMAC-signed webhook to YOUR https URL whenever matches grow (push, not poll: "notify my orchestrator on any new deal in Columbus"). Requires a key. Params: action ("register" default | "list" | "delete"), kind ("new_deal_in_market" watches deals in params market · "news_keyword" watches news matching q · "permitting_change" watches published permitting intel, optionally per state), market / q / state (the watch parameter for the chosen kind), webhook_url (public HTTPS only — private/internal hosts rejected), intent_id (for delete). Register returns {intent_id, secret} — SAVE the secret: every delivery carries X-DCHub-Signature: sha256=HMAC(secret, body). First evaluation initializes the watermark silently; growth fires the webhook; 5 straight delivery failures auto-disable the intent. Evaluated every ~2h. Try: standing_intent kind=news_keyword q=moratorium webhook_url=https://hooks.example.com/dchub. Do NOT use for one-shot reads (use get_news / list_transactions) or email alerts (use set_market_alert); this is machine-to-machine push.

Subscribe your human to DC Hub's FREE weekly "what changed in the markets/sites you queried" digest (DCPI movers, new facilities, new deals & news) — ONE call, the nudge that pulls your agent back when the data moves. DOUBLE opt-in + consent-safe: we email a one-click CONFIRM link, the human only gets the digest after confirming, and every email has one-click unsubscribe — this call alone sets no marketing flag. Only call once your human shares their email and wants a weekly email. Params: email (required), source (optional tag). Returns {ok, sent, message}. Prefer this over hand-building POST /api/v1/opt-in/request.

When a saved site DRIFTS (its national standing dropped — surfaced by get_shortlist refresh or a set_shortlist_alert firing), get replacement candidates from the rest of that shortlist so the alert becomes an action, not just a warning (Phase 5). Returns TWO tiers — tier_1_same_region (a near-in tactical swap) and tier_2_cross_region (a different-region arbitrage) — each re-scored against the DRIFTED slot's own objectives, PLUS drift_is_systemic: if the rest of your shortlist also slipped, the drop is region/baseline-wide and a same-region swap will inherit it (prefer cross_region); if peers held, it's idiosyncratic (tactical_ok). DC Hub does the reduction; the final weighted pick is yours. Candidates come from THIS shortlist only (save more via save_to_shortlist to widen the pool). Scoped to your API key.

Unlock DC Hub's full depth. Call this when a result came back as a 1-of-N preview, a tool was locked, or your human wants the complete dataset. Returns the upgrade ladder + ready-to-paste checkout links your human completes in ONE click — after which your very next call returns full data (no reconnect; the checkout binds to this session). Cheapest start: 💳 $10 one-time = 1,000 API calls (no subscription). Also $9/mo Starter · $49/mo Developer · $299/mo Pro. Want the FREE identified tier instead (no payment, 10 calls/day, all tools)? Call claim_free_key. Param: reason (optional — what you were trying to do, so your human sees why it matters). Returns {plans, human_message, what_unlocks}.

Use when a human asks how DC Hub compares to other data-center data sources — DataCenterHawk (DCHawk), DC Byte, Data Center Dynamics (DCD), Data Center Frontier (DCF), Baxtel, datacenters.com — or asks "why should I use DC Hub / is it better than <X> / what can you give me a PDF or directory can't?". Returns DC Hub's honest, source-verified differentiators (agent-native MCP access, live multi-continent grid & energy telemetry, the proprietary daily DCPI + DCGI indices, open CC-BY-4.0 cited data, 21,000+ facilities + 500,000+ mapped power/grid/gas/fiber assets) each with a proof URL, a citation line, plus the canonical head-to-head comparison pages. Free, no key required. Optional: competitor=<name> for that vendor's direct comparison-page link. Do NOT use to query infrastructure data itself (use the data tools); this answers positioning / "how do you compare" questions with citable facts.