Skip to main content
Glama

List Helpers

ha_config_list_helpers
Read-onlyIdempotent

Lists Home Assistant helpers by type with their configurations and pagination, helping you inspect existing helpers or learn config fields before creating or updating one.

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, or the menu_options a menu-based helper needs a menu_choice from. Call it before ha_config_set_helper to learn the config keys for a type.

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. First observedv9.2.0

TDQS

A4.5/5.0
Behavior5/5

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

Annotations already cover the read-only, idempotent safety profile, yet the description adds substantial behavior beyond them: pagination semantics (total_count/has_more), the exact per-record fields, the id vs entity_id resolution distinction and which one ha_config_set_helper resolves against, the degraded-registry case where only id/name survive plus a warning, and COMPONENT_NOT_INSTALLED failure modes for flow types and 'all'. It also discloses scope boundaries (storage-backed vs YAML-defined) and the person exception.

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?

Front-loading is good — purpose, then record shape, then edge cases, then examples. But the body is unusually long and partly redundant, and it ends with an unpunctuated keyword fragment ('list all helpers input_boolean input_number ...') that reads as scraped trailing text rather than guidance, weakening the structure at the exact place an agent expects a clean closing instruction.

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 six-parameter listing tool with an output schema, the description is more than sufficient: it covers scope, error modes, degraded behavior, cross-tool dependencies, and worked examples. Nothing an agent needs to invoke it or interpret the result 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, but the description adds real meaning on top: it explains each helper_type class (storage type, listed flow type, 'all'), states that 'all' requires the custom component rather than returning a partial list, and clarifies that describe with helper_id attaches current values. The examples also show offset and menu_choice usage in context.

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?

Opens with a specific verb and resource: 'List Home Assistant helpers of a specific type with their configurations.' It also names the companion tool (ha_config_set_helper) whose lookup relies on this one, so the agent can separate read-listing from mutation without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear when-to-use guidance in two places: 'Call it before ha_config_set_helper to learn the config keys for a type' for describe mode, and 'For detailed helper documentation, use ha_get_skill_guide' as the alternative for docs. It also states the preconditions (ha_mcp_tools component >= 1.1.0) that decide whether a call succeeds. It does not, however, address when to prefer this over generic entity reads such as ha_get_entity.

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