[FEATURE] Consolidate 5 redundant tools: areas+floors, rename entity, operation status

[kingpanther13]

What would you like to see?

Three tool consolidations to reduce tool count by 5 (93 → 88). All merge tools that share internal helpers or are near-identical code in the same file.

1. Merge area + floor tools (6 → 3, saves 3 tools)

ha_config_list_areas + ha_config_list_floors, ha_config_set_area + ha_config_set_floor, ha_config_remove_area + ha_config_remove_floor

All 6 live in tools_areas.py and are structurally identical — same WebSocket pattern (config/{area,floor}_registry/{list,create,update,delete}), same error handling, nearly identical parameters. The only differences are floor-specific params (level) vs area-specific params (floor_id, picture).

Approach: Add a type: Literal["area", "floor"] parameter (default "area") to each combined tool. Type-specific params are optional and only apply to their respective type. For the list tool, could also just return both areas and floors in a single call since both datasets are small.

2. Merge ha_rename_entity + ha_rename_entity_and_device (2 → 1, saves 1 tool)

Both already share _rename_entity_internal() in tools_registry.py. The combo tool is a thin wrapper that additionally looks up the device_id from the entity registry and calls _update_device_internal().

Approach: Add optional new_device_name param to ha_rename_entity. If provided, do the device lookup + rename. If omitted, behavior is identical to today. The new_entity_name param from the combo tool maps to the existing name param on ha_rename_entity.

3. Merge ha_get_operation_status + ha_get_bulk_status (2 → 1, saves 1 tool)

Both are read-only tools in tools_service.py checking async device operation status. Both delegate to device_tools. The bulk version loops over individual operations and aggregates results.

Approach: Make ha_get_operation_status accept operation_id: str | list[str]. Single string returns single status (current behavior). List returns aggregated results (current bulk behavior).

Why do you need this?

These are duplicates or near-duplicates that inflate the tool count without adding distinct functionality. Each consolidation follows patterns already established in the codebase — the str | list pattern is used by ha_get_entity/ha_set_entity, and the area+floor tools are already in the same file sharing the same structure.

Additional context

Per AGENTS.md: "When a tool's functionality is fully covered by another tool, remove the redundant tool rather than deprecating it. Fewer tools reduces cognitive load for AI agents and improves decision-making."

[github-actions]

🔍 Analysis

The proposed consolidation of these 5 redundant tools is a high-impact improvement that aligns with the project's goal of reducing cognitive load for AI agents. By merging tools that share underlying logic or target similar Home Assistant registries (areas and floors), we can simplify the interface without losing functionality.

1. Area and Floor Tools: These tools are structurally identical, interacting with similar WebSocket endpoints (config/area_registry/* vs config/floor_registry/*). Merging them by adding a type parameter (defaulting to "area") is the most efficient path.
2. Entity and Device Rename: ha_rename_entity_and_device is currently a wrapper that calls ha_rename_entity and then updates the device. Integrating the device rename as an optional parameter (new_device_name) in ha_rename_entity simplifies the workflow while maintaining full capabilities.
3. Operation Status: ha_get_operation_status and ha_get_bulk_status both check async operation results. Combining them to accept either a single string or a list of strings allows a single tool to handle both single and batch tracking.

This consolidation follows the directive in AGENTS.md to remove redundant tools entirely rather than deprecating them, ensuring a leaner toolset for better AI decision-making.

🛠️ Suggested Steps

1. Refactor tools_areas.py: Merge the 6 area/floor tools into 3 combined tools (ha_config_list_areas, ha_config_set_area, ha_config_remove_area) using a type parameter.
2. Refactor tools_registry.py: Add new_device_name to ha_rename_entity and remove the redundant ha_rename_entity_and_device.
3. Refactor tools_service.py: Update ha_get_operation_status to accept str | list[str] and remove ha_get_bulk_status.
4. Update References: Search and replace references to the removed tools in README.md, tests/, and documentation files.

📊 Technical Analysis (for maintainers)

Root Cause

The codebase currently maintains separate tools for functionally similar operations (areas vs floors, single vs bulk status) or convenience wrappers that could be integrated into base tools. This inflates the tool count (93 tools) which increases the context window usage and potential for AI confusion.

Affected Code

• src/ha_mcp/tools/tools_areas.py - Contains 6 area/floor tools.
• src/ha_mcp/tools/tools_registry.py - Contains entity rename tools.
• src/ha_mcp/tools/tools_service.py - Contains operation status tools.

Proposed Fix

1. Consolidation of Area and Floor Tools (src/ha_mcp/tools/tools_areas.py)

# Add Literal to imports
from typing import Annotated, Any, Literal

# Combine List tools
@mcp.tool(annotations={"idempotentHint": True, "readOnlyHint": True, "tags": ["area", "floor"], "title": "List Areas or Floors"})
async def ha_config_list_areas(
    type: Annotated[Literal["area", "floor"], Field(description="Type of registry to list", default="area")] = "area"
) -> dict[str, Any]:
    registry = "area" if type == "area" else "floor"
    message = {"type": f"config/{registry}_registry/list"}
    # ... handle response ...

# Combine Set tools (merge parameters)
async def ha_config_set_area(
    type: Literal["area", "floor"] = "area",
    name: str | None = None,
    area_id: str | None = None,
    floor_id: str | None = None,
    level: int | None = None,
    icon: str | None = None,
    aliases: str | list[str] | None = None,
    picture: str | None = None,
):
    # If type="floor", use floor_id as the primary identifier for update
    # If type="area", use area_id for update and floor_id for assignment

2. Consolidation of Rename Tools (src/ha_mcp/tools/tools_registry.py)

--- a/src/ha_mcp/tools/tools_registry.py
+++ b/src/ha_mcp/tools/tools_registry.py
@@ -350,6 +350,12 @@
             description="Migrate voice assistant exposure settings. Defaults to True.",
             default=None,
         ),
+    ] = None,
+    new_device_name: Annotated[
+        str | None,
+        Field(
+            description="Optional: New display name for the associated device. If provided, both entity and device are renamed.",
+            default=None,
+        ),
     ] = None,
 ) -> dict[str, Any]:
-    # ...
+    # 1. Perform entity rename
+    result = await _rename_entity_internal(...)
+    
+    # 2. If new_device_name provided, lookup device_id and call _update_device_internal
+    if new_device_name:
+        # lookup device_id from entity registry
+        await _update_device_internal(device_id=device_id, name=new_device_name)
+    return result

3. Consolidation of Operation Status Tools (src/ha_mcp/tools/tools_service.py)

--- a/src/ha_mcp/tools/tools_service.py
+++ b/src/ha_mcp/tools/tools_service.py
@@ -235,7 +235,11 @@
     @mcp.tool(annotations={"readOnlyHint": True, "title": "Get Operation Status"})
     @log_tool_usage
     async def ha_get_operation_status(
-        operation_id: str, timeout_seconds: int = 10
+        operation_id: Annotated[str | list[str], Field(description="Single operation ID or list of IDs to check")],
+        timeout_seconds: int = 10
     ) -> dict[str, Any]:
         """Check status of device operation(s) with real-time WebSocket verification."""
+        if isinstance(operation_id, list):
+            return await device_tools.get_bulk_operation_status(operation_ids=operation_id)
+            
         result = await device_tools.get_device_operation_status(

Related Issues/PRs

No similar issues found.

---

🤖 Automated analysis by Issue Bot