Plan Query
plan_queryINSPECT-ONLY — returns the plan WITHOUT running it. For a real multi-step DC Hub question call execute_plan(intent="...") instead: it uses the SAME deterministic no-LLM planner and then RUNS the sequence server-side, returning the…
Instructions
INSPECT-ONLY — returns the plan WITHOUT running it. For a real multi-step DC Hub question call execute_plan(intent="...") instead: it uses the SAME deterministic no-LLM planner and then RUNS the sequence server-side, returning the answers in one envelope. Reach for plan_query only to review, log, diff or audit a plan before executing it yourself. Deterministic keyword routing over the tool registry — no LLM, no network, same intent always returns the same plan (free). 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), execution_strategy.parallel_groups, execution_estimate {estimated_calls, estimated_latency_ms, parallelizable}, alternatives (each with when + rejected_because), coverage_notes, matched_classes} plus a versioned replay (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} — auditable and machine-readable, safe to log and diff across versions. args_hint values in 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. For a family-level browse use discover_tools. This tool plans — it never executes; tools/list stays canonical for schemas.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| intent | Yes | Natural-language description of what you are trying to find out, e.g. "rank markets for a 200MW AI campus" or "how much power is available in ERCOT" | |
| context | No | Optional structured hints: {lat, lon, iso, market, capacity_mw, candidate_id, state (2-letter), since} — sharpens args_hint values and routing (e.g. lat/lon boosts the site-analysis route) |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | No | true when the intent was routed | |
| note | No | Router disclaimer — deterministic keyword routing, tools/list stays canonical | |
| quota | No | Caller quota state (remaining calls, tier) when available. | |
| intent | No | The natural-language intent that was routed (echoed back) | |
| reason | No | Why the router chose best_tool — the matched keywords / context signals | |
| replay | No | FIRST-CLASS VERSIONED replay object (r-planner-v5.1, ChatGPT schema review): the planner's auditable decision trail — routing + per-step selection + rejections + concurrency graph, each decision with a stable id + status, keyed by planner_version so an agent can cite "Decision D2 selected rank_markets because…" and downstream tooling survives planner upgrades. | |
| _entity | No | Payload class discriminator (e.g. facility|market|iso_grid|queue_results|deal|report|response) — branch on this before parsing the rest. | |
| chaining | No | Zero-drift chaining guidance (candidate_id contract) when the plan crosses get_refined_queue → analyze_site / rank_sites | |
| 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. | |
| best_tool | No | The single best first tool to call for this intent (exact name from tools/list) | |
| confidence | No | Deterministic router confidence, 0-1 — same intent always yields the same score; low values mean the intent was ambiguous (check alternatives). Alias of intent_confidence (v1 back-compat). | |
| 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. | |
| alternatives | No | Adjacent tools for nearby intents, including runner-up intent classes | |
| intent_class | No | The matched intent class (market_ranking | capacity_search | market_comparison | grid_headroom | interconnection_queue | hosting_capacity | water_climate | site_analysis | deals_ma | fiber_power_pairing | fiber | price | incentives_tax | power_timeline | changes_delta | facility_search | unknown) | |
| routing_hint | No | ADVISORY router: collapses 91 tools to one starting point, then names what lies outside DC Hub entirely. Deliberately carries no tool list, latency promise, confidence score, execution graph or planner version — those ride `replay` AFTER routing. Four fields specified by ChatGPT in the 2026-08-29 partner round; external_sources_recommended added on its own request in the 2026-08-30 briefing, because a source we do not own is not execution metadata. | |
| coverage_notes | No | Tier/coverage caveats for the recommended tools (free-tier previews, depth gates, honest-unknown semantics) | |
| parallelizable | No | true when at least one execution wave holds 2+ steps — the plan is not purely sequential | |
| estimated_calls | No | Total estimated API calls for the whole plan (sum of per-step estimates) | |
| execution_waves | No | The execution graph as concurrency waves: array of arrays of step numbers; every step in a wave can run concurrently once earlier waves finish (derived from depends_on) | |
| matched_classes | No | Every intent class that scored, with its score — the router's full deterministic trace | |
| intent_confidence | No | How confident the router is that it read the QUESTION right (0-1, deterministic) — driven by keyword score + margin over the runner-up class | |
| planner_rationale | No | One sentence on why the PLAN has this shape (ordering / parallelism / what mints what) — distinct from reason, which covers intent routing | |
| execution_estimate | No | r-planner-v3 deterministic cost preview: {estimated_calls (plan NODE count — one per step; the top-level estimated_calls is the fan-out-weighted API-call total), estimated_latency_ms (sum over waves of the SLOWEST tool in each wave, from a static 3-tier table: heavy synthesis 3000ms / standard read 1200ms / light free read 500ms), parallelizable (any wave holds 2+ steps)} | |
| execution_strategy | No | r-planner-v3 explicit strategy: {parallel_groups: string[][] — execution_waves rendered as TOOL-NAME arrays (e.g. [["get_grid_intelligence","get_interconnection_queue","get_refined_queue"]]), note: plan-only disclaimer — this tool only plans; execute the sequence yourself} | |
| workflow_confidence | No | How confident the router is that the plan can EXECUTE cleanly with the signals in hand (0-1, deterministic) — boosted by resolved context signals, docked for placeholder args the user must still supply; step-minted placeholders don't dock | |
| recommended_sequence | No | Ordered tool sequence mirroring the DC Hub recipe for the matched intent class | |
| 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. | |
| workflow_confidence_basis | No | The arithmetic behind workflow_confidence: {resolved_signals, minted_placeholders, user_supplied_placeholders} |