ha-mcp-dev 8.7.0.dev3067__tar.gz → 8.7.0.dev3072__tar.gz

{ha_mcp_dev-8.7.0.dev3067 → ha_mcp_dev-8.7.0.dev3072}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.7.0.dev3067
+Version: 8.7.0.dev3072
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Keywords: mcp,home-assistant,ai,automation,smart-home
 Author: Julien

{ha_mcp_dev-8.7.0.dev3067 → ha_mcp_dev-8.7.0.dev3072}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.7.0.dev3067"
+version = "8.7.0.dev3072"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.15"

{ha_mcp_dev-8.7.0.dev3067 → ha_mcp_dev-8.7.0.dev3072}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.7.0.dev3067"
+version = "8.7.0.dev3072"
 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.7.0.dev3072/src/ha_mcp/backup_dashboards.py

@@ -0,0 +1,257 @@
+"""Auto-backup handlers for dashboards.
+
+A dashboard snapshot, marked ``kind: "dashboard_settings"``, holds the
+dashboard's ``lovelace/dashboards/list`` storage row beside its config body,
+``{"dashboard": <row>, "config": <body>}``, so a restore can re-create a deleted
+dashboard: Core's ``lovelace/config/save`` answers ``config_not_found`` for a
+url_path it has no dashboard for. A restore reads the live list before any
+write; a dashboard that still exists gets its config back, then its settings
+through ``lovelace/dashboards/update``. The row is ``None`` for a dashboard the
+list holds no storage row for (YAML, or a fresh install's default before Core
+migrates it); an unreadable list fails the capture instead. The body is
+``None`` for a dashboard whose config was never saved. A dashboard snapshot
+without that ``kind`` predates the row and holds the body alone; it restores
+and compares as the body only.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .backup_entity_ids import _manager
+from .client.rest_client import HomeAssistantCommandError, HomeAssistantError
+
+# Core's DASHBOARD_BASE_UPDATE_FIELDS: what lovelace/dashboards/update accepts.
+_SETTINGS_FIELDS = ("title", "icon", "require_admin", "show_in_sidebar")
+_DASHBOARD_KIND = "dashboard_settings"
+
+
+def valid_dashboard_capture(config: Any) -> bool:
+    """The shape a ``_DASHBOARD_KIND`` snapshot's config must have."""
+    if not isinstance(config, dict) or set(config) != {"dashboard", "config"}:
+        return False
+    row = config["dashboard"]
+    return row is None or (
+        isinstance(row, dict) and isinstance(row.get("url_path"), str)
+    )
+
+
+def dashboard_snapshot(data: dict[str, Any]) -> tuple[dict[str, Any], bool]:
+    """A snapshot's ``{"dashboard", "config"}`` value, and whether it is a
+    legacy body-only snapshot (one written without ``_DASHBOARD_KIND``)."""
+    if data.get("kind") == _DASHBOARD_KIND:
+        return data["config"], False
+    return {"dashboard": None, "config": data["config"]}, True
+
+
+def _storage_row(
+    dashboards: list[dict[str, Any]] | None, url_path: str
+) -> dict[str, Any] | None:
+    return next(
+        (
+            d
+            for d in dashboards or []
+            if d.get("url_path") == url_path and d.get("mode") == "storage"
+        ),
+        None,
+    )
+
+
+async def fetch_dashboard(client: Any, entity_id: str) -> Any:
+    """Fetch a dashboard config via the same helper the get tool uses.
+
+    The identifier is pre-resolved to its canonical url_path via the shared
+    ``_resolve_dashboard`` (component ``list`` when available), then the config is
+    read through the component ``get`` (one in-process frame) with a fall back to
+    the legacy ``lovelace/config`` read (``_get_dashboard_config_internal``, which
+    handles the WS envelope, force-cache-bypass, and structured error wrapping).
+    The component refuses YAML bodies, so those capture through legacy unchanged.
+    Imported lazily to avoid an import cycle.
+    """
+    from ha_mcp._vendor.fastmcp.exceptions import ToolError
+
+    from .tools.tools_config_dashboards import (
+        _component_dashboard_config,
+        _get_dashboard_config_internal,
+        _resolve_dashboard,
+    )
+
+    # The set/delete tools accept the canonical url_path, HA's internal
+    # (underscored) dashboard id and the ``default`` alias for Core's
+    # ``lovelace`` item. ``_get_dashboard_config_internal`` does NOT
+    # lazy-resolve (an internal id 404s with "Unknown config specified" and
+    # the snapshot is skipped), so pre-resolve to the form the tool targets.
+    fetch_path = "lovelace" if entity_id == "default" else entity_id
+    unread = (
+        "Could not read lovelace/dashboards/list, so the dashboard's settings "
+        "could not be captured"
+    )
+    try:
+        match, dashboards = await _resolve_dashboard(client, fetch_path)
+    except (HomeAssistantError, ToolError) as err:
+        raise HomeAssistantError(unread) from err
+    if dashboards is None:
+        raise HomeAssistantError(unread)
+    if match and match.get("url_path"):
+        fetch_path = match["url_path"]
+
+    row = _storage_row(dashboards, fetch_path)
+    config = await _component_dashboard_config(client, fetch_path)
+    if config is None:
+        # Legacy read: YAML dashboards, no component, and not-found.
+        try:
+            config, _config_hash = await _get_dashboard_config_internal(
+                client, fetch_path
+            )
+        except (ToolError, HomeAssistantError) as err:
+            # Both carry HA's preserved ``config_not_found`` code: an unknown
+            # url_path ("Unknown config specified", also the create path), or
+            # a dashboard whose config was never saved, which keeps its row.
+            msg = str(err).lower()
+            if "not_found" not in msg and "unknown config" not in msg:
+                raise
+            config = None
+            if row is None:
+                return None
+    return {"dashboard": row, "config": config}
+
+
+def _config_write(url_path: str | None, body: Any) -> dict[str, Any]:
+    """Put back ``body``; ``None`` was "no stored config", which Core's
+    ``lovelace/config/delete`` restores (it succeeds when nothing is stored).
+    No ``url_path`` targets Core's default store."""
+    message: dict[str, Any] = (
+        {"type": "lovelace/config/delete"}
+        if body is None
+        else {"type": "lovelace/config/save", "config": body}
+    )
+    return message if url_path is None else {**message, "url_path": url_path}
+
+
+async def _save(client: Any, url_path: str, config: Any) -> Any:
+    return await _manager()._ws_send(client, _config_write(url_path, config))
+
+
+async def _saved(client: Any, url_path: str, config: Any) -> bool:
+    """Write; ``False`` when Core has no dashboard at ``url_path``."""
+    try:
+        await _save(client, url_path, config)
+    except HomeAssistantCommandError as err:
+        if err.code != "config_not_found":
+            raise
+        return False
+    return True
+
+
+async def restore_dashboard(client: Any, entity_id: str, config: Any) -> Any:
+    from .tools.tools_config_dashboards import _resolve_dashboard
+
+    row = config["dashboard"]
+    body = config["config"]
+    if row is None:
+        return await _restore_body(client, entity_id, body)
+    url_path = row["url_path"]
+    _match, dashboards = await _resolve_dashboard(client, url_path)
+    if dashboards is None:
+        raise HomeAssistantError(
+            "Could not read lovelace/dashboards/list, so nothing was restored"
+        )
+    live = _storage_row(dashboards, url_path)
+    if live is None:
+        return await _recreate(client, row, body)
+    await _save(client, url_path, body)
+    return await _restore_settings(client, live["id"], row)
+
+
+async def _recreate(client: Any, row: dict[str, Any], body: Any) -> Any:
+    bm = _manager()
+    url_path = row["url_path"]
+    # The component's rows carry ``icon: None`` for an unset icon, which Core's
+    # create schema rejects; an omitted field takes Core's default.
+    fields = bm._strip_readonly(row, "id", "mode")
+    create = {
+        "type": "lovelace/dashboards/create",
+        **{key: value for key, value in fields.items() if value is not None},
+    }
+    if "-" not in url_path:
+        # Core's own single-word dashboards (``lovelace``, ``map``) need this.
+        create["allow_single_word"] = True
+    try:
+        await bm._ws_send(client, create)
+    except HomeAssistantCommandError as err:
+        # Deleting ``lovelace`` re-registers Core's built-in panel there, so
+        # create raises url_already_exists, sent as home_assistant_error.
+        if url_path != "lovelace" or err.code != "home_assistant_error":
+            raise
+        return await _restore_default_store(client, body)
+    if body is not None:
+        await _save(client, url_path, body)
+    return None
+
+
+async def _restore_settings(
+    client: Any, dashboard_id: str, row: dict[str, Any]
+) -> None:
+    """Put back the row's settings after its config; ``icon: None`` clears it."""
+    bm = _manager()
+    fields = {key: row[key] for key in _SETTINGS_FIELDS if key in row}
+    # Core's own list omits ``icon`` when none is stored; the component's sends None.
+    fields.setdefault("icon", None)
+    update = {"type": "lovelace/dashboards/update", "dashboard_id": dashboard_id}
+    try:
+        await bm._ws_send(client, {**update, **fields})
+    except bm._CAPTURE_TRANSIENT_ERRORS as err:
+        raise bm.BackupRestoreError(
+            f"The config of dashboard {row['url_path']} was restored, but its "
+            "settings (title, icon, sidebar, admin) may not have been.",
+            apply_status="unknown",
+            reason="settings_not_restored",
+        ) from err
+
+
+async def _restore_default_store(client: Any, body: Any) -> dict[str, Any]:
+    """Put the body in Core's default store, which the built-in panel reads."""
+    if body is None:
+        return {
+            "note": "Home Assistant shows its auto-generated default dashboard "
+            "at /lovelace again, as before; its saved title and icon are not "
+            "restored."
+        }
+    await _manager()._ws_send(client, _config_write(None, body))
+    return {
+        "note": "The config was restored to Home Assistant's default dashboard "
+        "store, shown at /lovelace. At the next restart Home Assistant moves it "
+        "back into a 'lovelace' dashboard with its default title and icon."
+    }
+
+
+async def _restore_body(client: Any, entity_id: str, config: Any) -> Any:
+    """Restore a snapshot's body alone to the dashboard it was taken from."""
+    from .tools.tools_config_dashboards import _resolve_dashboard
+
+    url_path = "lovelace" if entity_id == "default" else entity_id
+    if await _saved(client, url_path, config):
+        return None
+    # The snapshot may name the dashboard by its internal id.
+    match, dashboards = await _resolve_dashboard(client, url_path)
+    if dashboards is None:
+        raise HomeAssistantError("Could not read lovelace/dashboards/list")
+    if match and match["url_path"] != url_path:
+        return await _save(client, match["url_path"], config)
+    raise _manager().BackupRestoreError(
+        f"Dashboard {url_path} no longer exists, and this snapshot holds no "
+        "dashboard settings to re-create it from. Nothing was changed.",
+        reason="entry_deleted",
+        suggestions=[
+            f"Re-create it with ha_config_set_dashboard(url_path={url_path!r}, "
+            "title=...), then restore this snapshot again."
+        ],
+    )
+
+
+def dashboard_comparison(current: Any, *, legacy: bool) -> Any:
+    """The live value to diff a snapshot against: a legacy snapshot compares
+    with the live body."""
+    if current is None or not legacy:
+        return current
+    return current["config"]

