Home Assistant MCP Server

Official

by homeassistant-ai

Overview Schema Source Related Servers Discussions Admin

Python

Remote

Create or Update Label

ha_config_set_label

Destructive

Create or update Home Assistant labels to tag entities, devices, and areas, then apply them to areas for cross-domain organization.

Instructions

Create or update a Home Assistant label.

Creates a new label if label_id is not provided, or updates an existing label if label_id is provided. Labels are a cross-domain tagging system for entities, devices, and areas.

EXAMPLES:

Create: ha_config_set_label("Security", color="red", icon="mdi:shield", description="Security-related devices")
Update: ha_config_set_label("Updated Name", label_id="my_label_id", color="blue")
Create and apply to areas: ha_config_set_label("Site Home", areas=["kitchen", "living_room"])

After creating a label, use ha_set_entity(labels=["label_id"]) to assign it to entities, ha_set_device(labels=["label_id"]) for devices, or ha_set_area_or_floor(kind="area", labels=["label_id"]) for areas (replaces the area's set).

If a Claude Desktop user gets a 4-minute timeout with no result on this call, read the target back before repeating it, and tell them to wait a few seconds before clicking the manual-approve button, as clicking it too quickly is known to cause hangs in Claude Desktop. This workaround is specific to Claude Desktop.

Input Schema

TableJSON Schema

Name	Required	Description
`icon`	No	Material Design Icon (e.g., 'mdi:tag', 'mdi:label')
`name`	Yes	Display name for the label
`areas`	No	Area IDs to apply this label to (adds the label without removing existing ones). Omit to leave area assignments unchanged; an empty list is a no-op (assigns nothing and removes nothing). To clear an area's labels use ha_set_area_or_floor(kind='area', labels=[]).
`color`	No	Color for the label (e.g., 'red', 'blue', 'green', or hex like '#FF5733')
`label_id`	No	Label ID for updates.
`description`	No	Description of the label's purpose

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv8.6.0Oct 1, 2026

addedInput schema / properties / areas

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Area IDs to apply this label to (adds the label without removing existing ones). Omit to leave area assignments unchanged; an empty list is a no-op (assigns nothing and removes nothing). To clear an area's labels use ha_set_area_or_floor(kind='area', labels=[])."
+}

changedInput schema / properties / label_id / description

Previous value: -"Label ID for updates. If not provided, creates a new label."New value: +"Label ID for updates."

First observedv7.14.2Jul 29, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=false, so the safety profile is carried. The description still adds real behavioral context beyond that: the Claude Desktop timeout/hang workaround, and the subtlety that area assignment is additive rather than replacing. It does not, however, spell out what an update does to fields not supplied.

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 core rule is front-loaded in the first sentence and examples are compact and scannable. The closing Claude Desktop paragraph is long and interrupts flow, but it carries non-obvious operational information rather than 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?

With an output schema present and annotations covering safety, the description supplies what is left: create/update semantics, field examples, assignment follow-ups, and a deployment-specific failure mode. Nothing an agent needs to invoke it correctly is missing.

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 genuine meaning: label_id's presence is the create-vs-update switch, plus three worked examples showing name/color/icon/description/areas combinations. That is more than the schema's terse per-field strings convey.

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 (create/update) and resource (Home Assistant label), and the branching rule is explicit: creates when label_id is absent, updates when it is present. It also characterizes labels as a cross-domain tagging system for entities, devices, and areas, distinguishing it from siblings like ha_config_set_category or ha_config_set_group.

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?

Gives explicit when-to-use guidance (create vs update driven by label_id) and names the follow-up tools for applying the label to entities, devices, and areas. It also routes the agent elsewhere for clearing an area's labels (ha_set_area_or_floor with labels=[]), so the exclusion path is covered too.

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

Deploy Server