ha-mcp-dev 7.5.0.dev569__tar.gz → 7.5.0.dev571__tar.gz

{ha_mcp_dev-7.5.0.dev569/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.5.0.dev571}/PKG-INFO

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

{ha_mcp_dev-7.5.0.dev569 → ha_mcp_dev-7.5.0.dev571}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.5.0.dev569"
+version = "7.5.0.dev571"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"

{ha_mcp_dev-7.5.0.dev569 → ha_mcp_dev-7.5.0.dev571}/src/ha_mcp/client/rest_client.py

@@ -7,6 +7,7 @@ import json
 import logging
 import os
 import ssl
+import time
 from typing import Any
 
 import httpx
@@ -963,12 +964,18 @@ class HomeAssistantClient:
                 ) from e
             raise
 
-    # 3-attempt × 6s upper-bound budget; first poll 0.1s catches the
-    # typical sub-1s entity-publish window.
-    _POLL_CADENCE: tuple[float, ...] = (0.1, 1.0, 4.9)
+    # 3-attempt × 6s upper-bound budget; first poll 0.025s is a 5×
+    # cushion above the ~4ms HA-Core entity-registration latency
+    # measured by ``test_poll_cadence_measurement.py`` (#1389 — p50
+    # 104.1-104.8 ms on the prior 0.1s first-poll, all from the sleep
+    # itself with ~4 ms of real registration work).
+    _POLL_CADENCE: tuple[float, ...] = (0.025, 1.0, 4.975)
 
     async def _poll_for_automation_entity(self, unique_id: str) -> str | None:
         """Poll HA state to find the entity_id assigned to a newly created automation."""
+        # Measure cumulative elapsed from function entry to first successful match.
+        # Feeds the #1389 p50/p99 validation of `_POLL_CADENCE`.
+        start_monotonic = time.monotonic()
         try:
             for sleep_time in self._POLL_CADENCE:
                 await asyncio.sleep(sleep_time)
@@ -978,8 +985,13 @@ class HomeAssistantClient:
                         continue
                     if state.get("attributes", {}).get("id") == unique_id:
                         entity_id = state.get("entity_id")
+                        elapsed_ms = (time.monotonic() - start_monotonic) * 1000.0
                         logger.debug(
-                            f"Found actual entity_id for unique_id {unique_id}: {entity_id}"
+                            "entity-registration-elapsed: %.1fms "
+                            "(unique_id=%s, entity_id=%s)",
+                            elapsed_ms,
+                            unique_id,
+                            entity_id,
                         )
                         return entity_id
         except HomeAssistantError as e:

{ha_mcp_dev-7.5.0.dev569 → ha_mcp_dev-7.5.0.dev571}/src/ha_mcp/tools/tools_categories.py

@@ -36,7 +36,11 @@ class CategoryTools:
     @tool(
         name="ha_config_get_category",
         tags={"Labels & Categories"},
-        annotations={"idempotentHint": True, "readOnlyHint": True, "title": "Get Category"},
+        annotations={
+            "idempotentHint": True,
+            "readOnlyHint": True,
+            "title": "Get Category",
+        },
     )
     @log_tool_usage
     async def ha_config_get_category(
@@ -133,7 +137,7 @@ class CategoryTools:
                 available_ids = [cat.get("category_id") for cat in categories[:10]]
                 raise_tool_error(
                     create_error_response(
-                        ErrorCode.ENTITY_NOT_FOUND,
+                        ErrorCode.RESOURCE_NOT_FOUND,
                         f"Category not found: {category_id}",
                         context={
                             "category_id": category_id,
@@ -247,6 +251,22 @@ class CategoryTools:
                     "message": f"Successfully {action_past} category: {name}",
                 }
             else:
+                error_str = str(result.get("error", "")).lower()
+                if "not found" in error_str or "doesn't exist" in error_str:
+                    raise_tool_error(
+                        create_error_response(
+                            ErrorCode.RESOURCE_NOT_FOUND,
+                            f"Category not found: {category_id}",
+                            context={
+                                "name": name,
+                                "scope": scope,
+                                "category_id": category_id,
+                            },
+                            suggestions=[
+                                f"Use ha_config_get_category('{scope}') without category_id to see all categories",
+                            ],
+                        )
+                    )
                 raise_tool_error(
                     create_error_response(
                         ErrorCode.SERVICE_CALL_FAILED,
@@ -276,7 +296,11 @@ class CategoryTools:
     @tool(
         name="ha_config_remove_category",
         tags={"Labels & Categories"},
-        annotations={"destructiveHint": True, "idempotentHint": True, "title": "Remove Category"},
+        annotations={
+            "destructiveHint": True,
+            "idempotentHint": True,
+            "title": "Remove Category",
+        },
     )
     @log_tool_usage
     async def ha_config_remove_category(
@@ -333,6 +357,18 @@ class CategoryTools:
                     "message": f"Successfully deleted category: {category_id}",
                 }
             else:
+                error_str = str(result.get("error", "")).lower()
+                if "not found" in error_str or "doesn't exist" in error_str:
+                    raise_tool_error(
+                        create_error_response(
+                            ErrorCode.RESOURCE_NOT_FOUND,
+                            f"Category not found: {category_id}",
+                            context={"category_id": category_id, "scope": scope},
+                            suggestions=[
+                                f"Use ha_config_get_category('{scope}') without category_id to see all categories",
+                            ],
+                        )
+                    )
                 raise_tool_error(
                     create_error_response(
                         ErrorCode.SERVICE_CALL_FAILED,

{ha_mcp_dev-7.5.0.dev569 → ha_mcp_dev-7.5.0.dev571}/src/ha_mcp/tools/tools_config_automations.py

@@ -13,6 +13,7 @@ from fastmcp.tools import tool
 from pydantic import Field
 
 from ..client.rest_client import (
+    HomeAssistantAPIError,
     HomeAssistantAuthError,
     HomeAssistantConnectionError,
 )
@@ -53,6 +54,17 @@ from .util_helpers import (
 
 logger = logging.getLogger(__name__)
 
+# Distinctive prefix of the soft-failure warning emitted by
+# ``ha_config_set_automation`` when ``_poll_for_automation_entity``
+# exhausts ``_POLL_CADENCE`` without matching the new automation.
+# Exported so tests (e.g. ``test_poll_cadence_measurement.py``) can
+# detect a missed registration without hard-coding the literal —
+# rewording the warning becomes a compile-time coupling rather than
+# a silent test drift.
+NOT_VERIFIED_WARNING_PREFIX = (
+    "Automation was submitted to Home Assistant but the entity was not found"
+)
+
 
 def _normalize_automation_config(
     config: Any,
@@ -279,7 +291,9 @@ class AutomationConfigTools:
                 ):
                     return str(state["entity_id"])
         except Exception as e:
-            logger.debug(f"Failed to resolve entity_id for automation {identifier}: {e}")
+            logger.debug(
+                f"Failed to resolve entity_id for automation {identifier}: {e}"
+            )
         return None
 
     @tool(
@@ -334,13 +348,17 @@ class AutomationConfigTools:
                     "Use ha_search_entities(domain_filter='automation') to list automations",
                 ],
             )
-            normalized_config, config_hash = await self._get_automation_config_internal(identifier)
+            normalized_config, config_hash = await self._get_automation_config_internal(
+                identifier
+            )
 
             # Resolve entity_id and fetch category from entity registry
             # (injected after hash so transient registry failures don't affect the hash)
             entity_id = await self._resolve_automation_entity_id(identifier)
             if entity_id:
-                cat_id = await fetch_entity_category(self._client, entity_id, "automation")
+                cat_id = await fetch_entity_category(
+                    self._client, entity_id, "automation"
+                )
                 if cat_id:
                     normalized_config["category"] = cat_id
 
@@ -644,7 +662,10 @@ class AutomationConfigTools:
                                 "Provide the automation entity_id or unique_id",
                                 "Use ha_search_entities(domain_filter='automation') to find automations",
                             ],
-                            context={"action": "python_transform", "identifier": identifier},
+                            context={
+                                "action": "python_transform",
+                                "identifier": identifier,
+                            },
                         )
                     )
                 if config_hash is None:
@@ -656,7 +677,10 @@ class AutomationConfigTools:
                                 "Call ha_config_get_automation() first",
                                 "Use the config_hash from that response",
                             ],
-                            context={"action": "python_transform", "identifier": identifier},
+                            context={
+                                "action": "python_transform",
+                                "identifier": identifier,
+                            },
                         )
                     )
 
@@ -675,7 +699,10 @@ class AutomationConfigTools:
                             ErrorCode.VALIDATION_FAILED,
                             message,
                             suggestions=suggestions,
-                            context={"action": "python_transform", "identifier": identifier},
+                            context={
+                                "action": "python_transform",
+                                "identifier": identifier,
+                            },
                         )
                     )
 
@@ -698,11 +725,20 @@ class AutomationConfigTools:
 
                 # Re-apply category if present
                 entity_id = result.get("entity_id")
-                if not entity_id and identifier and identifier.startswith("automation."):
+                if (
+                    not entity_id
+                    and identifier
+                    and identifier.startswith("automation.")
+                ):
                     entity_id = identifier
                 if transform_category and entity_id:
                     await apply_entity_category(
-                        self._client, entity_id, transform_category, "automation", result, "automation"
+                        self._client,
+                        entity_id,
+                        transform_category,
+                        "automation",
+                        result,
+                        "automation",
                     )
 
                 response: dict[str, Any] = {
@@ -762,12 +798,14 @@ class AutomationConfigTools:
                 self._client, config_dict
             )
 
-            result = await self._client.upsert_automation_config(config_dict, identifier)
+            result = await self._client.upsert_automation_config(
+                config_dict, identifier
+            )
 
             # If the client could not verify the entity was registered, warn but don't hard-fail.
             if result.get("entity_not_verified"):
                 result.setdefault("warnings", []).append(
-                    "Automation was submitted to Home Assistant but the entity was not found "
+                    f"{NOT_VERIFIED_WARNING_PREFIX} "
                     "after polling. The automation may still have been created -- check Home "
                     "Assistant logs and try reloading automations. Common causes: "
                     "automations.yaml vs automation.yaml filename mismatch, invalid config "
@@ -784,7 +822,9 @@ class AutomationConfigTools:
             if wait_bool and entity_id:
                 action_word = "created" if identifier is None else "updated"
                 try:
-                    registered = await wait_for_entity_registered(self._client, entity_id)
+                    registered = await wait_for_entity_registered(
+                        self._client, entity_id
+                    )
                     if not registered:
                         result.setdefault("warnings", []).append(
                             f"Automation {action_word} but {entity_id} not yet queryable. "
@@ -798,7 +838,12 @@ class AutomationConfigTools:
             # Apply category to entity registry if provided
             if effective_category and entity_id:
                 await apply_entity_category(
-                    self._client, entity_id, effective_category, "automation", result, "automation"
+                    self._client,
+                    entity_id,
+                    effective_category,
+                    "automation",
+                    result,
+                    "automation",
                 )
 
             if bp_warnings:
@@ -820,6 +865,13 @@ class AutomationConfigTools:
         except ToolError:
             raise
         except Exception as e:
+            # 404 during update only — create (identifier=None) never hits this branch.
+            if (
+                identifier
+                and isinstance(e, HomeAssistantAPIError)
+                and e.status_code == 404
+            ):
+                await self._raise_automation_not_found(identifier)
             suggestions = [
                 "Check automation configuration format",
                 "Ensure required fields: alias, trigger, action",
@@ -838,6 +890,57 @@ class AutomationConfigTools:
                 suggestions=suggestions,
             )
 
+    async def _list_automation_entity_ids(self) -> list[str]:
+        """Best-effort list of automation entity_ids (up to 10) from the entity registry.
+
+        Used to populate ``available_automation_ids`` in RESOURCE_NOT_FOUND
+        error context. Returns an empty list on any failure — caller treats
+        absence as "no IDs to report" rather than failing the structured
+        error raise. The 10-entry cap lives here (not at the callers) so a
+        new call site can't accidentally bloat the error payload.
+        """
+        try:
+            result = await self._client.send_websocket_message(
+                {"type": "config/entity_registry/list"}
+            )
+        except Exception as e:
+            logger.debug("Failed to list automation entity_ids from registry: %s", e)
+            return []
+        entries = result.get("result", []) if isinstance(result, dict) else result
+        if not isinstance(entries, list):
+            return []
+        return [
+            entry["entity_id"]
+            for entry in entries
+            if isinstance(entry, dict)
+            and isinstance(entry.get("entity_id"), str)
+            and entry["entity_id"].startswith("automation.")
+        ][:10]
+
+    async def _raise_automation_not_found(self, identifier: str) -> None:
+        """Raise a structured RESOURCE_NOT_FOUND ToolError for a missing automation.
+
+        Single source of truth for the 404→RESOURCE_NOT_FOUND mapping used
+        by both the GET path (``_get_automation_config_internal``) and the
+        mutation paths (``ha_config_set_automation`` update branch,
+        ``ha_config_remove_automation``). Populates
+        ``available_automation_ids`` (up to 10) from the entity registry.
+        """
+        available_ids = await self._list_automation_entity_ids()
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.RESOURCE_NOT_FOUND,
+                f"Automation not found: {identifier}",
+                context={
+                    "automation_id": identifier,
+                    "available_automation_ids": available_ids,
+                },
+                suggestions=[
+                    "Use ha_search_entities(domain_filter='automation') to find existing automations"
+                ],
+            )
+        )
+
     async def _get_automation_config_internal(
         self, identifier: str
     ) -> tuple[dict[str, Any], str]:
