Skip to main content
Glama

Ferc1 Sales For Resale

ferc1_sales_for_resale
Read-onlyIdempotent

FERC Form 1 sales for resale (Schedule 310) for one utility and report year, 1994 to date: each purchaser (buyer), statistical classification (RQ, LF, IF, SF, LU, OS, AD), MWh sold and revenue dollars. Rows sorted by MWh, subtotal and total rows excluded and reported separately. Answers "who bought the most power for resale from LG&E in 1994". Source: FERC Form 1 as processed by Catalyst Cooperative PUDL.

Example tool call

This call uses example arguments supplied in the tool’s input schema.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "year": 1994,
      "utility": "LG&E"
    },
    "name": "ferc1_sales_for_resale"
  }
}

Input Schema

NameRequiredDescriptionDefault
yearNoReport year (e.g. 2023). Default: the latest year on file for the respondent.
limitNoMax rows to return (default 25, max 200).
utilityYesFERC Form 1 respondent: a name (e.g. "PacifiCorp") or the numeric FERC respondent id (utility_id_ferc1, e.g. 303). Find ids with ferc1_find_utility.
classificationNoOptional statistical classification code filter, e.g. SF, LF, OS, RQ.

Output Schema

NameRequiredDescriptionDefault
noteNo
rowsNo
foundNo
sourceNo
messageNo
utilityNo
currencyNo
ambiguousNo
row_countNo
candidatesNo
data_as_ofNo
attributionNo
report_yearNo
detail_mwh_sumNo
years_availableNo
copy_refreshed_atNo
subtotals_excludedNo
top_counterparties_aggregatedNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive, open-world, so the safety profile is covered. The description adds genuinely non-obvious behavior: rows are sorted by MWh descending, subtotal and total rows are excluded from the row set and reported separately, and the data covers 1994 to date with PUDL as the upstream source. It does not mention pagination behavior beyond the schema's limit, but the sorting and row-exclusion rules are exactly the kind of disclosure that prevents misreads of totals.

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 scope, field list, and behavioral rules are front-loaded, followed by a concrete example question and provenance. It is dense but nearly every clause carries information; the provenance sentence is useful for trust, though the description is longer than strictly needed for a single-utility extract.

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?

With four parameters, full schema coverage, a defined output schema, and clear read-only annotations, the description supplies what remains: temporal coverage, grain (one utility, one year), row ordering, treatment of subtotal/total rows, and data provenance. Nothing an agent needs to call this correctly or interpret totals is missing.

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

Parameters3/5

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

Schema coverage is 100%, so the schema already documents all four parameters including the utility name-or-id form and the year default, making 3 the baseline. The description adds a little by spelling out the full classification code set (RQ, LF, IF, SF, LU, OS, AD) and clarifying that 'purchaser' means the buyer, but it never explains what the individual codes mean, so no real semantic lift beyond the schema.

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?

The description names a specific resource and scope: FERC Form 1 Schedule 310 sales-for-resale rows for a single utility and report year, with the exact fields (purchaser, classification, MWh, revenue). An agent can tell this is a sales-for-resale extract rather than, say, purchased power or a balance sheet. It stops short of explicitly contrasting itself with the sibling ferc1_purchased_power, which is the natural confusion point.

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

Usage Guidelines3/5

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

Usage is conveyed by example rather than instruction: the sample question "who bought the most power for resale from LG&E in 1994" shows the intended analysis, and 'for one utility and report year' implies the required scoping. There is no explicit when-not guidance and no named alternative for closely related FERC queries, leaving routing to inference.

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.