{ha_mcp_dev-8.7.0.dev3067 → ha_mcp_dev-8.7.0.dev3072}/src/ha_mcp/backup_manager.py

@@ -66,6 +66,14 @@ import yaml  # type: ignore[import-untyped]
 from ha_mcp._vendor.fastmcp.exceptions import ToolError
 from ha_mcp._vendor.websockets.exceptions import ConnectionClosed
 
+from .backup_dashboards import (
+    _DASHBOARD_KIND,
+    dashboard_comparison,
+    dashboard_snapshot,
+    fetch_dashboard,
+    restore_dashboard,
+    valid_dashboard_capture,
+)
 from .backup_diff import (
     _TEXT_KIND,
     DiffResponse,
@@ -215,6 +223,17 @@ def _validate_snapshot_envelope(data: dict[str, Any]) -> None:
     for key in ("domain", "entity_id"):
         if not isinstance(data[key], str) or (key == "domain" and not data[key]):
             raise InvalidBackupSnapshotError(f"Snapshot has invalid {key}")
+    if data.get("kind") == _DASHBOARD_KIND and not valid_dashboard_capture(
+        data["config"]
+    ):
+        raise InvalidBackupSnapshotError("Snapshot has invalid config")
+
+
+def _handler_config(data: dict[str, Any]) -> Any:
+    """The config a domain handler restores from a snapshot."""
+    if data["domain"] == "dashboard":
+        return dashboard_snapshot(data)[0]
+    return data["config"]
 
 
 class _FlowHelperReadError(HomeAssistantError):
@@ -320,7 +339,8 @@ _MAX_SAME_SECOND = 100
 # Domains whose snapshot ``config`` is raw text (file/YAML content) rather
 # than a structured dict. They carry a ``kind: "text"`` marker in the
 # snapshot payload and diff via a unified text diff instead of JSON-Patch
-# (#1579 PR2). Everything else is the implicit ``"dict"`` kind.
+# (#1579 PR2). Dashboard snapshots carry ``kind: "dashboard_settings"``
+# (backup_dashboards); everything else is the implicit ``"dict"`` kind.
 #
 # ``yaml_file`` is a whole-file YAML-config snapshot: same fetch as ``file``
 # (read_file), but restored via edit_yaml_config(action="replace_file") because
@@ -1048,6 +1068,8 @@ class BackupManager:
         }
         if domain in _TEXT_DOMAINS:
             payload["kind"] = _TEXT_KIND
