Skip to main content
Glama
homeassistant-ai

Home Assistant MCP Server

Official
by homeassistant-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Get Device (incl. Zigbee/ZHA/Z2M, Z-Wave and Matter)

ha_get_device
Read-onlyIdempotent

Retrieve Home Assistant device details, including Zigbee and Z-Wave, by ID, entity, area, or integration. List paginated devices or fetch full info for one device.

Instructions

Get device information with pagination, including Zigbee (ZHA/Z2M) and Z-Wave JS devices.

Without device_id/entity_id: Lists devices with optional filters and pagination. With device_id or entity_id: Returns full detail for that specific device.

List devices (paginated):

  • First page: ha_get_device()

  • Next page: ha_get_device(offset=50)

  • By area: ha_get_device(area_id="living_room")

  • By integration: ha_get_device(integration="zigbee2mqtt")

  • Full details in list: ha_get_device(detail_level="full", limit=10)

Single device lookup (always full detail):

  • By device_id: ha_get_device(device_id="abc123")

  • By entity_id: ha_get_device(entity_id="light.living_room")

Zigbee: integration="zha" or "zigbee2mqtt". Returns ieee_address, radio metrics. Z-Wave: integration="zwave_js". Returns node_id, node_status. Matter: integration="matter". Returns node_diagnostics (network type, reachability, IPs, fabrics). For management use ha_manage_radio.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoMax devices to return per page in list mode
offsetNoNumber of devices to skip for pagination
area_idNoFilter devices by area ID (e.g., 'living_room')
device_idNoDevice ID to retrieve details for.
entity_idNoEntity ID to find the associated device for (e.g., 'light.living_room')
integrationNoFilter devices by integration: 'zha', 'zigbee2mqtt', 'zwave_js', 'mqtt', 'hue', etc.
detail_levelNo'summary': basic device info and protocol identifiers. 'full': in list mode also include each device's entities. Single-device lookups always return full detail, including radio metrics, node status and Matter diagnostics.summary
manufacturerNoFilter devices by manufacturer name (e.g., 'Philips')

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv8.6.0
    • changedInput schema / properties / detail_level / description
      Previous value: -"'summary': basic device info and protocol identifiers (default for list mode). 'full': include entities and all integration details. Single device lookups always return full detail."New value: +"'summary': basic device info and protocol identifiers. 'full': in list mode also include each device's entities. Single-device lookups always return full detail, including radio metrics, node status and Matter diagnostics."
    • changedInput schema / properties / device_id / description
      Previous value: -"Device ID to retrieve details for. If omitted, lists devices."New value: +"Device ID to retrieve details for."
    • changedInput schema / properties / limit / description
      Previous value: -"Max devices to return per page in list mode (default: 50)"New value: +"Max devices to return per page in list mode"
    • changedInput schema / properties / offset / description
      Previous value: -"Number of devices to skip for pagination (default: 0)"New value: +"Number of devices to skip for pagination"
  2. 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: detail_level interaction with list mode, the fact that single-device lookups always return full detail, and which protocol-specific fields (ieee_address, node_id/node_status, node_diagnostics) come back. It does not discuss pagination limits or ordering, but the remaining gap is minor.

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?

Well front-loaded with the mode distinction before the example block, and the bolded headers make scanning easy. It is on the long side, but each example line illustrates a distinct parameter combination, so few lines are wasted.

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-value documentation is not required, yet the description still notes protocol-specific return fields, and it covers both call modes, filtering, pagination, and the handoff to ha_manage_radio. Nothing needed 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 a baseline 3 applies, but the description goes further by showing how parameters combine (offset=50 for next page, limit=10 with detail_level='full', integration values mapped to protocols) and by clarifying that detail_level is effectively ignored in single-device mode — semantics the schema does not state.

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 ('Get device information') and immediately scopes the two operating modes (list with filters vs. single-device lookup). It also enumerates the protocol coverage (Zigbee/ZHA/Z2M, Z-Wave, Matter), which lets an agent distinguish it from generic entity-oriented siblings like ha_get_entity.

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 when-to-use guidance for both modes with concrete invocation examples (offset pagination, area/integration filtering, device_id vs entity_id), plus a routing hint to ha_manage_radio for Matter management. The alternatives and conditions are spelled out rather than inferred.

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