DC Hub: Data Center, Power Grid & Energy Intelligence

Rank Markets

rank_markets

Read-onlyIdempotent

Ranks data-center markets by cheapest power, capacity, operators, growth, or AI-ready grid access, with region and minimum-MW filters, returning scored rows.

Instructions

Use this when the user wants a ranked list of data-center markets, including where a data center can get grid power (criteria="ai_ready", DCPI): top N by cheapest_power, most_capacity, most_operators, fastest_growing, best_overall, or ai_ready (where new AI load can land, per DCPI). Filter by region, min_capacity_mw. Returns ranked rows with score, MW and a slug for follow-ups; score is the sort value, not a 0-100 scale, and score_basis says what it is (ai_ready omits it and explains its composite in methodology). Keyless: a trimmed preview; a free key gets a few full lists a day. Ex: "Top 10 US markets, ai_ready." Returns market slugs to feed get_market_intel and get_market_dcpi_rank. limit 1-500; set projection=identity_only to save tokens.

Input Schema

Name	Required	Description
`limit`	No	Number of markets to return, 1-50 (default 10)
`fields`	No	Return ONLY these row fields (array or comma string) — a token diet. The response envelope (citation, provenance, as_of, coverage, request_interpretation, the human relay line) is NEVER projected away; a projection narrows ROWS only.
`region`	No	Region scope: "global", "us" (default), "canada", "eu", "apac", or "americas"
`criteria`	No	Ranking criterion: "cheapest_power", "most_capacity", "most_operators", "fastest_growing", "best_overall" (default), or "ai_ready" (DCPI buildability — where new AI load can land, for AI-campus siting; region us/global)
`projection`	No	Named field preset, cheaper to send than a field list: market_summary (ranking rows), siting_summary (site/point rows), identity_only (ids + names).
`min_capacity_mw`	No	Minimum existing capacity filter in megawatts (MW), e.g. 100

Output Schema

Name	Required	Description	Default
`tier`	No
`region`	No
`cite_as`	No
`results`	No
`criteria`	No
`data_source`	No
`methodology`	No
`score_basis`	No
`result_count`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed26 schema fields changedv2.12.45Oct 22, 2026

changedOutput schema / additionalProperties
```
Previous value: -{}New value: +true
```

removedOutput schema / properties / _entity

Removed value: -{
-  "description": "Payload class (facility|market|iso_grid|queue_results|deal|report|response); branch on it.",
-  "type": "string"
-}

removedOutput schema / properties / _front_door

Removed value: -{
-  "additionalProperties": {},
-  "description": "First-tool hint: plan_query(intent) returns the ordered plan.",
-  "properties": {},
-  "type": "object"
-}

removedOutput schema / properties / _return_loop

Removed value: -{
-  "additionalProperties": {},
-  "description": "Next-session delta call (get_changes).",
-  "properties": {},
-  "type": "object"
-}

removedOutput schema / properties / citation

Removed value: -{
-  "anyOf": [
-    {
-      "additionalProperties": {},
-      "properties": {},
-      "type": "object"
-    },
-    {
-      "type": "string"
-    }
-  ],
-  "description": "How to attribute DC Hub: {source, url, license, cite_as, retrieved_at}, or the attribution line as a string."
-}

removedOutput schema / properties / cite_as / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / cite_as / description
```
Removed value: -"Ready-made attribution line"
```

removedOutput schema / properties / criteria / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / criteria / description
```
Removed value: -"Ranking criterion used"
```

removedOutput schema / properties / data_source / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / data_source / description
```
Removed value: -"Where the data comes from"
```

removedOutput schema / properties / methodology / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / methodology / description
```
Removed value: -"Method note"
```

removedOutput schema / properties / provenance

Removed value: -{
-  "additionalProperties": {},
-  "description": "Source, method, as_of, verification_counts, license, cite_as; quote it when citing.",
-  "properties": {},
-  "type": "object"
-}

removedOutput schema / properties / quota

