Skip to main content
Glama
homeassistant-ai

Home Assistant MCP Server

Official
by homeassistant-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Set Device

ha_set_device
DestructiveIdempotent

Update a Home Assistant device's name, area, disabled state, or labels. Renaming the device does not rename its entities, so update entity IDs separately.

Instructions

Update device properties such as name, area, disabled state, or labels.

IMPORTANT: Renaming a device does NOT rename its entities! Device and entity names are independent. To rename entities, use ha_set_entity(new_entity_id=...).

Common workflow for full rename:

  1. ha_set_device(device_id="abc", name="Living Room Sensor") # Rename device

  2. ha_set_entity("sensor.old", new_entity_id="sensor.living_room") # Rename entities separately

EXAMPLES:

  • Rename device: ha_set_device("abc123", name="Living Room Hub")

  • Move to area: ha_set_device("abc123", area_id="living_room")

  • Disable device: ha_set_device("abc123", disabled_by="user")

  • Enable device: ha_set_device("abc123", disabled_by="")

  • Add labels: ha_set_device("abc123", labels=["important", "sensor"])

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
NameRequiredDescriptionDefault
nameNoNew display name for the device (sets name_by_user). '' clears name_by_user and reverts to the integration-provided name. A whitespace-only value acts like '', for clients that cannot send an empty string.
labelsNoLabels to assign to the device (replaces existing labels)
area_idNoArea/room ID to assign the device to. Use empty string '' to unassign. A whitespace-only value acts like '', for clients that cannot send an empty string.
device_idYesDevice ID to update
disabled_byNoSet to 'user' to disable the device, or '' (empty string) to enable it. Omit to leave the disabled state unchanged. A whitespace-only value acts like '', for clients that cannot send an empty string.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv8.7.0
    • changedInput schema / properties / area_id / description
      Previous value: -"Area/room ID to assign the device to. Use empty string '' to unassign."New value: +"Area/room ID to assign the device to. Use empty string '' to unassign. A whitespace-only value acts like '', for clients that cannot send an empty string."
    • changedInput schema / properties / disabled_by / description
      Previous value: -"Set to 'user' to disable the device, or '' (empty string) to enable it. Omit to leave the disabled state unchanged."New value: +"Set to 'user' to disable the device, or '' (empty string) to enable it. Omit to leave the disabled state unchanged. A whitespace-only value acts like '', for clients that cannot send an empty string."
    • changedInput schema / properties / name / description
      Previous value: -"New display name for the device (sets name_by_user)"New value: +"New display name for the device (sets name_by_user). '' clears name_by_user and reverts to the integration-provided name. A whitespace-only value acts like '', for clients that cannot send an empty string."
  2. Changed1 schema field changedv8.6.0
    • changedInput schema / properties / disabled_by / description
      Previous value: -"Set to 'user' to disable, or None/empty string to enable"New value: +"Set to 'user' to disable the device, or '' (empty string) to enable it. Omit to leave the disabled state unchanged."
  3. First observedv7.14.2

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 and idempotentHint=true, but the description adds genuinely non-derivable behavior: the device/entity name independence gotcha and a client-specific timeout workaround that a caller could not infer from schema or annotations. It could still say more about permissions or reversibility, but the added context is substantive.

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 purpose, then an IMPORTANT gotcha, a workflow, and examples — a clean progression. The closing Claude Desktop timeout paragraph is useful but somewhat tangential and lengthens the definition, slightly diluting the otherwise tight structure.

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, return values need not be explained, and the description covers the key mutation gotcha, per-parameter behavior, and invocation examples. Nothing essential to calling 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; the description improves on it by giving concrete invocation examples (disabled_by='user' to disable, '' to enable, labels=[...]) that demonstrate the empty-string conventions in practice. It does not add semantics beyond what the schema already documents in detail, keeping it just above baseline.

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 ('Update device properties') and enumerates exactly what is mutable (name, area, disabled state, labels). It explicitly distinguishes itself from the sibling ha_set_entity, warning that renaming a device does not rename its entities.

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?

Names the alternative tool (ha_set_entity) and the precise condition under which it is needed, then supplies a numbered workflow showing the two calls chained for a full rename. Concrete invocation examples cover each parameter case.

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