Skip to main content
Glama

Find the cheapest times

octopus_find_cheapest_slots
Read-only

Locate low-cost continuous electricity-use blocks and individual half-hours on Octopus time-of-use tariffs, such as Agile, to schedule appliances, batteries, or EV charging.

Instructions

Find the cheapest time to use electricity on a time-of-use tariff such as Agile: the cheapest continuous block of a given length (for a dishwasher, washing machine, battery or car), runner-up blocks that don't overlap, and the cheapest individual half-hours. Only looks at prices Octopus has published (Agile prices for the next day usually appear around 4pm). 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

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_find_cheapest_slots"
  }
}

Input Schema

NameRequiredDescriptionDefault
toNoLatest end: a date and time, or a date (inclusive; default as far ahead as prices are published)
kwhNoEnergy the job will use, in kWh (for example 7 for a dishwasher and washing machine), to estimate its cost in the best block
fromNoEarliest start: a date and time, or now (default now)
fuelNoelectricity (default) or gas
slotsNoAlso list this many of the cheapest individual half-hours, which need not be together (default 6; 0 for none)
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
directionNoWith the account's tariff: import (default) or export
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)
duration_hoursNoLength of the continuous block to find, in hours, in steps of 0.5 (default 2)

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.4.1

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so the description's job is to add operational context, and it does: data-availability limits, the ~4pm publication timing for next-day Agile prices, and the tariff-resolution fallback chain. It does not explain why idempotentHint=false (the moving 'from now' default), which is the one behavioral nuance left implicit.

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 output contents are front-loaded in the first sentence and each subsequent sentence adds distinct information (data limits, tariff selection paths). The first sentence is overloaded with parentheticals, which slightly hurts scannability, but no sentence is filler.

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?

For a 12-parameter tool with no required parameters and no output schema, the description covers what matters: what is returned, how tariff selection resolves, and when price data will be available. The schema handles the rest at 100% coverage, so an agent has everything needed to call it correctly.

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?

Although schema coverage is already 100%, the description adds genuine semantic structure that the schema lacks: the fact that tariff_code, product_code+region/postcode, and the account default are alternative selection paths rather than additive parameters. It also clarifies the purpose of the block length and kWh inputs in human terms (cost estimate for a job), which helps an agent pick sensible values.

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 names a specific verb and resource ('find the cheapest time to use electricity') and then enumerates exactly what is returned: the cheapest continuous block of a given length, non-overlapping runner-up blocks, and the cheapest individual half-hours. The domain ('time-of-use tariff such as Agile') and the appliance framing (dishwasher, washing machine, battery, car) make it immediately distinguishable from a greener-slots or unit-rates tool.

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 concrete when-to-use framing (sizing a block for an appliance) and spells out the three mutually exclusive ways to select a tariff, including the default to the account's current tariff. The caveat that it 'only looks at prices Octopus has published' with next-day prices appearing around 4pm is a useful boundary. It stops short of explicitly excluding alternatives such as octopus_find_greener_slots when carbon rather than cost is the goal.

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