homeassistant-ai
diff --git a/‎AGENTS.md‎
Lines changed: 28 additions & 0 deletions b/‎AGENTS.md‎
Lines changed: 28 additions & 0 deletions
diff --git a/‎src/ha_mcp/tools/tools_mcp_component.py‎
Lines changed: 25 additions & 7 deletions b/‎src/ha_mcp/tools/tools_mcp_component.py‎
Lines changed: 25 additions & 7 deletions
diff --git a/‎tests/src/e2e/error_handling/test_network_errors.py‎
Lines changed: 0 additions & 1 deletion b/‎tests/src/e2e/error_handling/test_network_errors.py‎
Lines changed: 0 additions & 1 deletion
diff --git a/‎tests/src/e2e/tools/test_deep_search.py‎
Lines changed: 0 additions & 4 deletions b/‎tests/src/e2e/tools/test_deep_search.py‎
Lines changed: 0 additions & 4 deletions
diff --git a/‎tests/src/e2e/utilities/wait_helpers.py‎
Lines changed: 10 additions & 5 deletions b/‎tests/src/e2e/utilities/wait_helpers.py‎
Lines changed: 10 additions & 5 deletions
diff --git a/‎tests/src/e2e/workflows/areas/test_lifecycle.py‎
Lines changed: 0 additions & 14 deletions b/‎tests/src/e2e/workflows/areas/test_lifecycle.py‎
Lines changed: 0 additions & 14 deletions
diff --git a/‎tests/src/e2e/workflows/automation/test_helpers.py‎
Lines changed: 0 additions & 15 deletions b/‎tests/src/e2e/workflows/automation/test_helpers.py‎
Lines changed: 0 additions & 15 deletions
@@ -222,6 +222,34 @@ src/ha_mcp/
 
 **WebSocket Verification**: Device operations verified via real-time state changes.
 
