ha-nexus-agent

Overview Schema Source Related Servers Discussions Admin

Validate ESPHome device config

esphome_validate_config

Read-onlyIdempotent

Validate an ESPHome device's YAML configuration without compiling firmware or fetching PlatformIO packages, catching errors before you build.

Instructions

Validate an ESPHome device's YAML config without compiling it.

Uses the devices/validate command on Device Builder's newer multiplexed /ws protocol (github.com/esphome/device-builder, docs/API.md) — the legacy /validate route from the old ESPHome dashboard no longer exists. Unlike esphome_compile_device, this never builds firmware or fetches PlatformIO packages. If the dashboard needs a username/password, this fails fast instead of hanging (no credential wiring exists here).

Use when: checking a config's validity quickly, e.g. before esphome_compile_device. Not for: a full firmware build — use esphome_compile_device; not for LVGL-only structural checks — use esphome_lvgl_validate, which runs without the dashboard. Returns: {"device", "action": "validate", "success", "result", "log_tail", "log_lines"}. Errors: {"error": "Invalid device name: ..."} for a path-escaping or blocked (e.g. 'secrets') name; otherwise one of esphome_dashboard.DashboardError's stable codes — esphome_auth_required (credentials this tool cannot supply) and esphome_unreachable add diagnosis (see esphome_ping_dashboard); timeout adds log_tail/log_lines/job_may_still_be_running (always False — validation enqueues no job); esphome_command_failed adds dashboard_error_code/details.

Input Schema

TableJSON Schema

Name	Required	Description
`name`	Yes	Device name, with or without the '.yaml' suffix, e.g. 'kitchen_sensor'.
`timeout`	No	Maximum seconds to wait for the validation result, e.g. 60.
`log_lines`	No	Number of trailing log lines to return, e.g. 200.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv0.25.1Oct 4, 2026

addedInput schema / properties / log_lines

Added value: +{
+  "default": 200,
+  "description": "Number of trailing log lines to return, e.g. 200.",
+  "type": "integer"
+}

addedInput schema / properties / name / description

Added value: +"Device name, with or without the '.yaml' suffix, e.g. 'kitchen_sensor'."

addedInput schema / properties / timeout

Added value: +{
+  "default": 60,
+  "description": "Maximum seconds to wait for the validation result, e.g. 60.",
+  "type": "number"
+}

Addedv0.18.1Jun 19, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, and the description adds beyond them: it fails fast on missing credentials rather than hanging, performs no PlatformIO fetch, enqueues no job (so 'job_may_still_be_running' is always False), and documents the exact error codes and their extra diagnostic fields. This is unusually rich disclosure; only the timeout semantics could be stated more concretely.

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?

Front-loaded with purpose, then protocol detail, then Use when/Not for, returns, and errors — logically ordered. Slightly over-long: the repo path, docs/API.md reference, and legacy-route history are incidental to invocation, though they do support transparency.

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?

An output schema exists, yet the description still summarizes the return envelope and enumerates the stable error codes with their extra fields, so an agent has everything needed to call the tool and interpret failure modes. Nothing material is missing for a 3-parameter read-only validator.

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 the baseline would be 3, but the description adds real meaning for 'name' beyond the schema: it explains that path-escaping or blocked names (e.g. 'secrets') produce an 'Invalid device name' error, constraining acceptable values in a way the schema does not.

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+resource ('Validate an ESPHome device's YAML config') and immediately scopes it ('without compiling it'), distinguishing it from the obvious sibling by noting it never builds firmware. Names the multiplexed protocol and legacy route, so an agent knows exactly which operation this performs.

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 'Use when' clause (quick validity check, e.g. before esphome_compile_device) and explicit 'Not for' clause routing to esphome_compile_device for full builds and esphome_lvgl_validate for LVGL-only structural checks. Alternative-selection conditions are fully spelled out.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server