Skip to main content
Glama

Compare tariffs on your usage

octopus_compare_tariffs
Read-only

Re-price your half-hourly smart meter readings on other Octopus tariffs and compare unit and standing costs, including VAT, for electricity import/export or gas.

Instructions

Re-price your actual half-hourly smart meter readings on other Octopus tariffs, such as Agile, Go, Cosy, Tracker, Flux or a fixed deal, and compare them with what the tariffs you were on would have cost: unit costs at each tariff's real rate for every half-hour, plus standing charges, including VAT. Give product codes from octopus_list_products (your meter's region and fuel are used) or full tariff codes. Works for electricity import, export (compares earnings) and gas. These are estimates from past usage, which would change if you shifted it to suit a tariff; they ignore eligibility (Go and Intelligent Go need an EV or charger, Cosy a heat pump), exit fees, discounts and credits. Half-hours a tariff has no rate for (for example before a product existed) are left out and counted.

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": {
      "products": "<products>"
    },
    "name": "octopus_compare_tariffs"
  }
}

Input Schema

NameRequiredDescriptionDefault
toNoEnd: a date (inclusive, the whole day) or date and time (default the end of yesterday)
fromNoStart of the usage to re-price: a date (YYYY-MM-DD, UK time) or date and time (default 30 days ago)
fuelNoelectricity (default) or gas
serialNoA specific meter serial number (default: the meter point's meter that has readings)
productsYesTariffs to compare, up to 8: product codes like AGILE-24-10-01 or GO-VAR-22-10-14 (from octopus_list_products; the region and fuel come from your meter), or full tariff codes like E-1R-AGILE-24-10-01-C
directionNoFor electricity: import (default, what you use) or export (what you send to the grid, e.g. from solar panels)
gas_unitsNoOverride the units a gas meter reports in: kwh or m3 (default: as Octopus says for the meter, otherwise m3)
meter_pointNoA specific MPAN (electricity) or MPRN (gas), when the account has several (see octopus_get_account)
account_numberNoAccount number like A-1234ABCD (default OCTOPUS_ACCOUNT, or the only account the API key can see)
calorific_valueNoGas calorific value in MJ/m³ for converting m³ to kWh (default 39.5; your bill shows the actual value)

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.4.1

TDQS

A4.5/5.0
Behavior5/5

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

Annotations only declare read-only, closed-world and non-idempotent; the description adds substantive behavior the annotations cannot convey: results are estimates from past usage, ignore eligibility rules (EV for Go/Intelligent Go, heat pump for Cosy), omit exit fees, discounts and credits, and silently drop half-hours with no applicable rate while counting them. Export comparisons are framed as earnings rather than costs, and VAT and standing charges are stated to be included.

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 core action is front-loaded in the first sentence, with caveats and input sourcing following in a logical order. It is a dense single block with several clauses stacked in the final sentence, so it is efficient but slightly heavy to parse; no sentence is genuinely redundant.

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?

For a 10-parameter tool with no output schema, the description is nearly complete: it says what is computed (per-half-hour unit costs plus standing charges, VAT-inclusive), how missing data is handled, and the limits of the estimate. The remaining gap is the shape of the returned comparison itself, which the absent output schema leaves entirely to the description to imply.

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 100%, so the baseline is 3, but the description adds real meaning: product codes may be short codes with region/fuel inferred from the meter or full tariff codes, and the export direction changes the comparison to earnings. It also implies the up-to-8 product limit and the meter-point/serial fallbacks are handled contextually, though it does not elaborate on from/to, gas_units or calorific_value beyond 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?

The description opens with a specific verb and resource: re-price half-hourly smart meter readings against other Octopus tariffs and compare with the tariffs actually paid. It names concrete products (Agile, Go, Cosy, Tracker, Flux, fixed), states the covered domains (electricity import, export, gas), and clearly distinguishes itself from consumption/rate lookups by being a comparison over historical usage.

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 gives a clear entry condition and prerequisite: supply product codes from octopus_list_products, or full tariff codes, with region and fuel taken from the meter. It also explains what the comparison ignores (eligibility, exit fees, discounts, credits), which shapes when the result is appropriate. It stops short of explicitly excluding sibling tools such as unit-rate or cheapest-slot lookups, so no when-not guidance is stated.

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