Skip to main content
Glama
Vortitron

home-assistant-mcp

by Vortitron
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Create or update a helper

ha_set_helper
Destructive

Create or update Home Assistant helpers without editing configuration.yaml. Store them directly so their entities exist immediately.

Instructions

Create a Home Assistant helper, or update one that exists. This is how to add a helper without editing configuration.yaml — that file is not reachable from here and would need a restart; a helper created this way is stored by Home Assistant and its entity exists immediately.

Omit 'helper_id' to create; pass the id from ha_list_helpers to update. The new entity is ..

Fields per kind — Home Assistant validates and will name anything wrong: • input_boolean: name; optional icon, initial • input_number: name, min, max; optional step, initial, mode (box|slider), unit_of_measurement, icon • input_text: name; optional min, max, initial, pattern, mode (text|password), icon • input_select: name, options (array of strings); optional initial, icon • input_datetime: name, and at least one of has_date / has_time; optional initial, icon • input_button: name; optional icon • counter: name; optional initial, step, minimum, maximum, restore, icon • timer: name; optional duration (HH:MM:SS), restore, icon • schedule: name; optional monday…sunday (arrays of {from, to}), icon

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
kindYesHelper type: input_boolean, input_number, input_text, input_select, input_datetime, input_button, counter, timer, schedule.
configYesThe helper's fields, e.g. { name: 'Holiday mode', icon: 'mdi:palm-tree' }.
helper_idNoExisting helper id to update. Omit to create a new one.
instance_idNoOptional: the instance you mean (as listed by vomehome_list_instances). When given, the call is refused if this session is targeting a different home, instead of answering from it.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.10.0

TDQS

A4.7/5.0
Behavior4/5

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

Annotations already declare destructiveHint=true and openWorldHint=true, and the description adds real context beyond them: the entity exists immediately, Home Assistant validates and rejects misnamed fields, and the helper is stored by Home Assistant rather than in YAML. It does not, however, state what happens to config fields omitted on an update (merge vs. replace) or whether kind can change on an existing helper, which matters for a tool flagged destructive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

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

Front-loaded with the core purpose and the create/update switch, then a scannable bulleted per-kind field list. The list is long but every line carries information absent from the schema, so nothing is padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description still covers creation, update, entity naming, validation behavior, and storage. The remaining gap is update semantics on the existing helper (partial vs. full replacement, kind immutability) plus any permission requirements, which an agent would need before mutating an existing helper.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema description coverage is 100%, the schema leaves config as an untyped object with additionalProperties:{}, so it conveys nothing about valid keys. The description compensates fully with a per-kind field list including which fields are required vs. optional and enum-like values (mode box|slider, HH:MM:SS durations, weekday schedules).

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?

The description gives a specific verb pair (create/update) and resource (Home Assistant helper), and explicitly differentiates the tool from the config-file route used by ha_read_config_file/ha_edit_config_file: 'This is how to add a helper without editing configuration.yaml'. It also states the naming convention of the resulting entity (<kind>.<slug of name>), which no sibling tool provides.

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?

The create-vs-update rule is spelled out unambiguously ('Omit helper_id to create; pass the id from ha_list_helpers to update'), naming the sibling that supplies ids. It also rules out the alternative mechanism (configuration.yaml) and explains why it is not used (not reachable, requires restart).

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