+        elif domain == "dashboard":
+            payload["kind"] = _DASHBOARD_KIND
         body = yaml.safe_dump(payload, default_flow_style=False, sort_keys=False)
         # mkstemp creates a unique 0600 inode before any configuration is written.
         fd, tmp_name = tempfile.mkstemp(
@@ -1491,7 +1513,7 @@ class BackupManager:
     ) -> dict[str, Any]:
         domain = data["domain"]
         entity_id = data["entity_id"]
-        config = data["config"]
+        config = _handler_config(data)
         handler = self.handler_for(domain)
         if handler is None:
             raise BackupRestoreError(
@@ -1634,6 +1656,15 @@ class BackupManager:
         if handler is None:
             raise LookupError(f"No diff handler registered for domain {domain!r}")
         current = await handler.fetch(self._client, data["entity_id"])
+        if domain == "dashboard":
+            _stored, legacy = dashboard_snapshot(data)
+            current = dashboard_comparison(current, legacy=legacy)
+        elif domain == "dashboard_resource" and current is None:
+            # A re-created resource carries a Core-generated id, which is not
+            # a difference the snapshot can restore.
+            live = await _dashboard_resource_like(self._client, data["config"])
+            if live is not None:
+                current = {**live, "id": data["config"].get("id")}
         if (
             isinstance(current, dict)
             and isinstance(data["config"], dict)
@@ -2046,86 +2077,6 @@ async def _restore_scene(client: Any, entity_id: str, config: Any) -> Any:
     return await client.upsert_scene_config(config, entity_id)
 
 
-# Dashboards — WS lovelace/config (fetch) and lovelace/config/save (restore).
-
-
-async def _fetch_dashboard(client: Any, entity_id: str) -> Any:
-    """Fetch a dashboard config via the same helper the get tool uses.
-
-    The identifier is pre-resolved to its canonical url_path via the shared
-    ``_resolve_dashboard`` (component ``list`` when available), then the config is
-    read through the component ``get`` (one in-process frame) with a fall back to
-    the legacy ``lovelace/config`` read (``_get_dashboard_config_internal``, which
-    handles the WS envelope, force-cache-bypass, and structured error wrapping).
-    The component refuses YAML bodies, so those capture through legacy unchanged.
-    Imported lazily to avoid an import cycle.
-    """
-    from ha_mcp._vendor.fastmcp.exceptions import ToolError
-
-    from .tools.tools_config_dashboards import (
-        _component_dashboard_config,
-        _get_dashboard_config_internal,
-        _resolve_dashboard,
-    )
-
-    # The set/delete tools accept BOTH the canonical hyphenated url_path
-    # AND HA's internal (underscored) dashboard id, eagerly resolving the
-    # latter before writing. ``_get_dashboard_config_internal`` does NOT
-    # lazy-resolve, so an internal-id identifier 404s with "Unknown config
-    # specified" and the pre-write snapshot is silently skipped. Pre-resolve
-    # to the canonical url_path so capture works for whichever form the
-    # caller passed (matching the form the write tool ultimately targets).
-    fetch_path = entity_id
-    try:
-        match, _ = await _resolve_dashboard(client, entity_id)
-        if match and match.get("url_path"):
-            fetch_path = match["url_path"]
-    except (HomeAssistantError, ToolError) as err:
-        # Resolver failure (transport/shape) — fall through with the
-        # original identifier; the canonical form is often already correct.
-        logger.debug(
-            "Auto-backup: dashboard resolve failed for %r: %s — using as-is",
-            entity_id,
-            err,
-        )
-
-    # Component fast path (freshness-safe in-memory read); None ⇒ legacy below,
-    # which also covers YAML dashboards and not-found (nothing to back up).
-    component_config = await _component_dashboard_config(client, fetch_path)
-    if component_config is not None:
-        return component_config
-
-    try:
-        config, _config_hash = await _get_dashboard_config_internal(client, fetch_path)
-    except ToolError as err:
-        # ToolError carries the structured failure payload, including HA's
-        # preserved ``config_not_found`` code; treat a missing/unknown
-        # dashboard as "nothing to back up" (also covers a brand-new dashboard
-        # on the create path). "Unknown config specified" is HA's message for
-        # an unresolved url_path.
-        msg = str(err).lower()
-        if "not_found" in msg or "config_not_found" in msg or "unknown config" in msg:
-            return None
-        raise
-    except HomeAssistantError as err:
-        msg = str(err).lower()
-        if "not_found" in msg or "config_not_found" in msg or "unknown config" in msg:
-            return None
-        raise
-    return config
-
-
-async def _restore_dashboard(client: Any, entity_id: str, config: Any) -> Any:
-    return await _ws_send(
-        client,
-        {
-            "type": "lovelace/config/save",
-            "url_path": entity_id,
-            "config": config,
-        },
-    )
-
-
 def _require_list(value: Any, endpoint: str) -> list[Any]:
     """Return ``value`` if it's a list, else raise.
 
@@ -2165,24 +2116,50 @@ def _require_dict(value: Any, endpoint: str) -> dict[str, Any]:
     return value
 
 
-# Dashboard resources — WS lovelace_resources commands.
+# Dashboard resources — WS lovelace/resources commands. Rows store the
+# resource type as ``type``; the create/update field is ``res_type``. A restore
+# of a deleted resource re-creates it under a new id, so a snapshot falls back
+# to the row that holds its url and type; Core does not keep urls unique, so a
+# row that only shares the url is another resource and is left alone.
+async def _dashboard_resources(client: Any) -> list[Any]:
+    return _require_list(
+        await _ws_send(client, {"type": "lovelace/resources"}), "lovelace/resources"
+    )
 
 
 async def _fetch_dashboard_resource(client: Any, entity_id: str) -> Any:
-    resources = _require_list(
-        await _ws_send(client, {"type": "lovelace/resources"}), "lovelace/resources"
+    resources = await _dashboard_resources(client)
+    return next((r for r in resources if str(r.get("id")) == entity_id), None)
+
+
+async def _dashboard_resource_like(client: Any, config: dict[str, Any]) -> Any:
+    """The live row with the snapshot's url and type, else ``None``."""
+    resources = await _dashboard_resources(client)
+    return next(
+        (
+            r
+            for r in resources
+            if r.get("url") == config["url"] and r.get("type") == config.get("type")
+        ),
+        None,
     )
-    for res in resources:
-        if str(res.get("id")) == entity_id:
-            return res
-    return None
 
 
 async def _restore_dashboard_resource(client: Any, entity_id: str, config: Any) -> Any:
-    payload = _strip_readonly(config, "id")
-    payload["resource_id"] = entity_id
-    payload["type"] = "lovelace/resources/update"
-    return await _ws_send(client, payload)
+    # Core imported old ``resources:`` entries without a type (RESOURCE_FIELDS).
+    payload = _strip_readonly(config, "id", "type")
+    if "type" in config:
+        payload["res_type"] = config["type"]
+    update = {"type": "lovelace/resources/update", "resource_id": entity_id}
+    try:
+        return await _ws_send(client, {**update, **payload})
+    except HomeAssistantCommandError as err:
+        if err.code != "not_found":  # not_found: deleted since the snapshot
+            raise
+    live = await _dashboard_resource_like(client, config)
+    if live is not None:  # an earlier restore re-created it
+        return live
+    return await _ws_send(client, {"type": "lovelace/resources/create", **payload})
 
 
 # Labels — config/label_registry/{list,update}
@@ -3925,7 +3902,7 @@ def register_default_handlers(mgr: BackupManager, _client: Any) -> None:
     mgr.register(DomainHandler("automation", _fetch_automation, _restore_automation))
     mgr.register(DomainHandler("script", _fetch_script, _restore_script))
     mgr.register(DomainHandler("scene", _fetch_scene, _restore_scene))
-    mgr.register(DomainHandler("dashboard", _fetch_dashboard, _restore_dashboard))
+    mgr.register(DomainHandler("dashboard", fetch_dashboard, restore_dashboard))
     mgr.register(
         DomainHandler(
             "dashboard_resource", _fetch_dashboard_resource, _restore_dashboard_resource

{ha_mcp_dev-8.7.0.dev3067 → ha_mcp_dev-8.7.0.dev3072}/src/ha_mcp/tools/dashboard_card_describe.py

@@ -6,7 +6,7 @@ Home Assistant serves; this module compacts it the way helper ``describe`` does.
 
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, NoReturn
 
 from ..client.websocket_client import get_websocket_client
 from ..errors import ErrorCode, create_error_response
@@ -38,6 +38,77 @@ def _flatten(schema: list[Any]) -> list[dict[str, Any]]:
     return fields
 
 
+def _raise_describe_error(result: dict[str, Any], card_type: str | None) -> NoReturn:
+    """Map the component's describe error to a tool error."""
+    error = result.get("error")
+    if error == "describe_timeout":
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.TIMEOUT_OPERATION,
+                "Describing this card took longer than Home Assistant's command budget.",
+                suggestions=["Retry; a loaded index usually answers within a second"],
+                context={"action": "describe", "card_type": card_type},
+            )
+        )
+    if error == "definitions_loading":
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.SERVICE_CALL_FAILED,
+                "Home Assistant is still indexing the installed frontend's card "
+                "definitions (the first describe after a Home Assistant start; a "
+                "slow board can take minutes). Retry shortly.",
+                suggestions=[
+                    "Retry in a minute; the index is kept until the next restart"
+                ],
+                context={"action": "describe", "card_type": card_type},
+            )
+        )
+    if error in ("custom_cards_loading", "custom_card_not_inspected"):
+        status = result.get("custom_status", {})
+        loading = error == "custom_cards_loading"
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.SERVICE_CALL_FAILED,
+                "Custom card inspection is still loading; retry shortly."
+                if loading
+                else "This custom card could not be inspected from dashboard resources.",
+                suggestions=["Retry after resource loading finishes"]
+                if loading
+                else [
+                    "Check the resource inspection status and type spelling",
+                    "Cards loaded through extra JavaScript may work in the browser without appearing in dashboard resources",
+                ],
+                context={
+                    "action": "describe",
+                    "card_type": card_type,
+                    "custom_status": status,
+                },
+            )
+        )
+    if error == "unknown_card_type":
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.VALIDATION_INVALID_PARAMETER,
+                f"'{card_type}' is not a known card type.",
+                suggestions=[
+                    "Use one of: " + ", ".join(result.get("card_types", [])),
+                ],
+                context={"action": "describe", "card_type": card_type},
+            )
+        )
+    raise_tool_error(
+        create_error_response(
+            ErrorCode.SERVICE_CALL_FAILED,
+            "Home Assistant's card definitions are unavailable.",
+            details=str(error),
+            suggestions=[
+                "Use ha_get_skill_guide(file='references/dashboard-cards.md') for static card guidance"
+            ],
+            context={"action": "describe", "card_type": card_type},
+        )
+    )
+
+
 async def describe_card_response(client: Any, card_type: str | None) -> dict[str, Any]:
     """The card type list, or one card type's fields as its UI editor defines them."""
     card_type = card_type or None