+**Tool Completion Semantics**: Tools should wait for operations to complete before returning, with optional `wait` parameter for control.
+
+## Tool Waiting Behavior
+
+**Principle**: MCP tools should wait for operations to complete before returning, not just acknowledge API success.
+
+**Current State (#365)**: Tests use polling helpers to wait for completion after tool calls.
+
+**Future State (#381)**: Tools will have optional `wait` parameter (default `True`) to handle waiting internally:
+
+```python
+# Config operations wait by default
+await ha_config_set_helper(...)  # Polls until entity registered
+
+# Opt-out for bulk operations
+for config in configs:
+    await ha_config_set_automation(config, wait=False)
+await _verify_all_created(entity_ids)  # Batch verification
+```
+
+**Tool Categories**:
+- **Config ops** (automations, helpers, scripts): MUST wait by default
+- **Service calls** (lights, switches): SHOULD wait for state change
+- **Async ops** (automation triggers, external integrations): Return immediately, users poll
+- **Query ops** (get_state, search): Return immediately
+
+See issue #381 for implementation plan.
+
 ## Context Engineering & Progressive Disclosure
 
 This project applies [context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) and [progressive disclosure](https://www.nngroup.com/articles/progressive-disclosure/) principles to tool design. These complementary approaches help manage cognitive load for both the LLM and the end user.
 
@@ -202,21 +202,39 @@ async def ha_install_mcp_tools(
             repo_id = str(existing_repo.get("id")) if existing_repo else None
 
             if not repo_id:
-                # Re-fetch the list to get the ID
-                list_response = await ws_client.send_command("hacs/repositories/list")
-                repos = list_response.get("result", [])
-                for repo in repos:
-                    if repo.get("full_name", "").lower() == MCP_TOOLS_REPO.lower():
-                        repo_id = str(repo.get("id"))
+                # HACS processes additions asynchronously, so poll for the repo to appear
+                import asyncio
+                max_attempts = 10
+                poll_interval = 1.0  # seconds
+
+                for attempt in range(max_attempts):
+                    logger.debug(f"Polling for repository ID (attempt {attempt + 1}/{max_attempts})")
+                    list_response = await ws_client.send_command("hacs/repositories/list")
+                    repos = list_response.get("result", [])
+                    for repo in repos:
+                        if repo.get("full_name", "").lower() == MCP_TOOLS_REPO.lower():
+                            repo_id = str(repo.get("id"))
+                            logger.info(f"Found repository ID: {repo_id} after {attempt + 1} attempts")
+                            break
+
+                    if repo_id:
                         break
 
+                    if attempt < max_attempts - 1:
+                        await asyncio.sleep(poll_interval)
+
             if not repo_id:
                 return await add_timezone_metadata(
                     client,
                     {
                         "success": False,
-                        "error": "Could not find repository ID after adding",
+                        "error": "Could not find repository ID after adding (timed out after 10 attempts)",
                         "error_code": "HACS_REPO_ID_NOT_FOUND",
+                        "suggestions": [
+                            "HACS may be processing the request - try again in a few seconds",
+                            "Check HACS logs for errors",
+                            f"Verify the repository exists: https://github.com/{MCP_TOOLS_REPO}",
+                        ],
                     },
                 )
 
 
@@ -366,7 +366,6 @@ async def test_bulk_operation_error_scenarios(self, mcp_client):
 
                 # Check status of operations
                 if operation_ids:
-                    await asyncio.sleep(2)
                     status_result = await self._safe_tool_call(
                         mcp_client,
                         "ha_get_bulk_status",
 
@@ -2,7 +2,6 @@
 Tests for ha_deep_search tool - searches within automation/script/helper configs.
 """
 
-import asyncio
 import logging
 
 import pytest
@@ -43,7 +42,6 @@ async def test_deep_search_automation(mcp_client):
     logger.info(f"✅ Created automation: {create_data}")
 
     # Wait for entity to register in HA before searching
-    await asyncio.sleep(5)
 
     try:
         # Test: Search for the sensor entity mentioned in the trigger
@@ -126,7 +124,6 @@ async def test_deep_search_script(mcp_client):
     logger.info(f"✅ Created script: {create_data}")
 
     # Wait for entity to register in HA before searching
-    await asyncio.sleep(5)
 
     try:
         # Test: Search for the unique message in the script
@@ -203,7 +200,6 @@ async def test_deep_search_helper(mcp_client):
     logger.info(f"✅ Created helper: {create_data}")
 
     # Wait for entity to register in HA before searching
-    await asyncio.sleep(5)
 
     try:
         # Test: Search for the unique option in the helper
 
@@ -49,7 +49,8 @@ async def wait_for_entity_state(
             )
             state_data = parse_mcp_result(state_result)
 
-            if state_data.get("success"):
+            # Check if 'data' key exists (not 'success' key which doesn't exist in parse_mcp_result)
+            if 'data' in state_data and state_data['data'] is not None:
                 current_state = state_data.get("data", {}).get("state")
                 logger.debug(f"🔍 {entity_id} current state: {current_state}")
 
@@ -106,7 +107,8 @@ async def wait_for_entity_attribute(
             )
             state_data = parse_mcp_result(state_result)
 
-            if state_data.get("success"):
+            # Check if 'data' key exists (not 'success' key which doesn't exist in parse_mcp_result)
+            if 'data' in state_data and state_data['data'] is not None:
                 attributes = state_data.get("data", {}).get("attributes", {})
                 current_value = attributes.get(attribute_name)
 
@@ -286,7 +288,8 @@ async def wait_for_logbook_entry(
 
             logbook_data = parse_mcp_result(logbook_result)
 
-            if logbook_data.get("success"):
+            # Check if 'data' key exists (not 'success' key which doesn't exist in parse_mcp_result)
+            if 'data' in logbook_data and logbook_data['data'] is not None:
                 entries = logbook_data.get("entries", [])
 
                 for entry in entries:
@@ -372,7 +375,8 @@ async def wait_for_state_change(
         )
         initial_data = parse_mcp_result(initial_result)
 
-        if not initial_data.get("success"):
+        # Check if 'data' key exists (not 'success' key which doesn't exist in parse_mcp_result)
+        if 'data' not in initial_data or initial_data['data'] is None:
             logger.warning(f"⚠️ Could not get initial state for {entity_id}")
             return None
 
@@ -394,7 +398,8 @@ async def wait_for_state_change(
             )
             state_data = parse_mcp_result(state_result)
 
-            if state_data.get("success"):
+            # Check if 'data' key exists (not 'success' key which doesn't exist in parse_mcp_result)
+            if 'data' in state_data and state_data['data'] is not None:
                 current_state = state_data.get("data", {}).get("state")
 
                 if current_state != initial_state:
 
@@ -10,7 +10,6 @@
 - Aliases and icon management
 """
 
-import asyncio
 import logging
 import uuid
 
@@ -61,7 +60,6 @@ async def test_area_create_list_delete(self, mcp_client, cleanup_tracker):
         logger.info(f"Created area: {area_name} (ID: {area_id})")
 
         # 2. LIST: Verify area exists in list
-        await asyncio.sleep(REGISTRY_OPERATION_DELAY)  # Allow time for registration
         list_result = await mcp_client.call_tool("ha_config_list_areas", {})
 
         list_data = parse_mcp_result(list_result)
@@ -89,7 +87,6 @@ async def test_area_create_list_delete(self, mcp_client, cleanup_tracker):
         logger.info(f"Deleted area: {area_id}")
 
         # 4. VERIFY: Area no longer in list
-        await asyncio.sleep(REGISTRY_OPERATION_DELAY)
         verify_result = await mcp_client.call_tool("ha_config_list_areas", {})
         verify_data = parse_mcp_result(verify_result)
 
@@ -142,7 +139,6 @@ async def test_area_update(self, mcp_client, cleanup_tracker):
         logger.info(f"Updated area: {area_id}")
 
         # 3. VERIFY: Check changes in list
-        await asyncio.sleep(REGISTRY_OPERATION_DELAY)
         list_result = await mcp_client.call_tool("ha_config_list_areas", {})
         list_data = parse_mcp_result(list_result)
 
@@ -198,7 +194,6 @@ async def test_area_with_aliases(self, mcp_client, cleanup_tracker):
         logger.info(f"Created area with aliases: {area_id}")
 
         # 2. VERIFY: Check aliases in list
-        await asyncio.sleep(REGISTRY_OPERATION_DELAY)
         list_result = await mcp_client.call_tool("ha_config_list_areas", {})
         list_data = parse_mcp_result(list_result)
 
@@ -256,7 +251,6 @@ async def test_floor_create_list_delete(self, mcp_client, cleanup_tracker):
         logger.info(f"Created floor: {floor_name} (ID: {floor_id})")
 
         # 2. LIST: Verify floor exists in list
-        await asyncio.sleep(REGISTRY_OPERATION_DELAY)
         list_result = await mcp_client.call_tool("ha_config_list_floors", {})
 
         list_data = parse_mcp_result(list_result)
@@ -287,7 +281,6 @@ async def test_floor_create_list_delete(self, mcp_client, cleanup_tracker):
         logger.info(f"Deleted floor: {floor_id}")
 
         # 4. VERIFY: Floor no longer in list
-        await asyncio.sleep(REGISTRY_OPERATION_DELAY)
         verify_result = await mcp_client.call_tool("ha_config_list_floors", {})
         verify_data = parse_mcp_result(verify_result)
 
@@ -342,7 +335,6 @@ async def test_floor_update(self, mcp_client, cleanup_tracker):
         logger.info(f"Updated floor: {floor_id}")
 
         # 3. VERIFY: Check changes in list
-        await asyncio.sleep(REGISTRY_OPERATION_DELAY)
         list_result = await mcp_client.call_tool("ha_config_list_floors", {})
         list_data = parse_mcp_result(list_result)
 
@@ -402,7 +394,6 @@ async def test_floor_with_aliases(self, mcp_client, cleanup_tracker):
         logger.info(f"Created floor with aliases: {floor_id}")
 
         # 2. VERIFY: Check aliases in list
-        await asyncio.sleep(REGISTRY_OPERATION_DELAY)
         list_result = await mcp_client.call_tool("ha_config_list_floors", {})
         list_data = parse_mcp_result(list_result)
 
@@ -477,7 +468,6 @@ async def test_area_with_floor_assignment(self, mcp_client, cleanup_tracker):
         logger.info(f"Created area on floor: {area_id}")
 
         # 3. VERIFY: Check floor assignment in list
-        await asyncio.sleep(REGISTRY_OPERATION_DELAY)
         list_result = await mcp_client.call_tool("ha_config_list_areas", {})
         list_data = parse_mcp_result(list_result)
 
@@ -507,7 +497,6 @@ async def test_area_with_floor_assignment(self, mcp_client, cleanup_tracker):
         logger.info("Removed floor assignment")
 
         # 5. VERIFY: Floor assignment removed
-        await asyncio.sleep(REGISTRY_OPERATION_DELAY)
         verify_result = await mcp_client.call_tool("ha_config_list_areas", {})
         verify_data = parse_mcp_result(verify_result)
 
@@ -579,10 +568,8 @@ async def test_multiple_areas_on_floor(self, mcp_client, cleanup_tracker):
             cleanup_tracker.track("area", area_id)
             logger.info(f"Created area: {name} (ID: {area_id})")
 
-            await asyncio.sleep(BATCH_OPERATION_DELAY)
 
         # 3. VERIFY: All areas on floor
-        await asyncio.sleep(REGISTRY_OPERATION_DELAY)
         list_result = await mcp_client.call_tool("ha_config_list_areas", {})
         list_data = parse_mcp_result(list_result)
 
@@ -602,7 +589,6 @@ async def test_multiple_areas_on_floor(self, mcp_client, cleanup_tracker):
                 logger.error(f"Failed to delete area {area_id}: {delete_data}")
             else:
                 logger.info(f"Deleted area: {area_id}")
-            await asyncio.sleep(BATCH_OPERATION_DELAY)
 
         floor_delete_result = await mcp_client.call_tool("ha_config_remove_floor", {"floor_id": floor_id})
         floor_delete_data = parse_mcp_result(floor_delete_result)
 
@@ -14,7 +14,6 @@
 - Field validation and constraints
 """
 
-import asyncio
 import logging
 from typing import Any
 
@@ -195,7 +194,6 @@ async def test_input_boolean_lifecycle(
         logger.info("✅ Helper deleted successfully")
 
         # 5. VERIFY: Helper is gone - wait a moment for deletion to propagate
-        await asyncio.sleep(2)
         final_state_result = await mcp_client.call_tool(
             "ha_get_state", {"entity_id": helper_entity}
         )
@@ -317,7 +315,6 @@ async def test_input_number_validation(self, mcp_client, cleanup_tracker):
         assert max_data.get("success"), f"Failed to set max value: {max_data}"
 
         # Allow time for state change and verify
-        await asyncio.sleep(1.5)
         max_state_result = await mcp_client.call_tool(
             "ha_get_state", {"entity_id": helper_entity}
         )
@@ -347,7 +344,6 @@ async def test_input_number_validation(self, mcp_client, cleanup_tracker):
         )
 
         # Allow time for state change and verify
-        await asyncio.sleep(1.5)
         step_state_result = await mcp_client.call_tool(
             "ha_get_state", {"entity_id": helper_entity}
         )
@@ -442,7 +438,6 @@ async def test_input_select_options(self, mcp_client, cleanup_tracker):
         assert select_data.get("success"), f"Failed to select option: {select_data}"
 
         # Verify selection
-        await asyncio.sleep(1)
         new_state_result = await mcp_client.call_tool(
             "ha_get_state", {"entity_id": helper_entity}
         )
@@ -465,7 +460,6 @@ async def test_input_select_options(self, mcp_client, cleanup_tracker):
         first_data = parse_mcp_result(first_result)
         assert first_data.get("success"), f"Failed to select first option: {first_data}"
 
-        await asyncio.sleep(1)
         first_state_result = await mcp_client.call_tool(
             "ha_get_state", {"entity_id": helper_entity}
         )
@@ -557,7 +551,6 @@ async def test_input_text_validation(self, mcp_client, cleanup_tracker):
         assert set_data.get("success"), f"Failed to set valid text: {set_data}"
 
         # Verify new text
-        await asyncio.sleep(1)
         new_state_result = await mcp_client.call_tool(
             "ha_get_state", {"entity_id": helper_entity}
         )
@@ -584,7 +577,6 @@ async def test_input_text_validation(self, mcp_client, cleanup_tracker):
         max_data = parse_mcp_result(max_result)
         assert max_data.get("success"), f"Failed to set max length text: {max_data}"
 
-        await asyncio.sleep(1)
         max_state_result = await mcp_client.call_tool(
             "ha_get_state", {"entity_id": helper_entity}
         )
@@ -704,7 +696,6 @@ async def test_input_datetime_modes(self, mcp_client, cleanup_tracker):
             )
 
             # Verify value was set
-            await asyncio.sleep(1)
             new_state_result = await mcp_client.call_tool(
                 "ha_get_state", {"entity_id": helper_entity}
             )
@@ -795,7 +786,6 @@ async def test_input_button_stateless(self, mcp_client, cleanup_tracker):
         logger.info("✅ Button press executed successfully")
 
         # 4. VERIFY: Button state after press (shows timestamp when pressed)
-        await asyncio.sleep(1)
         post_press_result = await mcp_client.call_tool(
             "ha_get_state", {"entity_id": helper_entity}
         )
@@ -827,7 +817,6 @@ async def test_input_button_stateless(self, mcp_client, cleanup_tracker):
             assert multi_press_data.get("success"), (
                 f"Failed button press #{i + 2}: {multi_press_data}"
             )
-            await asyncio.sleep(0.5)
 
         logger.info("✅ Multiple button presses successful")
 
@@ -906,7 +895,6 @@ async def test_helper_bulk_operations(self, mcp_client, cleanup_tracker):
             cleanup_tracker.track(helper_type, helper_entity)
 
             logger.info(f"✅ Created: {helper_entity}")
-            await asyncio.sleep(0.5)  # Small delay between creations
 
         logger.info(f"✅ Bulk creation completed: {len(created_helpers)} helpers")
 
@@ -945,7 +933,6 @@ async def test_helper_bulk_operations(self, mcp_client, cleanup_tracker):
                 )
                 logger.info(f"✅ Toggled: {helper_entity}")
 
-        await asyncio.sleep(2)
 
         # 4. CLEANUP: Bulk deletion
         logger.info(f"🗑️ Bulk deleting {len(created_helpers)} helpers...")
@@ -963,7 +950,6 @@ async def test_helper_bulk_operations(self, mcp_client, cleanup_tracker):
                 f"Failed to delete {helper_entity}: {delete_data}"
             )
             logger.info(f"✅ Deleted: {helper_entity}")
-            await asyncio.sleep(0.5)  # Small delay between deletions
 
         logger.info("✅ Bulk deletion completed")
 
@@ -1103,7 +1089,6 @@ async def test_helper_list_functionality(mcp_client, cleanup_tracker):
         logger.info("✅ Created test input_number")
 
     # Wait for helpers to be registered
-    await asyncio.sleep(2)
 
     # Test listing for each helper type
     for helper_type in helper_types: