Rank Sites
rank_sitesDeterministic 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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| top_k | No | How many top-ranked sites to return (1-50, default 3) | |
| absolute | No | false (default) = min-max normalize within THIS batch (best-in-set, NOT stable across runs). true = score on a FIXED 0-100 scale for CROSS-RUN-STABLE, auditable scores — use ONLY when the objective fields are already 0-100 (analyze_site scores like risk_resilience/fiber_connectivity), not raw distances like fiber_km | |
| candidates | No | Array of candidate objects. PREFERRED: {candidate_id: "cand_…", <your metric fields>} using ids from get_refined_queue — frozen coordinates/capacity/fiber_km load from the mint (zero transcription drift), your enrichments (e.g. overall_score from analyze_site) overlay. Legacy: {id?, lat?, lng?, <metric fields>} flat objects also work. Omit if using shortlist_name | |
| objectives | No | Weighted objectives {field: signedWeight} — +weight maximizes, -weight minimizes. e.g. {"water_stress": -0.6, "fiber_km": -0.4}. Omit with shortlist_name to reuse the shortlist's saved objectives; required with candidates | |
| percentile | No | true = score each objective as its PERCENTILE against the viable-site POPULATION ("better than X% of viable sites") — the strongest cross-run + cross-region comparability. Works for fields with a maintained baseline (analyze_site metrics: overall_score, risk_resilience, fiber_connectivity, power_infrastructure, market_conditions, gas_pipeline_access, fiber_km, power_cost); other fields fall back to absolute (listed in unbaselined_fields). Takes precedence over absolute | |
| constraints | No | Hard filters {field: {min?, max?}} — a candidate missing a constrained field is dropped (fail-closed). e.g. {"risk_resilience": {"min": 70}, "estimated_ttp_months": {"max": 34}} | |
| shortlist_name | No | Alternative to candidates: re-rank a SAVED shortlist (created via save_to_shortlist) in one shot — loads its sites (scoped to your API key) + reuses their saved objectives if you pass none, and re-scores against the current baseline | |
| require_complete | No | true = DROP any candidate missing one or more of your (validated) objectives — dropped candidates are DECLARED in excluded_incomplete, never silent. Default false keeps incomplete candidates ranked on their carried objectives with missing_objectives flagged. Recommended true for autonomous take-rank-1 workflows (an incomplete candidate can otherwise top the ranking on its single best metric). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| quota | No | Caller quota state (remaining calls, tier). | |
| _entity | No | Payload class (facility|market|iso_grid|queue_results|deal|report|response); branch on it. | |
| citation | No | How to attribute DC Hub: {source, url, license, cite_as, retrieved_at}, or the attribution line as a string. | |
| provenance | No | Source, method, as_of, verification_counts, license, cite_as; quote it when citing. | |
| _front_door | No | First-tool hint: plan_query(intent) returns the ordered plan. | |
| _return_loop | No | Next-session delta call (get_changes). | |
| site_evaluation_handoff | No | Follow-up calls [{tool, parameters, why}] when the payload carries coordinates. |