Skip to main content
Glama

Elecz Electricity Price Signal API

by io.github.zemloai-ctrl

cheapest_hours

Read-only

TIMING tool. Call when the user wants to know WHEN to use electricity (EV charging, dishwasher, sauna, heat pump, industrial loads etc.). Also good for "is electricity cheap now?" questions.

Key agent fields:
- energy_state ("cheap" / "normal" / "expensive" / "negative")
- current_hour_is_cheap (bool)
- hours_until_next_cheap (0 = start now)
- cheap_window_ends, next_cheap_hour (UTC)
- best_3h_window (always the true-optimal fixed 3h/6h window)
- best_window (true-optimal CONTIGUOUS window sized to the `hours` param —
  use this, not cheap_hours, for "run this appliance for N hours straight"
  decisions; null if fewer than `hours` forecast rows are available)
- recommendation ("run_high_consumption_tasks" / "normal_usage" / "avoid")

Note: cheap_hours lists the N individually cheapest hours in the forecast
and is NOT guaranteed to be contiguous — it can include hours scattered
across the day, or (when the forecast has fewer than `hours` rows
available) can end up including comparatively expensive hours simply
because there aren't enough cheaper ones yet published. Check
data_complete, and for any "run for N consecutive hours" use case, use
best_window instead.

All timestamps are UTC — convert to local time before presenting.
data_complete: false = treat signals with caution.
Not available: AU, NZ, KR, KR-JEJU, ZA, PH-LUZ, PH-VIS, PH-MIN.

Args:
    zone: Any supported zone (see spot_price for full list).
          Use exact codes only — do not guess or abbreviate.
          AU, NZ, KR, KR-JEJU, ZA, PH-* return available: false.
    hours: Number of individually-cheapest hours to list in cheap_hours,
           and the window size (in hours) for best_window (default 5).
    window: Hours to look ahead (default 24).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
zoneNoElectricity market zone code. AU, NZ, KR, ZA, PH-* return available: false. See spot_price for full zone list.FI
hoursNoNumber of cheapest hours to return. Default: 5. Range: 1–24.
windowNoHours ahead to look. Default: 24. Range: 1–48.

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -{
-  "properties": {
-    "result": {
-      "title": "Result",
-      "type": "string"
-    }
-  },
-  "required": [
-    "result"
-  ],
-  "title": "_mcp_cheapestOutput",
-  "type": "object"
-}New value: +null
  2. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "properties": {
+    "result": {
+      "title": "Result",
+      "type": "string"
+    }
+  },
+  "required": [
+    "result"
+  ],
+  "title": "_mcp_cheapestOutput",
+  "type": "object"
+}
  3. Changed3 schema fields changed
    • addedInput schema / properties / hours / description
      Added value: +"Number of cheapest hours to return. Default: 5. Range: 1–24."
    • addedInput schema / properties / window / description
      Added value: +"Hours ahead to look. Default: 24. Range: 1–48."
    • addedInput schema / properties / zone / description
      Added value: +"Electricity market zone code. AU, NZ, KR, ZA, PH-* return available: false. See spot_price for full zone list."
  4. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare readOnlyHint=true, but the description adds substantial behavioral context beyond that: cheap_hours is not contiguous, best_window should be used for contiguous periods, data_complete caution, UTC timestamp convention, and unsupported zones. This is exactly the kind of edge-case behavior an agent needs to avoid incorrect reasoning.

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 long but well-structured with a clear call-to-action, key fields section, and usage notes. It is dense with essential information and not redundant. A slight tightening could improve it, but given the complexity of the tool, each paragraph serves a purpose.

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 no output schema and moderate parameter count, the description compensates by enumerating the agent-facing fields, their semantics (including the non-contiguity warning), timezone handling, data completeness signals, and regional unavailability. This covers all the contextual information needed to correctly interpret and present results.

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 descriptions cover all three parameters, so baseline is 3. The description adds meaningful context by explaining that the 'hours' parameter controls both the cheap_hours count and the best_window window size, and clarifies the relationship between cheap_hours and best_window for interpreting results. This enhances the schema's basic info.

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 clearly identifies the tool as a 'TIMING tool' for determining when to use electricity, with specific use cases (EV charging, dishwasher, etc.) and covers questions like 'is electricity cheap now?'. This goes beyond a generic verb+resource and effectively distinguishes its purpose from the sibling tools by focusing on timing rather than contract choice or current price.

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?

Provides explicit when-to-use guidance: 'Call when the user wants to know WHEN to use electricity' plus concrete examples. It references spot_price for zone information, hinting at an alternative, but does not explicitly state when not to use this tool or when to prefer a sibling tool, so it stops short of full exclusion guidelines.

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

All Elecz Electricity Price Signal API toolsInspect
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.9/5.0
Disambiguation5/5

Each tool serves a clearly distinct purpose: spot_price for current price, cheapest_hours for timing, and best_energy_contract for contract switching advice. The descriptions even include tool priority guidance to prevent confusion.

Naming Consistency5/5

All tool names follow the same lowercase_with_underscores style and are descriptive (best_energy_contract, cheapest_hours, spot_price). No mixed conventions or vague verbs.

Tool Count5/5

Three tools is well-scoped for an electricity price API, covering the essential user needs without bloat. Each tool earns its place.

Completeness5/5

The set covers the full lifecycle of electricity price inquiries: current price, when to use electricity, and contract decisions. No obvious gaps in the stated domain.

Resources