Skip to main content
Glama
Fistacho

ha-nexus-agent

by Fistacho
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Clean stale MQTT discovery entries

esphome_clean_mqtt
DestructiveIdempotent

Remove stale MQTT discovery entries for an ESPHome device through Home Assistant's MQTT integration. Use when a renamed or deleted device leaves lingering retained topics.

Instructions

Remove stale MQTT discovery entries for an ESPHome device, through HA's own MQTT integration.

Skips with zero network calls when the config has no mqtt: section. Otherwise resolves the node name (esphome.name, with substitutions:) and mqtt.discovery_prefix (default "homeassistant"). With a matching HA device, reads topics via WS mqtt/device/debug_info; otherwise briefly mqtt/subscribes to {prefix}/+/{node_name}/# and collects retained topics. Clears each topic via the mqtt.publish service, payload="" and retain=True -- MQTT's own way to delete a retained message. Never touches the ESPHome dashboard, which has no MQTT-topic-clearing command.

Use when: a removed/renamed device's old MQTT discovery entries still linger in Home Assistant. Not for: a config with no mqtt: section; firmware artifacts -- use esphome_compile_device. Returns: {"device", "action": "clean_mqtt", "skipped": True, "reason": ...} with no mqtt: section; otherwise {"success": <bool>, "method": "debug_info"|"wildcard_subscribe", "topics_cleared": [...], "count": <int>}, plus "errors": [...] on partial failures. Errors: {"error": "..."} for an invalid/missing device file, an unresolvable esphome.name/mqtt.discovery_prefix, or a WebSocket/ service-call failure. Limits: the wildcard fallback only collects for min(timeout, 3) seconds -- may miss a slow message or catch an unrelated topic.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
nameYesDevice name, with or without the '.yaml' suffix, e.g. 'kitchen_sensor'.
timeoutNoMaximum seconds to spend collecting retained MQTT discovery topics via a wildcard subscribe, e.g. 60. Only used when no matching HA device is found for this config's node name.
log_linesNoUnused by this tool's HA-mqtt-integration implementation (kept only for API/parameter-surface compatibility with earlier versions that spawned a dashboard process and returned trailing log lines), e.g. 200.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.25.1
    • addedInput schema / properties / log_lines
      Added value: +{
+  "default": 200,
+  "description": "Unused by this tool's HA-mqtt-integration implementation (kept only for API/parameter-surface compatibility with earlier versions that spawned a dashboard process and returned trailing log lines), 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 spend collecting retained MQTT discovery topics via a wildcard subscribe, e.g. 60. Only used when no matching HA device is found for this config's node name.",
+  "type": "number"
+}
  2. Addedv0.18.1

TDQS

A4.8/5.0
Behavior5/5

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

Goes well beyond the annotations: describes zero-network-call skip when no `mqtt:` section exists, the resolution order for node name/discovery prefix, the two collection methods (WS debug_info vs wildcard subscribe), the retained-message deletion technique (publish empty payload retain=true), and the min(timeout,3)s fallback limit. Annotations already carry destructive/idempotent hints, but the description adds substantial operational context.

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 and organized into clearly labeled sections (mechanism, Use when, Not for, Returns, Errors, Limits) so nothing is buried. It is on the long side, but each line conveys actionable detail rather than filler.

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 mutating tool with three parameters, an output schema, and full annotations, the description covers trigger conditions, execution paths, return shapes, error cases, and a known limitation. An agent has everything needed to decide and invoke correctly.

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 the non-obvious interaction that `timeout` is capped at min(timeout, 3) seconds and only applies to the wildcard fallback path. This meaningfully refines how the agent should set the parameter beyond the schema text.

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 ('Remove stale MQTT discovery entries for an ESPHome device') and the mechanism ('through HA's own MQTT integration'). It explicitly contrasts with the dashboard approach ('Never touches the ESPHome dashboard'), so an agent can distinguish it from sibling ESPHome tools 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?

Has explicit 'Use when' (removed/renamed device's stale discovery entries lingering) and 'Not for' clauses, including routing firmware work to `esphome_compile_device`. Alternatives and exclusions 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

Other Tools