Skip to main content
Glama
Vortitron

home-assistant-mcp

by Vortitron
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Save ESPHome config

esphome_save_config
Destructive

Writes full YAML content to an ESPHome configuration file, creating a new file. Requires enabled write permissions; follow with validation and upload.

Instructions

Write YAML to an ESPHome configuration file, whole: for a new file. To change part of an existing one, use esphome_edit_config. Requires HA_ALLOW_WRITE=true and HA_ALLOW_CONFIG_WRITE=true. Follow with esphome_validate to confirm it compiles, then esphome_upload to flash it.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
yamlYesFull YAML content to write.
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.
configurationYesConfiguration filename, e.g. 'living-room.yaml'.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.10.0

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true. The description adds the two env-flag preconditions and the post-write workflow, which are not derivable from annotations. It does not explicitly state that existing content is overwritten, though 'whole: for a new file' implies non-partial writes and destructiveHint covers it.

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?

Tight, front-loaded: scope first, alternative second, preconditions third, workflow last. Every clause is load-bearing. Slightly crowded into one block but no wasted words.

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?

For a 3-param write tool with no output schema, the description covers preconditions, the edit alternative, and the downstream validate/upload sequence. Missing only an explicit statement that the file is overwritten in place and whether validation is automatic.

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

Parameters3/5

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

Schema coverage is 100% with per-parameter descriptions, so the schema carries the parameter semantics. The description adds nothing about the yaml or configuration parameters, and the instance_id cross-session guard is only in the schema. Baseline 3 is appropriate.

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?

Specific verb 'Write' + resource 'ESPHome configuration file' with explicit scope qualifier 'whole: for a new file.' It also names the sibling esphome_edit_config for the partial-change case, making it distinguishable from all siblings at a glance.

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 (new file, whole write) vs when-not (partial change → esphome_edit_config), plus required feature flags (HA_ALLOW_WRITE, HA_ALLOW_CONFIG_WRITE) and prescribed follow-up order (validate → upload). This is a complete usage contract.

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