Removed value: -{
-  "additionalProperties": {},
-  "description": "Caller quota state (remaining calls, tier).",
-  "properties": {},
-  "type": "object"
-}

removedOutput schema / properties / region / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / region / description
```
Removed value: -"Region filter applied"
```

removedOutput schema / properties / result_count / anyOf

Removed value: -[
-  {
-    "anyOf": [
-      {
-        "type": "number"
-      },
-      {
-        "type": "string"
-      }
-    ]
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / result_count / description
```
Removed value: -"Rows returned in THIS response"
```

removedOutput schema / properties / results / anyOf

Removed value: -[
-  {
-    "items": {
-      "additionalProperties": {},
-      "properties": {},
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / results / description
```
Removed value: -"Ranked markets"
```

removedOutput schema / properties / score_basis / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / score_basis / description
```
Removed value: -"How the score is computed"
```

removedOutput schema / properties / site_evaluation_handoff

Removed value: -{
-  "anyOf": [
-    {
-      "items": {
-        "additionalProperties": {},
-        "properties": {},
-        "type": "object"
-      },
-      "type": "array"
-    },
-    {
-      "additionalProperties": {},
-      "properties": {},
-      "type": "object"
-    }
-  ],
-  "description": "Follow-up calls [{tool, parameters, why}] when the payload carries coordinates."
-}

removedOutput schema / properties / tier / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / tier / description
```
Removed value: -"Tier the response was served at"
```

Changed17 schema fields changedv2.12.43Oct 15, 2026

removedOutput schema / description

Removed value: -"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."

changedOutput schema / properties / _entity / description

Previous value: -"Payload class discriminator (e.g. facility|market|iso_grid|queue_results|deal|report|response) — branch on this before parsing the rest."New value: +"Payload class (facility|market|iso_grid|queue_results|deal|report|response); branch on it."

changedOutput schema / properties / _front_door / description

Previous value: -"In-band front-door hint (first workflow-entry tool of a session): call plan_query(intent) first for the ordered multi-step plan."New value: +"First-tool hint: plan_query(intent) returns the ordered plan."

changedOutput schema / properties / _return_loop / description

Previous value: -"Suggested next-session delta call (get_changes since=24h) so you pull only what changed."New value: +"Next-session delta call (get_changes)."

changedOutput schema / properties / citation / description

Previous 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."New value: +"How to attribute DC Hub: {source, url, license, cite_as, retrieved_at}, or the attribution line as a string."

addedOutput schema / properties / cite_as

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Ready-made attribution line"
+}

addedOutput schema / properties / criteria

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Ranking criterion used"
+}

addedOutput schema / properties / data_source

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Where the data comes from"
+}

addedOutput schema / properties / methodology

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Method note"
+}

changedOutput schema / properties / provenance / description

Previous value: -"Collection-level provenance block: {source, method, as_of, verification_counts, cite_url_template, license, cite_as}. Quote the verification level when citing."New value: +"Source, method, as_of, verification_counts, license, cite_as; quote it when citing."

changedOutput schema / properties / quota / description

Previous value: -"Caller quota state (remaining calls, tier) when available."New value: +"Caller quota state (remaining calls, tier)."

addedOutput schema / properties / region

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Region filter applied"
+}

addedOutput schema / properties / result_count

Added value: +{
+  "anyOf": [
+    {
+      "anyOf": [
+        {
+          "type": "number"
+        },
+        {
+          "type": "string"
+        }
+      ]
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Rows returned in THIS response"
+}

addedOutput schema / properties / results

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "additionalProperties": {},
+        "properties": {},
+        "type": "object"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Ranked markets"
+}

addedOutput schema / properties / score_basis

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "How the score is computed"
+}

changedOutput schema / properties / site_evaluation_handoff / description

Previous value: -"Pre-built follow-up calls (analyze_site / get_water_risk args) when the payload carries coordinates — an array of {tool, parameters, why} entries."New value: +"Follow-up calls [{tool, parameters, why}] when the payload carries coordinates."

