Skip to main content
Glama
Home Assistant MCP Server

Home Assistant MCP Server

Official

List Helpers

ha_config_list_helpers
Read-onlyIdempotent

List Home Assistant helpers by type with their configurations. Describe fields before creating or updating them.

Instructions

List Home Assistant helpers of a specific type with their configurations.

Returns one page of helpers; total_count and has_more report the full set. Each record carries the configuration for its helper: id (immutable storage key), entity_id (current — address the helper by this, where available), name (current display name), original_name (creation-time name), icon, type-specific settings, and area and label assignments. A flow helper record carries entry_id and options instead of id; a custom helper integration's options are withheld, marked options_withheld.

For a helper renamed in the UI, id/original_name keep the storage values while entity_id/name reflect the current entity registry (entity_id is the identifier ha_config_set_helper resolves against, so prefer it over id for a renamed helper). entity_id/original_name are present only for storage-collection helpers matched in the entity registry — types with no backing entity (e.g. tag), and every record when the registry read degrades, carry only id/name (a warning flags the degraded case).

Storage types list what HA's {type}/list command returns: the storage-backed helpers (created via UI/API), not the YAML-defined ones. person is the exception — HA lists its YAML-configured persons alongside the storage ones, so both appear here.

Listing flow types requires the ha_mcp_tools custom component (>= 1.1.0); without it, such a listing returns a COMPONENT_NOT_INSTALLED error.

With helper_type="all", each record carries its own helper_type. This mode is component-only (there is no single built-in command that lists all types): without the ha_mcp_tools component it returns a COMPONENT_NOT_INSTALLED error rather than a partial or empty list.

describe=True returns each field's name, type, required flag, options, default and (with helper_id) current value, the later_forms of a helper with several forms, or the menu_options a menu-based helper needs a menu_choice from. Call it before ha_config_set_helper.

EXAMPLES:

  • List all counters: ha_config_list_helpers("counter")

  • List every helper type at once: ha_config_list_helpers("all")

  • Next page: ha_config_list_helpers("input_boolean", offset=100)

  • Fields for a template sensor: ha_config_list_helpers("template", describe=True, menu_choice="sensor")

For detailed helper documentation, use ha_get_skill_guide.

list all helpers input_boolean input_number input_text counter timer input_datetime input_select

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": {
      "helper_type": "<helper_type>"
    },
    "name": "ha_config_list_helpers"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMax helpers to return per page
