Skip to main content
Glama

Control a light

hive_set_light
Idempotent

Switch a Hive light on or off and set its brightness, white colour temperature, or colour using hue and saturation for tuneable and colour bulbs.

Instructions

Switch a Hive light on or off, and set its brightness, its white colour temperature (tuneable and colour bulbs) or its colour as hue and saturation (colour bulbs).

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": "hive_set_light"
  }
}

Input Schema

NameRequiredDescriptionDefault
onNotrue to switch on, false to switch off. Setting a brightness, colour temperature or colour also switches the light on
hueNoColour, for colour bulbs: hue in degrees, 0 to 359 (0 red, 120 green, 240 blue). Switches the bulb to colour mode; the saturation is kept unless given
lightNoLight, by name or ID (see hive_list_smart_devices). Can be left out when there's only one
dry_runNoPreview only: check the call and return the exact requests it would send to Hive, without sending them. Nothing is changed
brightnessNoBrightness in percent, 5 to 100 (rounded to the nearest 5, as the Hive app does). With hue or saturation, the colour's brightness
saturationNoColour, for colour bulbs: saturation in percent, 0 (white) to 100 (full colour). Switches the bulb to colour mode; the hue is kept unless given
colour_temperatureNoWhite colour temperature in kelvin, for tuneable and colour bulbs: about 2700 (warm) to 6500 (cool)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.7.0

TDQS

A4/5.0
Behavior3/5

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

Annotations already declare the important traits (writable, idempotent, non-destructive, closed-world), so the bar is lower. The description itself adds no side-effect disclosure beyond the capability list; the genuinely useful behaviours (setting brightness/colour also switches the light on, mode switching on hue/saturation, rounding to nearest 5, dry_run preview) live in the schema, not here. Nothing contradicts the annotations, but the description earns little extra credit.

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?

A single front-loaded sentence that enumerates every capability in priority order with parenthetical constraints. No filler, no restatement of the title, nothing to trim.

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 7-parameter, zero-required tool with no output schema, the description covers the whole action space and the schema covers all remaining detail, including the single-light default and the dry_run preview. It is nearly complete; only a note on what a successful call returns or how partial failures behave is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so per-parameter meaning, ranges and interactions are already fully documented by the structured data. The description summarises the same capability set at a higher level and adds no syntax, format, or edge-case detail beyond it, which is the baseline case.

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 ('Switch a Hive light on or off') plus the full capability surface (brightness, white colour temperature, hue/saturation colour). The 'light' scoping clearly separates it from siblings such as hive_set_plug or hive_set_heating_temperature without needing to name them.

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 clear applicability guidance by bulb type — colour temperature is flagged '(tuneable and colour bulbs)' and hue/saturation colour '(colour bulbs)' — which tells the agent which parameters are valid for which hardware. It stops short of explicit when-to-use/when-not framing against sibling tools, so it is strong context rather than full routing guidance.

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