Skip to main content
Glama
Sign In
Home Assistant MCP Server

Home Assistant MCP Server

Official
by homeassistant-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Set Zone

ha_set_zone
Destructive

Create a new Home Assistant zone or update an existing one by providing a zone_id to change only specified fields. Use it to define locations with coordinates, radius, icon, or passive mode.

Instructions

Create or update a Home Assistant zone.

Omit zone_id to create a new zone (name, latitude, longitude required). Provide zone_id to update an existing zone (only specified fields change). Zones defined in YAML, and the home zone, cannot be changed here.

EXAMPLES:

  • Create: ha_set_zone(name="Office", latitude=40.7128, longitude=-74.0060, radius=150, icon="mdi:briefcase")

  • Update: ha_set_zone(zone_id="office", radius=200)

  • Update by entity_id: ha_set_zone(zone_id="zone.office", radius=200)

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.

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

Input Schema

NameRequiredDescriptionDefault
iconNoMaterial Design Icon (e.g., 'mdi:briefcase'). On update, '' clears it, except an icon stored in the zone itself (as the Home Assistant UI stores it; ha_get_zone shows it), which cannot be removed
nameNoDisplay name for the zone
waitNoWait for the zone to be queryable before returning. Set to False for bulk operations.
radiusNoRadius of the zone in meters; Home Assistant uses 100 when it is omitted on create
passiveNoPassive mode: the zone is hidden in the frontend and not used for device tracker state, but automations can still use it (false when omitted on create)
zone_idNoZone ID or entity_id of the zone to update (from ha_get_zone)
latitudeNoLatitude coordinate of the zone center
longitudeNoLongitude coordinate of the zone center

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv9.0.0
    • changedInput schema / properties / icon / description
      Previous value: -"Material Design Icon (e.g., 'mdi:briefcase', 'mdi:school')"New value: +"Material Design Icon (e.g., 'mdi:briefcase'). On update, '' clears it, except an icon stored in the zone itself (as the Home Assistant UI stores it; ha_get_zone shows it), which cannot be removed"
    • changedInput schema / properties / passive / description
      Previous value: -"Passive mode - if True, zone will not trigger enter/exit automations (defaults to False on create)"New value: +"Passive mode: the zone is hidden in the frontend and not used for device tracker state, but automations can still use it (false when omitted on create)"
    • changedInput schema / properties / radius / description
      Previous value: -"Radius of the zone in meters (must be > 0, defaults to 100 on create)"New value: +"Radius of the zone in meters; Home Assistant uses 100 when it is omitted on create"
    • addedInput schema / properties / wait
      Added value: +{
+  "default": true,
+  "description": "Wait for the zone to be queryable before returning. Set to False for bulk operations.",
+  "type": "boolean"
+}
    • changedInput schema / properties / zone_id / description
      Previous value: -"Zone ID to update (use ha_get_zone to find IDs)"New value: +"Zone ID or entity_id of the zone to update (from ha_get_zone)"
  2. Changed4 schema fields changedv8.6.0
    • changedInput schema / properties / latitude / description
      Previous value: -"Latitude coordinate of the zone center (required for create)"New value: +"Latitude coordinate of the zone center"
    • changedInput schema / properties / longitude / description
      Previous value: -"Longitude coordinate of the zone center (required for create)"New value: +"Longitude coordinate of the zone center"
    • changedInput schema / properties / name / description
      Previous value: -"Display name for the zone (required for create)"New value: +"Display name for the zone"
    • changedInput schema / properties / zone_id / description
      Previous value: -"Zone ID to update (omit to create new zone, use ha_get_zone to find IDs)"New value: +"Zone ID to update (use ha_get_zone to find IDs)"
  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=false, so the description's real contribution is the partial-update semantics ('only specified fields change') and the immutability of YAML/home zones. The Claude Desktop timeout-and-hang workaround is unusually specific operational context that cannot be inferred from the schema. It stops short of saying what happens to conflicting existing values or permissions needed, hence not a 5.

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 create/update branching and limitations, followed by three compact, immediately usable examples. The final Claude Desktop paragraph is long and slightly superstitious in tone, but it is distinct operational guidance rather than padding.

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, full annotation coverage, and 100% parameter description coverage, the description only needs to supply semantics and routing, which it does: create vs update, field-level partial semantics, immutability constraints, and examples. Nothing an agent needs in order to call this 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 baseline is 3; the description still earns credit by naming which params are required on create and by showing worked examples for radius/icon and for passing either a zone_id or an entity_id form. It does not add anything about `wait` or `passive` beyond the schema, so it is above baseline but not exhaustive.

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?

Specific verb+resource (create/update a Home Assistant zone) with the create-vs-update branch spelled out in the first two lines. It also carves out scope exclusions (YAML-defined zones and the home zone), which no sibling like ha_get_zone or ha_remove_zone covers, so an agent can select it unambiguously.

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 rule for the two modes: omit zone_id to create (with required fields named), provide zone_id to update (only specified fields change). It also states a hard when-not: zones defined in YAML and the home zone cannot be modified here, which prevents a whole class of misuse.

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