@@ -845,8 +948,18 @@ class AutomationConfigTools:
 
         Returns (normalized_config, config_hash) tuple.
         Used internally by _fetch_and_verify_hash and ha_config_get_automation.
+
+        Raises a structured ``RESOURCE_NOT_FOUND`` ToolError via
+        ``_raise_automation_not_found`` when the REST client returns 404.
+        Other ``HomeAssistantAPIError`` instances propagate unchanged to
+        caller exception handlers (``exception_to_structured_error`` route).
         """
-        config_result = await self._client.get_automation_config(identifier)
+        try:
+            config_result = await self._client.get_automation_config(identifier)
+        except HomeAssistantAPIError as e:
+            if e.status_code == 404:
+                await self._raise_automation_not_found(identifier)
+            raise
         normalized_config = _normalize_config_for_roundtrip(config_result)
         config_hash_value = compute_config_hash(normalized_config)
         return normalized_config, config_hash_value
@@ -859,7 +972,9 @@ class AutomationConfigTools:
         Returns the current normalized config dict.
         Raises ToolError if the hash does not match (conflict).
         """
-        current_config, current_hash = await self._get_automation_config_internal(identifier)
+        current_config, current_hash = await self._get_automation_config_internal(
+            identifier
+        )
         if current_hash != config_hash:
             raise_tool_error(
                 create_error_response(
@@ -880,22 +995,26 @@ class AutomationConfigTools:
         try:
             parsed_config = parse_json_param(config, "config")
         except ValueError as e:
-            raise_tool_error(create_error_response(
-                code=ErrorCode.VALIDATION_INVALID_JSON,
-                message=f"Invalid config parameter: {e}",
-                suggestions=[
-                    "Pass 'config' as a dict, not a JSON string, to avoid escaping issues.",
-                    "Check for JSON syntax errors: unquoted keys, trailing commas, or invalid escape sequences.",
-                ],
-                context={"parameter": "config"},
-            ))
+            raise_tool_error(
+                create_error_response(
+                    code=ErrorCode.VALIDATION_INVALID_JSON,
+                    message=f"Invalid config parameter: {e}",
+                    suggestions=[
+                        "Pass 'config' as a dict, not a JSON string, to avoid escaping issues.",
+                        "Check for JSON syntax errors: unquoted keys, trailing commas, or invalid escape sequences.",
+                    ],
+                    context={"parameter": "config"},
+                )
+            )
 
         if parsed_config is None or not isinstance(parsed_config, dict):
-            raise_tool_error(create_validation_error(
-                "Config parameter must be a JSON object",
-                parameter="config",
-                details=f"Received type: {type(parsed_config).__name__}",
-            ))
+            raise_tool_error(
+                create_validation_error(
+                    "Config parameter must be a JSON object",
+                    parameter="config",
+                    details=f"Received type: {type(parsed_config).__name__}",
+                )
+            )
 
         return cast(dict[str, Any], parsed_config)
 
@@ -924,24 +1043,28 @@ class AutomationConfigTools:
                 context: dict[str, Any] = {"missing_fields": missing_fields}
                 if identifier:
                     context["identifier"] = identifier
-                raise_tool_error(create_error_response(
-                    code=ErrorCode.CONFIG_MISSING_REQUIRED_FIELDS,
-                    message=f"Missing required fields: {', '.join(missing_fields)}",
-                    details=(
-                        "Config contains 'sequence', which belongs to scripts. "
-                        "Automations use 'trigger' and 'action'; scripts use 'sequence'."
-                    ),
-                    suggestions=[
-                        "Did you mean ha_config_set_script? Scripts use 'sequence' directly.",
-                        "For an automation, replace 'sequence' with 'action' and add a 'trigger'.",
-                    ],
-                    context=context,
-                ))
-            raise_tool_error(create_config_error(
-                f"Missing required fields: {', '.join(missing_fields)}",
-                identifier=identifier,
-                missing_fields=missing_fields,
-            ))
+                raise_tool_error(
+                    create_error_response(
+                        code=ErrorCode.CONFIG_MISSING_REQUIRED_FIELDS,
+                        message=f"Missing required fields: {', '.join(missing_fields)}",
+                        details=(
+                            "Config contains 'sequence', which belongs to scripts. "
+                            "Automations use 'trigger' and 'action'; scripts use 'sequence'."
+                        ),
+                        suggestions=[
+                            "Did you mean ha_config_set_script? Scripts use 'sequence' directly.",
+                            "For an automation, replace 'sequence' with 'action' and add a 'trigger'.",
+                        ],
+                        context=context,
+                    )
+                )
+            raise_tool_error(
+                create_config_error(
+                    f"Missing required fields: {', '.join(missing_fields)}",
+                    identifier=identifier,
+                    missing_fields=missing_fields,
+                )
+            )
 
         # Issue #1169: reject configs that wrap ``scene.create`` in an
         # automation with no functional trigger. Models occasionally produce
@@ -966,31 +1089,33 @@ class AutomationConfigTools:
                 if _action_contains_scene_create(a)
             ]
             if scene_create_indices:
-                raise_tool_error(create_error_response(
-                    code=ErrorCode.VALIDATION_INVALID_PARAMETER,
-                    message=(
-                        "Empty trigger paired with a scene.create action — "
-                        "this automation can never fire. For a state snapshot "
-                        "of one or more entities, use ha_config_set_scene "
-                        "directly instead of wrapping scene.create in an "
-                        "automation."
-                    ),
-                    suggestions=[
-                        "ha_config_set_scene(scene_id='...', config={'name': "
-                        "'...', 'entities': {'<entity_id>': {...}}}) creates "
-                        "a scene without a trigger.",
-                        "If the snapshot really should be the result of an "
-                        "event, add the trigger that should fire it and keep "
-                        "the automation.",
-                        "For a state-derived value that recomputes when its "
-                        "inputs change, use "
-                        "ha_config_set_helper(helper_type='template') instead.",
-                    ],
-                    context={
-                        "scene_create_action_indices": scene_create_indices,
-                        "identifier": identifier,
-                    },
-                ))
+                raise_tool_error(
+                    create_error_response(
+                        code=ErrorCode.VALIDATION_INVALID_PARAMETER,
+                        message=(
+                            "Empty trigger paired with a scene.create action — "
+                            "this automation can never fire. For a state snapshot "
+                            "of one or more entities, use ha_config_set_scene "
+                            "directly instead of wrapping scene.create in an "
+                            "automation."
+                        ),
+                        suggestions=[
+                            "ha_config_set_scene(scene_id='...', config={'name': "
+                            "'...', 'entities': {'<entity_id>': {...}}}) creates "
+                            "a scene without a trigger.",
+                            "If the snapshot really should be the result of an "
+                            "event, add the trigger that should fire it and keep "
+                            "the automation.",
+                            "For a state-derived value that recomputes when its "
+                            "inputs change, use "
+                            "ha_config_set_helper(helper_type='template') instead.",
+                        ],
+                        context={
+                            "scene_create_action_indices": scene_create_indices,
+                            "identifier": identifier,
+                        },
+                    )
+                )
 
         # HA accepts conditions with 'platform' (trigger syntax) but then crashes
         # with an unhelpful 500 rather than a 400 validation error.
@@ -998,30 +1123,34 @@ class AutomationConfigTools:
             if not isinstance(cond, dict):
                 continue
             if "platform" in cond and "condition" not in cond:
-                raise_tool_error(create_error_response(
-                    code=ErrorCode.VALIDATION_INVALID_PARAMETER,
-                    message=(
-                        f"Condition at index {idx} uses 'platform' (trigger syntax). "
-                        "Conditions use 'condition', not 'platform'."
-                    ),
-                    suggestions=[
-                        f"Replace 'platform' with 'condition': "
-                        f"{{'condition': '{cond['platform']}', ...}}",
-                        "Triggers use 'platform'; conditions use 'condition'.",
-                    ],
-                    context={"condition_index": idx, "found_key": "platform"},
-                ))
+                raise_tool_error(
+                    create_error_response(
+                        code=ErrorCode.VALIDATION_INVALID_PARAMETER,
+                        message=(
+                            f"Condition at index {idx} uses 'platform' (trigger syntax). "
+                            "Conditions use 'condition', not 'platform'."
+                        ),
+                        suggestions=[
+                            f"Replace 'platform' with 'condition': "
+                            f"{{'condition': '{cond['platform']}', ...}}",
+                            "Triggers use 'platform'; conditions use 'condition'.",
+                        ],
+                        context={"condition_index": idx, "found_key": "platform"},
+                    )
+                )
 
         # Prevent duplicate creation when config contains an existing automation id
         if identifier is None and "id" in config_dict:
             existing_id = config_dict["id"]
-            raise_tool_error(create_validation_error(
-                f"Config contains 'id' field ('{existing_id}') but no identifier was provided. "
-                "This would create a duplicate automation instead of updating the existing one.",
-                parameter="identifier",
-                details=f"To update, pass identifier='{existing_id}' (or the automation's entity_id). "
-                "To create a genuinely new automation, remove the 'id' field from the config.",
-            ))
+            raise_tool_error(
+                create_validation_error(
+                    f"Config contains 'id' field ('{existing_id}') but no identifier was provided. "
+                    "This would create a duplicate automation instead of updating the existing one.",
+                    parameter="identifier",
+                    details=f"To update, pass identifier='{existing_id}' (or the automation's entity_id). "
+                    "To create a genuinely new automation, remove the 'id' field from the config.",
+                )
+            )
 
     @tool(
         name="ha_config_remove_automation",
@@ -1086,7 +1215,9 @@ class AutomationConfigTools:
             wait_bool = coerce_bool_param(wait, "wait", default=True)
             if wait_bool and entity_id_for_wait:
                 try:
-                    removed = await wait_for_entity_removed(self._client, entity_id_for_wait)
+                    removed = await wait_for_entity_removed(
+                        self._client, entity_id_for_wait
+                    )
                     if not removed:
                         result.setdefault("warnings", []).append(
                             f"Deletion confirmed by API but {entity_id_for_wait} may still appear briefly."
@@ -1107,6 +1238,8 @@ class AutomationConfigTools:
         except ToolError:
             raise
         except Exception as e:
+            if isinstance(e, HomeAssistantAPIError) and e.status_code == 404:
+                await self._raise_automation_not_found(identifier)
             exception_to_structured_error(
                 e,
                 context={"identifier": identifier, "action": "delete"},

{ha_mcp_dev-7.5.0.dev569 → ha_mcp_dev-7.5.0.dev571}/src/ha_mcp/tools/tools_config_dashboards.py

@@ -1530,8 +1530,13 @@ def register_config_dashboard_tools(mcp: Any, client: Any, **kwargs: Any) -> Non
                 ],
                 context={"action": "delete"},
             )
-            resolved, _ = await _resolve_dashboard(client, url_path)
+            resolved, dashboards = await _resolve_dashboard(client, url_path)
             if resolved is None:
+                available_ids = [
+                    d.get("url_path")
+                    for d in (dashboards or [])[:10]
+                    if d.get("url_path")
+                ]
                 raise_tool_error(
                     create_error_response(
                         ErrorCode.RESOURCE_NOT_FOUND,
@@ -1541,7 +1546,11 @@ def register_config_dashboard_tools(mcp: Any, client: Any, **kwargs: Any) -> Non
                             "Use ha_config_get_dashboard(list_only=True) to see available dashboards",
                             "YAML-mode and default dashboards are not deletable via this tool",
                         ],
-                        context={"action": "delete", "url_path": url_path},
+                        context={
+                            "action": "delete",
+                            "url_path": url_path,
+                            "available_dashboard_ids": available_ids,
+                        },
                     )
                 )
             resolved_id = resolved["id"]