Skip to main content
Glama
Fistacho

ha-nexus-agent

by Fistacho
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Turn on an entity

entities_turn_on
Idempotent

Turn on any Home Assistant entity, optionally applying light-only color or brightness. Validates the domain first, converts mireds to Kelvin, and returns changed states.

Instructions

Turn on an entity, optionally with light-only color and brightness options.

Calls <domain>.turn_on for the entity's domain over HTTP. If any of brightness, color_temp, color_temp_kelvin or rgb_color is given for a non-light entity, the service is not called at all — HA's own turn_on for other domains (e.g. switch) rejects unknown fields, so this checks the domain first. A given color_temp (mireds) is converted to Kelvin (round(1_000_000 / mireds)) since HA's light.turn_on no longer accepts mireds.

Use when: turning on any entity, with or without light color/brightness. Not for: a dedicated light color/brightness change without an on/off intent — use services_set_light_color; an input_boolean-only helper — helpers_set_input_boolean is the domain-specific equivalent. Returns: the list of changed states from Home Assistant, or an error dict. Errors: {"error": "..."} when a light-only option is given for a non-light domain.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
entity_idYesFull entity ID to turn on, e.g. 'light.kitchen'.
rgb_colorNoLight RGB color as [r, g, b], each 0-255, light-only option.
brightnessNoLight brightness, 0-255. Light-only; passing it for a non-light entity returns an error.
color_tempNoDeprecated mired color temperature, light-only. Converted to Kelvin before the call; prefer color_temp_kelvin.
color_temp_kelvinNoLight color temperature in Kelvin, light-only option.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changedv0.25.1
    • addedInput schema / properties / brightness / description
      Added value: +"Light brightness, 0-255. Light-only; passing it for a non-light entity returns an error."
    • addedInput schema / properties / color_temp / description
      Added value: +"Deprecated mired color temperature, light-only. Converted to Kelvin before the call; prefer color_temp_kelvin."
    • addedInput schema / properties / color_temp_kelvin
      Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Light color temperature in Kelvin, light-only option."
+}
    • addedInput schema / properties / entity_id / description
      Added value: +"Full entity ID to turn on, e.g. 'light.kitchen'."
    • addedInput schema / properties / rgb_color / description
      Added value: +"Light RGB color as [r, g, b], each 0-255, light-only option."
    • addedOutput schema / properties / result / anyOf
      Added value: +[
+  {
+    "items": {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "additionalProperties": true,
+    "type": "object"
+  }
+]
    • removedOutput schema / properties / result / items
      Removed value: -{
-  "additionalProperties": true,
-  "type": "object"
-}
    • removedOutput schema / properties / result / type
      Removed value: -"array"
  2. First observedv0.3.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations declare the safety profile (readOnly=false, idempotent=true, destructive=false), and the description adds substantial context beyond them: the domain-first check, that the service is not called at all when light-only options hit a non-light entity, and the mireds-to-Kelvin conversion formula. This is exactly the kind of behavioral disclosure the dimension rewards.

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 core action, then organized into rationale, use/not-for, returns, and errors. Slightly long, but each section carries distinct information; the conversion and domain-check details earn their place.

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 an output schema present, the description need not explain return values, yet it briefly notes the changed-states return and, importantly, the error shape. Combined with the domain-routing and conversion behavior, an agent has everything needed to call 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?

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning beyond the schema: the domain-gating interaction (light-only fields reject non-light entities) and the color_temp conversion rule with its formula. It clarifies how parameters interact rather than just restating them.

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+resource ('Turn on an entity') and immediately scopes it with the light-only option qualifier. It names the underlying service call and distinguishes itself from siblings like services_set_light_color and helpers_set_input_boolean.

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?

Explicit 'Use when' and 'Not for' sections name two concrete alternatives (services_set_light_color for color-only changes, helpers_set_input_boolean for input_boolean) with the conditions that select them. Nothing is left to inference.

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