Skip to main content
Glama
Fistacho

ha-nexus-agent

by Fistacho
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Compile ESPHome firmware

esphome_compile_device
Idempotent

Build ESPHome firmware for a device to prepare it for upload. Runs a full compile and returns exit code plus build log.

Instructions

Compile ESPHome firmware for a device via the dashboard's /compile WebSocket route.

Blocks until the compile process exits (~60-180s). Compatible with the "ESPHome Device Builder" add-on (esphome/device-builder): /compile keeps the same spawn wire protocol as the old dashboard, now backed by its firmware job queue. A first build for a platform fetches PlatformIO packages from the internet before compiling. only_generate=True is rejected outright (see Errors) — Device Builder ignores that field and always runs a full build (ADR-0004 D4); it stays in the signature only for input-shape compatibility.

Use when: building firmware before esphome_upload_device. Not for: checking config validity only — use esphome_validate_config, which is faster and skips package downloads. Returns: {"device", "action": "compile", "exit_code", "success", "log_tail", "log_lines"}. Errors: {"error": "esphome_unsupported_option", ...} for only_generate=True (no I/O); {"error": "Invalid device name: ..."} for a path-escaping or blocked (e.g. 'secrets') name; otherwise one of esphome_dashboard.DashboardError's stable codes — esphome_unreachable/esphome_auth_required add diagnosis (see esphome_ping_dashboard); timeout adds log_tail/log_lines/ job_may_still_be_running (always True — do not retry, check esphome_get_addon_logs); esphome_command_failed adds dashboard_error_code/details. Limits: blocks up to timeout seconds; log_lines truncates the log.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
nameYesDevice name, with or without the '.yaml' suffix, e.g. 'kitchen_sensor'.
timeoutNoMaximum seconds to wait for the compile process to finish, e.g. 180.
log_linesNoNumber of trailing build-log lines to return, e.g. 200.
only_generateNoIf true, only generate the C++ source and skip the platform build. Set false for a full firmware build.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.25.1
    • addedInput schema / properties / log_lines
      Added value: +{
+  "default": 200,
+  "description": "Number of trailing build-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 / only_generate
      Added value: +{
+  "default": false,
+  "description": "If true, only generate the C++ source and skip the platform build. Set false for a full firmware build.",
+  "type": "boolean"
+}
    • addedInput schema / properties / timeout
      Added value: +{
+  "default": 180,
+  "description": "Maximum seconds to wait for the compile process to finish, e.g. 180.",
+  "type": "number"
+}
  2. Addedv0.18.1

TDQS

A4.6/5.0
Behavior5/5

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

Annotations declare non-readOnly, idempotent, non-destructive, open-world, but the description adds far more: blocking duration (~60-180s), first-build internet fetch for PlatformIO packages, a rejected option with no I/O, the ADR rationale for keeping only_generate in the signature, error taxonomy with stable codes, and explicit timeout guidance ('do not retry, check esphome_get_addon_logs'). This is rich context beyond structured fields, and no annotation is contradicted.

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-loaded with the core purpose and use-case routing, but the middle paragraphs pile on add-on compatibility, wire protocol, ADR-0004, and a full error-code enumeration. Much of this earns its place for a long-blocking tool, yet it is dense and partly better placed in tool docs, so it is adequate rather than tight.

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?

An output schema exists, so return shapes need not be described, though the description lists them anyway. For a mutating, open-world, long-blocking tool, it covers blocking behavior, prerequisites, the rejected option, and error codes with diagnostics, leaving only latency edge cases and auth details (delegated to esphome_ping_dashboard) unstated.

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 is 3. The description still adds meaning the schema lacks: only_generate=True is rejected outright and ignored by Device Builder (schema merely says it generates C++), and timeout blocks up to N seconds. It does not add syntax for name or log_lines beyond the schema.

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 (compile) and resource (ESPHome firmware for a device) and names the underlying route. It explicitly distinguishes itself from sibling esphome_validate_config ('checking config validity only — use esphome_validate_config') and routes to it, so an agent can tell them apart 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 Guidelines5/5

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

Gives explicit when-to-use ('building firmware before esphome_upload_device') and when-not-to-use with a named alternative and its tradeoff ('esphome_validate_config, which is faster and skips package downloads'). Nothing is left to inference.

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