Skip to main content
Glama

Kaleidoscope MCP (SEC & financial data)

Power Forward Demand (data-center/large-load wedge by year) [beta]

sec_power_demand_forward
Read-onlyIdempotent

Forward large-load demand from utility disclosures: data-center / hyperscaler / industrial / hydrogen / crypto MW commitments by year, firm vs pipeline. The answer to 'how much data-center load are utilities actually committing to' without rereading every PJM IRP.

Spec-validated headline: firm DC load 2.6 → 45 GW from 2024 to 2026 disclosures (the AI-buildout wedge). Live status enum (verified from data, the originally-spec'd values were renamed during extraction): firm side = 'contract', 'in_service', 'executed', 'firm', 'permitting'; pipeline side = 'mou', 'in_negotiation', 'announced', 'planned', 'pipeline'. Don't pass 'contracted' or 'signed_LOA' — those silently return 0 rows.

Filter by ticker_or_cik (per-utility), counterparty_type (data_center / industrial / crypto / hydrogen / ev_charging / mixed), iso, status, or year range. Returns one row per (filer, counterparty, start_year) deduped to latest filing, with the full source_accession + snippet.

Two caveats that bite per-ticker consumers hardest (power-sec 2026-07-23): (1) The firm-vs-speculative split is load-bearing, NOT cosmetic. The response separates firm_total_mw from pipeline_total_mw (and per-year in summary_by_year) — read the FIRM total, not a blended sum. Pipeline rows are interconnection-queue entries that double-count across overlapping territories and mostly never get built. Concrete trap: AEP's only demand rows are 2 pipeline entries totalling 200,000 MW — a blended read prints a 200 GW headline for one utility; its firm_total_mw is 0. (2) expected_load_mw is NULL on a meaningful share of FIRM rows (e.g. EVRG, ETR have firm events with no MW) — so sum(mw) under-represents coverage vs n_events. A null MW ≠ 'no commitment'; use n_events for count, the MW totals for magnitude, and don't conflate them.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "sec_power_demand_forward"
  }
}

Input Schema

NameRequiredDescriptionDefault
isoNoISO/RTO scope (PJM / ERCOT / CAISO / MISO / NYISO / ISO-NE / SPP / non-RTO).
as_ofNoISO date for PIT (default: latest disclosures).
limitNo
statusNoFilter by commitment status (LIVE enum: 'contract' / 'in_service' / 'executed' / 'firm' / 'permitting' on the firm side; 'mou' / 'in_negotiation' / 'announced' / 'planned' / 'pipeline' on the pipeline side). NB: the originally-spec'd 'contracted' and 'signed_LOA' values silently return 0 rows — use 'contract' / 'executed' / 'firm' instead.
year_toNo
year_fromNo
ticker_or_cikNoFilter to one filer.
include_undatedNoDefault false. When false, rows with `timeline_start_year IS NULL` are EXCLUDED (per futures smoke 2026-06-12: undated rows were bypassing the year_from filter and returning 2003/2011-2014 vintage disclosures + a 15,277 MW 'unknown' bucket alongside current commitments). Set true to inspect the full undated set.
counterparty_typeNoFilter to one segment (data_center / industrial / crypto / hydrogen / ev_charging / mixed).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.1/5.0
Behavior5/5

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

Goes well beyond the readOnly/idempotent annotations: rows are deduped to latest filing, pipeline rows double-count across overlapping territories (AEP's 200 GW trap), expected_load_mw is NULL on a meaningful share of firm rows, and undated rows previously bypassed year_from. It even discloses that certain status values silently return 0 rows, which is exactly the kind of failure mode an agent needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded, but the body carries promotional ballast ('without rereading every PJM IRP', the 2.6 → 45 GW headline, provenance stamps like 'power-sec 2026-07-23') alongside genuine caveats. The useful content is dense but the definition is roughly twice the length a 9-parameter filter tool needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does supply the return grain (one row per filer/counterparty/start_year, deduped) and the key output fields (firm_total_mw, pipeline_total_mw, summary_by_year, expected_load_mw, n_events, source_accession). Pagination via limit and the as_of point-in-time semantics are the remaining gaps.

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?

With 67% schema coverage the schema already documents most filters, but the description adds behavioral meaning: status enum values are 'LIVE' and verified from data, while 'contracted'/'signed_LOA' silently return zero, and counterparty_type segments are enumerated. It leaves limit and as_of ('PIT') unexplained, so it is not fully compensating.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Forward large-load demand from utility disclosures... MW commitments by year, firm vs pipeline', plus the question it answers. It is clearly a distinct dataset from the sibling capacity/fundamentals tools, but it never explicitly contrasts itself with them, so it stops short of a 5.

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?

Gives real when-to-use guidance inside the domain: read the FIRM total, not a blended sum, use n_events for count and MW totals for magnitude, set include_undated=true only to inspect the undated set. It never names an alternative tool or exclusion condition, which keeps it off a 5.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources