feat: add ha_get_states tool for bulk entity state retrieval (#588)

* feat: add ha_get_states tool for bulk entity state retrieval

Adds a new ha_get_states tool that retrieves state information for
multiple entities in a single call using parallel requests. Returns
states as a dict keyed by entity_id for direct access.

Features:
- Parallel fetching via asyncio.gather
- Input validation using create_validation_error
- 100 entity upper-bound limit
- Automatic deduplication preserving order
- Partial success support (partial=True flag)
- Structured error handling per entity (ENTITY_NOT_FOUND, etc.)

Also expands AGENTS.md Error Handling section to document the dedicated
error helper functions.

Closes #377

* test: add E2E tests for ha_get_states bulk state retrieval

Covers: multiple known entities, partial failure with nonexistent
entities, all-fail case, empty list validation, response structure
(dict-keyed states), and deduplication behavior.

* refactor: delegate 404 classification to exception_to_structured_error

Remove redundant manual 404 string matching in _fetch_state since
exception_to_structured_error already handles this classification
when entity_id is in context. Update AGENTS.md pattern accordingly.

Author: sergeykad

AGENTS.md

@@ -619,14 +619,41 @@ def register_<domain>_tools(mcp, client, **kwargs):
 | `idempotentHint: True` | `False` | Repeated calls with same args have no additional effect (only meaningful when `readOnlyHint` is false) |
 
 ### Error Handling
-Use structured errors from `errors.py`:
+
+**Always use the dedicated error functions** from `errors.py` and `helpers.py`. Never construct raw error dicts manually — the helpers ensure consistent structure, error codes, and suggestions across all tools.
+
+**Domain-specific errors** (`errors.py`) — use these when the error type is known:
 ```python
-from ..errors import create_error_response, ErrorCode
-return create_error_response(
-    code=ErrorCode.ENTITY_NOT_FOUND,
-    message="Entity not found",
-    suggestions=["Use ha_search_entities() to find valid IDs"]
-)
+from ..errors import create_entity_not_found_error, create_validation_error, create_service_error
+
+# Entity lookup failures (404 / not found)
+return create_entity_not_found_error(entity_id, details=str(e))
+
+# Invalid parameters
+return create_validation_error("Invalid format", parameter="entity_ids", details=str(e))
+
+# Service call failures
+return create_service_error(domain, service, message=f"Service call failed: {e}", details=str(e))
+```
+
+Available helpers: `create_entity_not_found_error`, `create_connection_error`, `create_auth_error`, `create_service_error`, `create_validation_error`, `create_config_error`, `create_timeout_error`, `create_resource_not_found_error`, and the generic `create_error_response`.
+
+**Catch-all exception handler** (`helpers.py`) — use in `except Exception` blocks:
+```python
+from .helpers import exception_to_structured_error
+
+except Exception as e:
+    return exception_to_structured_error(e, context={"entity_id": entity_id})
+```
+
+**Pattern for tools**: Use `exception_to_structured_error` as the catch-all — it already classifies 404s, auth errors, timeouts, etc. based on exception type and message. Pass `context={"entity_id": ...}` so it can produce `ENTITY_NOT_FOUND` for 404 errors automatically. No manual 404 string matching needed:
+```python
+try:
+    result = await client.get_entity_state(entity_id)
+    return await add_timezone_metadata(client, result)
+except Exception as e:
+    error_response = exception_to_structured_error(e, context={"entity_id": entity_id})
+    return await add_timezone_metadata(client, error_response)
 ```
 
 ### Return Values

src/ha_mcp/tools/tools_search.py

@@ -10,7 +10,7 @@
 
 from pydantic import Field
 
-from ..errors import create_entity_not_found_error
+from ..errors import create_entity_not_found_error, create_validation_error
 from .helpers import exception_to_structured_error, log_tool_usage
 from .util_helpers import (
     add_timezone_metadata,
@@ -682,3 +682,131 @@ async def ha_get_state(entity_id: str) -> dict[str, Any]:
                     "Use ha_search_entities() to find correct entity IDs",
                 ]
             return await add_timezone_metadata(client, error_response)
+
+    @mcp.tool(
+        annotations={
+            "idempotentHint": True,
+            "readOnlyHint": True,
+            "tags": ["search"],
+            "title": "Get Multiple Entity States",
+        }
+    )
+    @log_tool_usage
+    async def ha_get_states(
+        entity_ids: Annotated[
+            list[str],
+            Field(
+                description="List of entity IDs to retrieve states for (e.g., ['light.kitchen', 'sensor.temperature'])"
+            ),
+        ],
+    ) -> dict[str, Any]:
+        """Get state information for multiple Home Assistant entities in a single call.
+
+        Efficiently retrieves states for multiple entities using parallel requests
+        instead of calling ha_get_state repeatedly. Maximum 100 entities per call.
+        Duplicate entity IDs are automatically deduplicated.
+
+        Returns success=True if at least one entity state was retrieved.
+        Check 'error_count' for any failed lookups in partial-success scenarios.
+
+        WHEN TO USE:
+        - Checking states of multiple entities at once (e.g., verifying automation results)
+        - Comparing states across related entities
+        - Any scenario requiring 2+ entity state lookups
+
+        EXAMPLES:
+        - ha_get_states(["light.kitchen", "light.living_room", "sensor.temperature"])
+        - ha_get_states(["automation.morning_routine", "binary_sensor.motion"])
+
+        NOTE: For a single entity, use ha_get_state() instead.
+        """
+        MAX_ENTITIES = 100
+
+        if not isinstance(entity_ids, list) or not entity_ids:
+            return await add_timezone_metadata(
+                client,
+                create_validation_error(
+                    "entity_ids must be a non-empty list of entity ID strings",
+                    parameter="entity_ids",
+                ),
+            )
+
+        if not all(isinstance(eid, str) for eid in entity_ids):
+            return await add_timezone_metadata(
+                client,
+                create_validation_error(
+                    "All entity_ids values must be strings",
+                    parameter="entity_ids",
+                ),
+            )
+
+        if len(entity_ids) > MAX_ENTITIES:
+            return await add_timezone_metadata(
+                client,
+                create_validation_error(
+                    f"Too many entity IDs: {len(entity_ids)} exceeds maximum of {MAX_ENTITIES}",
+                    parameter="entity_ids",
+                ),
+            )
+
+        # Deduplicate while preserving order
+        unique_ids = list(dict.fromkeys(entity_ids))
+        if len(unique_ids) < len(entity_ids):
+            logger.debug(
+                f"Deduplicated entity_ids: {len(entity_ids)} -> {len(unique_ids)}"
+            )
+
+        try:
+            async def _fetch_state(entity_id: str) -> dict[str, Any]:
+                try:
+                    state = await client.get_entity_state(entity_id)
+                    return {"success": True, "entity_id": entity_id, "state": state}
+                except Exception as e:
+                    logger.warning(f"Failed to fetch state for '{entity_id}': {e}")
+                    return exception_to_structured_error(
+                        e, context={"entity_id": entity_id}
+                    )
+
+            results = await asyncio.gather(
+                *(_fetch_state(eid) for eid in unique_ids)
+            )
+
+            states: dict[str, Any] = {}
+            errors: list[dict[str, Any]] = []
+
+            for eid, result in zip(unique_ids, results, strict=True):
+                if result.get("success") is True and "state" in result:
+                    states[eid] = result["state"]
+                else:
+                    error_detail = result.get("error")
+                    if error_detail is None:
+                        error_detail = {"code": "INTERNAL_ERROR", "message": "Unknown error"}
+                    errors.append({
+                        "entity_id": result.get("entity_id", eid),
+                        "error": error_detail,
+                    })
+
+            response: dict[str, Any] = {
+                "success": len(states) > 0,
+                "count": len(states),
+                "states": states,
+            }
+
+            if errors:
+                response["errors"] = errors
+                response["error_count"] = len(errors)
+                response["suggestions"] = [
+                    "Use ha_search_entities() to find correct entity IDs for failed lookups",
+                    "Verify entities exist in Home Assistant",
+                ]
+                if states:
+                    response["partial"] = True
+
+            return await add_timezone_metadata(client, response)
+
+        except Exception as e:
+            logger.error(f"Error getting bulk states: {e}", exc_info=True)
+            error_response = exception_to_structured_error(
+                e, context={"entity_ids": entity_ids}
+            )
+            return await add_timezone_metadata(client, error_response)

tests/src/e2e/workflows/core/test_get_states.py

@@ -0,0 +1,177 @@
+"""
+E2E tests for ha_get_states tool - bulk entity state retrieval.
+
+Tests the bulk state retrieval functionality that fetches multiple entity
+states in a single call using parallel requests.
+"""
+
+import logging
+
+import pytest
+
+from ...utilities.assertions import assert_mcp_success, parse_mcp_result, safe_call_tool
+
+logger = logging.getLogger(__name__)
+
+
+@pytest.mark.asyncio
+@pytest.mark.core
+class TestGetStates:
+    """Test ha_get_states bulk entity state retrieval."""
+
+    async def test_multiple_known_entities(self, mcp_client):
+        """Retrieve states for multiple known entities; all succeed."""
+        logger.info("Testing ha_get_states with sun.sun + a sensor")
+
+        # Find a sensor entity to pair with sun.sun
+        search_result = await mcp_client.call_tool(
+            "ha_search_entities",
+            {"query": "", "domain_filter": "sensor", "limit": 1},
+        )
+        search_data = parse_mcp_result(search_result)
+
+        if "data" in search_data:
+            results = search_data.get("data", {}).get("results", [])
+        else:
+            results = search_data.get("results", [])
+
+        if not results:
+            pytest.skip("No sensor entities available for testing")
+
+        sensor_id = results[0]["entity_id"]
+        entity_ids = ["sun.sun", sensor_id]
+        logger.info(f"Testing with entities: {entity_ids}")
+
+        result = await mcp_client.call_tool(
+            "ha_get_states",
+            {"entity_ids": entity_ids},
+        )
+
+        data = assert_mcp_success(result, "Get multiple entity states")
+
+        assert "data" in data, f"Missing 'data' in response: {data}"
+        inner = data["data"]
+
+        assert inner["success"] is True, f"Expected success: {inner}"
+        assert inner["count"] == 2, f"Expected count 2: {inner}"
+        assert isinstance(inner["states"], dict), f"states should be a dict: {inner}"
+        assert "sun.sun" in inner["states"], f"Missing sun.sun: {inner['states']}"
+        assert sensor_id in inner["states"], f"Missing {sensor_id}: {inner['states']}"
+
+        # Verify sun.sun state data
+        sun_state = inner["states"]["sun.sun"]
+        assert "state" in sun_state, f"Missing state in sun data: {sun_state}"
+        assert sun_state["state"] in ["above_horizon", "below_horizon"]
+
+        # No errors should be present
+        assert "errors" not in inner, f"Unexpected errors: {inner.get('errors')}"
+        assert "partial" not in inner, f"Unexpected partial flag: {inner}"
+
+        # Verify metadata from add_timezone_metadata
+        assert "metadata" in data, f"Missing metadata: {data}"
+
+        logger.info(f"Retrieved {inner['count']} states successfully")
+
+    async def test_partial_failure_with_nonexistent_entity(self, mcp_client):
+        """Mix of real and nonexistent entities returns partial success."""
+        logger.info("Testing ha_get_states with partial failure")
+
+        result = await mcp_client.call_tool(
+            "ha_get_states",
+            {"entity_ids": ["sun.sun", "sensor.nonexistent_test_xyz_99999"]},
+        )
+
+        data = assert_mcp_success(result, "Partial failure get_states")
+
+        assert "data" in data, f"Missing 'data': {data}"
+        inner = data["data"]
+
+        assert inner["success"] is True, f"Partial should still be success: {inner}"
+        assert inner["count"] == 1, f"Only one entity should succeed: {inner}"
+        assert "sun.sun" in inner["states"], f"sun.sun should be present: {inner}"
+        assert inner["partial"] is True, f"Should have partial flag: {inner}"
+        assert inner["error_count"] == 1, f"Should have 1 error: {inner}"
+        assert len(inner["errors"]) == 1, f"errors list should have 1 entry: {inner}"
+        assert inner["errors"][0]["entity_id"] == "sensor.nonexistent_test_xyz_99999"
+        assert "suggestions" in inner, f"Should have suggestions: {inner}"
+
+        logger.info("Partial failure handled correctly")
+
+    async def test_all_nonexistent_entities(self, mcp_client):
+        """All entities nonexistent returns success=False."""
+        logger.info("Testing ha_get_states with all nonexistent entities")
+
+        result = await safe_call_tool(
+            mcp_client,
+            "ha_get_states",
+            {"entity_ids": ["sensor.fake_aaa_111", "sensor.fake_bbb_222"]},
+        )
+
+        inner = result.get("data", result)
+
+        assert inner.get("success") is False, f"Should be failure: {inner}"
+        assert inner.get("count") == 0, f"No states should be returned: {inner}"
+        assert len(inner.get("states", {})) == 0, f"states should be empty: {inner}"
+        assert inner.get("error_count") == 2, f"Should have 2 errors: {inner}"
+        assert "partial" not in inner, f"Should not have partial flag: {inner}"
+
+        logger.info("All-fail case handled correctly")
+
+    async def test_empty_entity_ids_rejected(self, mcp_client):
+        """Empty entity_ids list returns validation error."""
+        logger.info("Testing ha_get_states with empty list")
+
+        result = await safe_call_tool(
+            mcp_client,
+            "ha_get_states",
+            {"entity_ids": []},
+        )
+
+        inner = result.get("data", result)
+
+        assert inner.get("success") is False, f"Should fail validation: {inner}"
+        assert inner.get("error", {}).get("code") == "VALIDATION_FAILED", (
+            f"Should be VALIDATION_FAILED: {inner}"
+        )
+
+        logger.info("Empty list validation works correctly")
+
+    async def test_response_states_keyed_by_entity_id(self, mcp_client):
+        """Verify states dict is keyed by entity_id, not a list."""
+        logger.info("Testing ha_get_states response structure")
+
+        result = await mcp_client.call_tool(
+            "ha_get_states",
+            {"entity_ids": ["sun.sun"]},
+        )
+
+        data = assert_mcp_success(result, "Single entity get_states")
+
+        inner = data["data"]
+        assert isinstance(inner["states"], dict), f"states must be dict: {type(inner['states'])}"
+        assert "sun.sun" in inner["states"], f"Key should be entity_id: {inner['states']}"
+
+        sun_data = inner["states"]["sun.sun"]
+        assert "entity_id" in sun_data, f"State data should contain entity_id: {sun_data}"
+        assert "state" in sun_data, f"State data should contain state: {sun_data}"
+        assert "attributes" in sun_data, f"State data should contain attributes: {sun_data}"
+
+        logger.info("Response structure is correct")
+
+    async def test_duplicate_entity_ids_deduplicated(self, mcp_client):
+        """Duplicate IDs are deduplicated; only one state returned per unique ID."""
+        logger.info("Testing ha_get_states deduplication")
+
+        result = await mcp_client.call_tool(
+            "ha_get_states",
+            {"entity_ids": ["sun.sun", "sun.sun", "sun.sun"]},
+        )
+
+        data = assert_mcp_success(result, "Deduplicated get_states")
+
+        inner = data["data"]
+        assert inner["count"] == 1, f"Should have 1 unique state: {inner}"
+        assert len(inner["states"]) == 1, f"states dict should have 1 entry: {inner}"
+        assert "sun.sun" in inner["states"]
+
+        logger.info("Deduplication works correctly")