Skip to main content
Glama

Manage Radios (Z-Wave / Zigbee / Matter / Thread)

ha_manage_radio
Destructive

Manage Home Assistant Z-Wave, Zigbee, Matter, and Thread radios: run diagnostics, ping nodes, read parameters, and handle inclusion, removal, healing, reconfiguration, firmware updates, provisioning.

Instructions

Manage Home Assistant radios — Z-Wave, Zigbee, Matter, and Thread.

For node diagnostics and network summaries prefer ha_get_device / ha_get_system_health, which mirror 'diagnostics' and 'network_status'. This tool also exposes active 'ping' probes and parameter reads. Z-Wave 'get_config_params' lists cached configuration values/metadata; 'get_config_param' reads one from the cache or explicitly from the device. Neither enables or creates entities. Write actions perform inclusion/commissioning, removal, healing, reconfiguration, firmware updates and credential provisioning.

Caveats: long-running actions (inclusion, rebuild routes, firmware) start the operation and return immediately with long_running=true; completion happens out-of-band. Interactive Z-Wave S2 secure inclusion (read-the- PIN pairing) is not scriptable — use SmartStart/QR provisioning here or the HA UI. HA administrator access is required for parameter reads.

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

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "radio": "<radio>",
      "action": "<action>"
    },
    "name": "ha_manage_radio"
  }
}

Input Schema

NameRequiredDescriptionDefault
radioYesWhich radio to manage.
actionYesOperation to perform. Actions vary per radio; an unknown action returns the supported list for that radio. Common: 'diagnostics', 'network_status', 'ping', 'add'/'commission', 'remove_device', 'reinterview'/'reconfigure', 'firmware_update'.
paramsNoAction-specific parameters (e.g. code, pin, channel, property, value). Z-Wave get_config_param: property (parameter number), endpoint (default 0), property_key (partial-parameter bit mask), refresh (default False; full root parameters only).
confirmNoRequired (True) to run destructive actions (e.g. remove_device, network restore, change_channel, hard_reset, remove_fabric).
device_idNoTarget device (node) for node-scoped actions.
entity_idNoResolve the device from this entity for node-scoped actions.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv9.2.0

TDQS

A4.8/5.0
Behavior5/5

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

Goes well beyond the annotations: long-running actions return immediately with long_running=true and complete out-of-band, S2 interactive pairing is not scriptable, admin access is required for parameter reads, and destructive actions are enumerated. It also clarifies that config-param reads neither create nor enable entities, resolving the mixed read/write nature of a tool whose annotations mark it destructive.

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 purpose, then alternatives, then caveats — a sensible ordering. The final Claude Desktop timeout/manual-approve paragraph is operationally useful but verbose and client-specific, diluting an otherwise tight description.

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?

An output schema exists, so return values need no explanation; the description instead supplies the behavioral context an agent needs (long-running semantics, auth, action-discovery fallback, destructive-action confirmation). Complete for a broad multi-action tool.

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 real meaning: it distinguishes 'get_config_params' (cached list) from 'get_config_param' (cache or explicitly from device), explaining the refresh/scope behavior behind the params. It does not enumerate every action-specific param, but the schema plus the unknown-action-returns-list convention covers that.

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 ('Manage Home Assistant radios') and enumerates the four radio types it covers. It explicitly routes diagnostics to sibling tools ha_get_device / ha_get_system_health, so an agent can distinguish this tool from related readers without opening a 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?

Gives explicit when-to-use-this vs alternatives ('For node diagnostics and network summaries prefer ha_get_device / ha_get_system_health'), and calls out the non-scriptable case (interactive S2 PIN inclusion) with a redirect to SmartStart/QR or the HA UI. Prerequisite (HA administrator access) is stated.

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