@@ -73,51 +144,7 @@ async def describe_card_response(client: Any, card_type: str | None) -> dict[str
     if not isinstance(result, dict):
         result = {}
     if result.get("success") is not True:
-        error = result.get("error")
-        if error in ("custom_cards_loading", "custom_card_not_inspected"):
-            status = result.get("custom_status", {})
-            loading = error == "custom_cards_loading"
-            raise_tool_error(
-                create_error_response(
-                    ErrorCode.SERVICE_CALL_FAILED,
-                    "Custom card inspection is still loading; retry shortly."
-                    if loading
-                    else "This custom card could not be inspected from dashboard resources.",
-                    suggestions=["Retry after resource loading finishes"]
-                    if loading
-                    else [
-                        "Check the resource inspection status and type spelling",
-                        "Cards loaded through extra JavaScript may work in the browser without appearing in dashboard resources",
-                    ],
-                    context={
-                        "action": "describe",
-                        "card_type": card_type,
-                        "custom_status": status,
-                    },
-                )
-            )
-        if error == "unknown_card_type":
-            raise_tool_error(
-                create_error_response(
-                    ErrorCode.VALIDATION_INVALID_PARAMETER,
-                    f"'{card_type}' is not a known card type.",
-                    suggestions=[
-                        "Use one of: " + ", ".join(result.get("card_types", [])),
-                    ],
-                    context={"action": "describe", "card_type": card_type},
-                )
-            )
-        raise_tool_error(
-            create_error_response(
-                ErrorCode.SERVICE_CALL_FAILED,
-                "Home Assistant's card definitions are unavailable.",
-                details=str(error),
-                suggestions=[
-                    "Use ha_get_skill_guide(file='references/dashboard-cards.md') for static card guidance"
-                ],
-                context={"action": "describe", "card_type": card_type},
-            )
-        )
+        _raise_describe_error(result, card_type)
     if card_type is None:
         return {
             "success": True,