Skip to main content
Glama
Fistacho

ha-nexus-agent

by Fistacho
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Set light color and brightness

services_set_light_color
Idempotent

Set a light's color, color temperature, and brightness in one Home Assistant call. Adjust color or dimming for any light, whether currently on or off.

Instructions

Set a light's color, color temperature and/or brightness in one call.

Calls light.turn_on with only the given fields set (rgb_color, color_temp_kelvin, brightness); a given color_temp (mireds) is converted to Kelvin (round(1_000_000 / mireds)) first, since HA's light.turn_on no longer accepts mireds.

Use when: adjusting a light's color/brightness, whether it is currently on or off — light.turn_on also turns it on. Not for: a plain on/off/toggle with no color change — use entities_turn_on, which supports the same brightness/color options for lights alongside generic on/off for any domain. Returns: the list of states changed by the call.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
entity_idYesFull light entity ID to change, e.g. 'light.kitchen'.
rgb_colorNoTarget RGB color as [r, g, b], each 0-255. Omit to leave color unchanged.
brightnessNoTarget brightness, 0-255. Omit to leave brightness unchanged.
color_tempNoDeprecated mired color temperature. Converted to Kelvin; prefer color_temp_kelvin.
color_temp_kelvinNoTarget color temperature in Kelvin. Omit to leave it unchanged.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv0.25.1
    • addedInput schema / properties / brightness / description
      Added value: +"Target brightness, 0-255. Omit to leave brightness unchanged."
    • addedInput schema / properties / color_temp / description
      Added value: +"Deprecated mired color temperature. Converted to Kelvin; prefer color_temp_kelvin."
    • addedInput schema / properties / color_temp_kelvin
      Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Target color temperature in Kelvin. Omit to leave it unchanged."
+}
    • addedInput schema / properties / entity_id / description
      Added value: +"Full light entity ID to change, e.g. 'light.kitchen'."
    • addedInput schema / properties / rgb_color / description
      Added value: +"Target RGB color as [r, g, b], each 0-255. Omit to leave color unchanged."
  2. First observedv0.3.0

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the mutation safety profile is covered. The description adds substantial behavioral context beyond annotations: it calls light.turn_on with only the given fields, converts deprecated mireds to Kelvin, turns the light on if it is off, and returns the list of changed states. This is unusually transparent for a service wrapper.

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?

The description is front-loaded with the core action, then structured into implementation notes, use-when, not-for, and returns. Each section earns its place and there is no redundant 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?

The tool has an output schema, rich annotations, and full schema coverage, so the description does not need to explain return values. It nevertheless completes the picture by covering behavior, parameter conversion, light-on side effect, and sibling routing. Nothing material is missing for correct invocation.

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 description coverage is 100%, so the schema already documents each parameter thoroughly. The description still adds semantic value by explaining that only provided fields are forwarded and by giving the exact mired-to-Kelvin conversion formula, which the schema only alludes to. It does not add meaning for entity_id, but the parameter contract is otherwise clear.

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 states a specific verb and resource: set a light's color, color temperature, and/or brightness in one call. It distinguishes itself from the sibling entities_turn_on by explaining that entities_turn_on is for plain on/off/toggle without color changes. An agent can identify the tool's exact purpose without opening the 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?

It gives explicit when-to-use guidance: adjusting color/brightness whether the light is on or off. It also gives explicit when-not-to-use guidance: use entities_turn_on for plain on/off/toggle with no color change. This directly routes the agent between competing siblings.

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

Deploy Server

Other Tools