oegb-kraken-mcp

Get meter consumption

get_consumption

Read-onlyIdempotent

Retrieves half-hourly smart-meter electricity or gas consumption by MPAN/MPRN and serial, with optional date filters, grouping, pagination, and ordering.

Instructions

Get smart-meter consumption for an electricity meter (MPAN + serial) or gas meter (MPRN + serial). Needs OCTOPUS_API_KEY. Half-hourly by default. Electricity is in kWh. Gas is in kWh for SMETS1 and m³ for SMETS2. Use group_by to aggregate, and order_by=period for oldest first (default is newest first). Get the identifiers from get_account.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "fuel": "<fuel>",
      "meter_point": "<meter_point>",
      "serial_number": "<serial_number>"
    },
    "name": "get_consumption"
  }
}

Input Schema

Name	Required	Description
`fuel`	Yes
`page`	No	Page number for paginated results (use next_page from the previous call).
`group_by`	No
`order_by`	No
`page_size`	No	Results per page (default 100, max 1500).
`period_to`	No	ISO 8601 datetime, ideally with a Z or offset, e.g. 2026-01-01T00:00:00Z. Without a timezone, Europe/London is assumed.
`meter_point`	Yes	MPAN for electricity, MPRN for gas.
`period_from`	No	ISO 8601 datetime, ideally with a Z or offset, e.g. 2026-01-01T00:00:00Z. Without a timezone, Europe/London is assumed.
`serial_number`	Yes	Meter serial number.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 10, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already cover read-only, idempotent and open-world traits, yet the description still adds genuine context: the OCTOPUS_API_KEY requirement, the half-hourly default granularity, the default newest-first ordering, and the unit variance (kWh for electricity, kWh for SMETS1 gas vs m³ for SMETS2 gas). It does not describe the shape of the returned reading series, but for a read-only tool the added operational facts are substantial.

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?

Five short sentences, front-loaded with what is fetched and the identifier pairs, then auth, defaults, units and ordering. Every sentence carries distinct information; nothing repeats the schema verbatim.

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 9 parameters, three enums and no output schema, the description covers auth, granularity, units, sorting and the identifier source well. The only real gap is what a reading record looks like, which is minor for a read-only consumption fetch.

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 coverage is 67% and the enum fields carry no inline descriptions, so the description usefully explains what group_by does (aggregation) and that order_by=period reverses the default newest-first sort. It also maps meter_point to MPAN/MPRN and fuel to the meter family. period_from/period_to and paging are left to the 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?

States a specific verb and resource ('Get smart-meter consumption') and immediately scopes the two identifier pairs (MPAN + serial for electricity, MPRN + serial for gas). An agent can tell exactly what entity is being read and which resource it touches versus get_tariff_rates or get_product.

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?

Explicitly routes the agent to get_account for identifiers and gives tactical guidance ('use group_by to aggregate', 'order_by=period for oldest first'), which is real when-to guidance. It stops short of naming when to prefer this over rate/pricing tools, so no explicit exclusion is stated.

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

Deploy Server