Skip to main content
Glama

Live electricity demand

octopus_get_live_usage
Read-only

Retrieve near real-time electricity readings from an Octopus Home Mini smart meter, including current demand in watts and energy used per interval; requires a paired Home Mini.

Instructions

Get near real-time electricity readings from the smart meter through an Octopus Home Mini: current demand in watts and energy used in each interval. Needs a Home Mini paired with the smart meter; without one this returns no data. Readings are typically a few seconds to a few minutes old.

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": "octopus_get_live_usage"
  }
}

Input Schema

NameRequiredDescriptionDefault
hoursNoHow far back to look, in hours; fractions allowed, for example 0.25 for 15 minutes (default 1, at most 24)
limitNoReturn at most this many readings, the most recent (default 60)
groupingNoReading interval: TEN_SECONDS, ONE_MINUTE, FIVE_MINUTES, HALF_HOURLY or HOURLY (default ONE_MINUTE up to an hour, FIVE_MINUTES beyond)
device_idNoSmart meter device ID (default: the electricity import meter's, from octopus_get_account)
account_numberNoAccount number like A-1234ABCD (default OCTOPUS_ACCOUNT, or the only account the API key can see)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • addedInput schema / properties / hours
      Added value: +{
      +  "description": "How far back to look, in hours; fractions allowed, for example 0.25 for 15 minutes (default 1, at most 24)",
      +  "type": "number"
      +}
    • addedInput schema / properties / limit
      Added value: +{
      +  "description": "Return at most this many readings, the most recent (default 60)",
      +  "type": "integer"
      +}
    • removedInput schema / properties / max_rows
      Removed value: -{
      -  "description": "Return at most this many readings, the most recent (default 60)",
      -  "type": "integer"
      -}
    • removedInput schema / properties / minutes
      Removed value: -{
      -  "description": "How far back to look, in minutes (default 60, at most 1440)",
      -  "type": "integer"
      -}
  2. First observedv0.4.1

TDQS

A4/5.0
Behavior4/5

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

Annotations already cover read-only, non-open-world, and non-idempotent semantics, and the description adds genuinely non-structured context: hardware dependency, the empty-result failure mode, and data staleness ('a few seconds to a few minutes old'). It does not explain why the call is non-idempotent or how the empty case is signaled to the caller, keeping it below a 5.

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

Conciseness5/5

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

Three short sentences, front-loaded with what the tool returns, then the precondition, then data freshness. No filler and no repetition of schema content.

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 covers the shape of the returned data (watts demand, per-interval energy), freshness, and the empty-result condition, which is most of what an agent needs. Minor gaps remain around how the empty case is surfaced and the default lookback behavior when hours is omitted.

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 description coverage is 100% and every parameter, including the grouping enum values and defaults, is fully documented in the schema. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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 gives a specific verb and resource ('Get near real-time electricity readings from the smart meter') plus the exact channel (Octopus Home Mini) and payload ('current demand in watts and energy used in each interval'). The 'near real-time' framing implicitly separates it from the historical octopus_get_consumption sibling, but no sibling is named, so differentiation is left to inference.

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?

It states a hard precondition and the resulting behavior when unmet ('Needs a Home Mini paired with the smart meter; without one this returns no data'), which effectively tells the agent when this tool is and isn't usable. It does not route to an alternative (e.g. historical consumption) for accounts without a Home Mini, so the alternatives half of the guideline is missing.

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