Skip to main content
Glama

Find HA entity usage in Node-RED

nodered_find_entity_usage
Read-onlyIdempotent

Find every Node-RED node and flow that references a Home Assistant entity before renaming or removing it. Scans exact fields, templates, code, and selectors without changing anything.

Instructions

List the Node-RED nodes and flows that reference one Home Assistant entity.

Reads GET /flows and scans every node's configuration: a field equal to the entity id (exact, e.g. entities.entity, target.entityId), the id inside a template, JSON or function code as a whole word (text), and Home Assistant node selectors that would match it by substring or regex (also the older entityId + entityIdType form). Changes nothing.

Use when: checking what breaks before renaming or removing an entity, or explaining what controls a device, together with HA automations. Not for: HA automations and scripts — use search_find_related or automations_validate_automation_references; nodes by type — use nodered_search_nodes. Returns: {"addon_slug", "rev", "entity_id", "nodes": [{id, type, name, flow_id, flow_label, in_subflow, disabled, match: [...], fields: [...]}], "flows": [{flow_id, flow_label, node_count}], "count", "skipped_patterns"}. Errors: invalid_entity_id (no I/O), plus the add-on lookup errors of nodered_list_flows. Limits: a regex is evaluated with Python's engine; one over 200 characters or with nested quantifiers is skipped (counted in skipped_patterns); entity ids built at runtime are not found.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "entity_id": "<entity_id>"
    },
    "name": "nodered_find_entity_usage"
  }
}

Input Schema

NameRequiredDescriptionDefault
entity_idYesHome Assistant entity id, e.g. `light.kitchen` or `binary_sensor.front_door`.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.29.0

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description reinforces this with 'Changes nothing' plus the underlying GET /flows read. Beyond that it discloses genuine behavioral limits annotations cannot: regexes are evaluated by Python's engine and skipped if over 200 chars or nested-quantifier, skips are reported in skipped_patterns, and runtime-constructed entity ids are invisible.

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 the one-line purpose, then cleanly sectioned into Use when / Not for / Returns / Errors / Limits, so an agent can scan it quickly. The inline Returns block restates the shape already provided by the output schema, which is redundant payload against an otherwise tight definition.

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 read-only scan tool it covers everything an agent needs: what it reads, what counts as a match, what is not found, error identifiers, and inheritance of add-on lookup errors from nodered_list_flows. Return-value detail is the only duplicated element and it is harmless rather than missing.

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?

The single parameter has 100% schema coverage with a concrete example, so the schema carries the baseline. The description adds some meaning by explaining how the supplied id is matched against node configs (exact field equality, whole-word in code, selector substring/regex), but it does not add format or validation detail for the parameter itself.

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 first sentence gives a precise verb and resource: list Node-RED nodes and flows that reference one Home Assistant entity. It then explains the matching modes (exact, text/whole-word, substring/regex selector) so the agent understands the scope of 'reference' rather than guessing.

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' cases (pre-rename/pre-removal checks, explaining what controls a device) are paired with named exclusions and their correct alternatives: search_find_related and automations_validate_automation_references for HA automations, nodered_search_nodes for node-type searches. No routing decision 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