offsetNoNumber of helpers to skip for pagination
describeNoInstead of listing, return the fields ha_config_set_helper accepts in config for helper_type, as Home Assistant reports them (the form the HA UI shows).
helper_idNodescribe only: an existing helper (config entry id for flow helpers, entity_id or id otherwise); each field then carries its current value.
helper_typeYesHelper type to list: a storage type (input_boolean, counter, timer, ...), a helper flow Home Assistant lists (template, group, utility_meter, ...), or 'all' for every type in one call.
menu_choiceNodescribe only: sub-type of a menu-based helper (template, group), e.g. 'sensor'. A choice that finishes the flow saves the helper: flow_type create_entry.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv9.1.1
    • changedInput schema / properties / menu_choice / description
      Previous value: -"describe only: sub-type of a menu-based helper (template, group), e.g. 'sensor'."New value: +"describe only: sub-type of a menu-based helper (template, group), e.g. 'sensor'. A choice that finishes the flow saves the helper: flow_type create_entry."
  2. Changed5 schema fields changedv8.7.0
    • addedInput schema / properties / describe
      Added value: +{
      +  "default": false,
      +  "description": "Instead of listing, return the fields ha_config_set_helper accepts in config for helper_type, as Home Assistant reports them (the form the HA UI shows).",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / helper_id
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "describe only: an existing helper (config entry id for flow helpers, entity_id or id otherwise); each field then carries its current value."
      +}
    • changedInput schema / properties / helper_type / anyOf
      Previous value: -[
      -  {
      -    "enum": [
      -      "input_button",
      -      "input_boolean",
      -      "input_select",
      -      "input_number",
      -      "input_text",
      -      "input_datetime",
      -      "counter",
      -      "timer",
      -      "schedule",
      -      "zone",
      -      "person",
      -      "tag",
      -      "all"
      -    ],
      -    "type": "string"
      -  },
      -  {
      -    "enum": [
      -      "template",
      -      "group",
      -      "utility_meter",
      -      "derivative",
      -      "min_max",
      -      "threshold",
      -      "integration",
      -      "statistics",
      -      "trend",
      -      "random",
      -      "filter",
      -      "tod",
      -      "generic_thermostat",
      -      "switch_as_x",
      -      "generic_hygrostat",
      -      "history_stats",
      -      "mold_indicator"
      -    ],
      -    "type": "string"
      -  }
      -]New value: +[
      +  {
      +    "enum": [
      +      "input_button",
      +      "input_boolean",
      +      "input_select",
      +      "input_number",
      +      "input_text",
      +      "input_datetime",
      +      "counter",
      +      "timer",
      +      "schedule",
      +      "zone",
      +      "person",
      +      "tag"
      +    ],
      +    "type": "string"
      +  },
      +  {
      +    "const": "all",
      +    "type": "string"
      +  },
      +  {
      +    "type": "string"
      +  }
      +]
    • changedInput schema / properties / helper_type / description
      Previous value: -"Helper type to list. Storage types are listed on all installs; flow-based types require the ha_mcp_tools custom component. Pass 'all' to list every helper type in one call (also requires the ha_mcp_tools component)."New value: +"Helper type to list: a storage type (input_boolean, counter, timer, ...), a helper flow Home Assistant lists (template, group, utility_meter, ...), or 'all' for every type in one call."
    • addedInput schema / properties / menu_choice
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "describe only: sub-type of a menu-based helper (template, group), e.g. 'sensor'."
      +}
  3. Changed2 schema fields changedv8.6.0
    • changedInput schema / properties / limit / description
      Previous value: -"Max helpers to return per page (default: 100)"New value: +"Max helpers to return per page"
    • changedInput schema / properties / offset / description
      Previous value: -"Number of helpers to skip for pagination (default: 0)"New value: +"Number of helpers to skip for pagination"
  4. Changed1 schema field changedv8.3.0
    • changedInput schema / properties / helper_type / anyOf
      Previous value: -[
      -  {
      -    "enum": [
      -      "input_button",
      -      "input_boolean",
      -      "input_select",
      -      "input_number",
      -      "input_text",
      -      "input_datetime",
      -      "counter",
      -      "timer",
      -      "schedule",
      -      "zone",
      -      "person",
      -      "tag",
      -      "all"
      -    ],
      -    "type": "string"
      -  },
      -  {
      -    "enum": [
      -      "template",
      -      "group",
      -      "utility_meter",
      -      "derivative",
      -      "min_max",
      -      "threshold",
      -      "integration",
      -      "statistics",
      -      "trend",
      -      "random",
      -      "filter",
      -      "tod",
      -      "generic_thermostat",
      -      "switch_as_x",
      -      "generic_hygrostat"
      -    ],
      -    "type": "string"
      -  }
      -]New value: +[
      +  {
      +    "enum": [
      +      "input_button",
      +      "input_boolean",
      +      "input_select",
      +      "input_number",
      +      "input_text",
      +      "input_datetime",
      +      "counter",
      +      "timer",
      +      "schedule",
      +      "zone",
      +      "person",
      +      "tag",
      +      "all"
      +    ],
      +    "type": "string"
      +  },
      +  {
      +    "enum": [
      +      "template",
      +      "group",
      +      "utility_meter",
      +      "derivative",
      +      "min_max",
      +      "threshold",
      +      "integration",
      +      "statistics",
      +      "trend",
      +      "random",
      +      "filter",
      +      "tod",
      +      "generic_thermostat",
      +      "switch_as_x",
      +      "generic_hygrostat",
      +      "history_stats",
      +      "mold_indicator"
      +    ],
      +    "type": "string"
      +  }
      +]
  5. First observedv7.14.2

TDQS

A4.5/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 bar is lower, but the description adds real context: pagination via total_count/has_more, the degraded entity-registry case with a warning, and COMPONENT_NOT_INSTALLED failures for flow types and helper_type='all'. It also warns that 'all' is component-only and never returns a partial list — exactly the kind of failure mode an agent needs. It stops short of describing auth or rate-limit behavior, but for a read tool that 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.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded and the examples block is genuinely useful, but the body is long for a list operation and re-explains record fields that the output schema already carries. The trailing line ('list all helpers input_boolean input_number ...') reads as keyword stuffing rather than information and should be cut.

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?

For a tool with six parameters, flow-vs-storage helper distinctions, and two error paths, the definition covers everything an agent needs to call it correctly — type selection, pagination, describe mode, component prerequisites, and the renamed-helper pitfall. The output schema exists, so the extra field walkthrough is surplus rather than a gap.

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, and the description goes beyond it by explaining the cross-tool consequence of fields (entity_id is what ha_config_set_helper resolves against, prefer it over id for a renamed helper) and the meaning of menu_choice finishing the flow (flow_type create_entry). These are semantic links the schema does not encode. It does not restate limit/offset syntax beyond one example, which the schema already covers.

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?

Opening sentence gives a specific verb (list), resource (Home Assistant helpers), and scope (a specific type, with configurations). It also names the sibling it complements (ha_config_set_helper) and the sibling for deeper docs (ha_get_skill_guide), so an agent can place it without opening another 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?

Explicit routing: 'describe=True ... Call it before ha_config_set_helper' tells the agent exactly when this precedes a mutation, and 'For detailed helper documentation, use ha_get_skill_guide' names the alternative for a different need. The examples map common intents (all types, pagination, template describe) directly to argument combinations.

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