Skip to main content
Glama

Set hot water schedule

hive_set_hot_water_schedule
DestructiveIdempotent

Change the weekly hot water schedule for selected days or day groups, replacing their on/off periods while other days keep current settings. Preview changes first and confirm before applying.

Instructions

Change the weekly hot water schedule. In days, give the periods for the days that change, keyed by day or by weekdays, weekend or every_day (a day wins over a group); other days keep their current periods. Each day has 1 to 6 periods, each a start time (HH:MM, home's local time) and on or off, lasting until the next period starts (before a day's first period, the previous day's last one carries on). This replaces those days' schedule for good, so show the user the new periods and get their go-ahead first. The hot water only follows it in schedule mode.

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": {
      "days": "<days>"
    },
    "name": "hive_set_hot_water_schedule"
  }
}

Input Schema

NameRequiredDescriptionDefault
daysYesThe new periods for the days that change, keyed by day (monday ... sunday) or group (weekdays, weekend, every_day); a day wins over a group. Days left out keep their periods
dry_runNoPreview only: check the call and return the exact requests it would send to Hive, without sending them. Nothing is changed

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.7.0

TDQS

A4.5/5.0
Behavior5/5

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

Annotations already flag destructive=true and idempotent=true, but the description adds real context: the change is permanent for the named days ('for good'), unnamed days are untouched, a user go-ahead is expected, and dry_run previews the exact requests. The carry-over rule and the schedule-mode caveat are behaviours no annotation conveys.

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 the action, then the parameter mechanics, then the caution and mode caveat — a logical order with no filler sentences. The nested parentheticals make it dense, but every clause carries operational meaning.

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 destructive, nested-parameter, no-output-schema mutation tool, it covers what is replaced, what is preserved, the confirmation requirement, and the mode dependency. The only gap is a brief note on what a successful call returns, though dry_run's return is documented in the schema.

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 a baseline of 3 applies; the description goes further by adding the 1-to-6 periods-per-day limit and the inheritance rule that the previous day's last period carries into the morning. Some of its day-keying and day-beats-group wording duplicates 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: 'Change the weekly hot water schedule.' An agent can immediately distinguish it from hive_get_hot_water_schedule (read) and hive_set_heating_schedule (different device) without opening any schema.

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?

Gives concrete preconditions: confirm the new periods with the user first, and the schedule is only honoured while hot water is in schedule mode. It does not explicitly name alternatives (e.g. use hive_set_hot_water_mode to switch modes, or the getter to read first), so routing guidance is implied rather than spelled out.

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