Skip to main content
Glama

FindEnergyRates Electricity Rates

by com.findenergyrates
OverviewDiscussionsAdmin

search_plans

Read-onlyIdempotent

Search live residential electricity plans for one utility in one state, ordered cheapest first. state and utility are both required — this API does not support bulk or unscoped export. Results are limited to plans observed within the last 7 days. Read the status field before summarising: no_data_for_scope means we have no recent data, NOT that the market has no plans. Pass usage_kwh to see each plan's price at the EFL-disclosed usage (500, 1000 or 2000 kWh) nearest it: every plan then reports the anchor used, and results are grouped by that anchor, then cheapest first. The price is the plan's own disclosed figure at that anchor — it is not recalculated for the exact usage.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
greenNotrue = 100% renewable only; false = 0% renewable only. Plans whose renewable content is unknown are excluded by both settings.
limitNoRows to return, 1-50.
stateYesTwo-letter state code, e.g. 'OH'. Required.
offsetNoRows to skip, for paging.
utilityYesUtility / TDU name exactly as we publish it, e.g. 'AEP Columbus', 'ONCOR', 'PECO Energy'. Required. If unsure, call with a wrong value once — the error lists every utility we hold for that state.
usage_kwhNoMonthly usage in kWh, 100-5000. Optional. Adds pricing_basis, pricing_basis_kwh, rate_at_usage_cents, anchor_distance_kwh, est_monthly_cost_dollars (always null in this version) and anchor_shape to every plan: the disclosed EFL average price at the anchor (500/1000/2000 kWh) nearest this usage, ties to 1000. anchor_shape says how the three disclosed anchors move with usage: flat, falling, rising, v (1000 below both ends, typically a bill credit) or peak; null if any anchor is missing. Plans that disclose no anchor are returned last as 'unpriced'.
term_monthsNoExact contract length in months, e.g. 12.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / usage_kwh / description
      Previous value: -"Monthly usage in kWh, 100-5000. Optional. Adds pricing_basis, pricing_basis_kwh, rate_at_usage_cents, anchor_distance_kwh and est_monthly_cost_dollars (always null in this version) to every plan: the disclosed EFL average price at the anchor (500/1000/2000 kWh) nearest this usage, ties to 1000. Plans that disclose no anchor are returned last as 'unpriced'."New value: +"Monthly usage in kWh, 100-5000. Optional. Adds pricing_basis, pricing_basis_kwh, rate_at_usage_cents, anchor_distance_kwh, est_monthly_cost_dollars (always null in this version) and anchor_shape to every plan: the disclosed EFL average price at the anchor (500/1000/2000 kWh) nearest this usage, ties to 1000. anchor_shape says how the three disclosed anchors move with usage: flat, falling, rising, v (1000 below both ends, typically a bill credit) or peak; null if any anchor is missing. Plans that disclose no anchor are returned last as 'unpriced'."
  2. Changed1 schema field changed
    • addedInput schema / properties / usage_kwh
      Added value: +{
+  "description": "Monthly usage in kWh, 100-5000. Optional. Adds pricing_basis, pricing_basis_kwh, rate_at_usage_cents, anchor_distance_kwh and est_monthly_cost_dollars (always null in this version) to every plan: the disclosed EFL average price at the anchor (500/1000/2000 kWh) nearest this usage, ties to 1000. Plans that disclose no anchor are returned last as 'unpriced'.",
+  "maximum": 5000,
+  "minimum": 100,
+  "type": "integer"
+}
  3. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond that: results are limited to the last 7 days, the `status` field can mean `no_data_for_scope` rather than no plans, pricing is anchored to EFL-disclosed usage (500/1000/2000 kWh) and not recalculated for exact usage, and unpriced plans are returned last. This is rich, non-obvious behavior that an agent needs to interpret results correctly.

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 dense but well-organized: scope and ordering are front-loaded, then the 7-day window and status caveat, then the optional `usage_kwh` behavior. Every sentence adds information, and the most important constraints (required params, no bulk export) come first. It is longer than the typical description, but the length is justified by the genuinely complex pricing-anchor behavior that would otherwise be a trap for an agent.

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?

For a read-only search tool with 100% schema coverage and no output schema, the description covers everything an agent needs to call it correctly: required scope, result ordering, recency limit, status-field interpretation, and the full semantics of the optional pricing parameter. The sibling tools are different enough (get_ptc_rates, get_utility_by_zip) that no additional differentiation is needed. The only thing not described is the exact output shape, but the absence of an output schema and the detailed field list in the description make that acceptable.

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?

Schema description coverage is 100%, so the schema already documents all 7 parameters. The description adds value by explaining the semantics of `usage_kwh` in depth: how the anchor is chosen (nearest of 500/1000/2000, ties to 1000), what fields are added, what `anchor_shape` means, and that `est_monthly_cost_dollars` is always null. It also clarifies the `utility` parameter's exact-match requirement and the error-based discovery trick. The only minor gap is that it doesn't restate every parameter, but the schema already covers them.

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 states a specific verb ('Search'), a precise resource ('live residential electricity plans'), and a clear scope ('for one utility in one state, ordered cheapest first'). It explicitly distinguishes itself from bulk/unscoped export and names the required scope, so an agent can tell it apart from siblings like get_ptc_rates or get_utility_by_zip without opening the schema.

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?

The description explicitly says both `state` and `utility` are required, warns that the API does not support bulk or unscoped export, and explains when to pass `usage_kwh`. It also gives a concrete fallback for an uncertain utility value ('call with a wrong value once — the error lists every utility we hold for that state'). This is clear when-to-use guidance with an alternative strategy.

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

All FindEnergyRates Electricity Rates toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources