Skip to main content
Glama

Plan a charging or heating schedule

octopus_plan_schedule
Read-only

Plan when to charge a home battery, car, or heat pump by spreading required energy across cheap half-hours in a tariff period. Returns start/stop times and compares cost with starting now.

Instructions

Plan when to charge a home battery or car, or run a heat pump, so that a given amount of energy goes in as cheaply as possible on a time-of-use tariff such as Cosy, Flux, Go, Intelligent Go or Agile. Unlike octopus_find_cheapest_slots, which finds one continuous block, this spreads the energy over the cheapest half-hours the device's power allows, across every cheap window in the period, and merges them into start and stop times. Also lists the tariff's price windows over the period (for example Cosy's three cheap windows and its peak) and compares the cost with starting straight away. It only plans; it doesn't change any device. Only uses published prices. Choose the tariff by tariff_code, by product_code with region or postcode, or leave them out for the account's current tariff.

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": {
      "energy_kwh": "<energy_kwh>",
      "power_kw": "<power_kw>"
    },
    "name": "octopus_plan_schedule"
  }
}

Input Schema

NameRequiredDescriptionDefault
toNoWhen it must be done by: a date and time, or a date (inclusive; default as far ahead as prices are published)
fromNoEarliest start: a date and time, or now (default now)
fuelNoelectricity (default) or gas
regionNoWith product_code: the region letter A to P (see octopus_find_region)
postcodeNoWith product_code, instead of region: a UK postcode, used to look up the region
power_kwYesThe most the device draws, in kW: the battery's charge rate, the heat pump's input power or the car charger's rating (7 for most home chargers)
directionNoWith the account's tariff: import (default) or export
energy_kwhYesEnergy to put in over the period, in kWh: for example 9 to charge a 10 kWh battery from 10% to full, or a heat pump's expected electricity use for the day
tariff_codeNoA tariff code like E-1R-AGILE-24-10-01-C (from octopus_get_product or octopus_get_account)
product_codeNoInstead of tariff_code: a product code like AGILE-24-10-01 (see octopus_list_products), with region or postcode
account_numberNoWith none of the above, the account's current tariff is used: account number like A-1234ABCD (default OCTOPUS_ACCOUNT or the only account)

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.4.1

TDQS

A4.6/5.0
Behavior4/5

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

Goes well beyond the readOnlyHint/openWorldHint/idempotentHint annotations: it discloses what the output contains (merged start/stop times, the tariff's price windows, a cost comparison against starting immediately) and the data constraint that only published prices are used. It does not explain why the call is non-idempotent (presumably time/price dependent), which is the one behavioral gap.

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?

Front-loaded with purpose and the sibling contrast, then output shape, then tariff selection. Four dense sentences with almost no filler, though the tariff-selection sentence partly repeats what the schema fields already say.

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 11 parameters and no output schema, the description carries the burden of describing return content (start/stop times, price windows, cost comparison) and does so, plus it states the read-only, published-prices-only constraint. Nothing needed to call it correctly is missing.

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: it explains that tariff can be chosen by tariff_code, by product_code with region/postcode, or omitted for the account's current tariff, which clarifies the mutual exclusivity and defaulting logic the flat schema doesn't state. It also ties energy_kwh and power_kw to the spreading algorithm's behavior.

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?

Opens with a specific verb and resource ('Plan when to charge a home battery or car, or run a heat pump') plus the optimization objective, and explicitly distinguishes itself from octopus_find_cheapest_slots by describing the spreading-versus-single-block difference. An agent can route between the two without opening either 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?

Names the closest alternative and the condition that selects it ('unless you want one continuous block, use octopus_find_cheapest_slots'). Also states the tariff selection paths (tariff_code, product_code plus region/postcode, or account default) and the explicit boundary 'It only plans; it doesn't change any device.'

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