Rank Markets
rank_marketsFRONT DOOR CHECK — if the question is "WHERE SHOULD I PUT MW" (a siting decision), call execute_plan(intent="<the user's question, unchanged>") instead: ONE call runs the market ranking AND the per-finalist BUILD/CAUTION/AVOID verdict AND the grid reality-check, and returns a replay naming the markets it rejected and why. If the question is "RANK MARKETS BY " — you want the ranked list itself and nothing attached — rank_markets IS the right call: stay here. The trade is real and runs the other way: execute_plan spent ~3 steps and roughly 4x this tool's latency on a measured market-ranking intent, so a single-capability ask should NOT be routed through the planner. 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, score_basis}. score is the value the list is sorted by (score_basis states this in words; ai_ready omits it and explains its composite in methodology): best_overall = 0.4×total_mw + 50×operator_count + 20×facility_count; most_capacity and cheapest_power = total_mw; most_operators = operator_count; fastest_growing = facility_count; ai_ready = the DCPI composite. It is NOT a 0-100 scale and does not change with limit, so compare scores only within one criteria; rank is the position. 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), for scoring a specific lat/lon (use analyze_site), or for a siting question that also needs the verdict and grid check attached (use execute_plan).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| 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" | |
| mpp_pay | No | Autonomous payment (Stripe MPP), step 1: set true to receive a signed $0.50 payment challenge for this call instead of the free preview. No money moves — a challenge is a price quote. Humans never set this, so it does not affect the normal free/trial funnel. | |
| 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). | |
| mpp_credential | No | Autonomous payment (Stripe MPP), step 2: the Shared Payment Token you minted for challenges[0]. Set it here to pay $0.50 for this single call and receive the full result — no API key, no subscription, no human. One payment covers one call. | |
| min_capacity_mw | No | Minimum existing capacity filter in megawatts (MW), e.g. 100 |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| 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. |