addedOutput schema / properties / tier

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Tier the response was served at"
+}

Changed4 schema fields changedAug 30, 2026

removedInput schema / $schema

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

addedInput schema / properties / fields

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "string"
+    }
+  ],
+  "description": "Return ONLY these row fields (array or comma string) — a token diet. The response envelope (citation, provenance, as_of, coverage, request_interpretation, the human relay line) is NEVER projected away; a projection narrows ROWS only."
+}

addedInput schema / properties / projection

Added value: +{
+  "description": "Named field preset, cheaper to send than a field list: market_summary (ranking rows), siting_summary (site/point rows), identity_only (ids + names).",
+  "enum": [
+    "siting_summary",
+    "market_summary",
+    "identity_only"
+  ],
+  "type": "string"
+}

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"
```

Changed2 schema fields changedv2.3.12Jul 28, 2026

changedInput schema / properties / criteria / description

Previous value: -"Ranking criterion: \"cheapest_power\", \"most_capacity\", \"most_operators\", \"fastest_growing\", or \"best_overall\" (default)"New value: +"Ranking criterion: \"cheapest_power\", \"most_capacity\", \"most_operators\", \"fastest_growing\", \"best_overall\" (default), or \"ai_ready\" (DCPI buildability — where new AI load can land, for AI-campus siting; region us/global)"

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"
+}

Changed6 schema fields changedv2.3.6Jul 2, 2026

addedInput schema / properties / criteria / description

Added value: +"Ranking criterion: \"cheapest_power\", \"most_capacity\", \"most_operators\", \"fastest_growing\", or \"best_overall\" (default)"

addedInput schema / properties / limit / description

Added value: +"Number of markets to return, 1-50 (default 10)"

changedInput schema / properties / limit / maximum

Previous value: -9007199254740991New value: +500

changedInput schema / properties / limit / minimum

Previous value: --9007199254740991New value: +1

addedInput schema / properties / min_capacity_mw / description

Added value: +"Minimum existing capacity filter in megawatts (MW), e.g. 100"

addedInput schema / properties / region / description

Added value: +"Region scope: \"global\", \"us\" (default), \"canada\", \"eu\", \"apac\", or \"americas\""

First observedv2.1.19Jun 8, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Goes well beyond the readOnly/idempotent annotations: it discloses that keyless access returns a trimmed preview while a free key unlocks a few full lists per day, warns that score is a raw sort value rather than a 0-100 scale, and explains score_basis/methodology for ai_ready. These are exactly the behavioral traits an agent cannot infer from structured fields.

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?

Front-loaded with the usage trigger and packed with useful specifics, but it reads as a dense run-on sentence chain that could be split for easier scanning. Nearly every clause earns its place, so the length is justified even if the structure is slightly tangled.

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?

For a six-parameter tool with an output schema, it covers the remaining gaps: what the score means, how it varies by criterion, what the returned slugs enable (get_market_intel, get_market_dcpi_rank), and access-tier behavior. An agent has everything needed to call it and interpret the result.

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?

Schema coverage is 100%, so the baseline is 3, but the description adds value by explaining what each criterion means in practice and recommending projection=identity_only as a token-saving option. One blemish: it says 'limit 1-500' while the schema's own limit description says '1-50 (default 10)', a minor internal inconsistency the agent has to reconcile.

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?

States a specific verb and resource (rank markets) and enumerates the exact ranking criteria available, so the agent knows precisely what the output ordering means. It also implicitly distinguishes itself from the sibling rank_sites by scoping to markets rather than sites.

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

Usage Guidelines4/5

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

Opens with an explicit trigger ('Use this when the user wants a ranked list of data-center markets'), gives a concrete example, and ties criteria selection to intent (ai_ready for AI-campus siting). It lacks an explicit when-not or a direct pointer to rank_sites as the alternative, which keeps it from a 5.

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

Deploy Server