osint

Query Power Retail Sales

query_power_retail_sales_v1

Read-onlyIdempotent

Query verified U.S. annual retail electricity sales — billed MWh, revenue, and customer counts — by utility, state, and customer sector from EIA-861.

Use this for "who sold how much power to whom" questions at the annual utility×state×sector grain: filter or group by data_year, state, sector (residential / commercial / industrial / transportation), part, service_type, ownership, ba_code, data_type, eia_utility_id, or utility_name. Pass filters inside the params object. Returns JSON aggregates with citations down to the exact stacked sector/measure cell, and optional row-level records when include_records is true. Defaults keep totals faithful: the in-row total sector block is excluded unless named explicitly (it duplicates the four sectors); EIA's state-level Adjustment (99999) and Withheld (88888) sentinel rows stay in state totals but are auto-excluded from any utility-keyed query; territories are excluded unless included_in_default_us_metrics is false. A result mixing service types carries a service_type_mix note quoting the file's own law — revenue sums Parts A,B,C,D but sales/customers sum A,B,D only (Part C delivery re-counts Part B energy). History spans data years 2016–2024, one annual census per year, each its own vintage. Reach an earlier year through as_of, not data_year: as_of resolves to the newest census at or before it (so as_of 2018-06-01 — or just 2018 — returns the 2018 census) and the response echoes that resolved as_of. data_year only filters within the resolved vintage, so data_year 2018 under the default as_of (latest = 2024) returns an empty scope, not 2018; the default serves 2024, a multi-year trend is one query per year, and an as_of before 2016 is refused, naming the floor. Does not determine hourly or peak load (sales are billed MWh over a year — use power.demand), facility-level or data-center-specific load, county-level detail, average retail price (cents/kWh — deferred), the ~1,700 small short-form (EIA-861S) utilities, or monthly freshness (this is the annual census, not the monthly EIA-861M sample).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`params`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

TDQS

A4.9/5.0

Behavior5/5

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description goes far beyond by disclosing default total-block exclusion, sentinel row handling, service_type_mix summation rules, as_of resolution behavior, territory exclusions, and error floors. No contradictions with annotations.

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?

The description is front-loaded with purpose and every sentence adds a distinct behavioral fact. However, it is an extremely dense single paragraph; breaking it into bullets or shorter sections would improve scannability without losing information.

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?

Given the tool's complexity and near-empty input schema, the description is exceptionally complete: it covers filters, defaults, sentinel rows, service-type math, vintage semantics, as_of edge cases, and explicit exclusions. The agent has enough context to invoke the tool correctly without external documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the description enumerates all filterable fields (data_year, state, sector, part, service_type, ownership, ba_code, data_type, eia_utility_id, utility_name) and explains nuanced parameters like as_of, include_records, and included_in_default_us_metrics. This fully compensates for the sparse schema.

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?

The description opens with a specific verb and resource: 'Query verified U.S. annual retail electricity sales — billed MWh, revenue, and customer counts — by utility, state, and customer sector from EIA-861.' This clearly distinguishes the tool from descriptive siblings like describe_power_retail_sales_v1 and from demand-focused tools.

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

Usage Guidelines5/5

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

It explicitly states 'Use this for "who sold how much power to whom" questions' and provides an extensive 'Does not determine' list pointing to alternatives (e.g., power.demand for hourly/peak load, EIA-861M for monthly fresh data). It also explains the as_of/data_year distinction to prevent misuse.

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

All osint tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4/5.0

Disambiguation4/5

Each capability has a clearly named describe/query pair, and domains like power, AI infrastructure, robotics, and space are distinct. The generic describe_capability_v1/query_capability_v1 could be confused with the named variants, and the many ISO-specific interconnection queues share similar names, but descriptions explicitly disambiguate them.

Naming Consistency5/5

All tools follow a consistent lowercase snake_case verb_noun pattern: describe_<capability>_v1 and query_<capability>_v1, with a few utility tools like list_capabilities_v1 and get_source_evidence_v1. There is no mixing of conventions.

Tool Count2/5

At 62 tools, the set is far too large for typical server scope. The describe/query pairs inflate the count even though each is justified, and the generic capabilities plus per-ISO variants make it feel heavy and hard to navigate.

Completeness4/5

The server covers each domain thoroughly with describe, query, and evidence verification, plus generic fallbacks for capabilities not yet in the client's tool list. Minor gaps exist (e.g., no county/state attribution for some data, no load types in ISO queues) but they are explicitly documented and workable.

Resources

Need Help?