Skip to main content
Glama

Remove entity from registry

entities_remove_entity
DestructiveIdempotent

Remove an orphaned entity's registry entry when no loaded integration provides it. Refuses entries an integration still supplies unless forced, preventing recreation.

Instructions

Remove an entity's entry from the entity registry, refusing one an integration still provides.

Reads the entry (config/entity_registry/get) and the entity's state. An entity counts as still provided when it has a state that is not a restored placeholder (attributes.restored, which HA sets for entities no loaded integration provides). Such an entity is refused unless force, because its integration re-creates the entry at the next reload. Otherwise sends config/entity_registry/remove; its customised name, area, labels and entity_id are lost.

Use when: cleaning up orphaned entities ("no longer provided"). Not for: hiding a working entity — use entities_disable_entity; removing a device with its entities — use devices_remove_device. Returns: {"removed": true, "entity_id", "platform", "was_provided"}. Errors: invalid_entity_id (no I/O), not_found, entity_still_provided (nothing removed), state_check_failed, ws_error with Home Assistant's code/message.

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": "entities_remove_entity"
  }
}

Input Schema

NameRequiredDescriptionDefault
forceNoTrue removes the entry even while an integration still provides the entity (it comes back).
entity_idYesFull entity ID to remove from the registry, e.g. 'sensor.old_plug_power'.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.29.0

TDQS

A4.8/5.0
Behavior5/5

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

Beyond annotations already marking this destructive and idempotent, the description explains the internal check (reads the registry entry and entity state), the precise condition for refusal (a non-restored state), why force is needed (the integration would recreate the entry), and exactly what data is lost on removal: customised name, area, labels, and entity_id. It also enumerates error outcomes including entity_still_provided and state_check_failed, which is unusually strong behavioral disclosure.

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?

The description is dense but front-loaded and well organized: purpose first, then mechanics, then usage guidance, then return and error behavior. Every sentence carries information, though the tight packing of implementation details and error codes makes it slightly heavier than necessary for quick scanning.

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?

Given that this is a destructive mutation with conditional refusal behavior, the description covers the decision logic, the force escape hatch, what is irreversibly lost, and the expected success and error outcomes. Even though an output schema exists, the stated return shape and error names make the tool's behavior fully predictable for an agent.

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 description coverage is 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema: force is tied to the integration re-creating the entry and to the refusal logic based on restored state. The entity_id parameter's consequence (loss of entity_id and customisation) is also made explicit, giving the agent more than the field descriptions alone.

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 description opens with a specific verb and resource: removing an entity's entry from the entity registry, and immediately states the key constraint that an entity still provided by an integration is refused. This distinguishes it clearly from sibling cleanup tools such as entities_disable_entity and devices_remove_device.

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?

It provides explicit 'Use when' guidance (cleaning up orphaned entities that are no longer provided) and an explicit 'Not for' section naming alternatives: entities_disable_entity for hiding a working entity, and devices_remove_device for device removal with its entities. The conditions selecting each alternative are stated, not merely implied.

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