fix: clarify ha_search_entities vs ha_deep_search descriptions to prevent tool misuse (#761)

LLM agents were defaulting to ha_deep_search for simple entity lookups by name
because its description sounded more comprehensive. Updated both docstrings to
make the distinction explicit:

- ha_search_entities: now leads with "PRIMARY tool for finding entities by name"
  and redirects config searches to ha_deep_search
- ha_deep_search: now opens with "not for finding entity IDs" and redirects
  entity lookups to ha_search_entities

Verified with UAT runs: agent calls ha_search_entities for "find kitchen light"
and ha_deep_search for "which automations reference light.bed_light".

Also adds UAT story s13 covering the "find automations by referenced entity"
workflow, which was missing from the catalog.

Author: sergeykad

src/ha_mcp/tools/tools_search.py

@@ -156,7 +156,9 @@ async def ha_search_entities(
         ] = 0,
         group_by_domain: bool | str = False,
     ) -> dict[str, Any]:
-        """Comprehensive entity search with fuzzy matching, domain/area filtering, and optional grouping.
+        """PRIMARY tool for finding entities (lights, sensors, switches, etc.) by name, area, or domain. Use this first when looking up any entity ID.
+
+        For searching *inside* automation/script/helper configurations, use ha_deep_search instead.
 
         **Listing Entities by Domain:**
         Use domain_filter with an empty query to list all entities of a specific type:
@@ -614,12 +616,15 @@ async def ha_deep_search(
             ),
         ] = False,
     ) -> dict[str, Any]:
-        """Deep search across automation, script, and helper definitions.
+        """Search inside automation, script, and helper *configurations* — not for finding entity IDs.
+
+        Use this when you need to find automations/scripts by what they *do* (e.g., which automations
+        call a specific service, reference a particular entity, or contain a certain action).
+        For finding entity IDs by name, use ha_search_entities instead.
 
-        Searches not only entity names but also within configuration definitions including
-        triggers, actions, sequences, and other config fields. Perfect for finding automations
-        that use specific services, helpers referenced in scripts, or tracking down where
-        particular entities are being used.
+        Searches within configuration definitions including triggers, actions, sequences, and other
+        config fields. Perfect for finding automations that use specific services, helpers referenced
+        in scripts, or tracking down where particular entities are being used.
 
         Args:
             query: Search query (can be partial, with typos)

tests/uat/stories/catalog/s13_find_automations_by_entity.yaml

@@ -0,0 +1,57 @@
+id: s13
+title: "Find automations and scripts that reference a specific entity"
+category: automation
+weight: 3
+description: >
+  User wants to know which automations or scripts use a specific entity.
+  This requires searching inside configuration definitions (triggers, actions),
+  not just entity names. A common troubleshooting workflow when a user wants
+  to understand what controls a device or before renaming/removing an entity.
+
+tags:
+  - search
+  - automation
+  - script
+  - deep_search
+
+setup:
+  - tool: ha_config_set_automation
+    args:
+      config:
+        alias: "Bed Light Evening"
+        description: "Turn on bed light in the evening"
+        mode: single
+        trigger:
+          - platform: time
+            at: "20:00:00"
+        action:
+          - action: light.turn_on
+            target:
+              entity_id: light.bed_light
+            data:
+              brightness_pct: 80
+
+prompt: >
+  Which automations or scripts reference light.bed_light? I want to know all the
+  places in my configuration that use this entity.
+
+teardown: []
+
+verify:
+  questions:
+    - "Which automation references light.bed_light?"
+    - "What does the automation do with light.bed_light?"
+    - "Is this an automation, script, or both?"
+  ha_checks:
+    - type: automation_exists
+      alias: "Bed Light Evening"
+    - type: response_contains
+      value: "Bed Light Evening"
+
+expected:
+  tools_should_use:
+    - ha_deep_search
+  description: >
+    Agent should use ha_deep_search to search inside automation/script
+    configurations for references to light.bed_light. A good agent will
+    report the automation name, its purpose, and how it uses the entity.