ha-mcp-dev 8.3.0.dev2379__tar.gz → 8.3.0.dev2385__tar.gz

{ha_mcp_dev-8.3.0.dev2379/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.3.0.dev2385}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.3.0.dev2379
+Version: 8.3.0.dev2385
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT

{ha_mcp_dev-8.3.0.dev2379 → ha_mcp_dev-8.3.0.dev2385}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.3.0.dev2379"
+version = "8.3.0.dev2385"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's

{ha_mcp_dev-8.3.0.dev2379 → ha_mcp_dev-8.3.0.dev2385}/src/ha_mcp/settings_ui/locales/cs.json

@@ -470,7 +470,7 @@
   "tools": {
     "ha_bulk_control": {
       "title": "Hromadné ovládání",
-      "description": "Ovládejte více zařízení s podporou hromadných operací a sledováním přes WebSocket."
+      "description": "Správa více akcí entit v jednom požadavku."
     },
     "ha_call_event": {
       "title": "Vyvolat událost",

{ha_mcp_dev-8.3.0.dev2379 → ha_mcp_dev-8.3.0.dev2385}/src/ha_mcp/settings_ui/locales/de.json

@@ -501,7 +501,7 @@
   "tools": {
     "ha_bulk_control": {
       "title": "Massensteuerung",
-      "description": "Steuere mehrere Geräte mit Unterstützung für Massenoperationen und WebSocket-Verfolgung."
+      "description": "Verwalte mehrere Entitätsaktionen in einer Anfrage."
     },
     "ha_call_event": {
       "title": "Ereignis aufrufen",

{ha_mcp_dev-8.3.0.dev2379 → ha_mcp_dev-8.3.0.dev2385}/src/ha_mcp/settings_ui/locales/eo.json

@@ -470,7 +470,7 @@
   "tools": {
     "ha_bulk_control": {
       "title": "Amasa Kontrolo",
-      "description": "Kontrolu plurajn aparatojn kun subteno por amasa operacio kaj WebSocket-spurado."
+      "description": "Mastrumi plurajn entajn agojn en unu peto."
     },
     "ha_call_event": {
       "title": "Voki Eventon",

{ha_mcp_dev-8.3.0.dev2379 → ha_mcp_dev-8.3.0.dev2385}/src/ha_mcp/settings_ui/locales/es.json

@@ -501,7 +501,7 @@
   "tools": {
     "ha_bulk_control": {
       "title": "Control en bloque",
-      "description": "Controla varios dispositivos a la vez con seguimiento por WebSocket."
+      "description": "Gestiona múltiples acciones de entidades en una sola solicitud."
     },
     "ha_call_event": {
       "title": "Lanzar evento",

{ha_mcp_dev-8.3.0.dev2379 → ha_mcp_dev-8.3.0.dev2385}/src/ha_mcp/settings_ui/locales/fr.json

@@ -501,7 +501,7 @@
   "tools": {
     "ha_bulk_control": {
       "title": "Contrôle groupé",
-      "description": "Contrôler plusieurs appareils avec prise en charge des opérations en masse et suivi WebSocket."
+      "description": "Gérer plusieurs actions d'entité en une seule requête."
     },
     "ha_call_event": {
       "title": "Déclencher un événement",

{ha_mcp_dev-8.3.0.dev2379 → ha_mcp_dev-8.3.0.dev2385}/src/ha_mcp/settings_ui/locales/it.json

@@ -501,7 +501,7 @@
   "tools": {
     "ha_bulk_control": {
       "title": "Controllo in blocco",
-      "description": "Controlla più dispositivi con supporto alle operazioni in blocco e monitoraggio via WebSocket."
+      "description": "Gestisci più azioni di entità in una singola richiesta."
     },
     "ha_call_event": {
       "title": "Invia un evento",

{ha_mcp_dev-8.3.0.dev2379 → ha_mcp_dev-8.3.0.dev2385}/src/ha_mcp/settings_ui/locales/nl.json

@@ -470,7 +470,7 @@
   "tools": {
     "ha_bulk_control": {
       "title": "Bulkbediening",
-      "description": "Bedien meerdere apparaten met ondersteuning voor bulkbewerkingen en WebSocket-tracking."
+      "description": "Beheer meerdere entiteitsacties in één verzoek."
     },
     "ha_call_event": {
       "title": "Roep Gebeurtenis aan",

{ha_mcp_dev-8.3.0.dev2379 → ha_mcp_dev-8.3.0.dev2385}/src/ha_mcp/settings_ui/locales/pl.json

@@ -470,7 +470,7 @@
   "tools": {
     "ha_bulk_control": {
       "title": "Sterowanie zbiorcze",
-      "description": "Steruj wieloma urządzeniami z obsługą operacji zbiorczych i śledzeniem WebSocket."
+      "description": "Zarządzaj wieloma akcjami encji w jednym żądaniu."
     },
     "ha_call_event": {
       "title": "Wywołaj zdarzenie",

{ha_mcp_dev-8.3.0.dev2379 → ha_mcp_dev-8.3.0.dev2385}/src/ha_mcp/settings_ui/locales/ru.json

@@ -501,7 +501,7 @@
   "tools": {
     "ha_bulk_control": {
       "title": "Массовое управление",
-      "description": "Управление несколькими устройствами с поддержкой массовых операций и отслеживанием через WebSocket."
+      "description": "Управление действиями нескольких сущностей в одном запросе."
     },
     "ha_call_event": {
       "title": "Вызвать событие",

{ha_mcp_dev-8.3.0.dev2379 → ha_mcp_dev-8.3.0.dev2385}/src/ha_mcp/settings_ui/locales/sv.json

@@ -470,7 +470,7 @@
   "tools": {
     "ha_bulk_control": {
       "title": "Masskontroll",
-      "description": "Kontrollera flera enheter med stöd för massoperationer och WebSocket-spårning."
+      "description": "Hantera flera entitetsåtgärder i en enda begäran."
     },
     "ha_call_event": {
       "title": "Anropa Händelse",

{ha_mcp_dev-8.3.0.dev2379 → ha_mcp_dev-8.3.0.dev2385}/src/ha_mcp/settings_ui/locales/zh-Hans.json

@@ -501,7 +501,7 @@
   "tools": {
     "ha_bulk_control": {
       "title": "批量控制",
-      "description": "支持批量操作与 WebSocket 跟踪，同时控制多个设备。"
+      "description": "在单个请求中管理多个实体操作。"
     },
     "ha_call_event": {
       "title": "调用事件",

{ha_mcp_dev-8.3.0.dev2379 → ha_mcp_dev-8.3.0.dev2385}/src/ha_mcp/tools/device_control.py

@@ -42,10 +42,23 @@ from .helpers import (
     safe_info,
     safe_progress,
 )
+from .tools_service import BulkControlOperation
 from .util_helpers import _SERVICE_TO_STATE
 
 logger = logging.getLogger(__name__)
 
+# The bulk row contract is declared once, on the advertised transport schema.
+# Reading its keys back here keeps the runtime batch validator from drifting
+# out of sync with what models are told they may send.
+_BULK_OPERATION_KEYS: frozenset[str] = frozenset(BulkControlOperation.__annotations__)
+
+# The row shape models get wrong most often is a service-style row, so this
+# leads every suggestion list a rejected bulk batch produces.
+_BULK_ROW_SHAPE_SUGGESTION = (
+    "Use entity_id and action (e.g. action='off', not service='turn_off'); "
+    "send no domain or service keys and put action data in parameters"
+)
+
 # The ha_mcp_tools/bulk_call_service WS command (Phase 3, D5a): the BATCH write
 # capability. When the component advertises ``bulk_call_service`` the consumer
 # resolves every op's domain/service server-side (D6), sends one register-before-fire
@@ -347,6 +360,10 @@ class DeviceControlTools:
         "set": "set_temperature",
     }
 
+    # Silent allowlist: _add_domain_params copies only these keys into the
+    # service call and drops everything else without an error, and a domain
+    # absent from this table loses every parameter. Extend it when adding
+    # support for a new parameter, or the parameter vanishes at dispatch.
     _DOMAIN_PARAMS: ClassVar[dict[str, list[str]]] = {
         "light": [
             "brightness",
@@ -474,10 +491,10 @@ class DeviceControlTools:
         """Check status of a device operation, waiting up to ``timeout_seconds`` for completion.
 
         Polls the in-memory operation registry (mutated by the WebSocket
-        listener as state changes arrive) every 0.2s while the operation is
-        pending, up to ``timeout_seconds``. Returns the final structured status
-        — completed/failed/timeout/pending — produced by
-        ``control_device_smart``.
+        listener as state changes arrive) while the operation is pending, at
+        0.2s intervals except for a final shorter poll that lands exactly on
+        the deadline. Returns the final structured status —
+        completed/failed/timeout/pending — produced by ``control_device_smart``.
         """
         operation = get_operation_from_memory(operation_id)
 
@@ -607,31 +624,58 @@ class DeviceControlTools:
     @staticmethod
     def _normalize_bulk_parameters(
         value: Any,
-    ) -> tuple[dict[str, Any] | None, ErrorCode | None]:
-        """Normalize optional bulk parameters and identify invalid values."""
+    ) -> tuple[dict[str, Any] | None, ErrorCode | None, str]:
+        """Normalize a present ``parameters`` value and identify invalid ones.
+
+        Returns ``(parameters, error_code, detail)``. ``detail`` carries the
+        decoder's own reason and offset for a JSON failure — without it the
+        caller can only say "invalid JSON", which does not tell the sender
+        where its string went wrong. It is empty for every other outcome.
+        """
         if isinstance(value, str):
             try:
                 value = json.loads(value)
-            except json.JSONDecodeError:
-                return None, ErrorCode.VALIDATION_INVALID_JSON
-        if value is not None and not isinstance(value, dict):
-            return None, ErrorCode.VALIDATION_INVALID_PARAMETER
-        return value, None
+            except json.JSONDecodeError as exc:
+                return (
+                    None,
+                    ErrorCode.VALIDATION_INVALID_JSON,
+                    f"{exc.msg} at position {exc.pos}",
+                )
+            except RecursionError:
+                # json.loads recurses per nesting level; a pathologically
+                # nested string must skip the row, not abort the batch.
+                return (
+                    None,
+                    ErrorCode.VALIDATION_INVALID_JSON,
+                    "JSON nested too deeply",
+                )
+        if not isinstance(value, dict):
+            # A present-but-null value is malformed, same as timeout_seconds
+            # and validate_first; an absent key never reaches this helper.
+            return None, ErrorCode.VALIDATION_INVALID_PARAMETER, ""
+        return value, None, ""
 
     @staticmethod
-    def _normalize_bulk_timeout(value: Any) -> tuple[float | None, bool]:
-        """Normalize an optional non-negative finite timeout."""
-        if value is None:
-            return None, True
+    def _normalize_bulk_timeout(value: Any) -> float | None:
+        """Normalize a non-negative finite timeout, or ``None`` when invalid.
+
+        Bools are rejected before ``float()`` sees them: ``float(True)`` is 1.0,
+        which would silently accept ``timeout_seconds: true`` as a one-second
+        wait. Strings are rejected for the same reason — the advertised schema
+        is ``strict``, so coercing ``"10"`` here would silently accept what the
+        schema tells the model is invalid. ``None`` is invalid here too — the
+        caller only calls this when the key is present, and a present-but-null
+        timeout is a malformed row.
+        """
+        if isinstance(value, (bool, str)) or value is None:
+            return None
         try:
             timeout = float(value)
-        except (TypeError, ValueError):
-            return None, False
-        return (
-            (timeout, True)
-            if math.isfinite(timeout) and timeout >= 0
-            else (None, False)
-        )
+        except (TypeError, ValueError, OverflowError):
+            # OverflowError: an int too large for float must skip the row,
+            # not abort the batch through the generic exception handler.
+            return None
+        return timeout if math.isfinite(timeout) and timeout >= 0 else None
 
     @staticmethod
     def _normalized_bulk_operation(
@@ -647,6 +691,28 @@ class DeviceControlTools:
             normalized["timeout_seconds"] = timeout
         return normalized
 
+    @staticmethod
+    def _skip_bulk_operation(
+        skipped_operations: list[dict[str, Any]],
+        op: Any,
+        code: ErrorCode,
+        error: str,
+        context: dict[str, Any],
+        suggestions: list[str] | None = None,
+    ) -> None:
+        """Log one rejected bulk row and record its structured skip entry.
+
+        ``create_error_response`` lifts every ``context`` key to the top level,
+        so ``index`` needs no separate write; ``operation`` is not a context
+        key and is attached here so callers can see the row they sent.
+        """
+        logger.warning(f"Bulk control: {error}")
+        err_response = create_error_response(
+            code, error, suggestions=suggestions, context=context
+        )
+        err_response["operation"] = op
+        skipped_operations.append(err_response)
+
     @classmethod
     def _validate_bulk_operations(
         cls,
@@ -656,41 +722,28 @@ class DeviceControlTools:
         valid: list[tuple[int, dict[str, Any], str, str]] = []
         for i, op in enumerate(operations):
             if not isinstance(op, dict):
-                error = f"Operation at index {i} is not a dict: {type(op).__name__}"
-                logger.warning(f"Bulk control: {error}")
-                err_response = create_error_response(
-                    ErrorCode.VALIDATION_MISSING_PARAMETER, error, context={"index": i}
+                cls._skip_bulk_operation(
+                    skipped_operations,
+                    op,
+                    ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    f"Operation at index {i} is not a dict: {type(op).__name__}",
+                    {"index": i},
                 )
-                err_response["index"] = i
-                err_response["operation"] = op
-                skipped_operations.append(err_response)
                 continue
 
-            allowed_keys = {
-                "entity_id",
-                "action",
-                "parameters",
-                "timeout_seconds",
-                "validate_first",
-            }
-            obsolete_keys = sorted(set(op) - allowed_keys)
+            # str() before sorting: a direct Python caller can pass non-string
+            # keys, and mixed key types make sorted()/join() raise mid-batch.
+            obsolete_keys = sorted(str(key) for key in set(op) - _BULK_OPERATION_KEYS)
             if obsolete_keys:
                 key_list = ", ".join(obsolete_keys)
-                error = (
-                    f"Operation at index {i} contains unsupported key(s): {key_list}"
-                )
-                logger.warning(f"Bulk control: {error}")
-                err_response = create_error_response(
+                cls._skip_bulk_operation(
+                    skipped_operations,
+                    op,
                     ErrorCode.VALIDATION_INVALID_PARAMETER,
-                    error,
-                    suggestions=[
-                        "Use entity_id and action; put action data inside parameters"
-                    ],
-                    context={"index": i, "unsupported_keys": obsolete_keys},
+                    f"Operation at index {i} contains unsupported key(s): {key_list}",
+                    {"index": i, "unsupported_keys": obsolete_keys},
+                    suggestions=[_BULK_ROW_SHAPE_SUGGESTION],
                 )
-                err_response["index"] = i
-                err_response["operation"] = op
-                skipped_operations.append(err_response)
                 continue
 
             entity_id = op.get("entity_id")
@@ -698,83 +751,70 @@ class DeviceControlTools:
             missing = [f for f in ("entity_id", "action") if not op.get(f)]
 
             if missing:
-                error = f"Operation at index {i} missing required fields: {', '.join(missing)}"
-                logger.warning(f"Bulk control: {error}")
-                err_response = create_error_response(
-                    ErrorCode.VALIDATION_MISSING_PARAMETER, error, context={"index": i}
+                cls._skip_bulk_operation(
+                    skipped_operations,
+                    op,
+                    ErrorCode.VALIDATION_MISSING_PARAMETER,
+                    f"Operation at index {i} missing required fields: "
+                    f"{', '.join(missing)}",
+                    {"index": i},
                 )
-                err_response["index"] = i
-                err_response["operation"] = op
-                skipped_operations.append(err_response)
                 continue
 
             if not isinstance(entity_id, str) or not isinstance(action, str):
-                error = f"Operation at index {i} requires string entity_id and action fields"
-                logger.warning(f"Bulk control: {error}")
-                err_response = create_error_response(
+                cls._skip_bulk_operation(
+                    skipped_operations,
+                    op,
                     ErrorCode.VALIDATION_INVALID_PARAMETER,
-                    error,
-                    context={"index": i},
+                    f"Operation at index {i} requires string entity_id and "
+                    "action fields",
+                    {"index": i},
                 )
-                err_response["index"] = i
-                err_response["operation"] = op
-                skipped_operations.append(err_response)
                 continue
 
-            parameters, parameter_error = cls._normalize_bulk_parameters(
-                op.get("parameters")
+            parameters, parameter_error, parameter_detail = (
+                cls._normalize_bulk_parameters(op["parameters"])
+                if "parameters" in op
+                else (None, None, "")
             )
             if parameter_error is not None:
-                error = (
-                    f"Operation at index {i} has invalid JSON parameters"
+                parameter_message = (
+                    f"Operation at index {i} has invalid JSON parameters: "
+                    f"{parameter_detail}"
                     if parameter_error == ErrorCode.VALIDATION_INVALID_JSON
                     else f"Operation at index {i} parameters must be a JSON object"
                 )
-                logger.warning(f"Bulk control: {error}")
-                err_response = create_error_response(
+                cls._skip_bulk_operation(
+                    skipped_operations,
+                    op,
                     parameter_error,
-                    error,
-                    context={"index": i},
+                    parameter_message,
+                    {"index": i},
                 )
-                err_response["index"] = i
-                err_response["operation"] = op
-                skipped_operations.append(err_response)
                 continue
 
-            timeout = None
-            timeout_valid = "timeout_seconds" not in op
-            if not timeout_valid:
-                timeout, timeout_valid = cls._normalize_bulk_timeout(
-                    op["timeout_seconds"]
-                )
-                timeout_valid = timeout_valid and timeout is not None
-            if not timeout_valid:
-                error = (
-                    f"Operation at index {i} timeout_seconds must be a "
-                    "non-negative number"
-                )
-                logger.warning(f"Bulk control: {error}")
-                err_response = create_error_response(
-                    ErrorCode.VALIDATION_INVALID_PARAMETER,
-                    error,
-                    context={"index": i},
-                )
-                err_response["index"] = i
-                err_response["operation"] = op
-                skipped_operations.append(err_response)
-                continue
+            timeout: float | None = None
+            if "timeout_seconds" in op:
+                timeout = cls._normalize_bulk_timeout(op["timeout_seconds"])
+                if timeout is None:
+                    cls._skip_bulk_operation(
+                        skipped_operations,
+                        op,
+                        ErrorCode.VALIDATION_INVALID_PARAMETER,
+                        f"Operation at index {i} timeout_seconds must be a "
+                        "non-negative number",
+                        {"index": i},
+                    )
+                    continue
 
-            if "validate_first" in op and type(op["validate_first"]) is not bool:
-                error = f"Operation at index {i} validate_first must be a boolean"
-                logger.warning(f"Bulk control: {error}")
-                err_response = create_error_response(
+            if "validate_first" in op and not isinstance(op["validate_first"], bool):
+                cls._skip_bulk_operation(
+                    skipped_operations,
+                    op,
                     ErrorCode.VALIDATION_INVALID_PARAMETER,
-                    error,
-                    context={"index": i},
+                    f"Operation at index {i} validate_first must be a boolean",
+                    {"index": i},
                 )
-                err_response["index"] = i
-                err_response["operation"] = op
-                skipped_operations.append(err_response)
                 continue
 
             normalized_op = cls._normalized_bulk_operation(op, parameters, timeout)
@@ -824,8 +864,24 @@ class DeviceControlTools:
                 f"mode={'parallel' if parallel else 'sequential'}",
             )
             if not valid_operations:
-                return self._build_bulk_response(
-                    operations, results, operation_ids, skipped_operations, parallel
+                # Nothing dispatched, so nothing to fail soft for: the batch
+                # carve-out from "all tool-level failures raise" exists to
+                # protect successful siblings, and there are none. Raising
+                # before the component probe keeps the no-dispatch guarantee.
+                raise_tool_error(
+                    create_error_response(
+                        ErrorCode.VALIDATION_INVALID_PARAMETER,
+                        f"All {len(operations)} operation(s) failed validation; "
+                        "nothing was dispatched",
+                        suggestions=[
+                            _BULK_ROW_SHAPE_SUGGESTION,
+                            "Each operation requires 'entity_id' and 'action'",
+                            "Check skipped_details for the per-operation reason",
+                            "Example: {'entity_id': 'light.living_room', "
+                            + "'action': 'on'}",
+                        ],
+                        context={"skipped_details": skipped_operations},
+                    )
                 )
 
             # Route through the component's bulk_call_service capability when
@@ -1439,6 +1495,7 @@ class DeviceControlTools:
         if skipped_operations:
             response["skipped_details"] = skipped_operations
             response["suggestions"] = [
+                _BULK_ROW_SHAPE_SUGGESTION,
                 "Some operations were skipped due to validation errors",
                 "Each operation requires 'entity_id' and 'action' fields",
                 "Check skipped_details for specific errors",

{ha_mcp_dev-8.3.0.dev2379 → ha_mcp_dev-8.3.0.dev2385}/src/ha_mcp/tools/smart_search/_base.py

@@ -40,9 +40,14 @@ class _SearchBase:
             logger.debug(f"Could not fetch {label}: {result}")
             cause = str(result) or type(result).__name__
         elif isinstance(result, dict) and result.get("success"):
-            payload = result.get("result", [])
+            # No default for a missing key: a legitimate empty registry is
+            # "result": [], so an absent result is a malformed envelope and
+            # must degrade loudly, not read as available-and-empty.
+            payload = result.get("result")
             if isinstance(payload, list):
                 registry = payload
+            elif payload is None and "result" not in result:
+                cause = "malformed result payload: result key missing"
             else:
                 cause = (
                     "malformed result payload: expected list, "

{ha_mcp_dev-8.3.0.dev2379 → ha_mcp_dev-8.3.0.dev2385}/src/ha_mcp/tools/smart_search/_entities.py

@@ -473,13 +473,15 @@ class EntitySearchMixin(_SearchBase):
             area_registry = self._parse_area_registry(results[1], registry_warnings)
             entity_reg_map = self._parse_entity_reg_map(results[2], registry_warnings)
             device_area_map = self._parse_device_area_map(results[3], registry_warnings)
-            floor_result = results[4]
-            floor_registry_available = (
-                isinstance(floor_result, dict)
-                and floor_result.get("success") is True
-                and isinstance(floor_result.get("result"), list)
-            )
-            floor_registry = self._parse_floor_registry(floor_result, registry_warnings)
+            # Availability is read back OUT of the parse rather than re-derived
+            # from the raw payload: the parser already decides what counts as
+            # usable floor data, and a second predicate here drifted from it
+            # once. An empty warnings list means the parser accepted the
+            # payload; anything else disables the fuzzy floor/area fallback.
+            floor_warnings: list[str] = []
+            floor_registry = self._parse_floor_registry(results[4], floor_warnings)
+            floor_registry_available = not floor_warnings
+            registry_warnings.extend(floor_warnings)
             degraded_warnings = registry_warnings + visibility_warnings
 
             matched_area_ids, resolution_warnings = self._resolve_area_query(
@@ -657,8 +659,15 @@ class EntitySearchMixin(_SearchBase):
 
         if not floor_registry_available:
             # Without the floor registry, fuzzy area matching could silently
-            # recreate the original floor->partial-area misresolution.
-            return set(), []
+            # recreate the original floor->partial-area misresolution. The
+            # fetch warning names the outage; this one names what the outage
+            # cost the caller, so "no match" is not read as "no such area".
+            return set(), [
+                f"Floor data is unavailable, so '{area_query}' was matched only "
+                "against exact area IDs, names, and aliases; close-spelling "
+                "matching was skipped. Retry, or pass an exact area_id from "
+                "ha_list_floors_areas."
+            ]
 
         fuzzy_floor_ids, floor_score = cls._match_fuzzy_registry_ids(
             floor_registry, "floor_id", query_lower
@@ -768,7 +777,10 @@ class EntitySearchMixin(_SearchBase):
         """Resolve the query to area IDs: exact id/name/alias, then fuzzy.
 
         Exact matches delegate to the shared registry matcher so area and floor
-        precedence use identical case-insensitive semantics.
+        precedence use identical case-insensitive semantics. Exact must win
+        outright: a query like "bedroom_kids" partial-matches its parent
+        "bedroom" at ratio 100, so falling through to the fuzzy pass would
+        aggregate every sibling area's entities under an exact hit.
         """
         exact_area_ids = cls._match_exact_registry_ids(
             area_registry, "area_id", area_query_lower

{ha_mcp_dev-8.3.0.dev2379 → ha_mcp_dev-8.3.0.dev2385}/src/ha_mcp/tools/tools_search.py

@@ -321,12 +321,11 @@ def _finalize_partial_state(
     if partial_local:
         response["partial"] = True
         response["errors"].extend(errors_local)
-        local_reason = "; ".join(
-            f"{error['surface']}: {error['error']}" for error in errors_local
-        )
-        existing_reason = response.get("partial_reason")
-        response["partial_reason"] = (
-            f"{existing_reason}; {local_reason}" if existing_reason else local_reason
+        _merge_partial_reason(
+            response,
+            "; ".join(
+                f"{error['surface']}: {error['error']}" for error in errors_local
+            ),
         )
 
 
@@ -2217,7 +2216,11 @@ class SearchTools:
                 raise outcome
             if isinstance(outcome, Exception):
                 partial = True
-                errors.append({"surface": label, "error": str(outcome)})
+                # ``str(asyncio.TimeoutError())`` is "" — fall back to the type
+                # name so partial_reason never reads "entities: ".
+                errors.append(
+                    {"surface": label, "error": str(outcome) or type(outcome).__name__}
+                )
                 logger.warning("ha_search %s branch failed: %r", label, outcome)
                 continue
             _apply_search_outcome(response, label, outcome)