ha-mcp-dev 7.4.1.dev458__tar.gz → 7.4.1.dev460__tar.gz

{ha_mcp_dev-7.4.1.dev458/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.4.1.dev460}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.4.1.dev458
+Version: 7.4.1.dev460
 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.4.1.dev458 → ha_mcp_dev-7.4.1.dev460}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.4.1.dev458"
+version = "7.4.1.dev460"
 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.4.1.dev458 → ha_mcp_dev-7.4.1.dev460}/src/ha_mcp/server.py

@@ -58,6 +58,48 @@ class HaResourcesAsTools(ResourcesAsTools):
         "list_resources": LIST_TOOL_NAME,
         "read_resource": READ_TOOL_NAME,
     }
+    # Shared action-phrased keyword block for retrieval. Some MCP clients
+    # (Claude Code, others) rank candidate tools by token-overlap between
+    # the user's natural-language query and each tool's `description`
+    # field; FastMCP's terse defaults ("List MCP resources") never overlap
+    # with task-phrased queries like "create automation" or "writing
+    # trigger". This block lists the workflow positions where consulting
+    # the bundled skill reference files matters, so retrieval surfaces
+    # this tool when an agent is about to write config.
+    _USE_BEFORE_KEYWORDS = (
+        "Use BEFORE: creating or editing automations, scripts, scenes, "
+        "helpers, or dashboards; writing triggers, conditions, actions, "
+        "wait_template, or service calls; renaming entities or migrating "
+        "device_id to entity_id; calling ha_config_set_automation, "
+        "ha_config_set_script, ha_config_set_helper, ha_config_set_dashboard, "
+        "or ha_set_entity."
+    )
+    _DESCRIPTIONS: ClassVar[dict[str, str]] = {
+        LIST_TOOL_NAME: (
+            "List all available MCP resources, including bundled skill "
+            "reference files. " + _USE_BEFORE_KEYWORDS + " Pair with "
+            "ha_read_resource to load a specific guide."
+        ),
+        READ_TOOL_NAME: (
+            "Get the contents of an MCP resource by URI. Use this to load "
+            "skill reference files (e.g., "
+            "skill://home-assistant-best-practices/references/"
+            "automation-patterns.md) for guidance on native conditions and "
+            "triggers, helper selection, automation modes, template "
+            "guidelines, device control, and safe refactoring. "
+            + _USE_BEFORE_KEYWORDS
+            + " Use ha_list_resources to discover available URIs."
+        ),
+    }
+
+    @classmethod
+    def _rewrite(cls, tool: Tool, new_name: str) -> Tool:
+        """Return a copy of ``tool`` renamed and re-described for ha-mcp."""
+        update: dict[str, Any] = {"name": new_name}
+        description = cls._DESCRIPTIONS.get(new_name)
+        if description is not None:
+            update["description"] = description
+        return tool.model_copy(update=update)
 
     async def list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]:
         # Scan the entire result rather than slicing the tail so a future
@@ -72,7 +114,7 @@ class HaResourcesAsTools(ResourcesAsTools):
             if new_name is None:
                 renamed.append(tool)
                 continue
-            renamed.append(tool.model_copy(update={"name": new_name}))
+            renamed.append(self._rewrite(tool, new_name))
             matches += 1
         if matches != len(self._RENAMES):
             logger.warning(
@@ -93,13 +135,9 @@ class HaResourcesAsTools(ResourcesAsTools):
         version: VersionSpec | None = None,
     ) -> Tool | None:
         if name == self.LIST_TOOL_NAME:
-            return self._make_list_resources_tool().model_copy(
-                update={"name": self.LIST_TOOL_NAME}
-            )
+            return self._rewrite(self._make_list_resources_tool(), self.LIST_TOOL_NAME)
         if name == self.READ_TOOL_NAME:
-            return self._make_read_resource_tool().model_copy(
-                update={"name": self.READ_TOOL_NAME}
-            )
+            return self._rewrite(self._make_read_resource_tool(), self.READ_TOOL_NAME)
         return await call_next(name, version=version)
 
 # Server icon configuration using GitHub-hosted images
@@ -772,12 +810,27 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
             tool_name = f"ha_get_skill_{skill_name.replace('-', '_')}"
             uri = f"skill://{skill_name}/SKILL.md"
 
+            # Action-phrased keyword block for retrieval. Some MCP clients
+            # rank candidate tools by token-overlap between the user's
+            # query and each tool's `description`; the upstream SKILL.md
+            # description is symptom-framed ("Agent uses Jinja2 templates
+            # where..."), which doesn't overlap with task-phrased queries
+            # like "create automation" / "set automation config" / "writing
+            # trigger". This block re-anchors the description in those
+            # task verbs so it surfaces when an agent is about to write
+            # config. Same shared keyword block as
+            # HaResourcesAsTools._USE_BEFORE_KEYWORDS above.
             tool_description = (
+                f"Get available reference files for the {skill_name} skill. "
                 f"CALL THIS FIRST before performing matching actions. "
                 f"{description}\n\n"
-                f"Returns available reference files. Read each file via "
-                f"resources/read (or ha_read_resource as a fallback) using "
-                f"the file URI to load specific guides as needed."
+                f"{HaResourcesAsTools._USE_BEFORE_KEYWORDS} The reference "
+                f"files below cover automation patterns, helper selection, "
+                f"template guidelines, device control, dashboards, and safe "
+                f"refactoring.\n\n"
+                f"Read each reference file via resources/read (or "
+                f"ha_read_resource as a fallback) using the file URI to load "
+                f"specific guides as needed."
             )
 
             ref_files = self._collect_skill_ref_files(skill_dir, skill_name)

{ha_mcp_dev-7.4.1.dev458 → ha_mcp_dev-7.4.1.dev460}/src/ha_mcp/tools/best_practice_checker.py

@@ -8,6 +8,30 @@ file via the bundled SkillsDirectoryProvider. The ``skill_prefix`` kwarg
 lets callers pass any URL prefix (e.g., a GitHub mirror) when skill://
 isn't reachable, or ``None`` to omit references entirely.
 
+Each warning carries the native alternative inline (a concrete example or
+short explanation) before the URI suffix, so clients that don't auto-fetch
+resource URIs still receive actionable guidance.
+
+The checker covers two layers:
+
+1. *Specific* detectors for known anti-pattern shapes — each emits a tailored
+   message that names the native alternative concretely.
+2. A *generic* fallback that fires when ``{{ ... }}`` or ``{% ... %}`` shows
+   up in a logic position (condition / trigger / wait_template / target field)
+   without matching a specific pattern. This catches new template misuse
+   without waiting for a regex to be added.
+
+Allowlist by design — these positions are NOT walked by any recursion path,
+so templates in them never trigger a warning even when present. They are the
+documented legitimate dynamic-data positions per
+``template-guidelines.md#when-templates-are-appropriate``:
+
+* Action ``data.*`` fields (notification messages, brightness, volume, etc.)
+* Notification ``message`` / ``title`` bodies
+* Action ``event_data.*`` (HA evaluates event_data as a template at runtime)
+* Top-level ``variables.*``
+* Action ``service_data.*`` (legacy alias for ``data``)
+
 Anti-patterns sourced from:
   https://github.com/homeassistant-ai/skills
   skill://home-assistant-best-practices
@@ -39,6 +63,14 @@ _RE_WEEKDAY = re.compile(
     r"\bnow\(\)\s*\.\s*(?:weekday|isoweekday)\s*\("
     r"|\bnow\(\)\s*\.\s*strftime\s*\(\s*['\"]%[Aaw]['\"]"
 )
+# Date-component checks: now().date(), now().year/month/day.
+# `\b` after year/month/day prevents matching `day_of_week`/`day_of_year`/etc.;
+# `(?!\s*\()` rejects method-call shapes like `now().day()` that don't exist
+# in HA's Jinja env.
+_RE_NOW_DATE = re.compile(
+    r"\bnow\(\)\s*\.\s*date\s*\("
+    r"|\bnow\(\)\s*\.\s*(?:year|month|day)\b(?!\s*\()"
+)
 # sun.sun entity references
 _RE_SUN = re.compile(r"(?:is_state|state_attr|states)\s*\(\s*['\"]sun\.sun['\"]")
 # states('x') in [...] or states('x') in (...)
@@ -47,6 +79,18 @@ _RE_STATE_IN = re.compile(r"states\s*\([^)]+\)\s+in\s+[\[(]")
 _RE_DIRECT_STATE = re.compile(r"\bstates\.\w+\.\w+\.state\b")
 # Motion entity pattern
 _RE_MOTION = re.compile(r"binary_sensor\.\w*motion", re.IGNORECASE)
+# Any Jinja template marker — catch-all and target-field scan.
+_RE_ANY_TEMPLATE = re.compile(r"\{\{|\{%")
+# `this.X` self-reference (e.g. `{{ this.entity_id }}`)
+_RE_THIS_REFERENCE = re.compile(r"\bthis\s*\.\s*\w+")
+
+# Target sub-fields scanned for templates. These are the only keys allowed
+# under ``target:`` in HA's modern action schema.
+_TARGET_FIELDS = ("entity_id", "device_id", "area_id", "floor_id", "label_id")
+
+# Keys that hold the service/action name in an action step. HA accepts both
+# ``service:`` (legacy) and ``action:`` (modern, 2024+) for the same field.
+_SERVICE_KEYS = ("service", "action")
 
 
 # ---------------------------------------------------------------------------
@@ -76,7 +120,7 @@ def check_automation_config(
     # Condition templates
     _check_condition_templates(config.get("condition", []), warnings, skill_prefix)
 
-    # Action tree (wait_template + nested conditions)
+    # Action tree (wait_template + nested conditions + target templates)
     _check_action_tree(config.get("action", []), warnings, skill_prefix)
 
     # Trigger templates + device_id
@@ -132,12 +176,20 @@ def _check_condition_templates(
     for cond in _as_list(conditions):
         if isinstance(cond, str) and "{{" in cond:
             # Shorthand template condition
-            _check_template_string(cond, warnings, skill_prefix)
+            _check_template_string(cond, warnings, skill_prefix, "condition")
         elif isinstance(cond, dict):
             if cond.get("condition") == "template":
                 vt = cond.get("value_template", "")
                 if isinstance(vt, str):
-                    _check_template_string(vt, warnings, skill_prefix)
+                    _check_template_string(vt, warnings, skill_prefix, "condition")
+            else:
+                # Non-template conditions (numeric_state, state, etc.) can
+                # still carry a `value_template` field (numeric_state uses one
+                # to compute the numeric value being compared). Scan it too,
+                # otherwise these templates slip past every detector.
+                vt = cond.get("value_template", "")
+                if isinstance(vt, str) and "{{" in vt:
+                    _check_template_string(vt, warnings, skill_prefix, "condition")
             # Recurse into compound conditions (and/or/not)
             nested = cond.get("conditions")
             if nested:
@@ -145,54 +197,99 @@ def _check_condition_templates(
 
 
 def _check_template_string(
-    template: str, warnings: list[str], skill_prefix: str | None
+    template: str,
+    warnings: list[str],
+    skill_prefix: str | None,
+    position: str,
 ) -> None:
-    """Check a single template string for known anti-patterns."""
+    """Check a single template string for known anti-patterns.
+
+    ``position`` is currently only "condition" (the function is called from
+    ``_check_condition_templates``). It's parameterized so both the warning
+    prefix AND the suggestion text adapt if a future caller passes "trigger".
+    The native shapes named here (numeric_state, state, time, sun) work as
+    both conditions and triggers in HA — only the noun changes.
+    """
+    initial_count = len(warnings)
+    label = position.capitalize()
+
     if _RE_NUMERIC_CMP.search(template):
         warnings.append(
-            "Condition uses template with float/int comparison — use native "
-            "`numeric_state` condition instead."
+            f"{label} uses template with float/int comparison — use native "
+            f"`numeric_state` {position} instead "
+            f"(e.g., `{position}: numeric_state, entity_id: sensor.temp, above: 25`). "
+            "Native conditions are validated at config load and don't bypass HA's schema."
             + _ref(skill_prefix, "automation-patterns.md#native-conditions")
         )
     if _RE_SUN.search(template):
         warnings.append(
-            "Condition uses template referencing `sun.sun` — use native "
-            "`sun` condition instead."
+            f"{label} uses template referencing `sun.sun` — use native "
+            f"`sun` {position} instead "
+            f"(e.g., `{position}: sun, after: sunset` or `before: sunrise`)."
             + _ref(skill_prefix, "automation-patterns.md#native-conditions")
         )
     elif _RE_IS_STATE.search(template):
         # Only flag if not already flagged as sun pattern
         warnings.append(
-            "Condition uses template with `is_state()` — use native "
-            "`state` condition instead."
+            f"{label} uses template with `is_state()` — use native "
+            f"`state` {position} instead "
+            f"(e.g., `{position}: state, entity_id: light.bedroom, state: 'on'`)."
             + _ref(skill_prefix, "automation-patterns.md#native-conditions")
         )
     if _RE_NOW_TIME.search(template):
         warnings.append(
-            "Condition uses template with `now().hour/minute` — use native "
-            "`time` condition instead."
+            f"{label} uses template with `now().hour/minute` — use native "
+            f"`time` {position} instead "
+            f"(e.g., `{position}: time, after: '09:00:00', before: '17:00:00'`)."
             + _ref(skill_prefix, "automation-patterns.md#native-conditions")
         )
     if _RE_WEEKDAY.search(template):
         warnings.append(
-            "Condition uses template for day-of-week check — use native "
-            "`time` condition with `weekday:` list instead."
+            f"{label} uses template for day-of-week check — use native "
+            f"`time` {position} with `weekday:` list instead "
+            f"(e.g., `{position}: time, weekday: ['mon', 'tue', 'wed']`)."
+            + _ref(skill_prefix, "automation-patterns.md#native-conditions")
+        )
+    if _RE_NOW_DATE.search(template):
+        warnings.append(
+            f"{label} uses date-based check (`now().date()` / `now().year/month/day`) — "
+            "for one-shot date-specific firing, use a `time` trigger and self-disable via "
+            "`automation.turn_off` with a hardcoded `entity_id` (the next `00:01` fire IS the "
+            "target date on creation day). For recurring date logic, expose a `sensor.date` via "
+            f"the `time_date` integration and use a `state` {position}."
             + _ref(skill_prefix, "automation-patterns.md#native-conditions")
         )
     if _RE_STATE_IN.search(template):
         warnings.append(
-            "Condition uses template with `states(...) in [...]` — use native "
-            "`state` condition with `state:` list instead."
+            f"{label} uses template with `states(...) in [...]` — use native "
+            f"`state` {position} with `state:` list instead "
+            f"(e.g., `{position}: state, entity_id: climate.living_room, state: ['heat', 'cool']`)."
             + _ref(skill_prefix, "automation-patterns.md#native-conditions")
         )
     if _RE_DIRECT_STATE.search(template):
         warnings.append(
-            "Template uses `states.domain.entity.state` direct access which "
-            "errors if entity doesn't exist — use `states('entity_id')` "
-            "function instead."
+            f"{label} template uses `states.domain.entity.state` direct access which "
+            "errors if entity doesn't exist — use the `states('entity_id')` "
+            "function instead (returns 'unknown' if missing rather than raising)."
             + _ref(skill_prefix, "template-guidelines.md#common-patterns")
         )
 
+    # Generic fallback: any Jinja in this logic position that didn't match
+    # a specific detector. Catches new anti-patterns (issue #1011) and
+    # reframes #695 from "enumerate bad shapes" to "surface every template
+    # in a logic position". Specific detectors above keep their tailored
+    # messages.
+    if (
+        len(warnings) == initial_count
+        and _RE_ANY_TEMPLATE.search(template)
+    ):
+        warnings.append(
+            f"Template detected in {position} — if this maps to a native option "
+            "(`numeric_state`, `state`, `time`, `sun`, `zone`, `device`), use that "
+            "instead. Templates fail silently at runtime and bypass schema validation."
+            + _ref(skill_prefix, "template-guidelines.md#when-to-avoid-templates")
+        )
+
 
 # ---------------------------------------------------------------------------
 # Action tree checks
@@ -223,11 +320,22 @@ def _check_repeat_actions(
 def _check_action_tree(
     actions: Any, warnings: list[str], skill_prefix: str | None
 ) -> None:
-    """Walk action tree checking for wait_template and nested conditions."""
+    """Walk action tree checking for wait_template, nested conditions, and target templates."""
     for action in _as_list(actions):
         if not isinstance(action, dict):
             continue
 
+        # Inline condition steps (e.g. `- condition: template, value_template: ...`
+        # in a sequence). Detect by `condition: <str>` AND no service/action key
+        # present — a service-call step uses `condition:` as a legacy run-if
+        # filter, not as a step kind. Without this branch, templates in
+        # condition shorthand inside scripts/automation actions slipped past
+        # the checker; only conditions in `if:`, `choose.conditions`, and
+        # `repeat.while/until` were inspected.
+        cond_kind = action.get("condition")
+        if isinstance(cond_kind, str) and not any(k in action for k in _SERVICE_KEYS):
+            _check_condition_templates([action], warnings, skill_prefix)
+
         if "wait_template" in action:
             warnings.append(
                 "Action uses `wait_template` — consider `wait_for_trigger` "
@@ -237,6 +345,20 @@ def _check_action_tree(
                 + _ref(skill_prefix, "automation-patterns.md#wait-actions")
             )
 
+        # Templated service dispatch: `service:`/`action:` containing `{{ }}`
+        # or any `service_template:` field. The native alternative is a
+        # `choose` (or `if/then/else`) action that picks between hardcoded
+        # service names based on state.
+        _check_service_template(action, warnings, skill_prefix)
+
+        # Templates in target sub-fields. Action `data`, `event_data`,
+        # `service_data`, notification message/title, and `variables` are
+        # legitimate dynamic-data positions per template-guidelines.md and
+        # are not walked by any recursion path here.
+        target = action.get("target")
+        if isinstance(target, dict):
+            _check_target_dict(target, warnings, skill_prefix)
+
         # Nested conditions in choose/if/repeat
         if "choose" in action:
             _check_choose_actions(action["choose"], warnings, skill_prefix)
@@ -252,6 +374,82 @@ def _check_action_tree(
         if "repeat" in action and isinstance(action["repeat"], dict):
             _check_repeat_actions(action["repeat"], warnings, skill_prefix)
 
+        # `parallel:` runs sub-actions concurrently — same shape as `sequence`,
+        # different semantics. Recurse so templates inside parallel branches
+        # are inspected the same as templates inside choose/repeat sequences.
+        if "parallel" in action and isinstance(action["parallel"], list):
+            _check_action_tree(action["parallel"], warnings, skill_prefix)
+
+
+def _check_service_template(
+    action: dict[str, Any], warnings: list[str], skill_prefix: str | None
+) -> None:
+    """Flag template-based service dispatch in an action.
+
+    Three shapes:
+    - ``service_template:`` — legacy explicit way to template a service name.
+      Flag any value.
+    - ``service:`` containing ``{{`` — modern syntax with a template.
+    - ``action:`` containing ``{{`` — HA's 2024+ rename of ``service:``.
+
+    The native alternative is a ``choose`` (or ``if/then/else``) action that
+    dispatches to different hardcoded service names based on state.
+    """
+    if "service_template" in action:
+        warnings.append(
+            "Action uses `service_template` (legacy templated service dispatch) — "
+            "use a `choose` (or `if/then/else`) action that dispatches to different "
+            "hardcoded `action:` names based on state. Native dispatch validates "
+            "each service name at config load."
+            + _ref(skill_prefix, "automation-patterns.md#ifthen-vs-choose")
+        )
+        return
+    for key in _SERVICE_KEYS:
+        value = action.get(key)
+        if isinstance(value, str) and _RE_ANY_TEMPLATE.search(value):
+            warnings.append(
+                f"Action `{key}:` field contains a template — use a `choose` "
+                "(or `if/then/else`) action with hardcoded service names instead. "
+                "Templates here bypass HA's service-name validation and fail "
+                "silently if the resolved string is invalid."
+                + _ref(skill_prefix, "automation-patterns.md#ifthen-vs-choose")
+            )
+            return
+
+
+def _check_target_dict(
+    target: dict[str, Any], warnings: list[str], skill_prefix: str | None
+) -> None:
+    """Flag any Jinja in target.entity_id/device_id/area_id/floor_id/label_id.
+
+    Templates in target fields bypass HA's entity-existence validation at
+    config load and fail silently if they resolve to a non-existent entity.
+    `{{ this.entity_id }}`-style self-references are especially pointless —
+    the calling automation/script already knows its own entity_id, so
+    hardcoding the literal is both simpler and safer.
+    """
+    for field in _TARGET_FIELDS:
+        value = target.get(field)
+        for item in _as_list(value):
+            if not isinstance(item, str) or not _RE_ANY_TEMPLATE.search(item):
+                continue
+            if _RE_THIS_REFERENCE.search(item):
+                warnings.append(
+                    f"Action `target.{field}` uses a `this.*` self-reference template — "
+                    f"hardcode the literal value instead. The self-reference is always "
+                    f"resolvable at write time, so the template adds runtime cost without "
+                    f"any flexibility."
+                    + _ref(skill_prefix, "template-guidelines.md#when-to-avoid-templates")
+                )
+            else:
+                warnings.append(
+                    f"Action `target.{field}` uses a template — prefer a hardcoded literal, "
+                    f"or use a `choose` action with native conditions to dispatch to different "
+                    f"hardcoded targets. Templates in target fields fail silently if they "
+                    f"resolve to a non-existent entity."
+                    + _ref(skill_prefix, "template-guidelines.md#when-to-avoid-templates")
+                )
+
 
 # ---------------------------------------------------------------------------
 # Trigger checks
@@ -277,14 +475,16 @@ def _check_triggers(
                 + _ref(skill_prefix, "device-control.md#entity-id-vs-device-id")
             )
 
-        # Template trigger with detectable native alternative
+        # Template trigger — specific shapes first, generic fallback after.
         if platform == "template":
             vt = trigger.get("value_template", "")
             if isinstance(vt, str):
+                initial = len(warnings)
                 if _RE_NUMERIC_CMP.search(vt):
                     warnings.append(
                         "Trigger uses template with float/int comparison — "
-                        "use native `numeric_state` trigger instead."
+                        "use native `numeric_state` trigger instead "
+                        "(e.g., `platform: numeric_state, entity_id: sensor.temp, above: 30`)."
                         + _ref(
                             skill_prefix,
                             "automation-patterns.md#trigger-types",
@@ -293,7 +493,20 @@ def _check_triggers(
                 if _RE_IS_STATE.search(vt):
                     warnings.append(
                         "Trigger uses template with `is_state()` — use "
-                        "native `state` trigger instead."
+                        "native `state` trigger instead "
+                        "(e.g., `platform: state, entity_id: light.x, to: 'on'`)."
+                        + _ref(
+                            skill_prefix,
+                            "automation-patterns.md#trigger-types",
+                        )
+                    )
+                # Generic fallback for unmatched template triggers.
+                if len(warnings) == initial and _RE_ANY_TEMPLATE.search(vt):
+                    warnings.append(
+                        "Trigger uses `template` platform — if this maps to a native option "
+                        "(`state`, `numeric_state`, `time`, `time_pattern`, `sun`, `zone`, "
+                        "`event`), use that instead. Native triggers are event-driven; "
+                        "template triggers re-evaluate on every state change."
                         + _ref(
                             skill_prefix,
                             "automation-patterns.md#trigger-types",

{ha_mcp_dev-7.4.1.dev458 → ha_mcp_dev-7.4.1.dev460}/src/ha_mcp/tools/tools_config_automations.py

@@ -371,6 +371,25 @@ class AutomationConfigTools:
         """
         Create or update a Home Assistant automation.
 
+        PREFER NATIVE SOLUTIONS OVER TEMPLATES (read this before writing any `{{ ... }}`):
+        Native triggers/conditions/actions are validated at config load, fail loudly, and
+        do not bypass HA's schema. Templates fail silently at runtime and obscure intent.
+        - `condition: numeric_state` instead of `{{ states('x') | float > N }}`
+        - `condition: state` (with `state:` list) instead of `{{ is_state(...) }}` /
+          `{{ states(x) in [...] }}`
+        - `condition: time` instead of `{{ now().hour ... }}` or `{{ now().weekday() ... }}`
+        - `condition: sun` instead of `{{ is_state('sun.sun', ...) }}`
+        - `wait_for_trigger` instead of `wait_template`
+        - `choose` action instead of template-based service names
+        - For one-shot date firing, use a `time` trigger plus `automation.turn_off` on a
+          hardcoded entity_id — not `{{ now().date() ... }}`.
+        - Hardcode `target.entity_id` literals — never `{{ this.entity_id }}`.
+        Templates are appropriate ONLY in `data.*` fields, notification message/title,
+        `event_data`, and `variables`. The reactive best-practice checker on this tool
+        will surface anything in a logic position that should be native; consult the
+        `best_practice_warnings` field on the response and fix before re-submitting.
+        For comprehensive guidance, call `ha_get_skill_home_assistant_best_practices`.
+
         Supports two modes: full config replacement OR Python transformation.
 
         WHEN TO USE WHICH MODE:
@@ -478,14 +497,6 @@ class AutomationConfigTools:
             }
         )
 
-        PREFER NATIVE SOLUTIONS OVER TEMPLATES:
-        Before using template triggers/conditions/actions, check if a native option exists:
-        - Use `condition: state` with `state: [list]` instead of template for multiple states
-        - Use `condition: state` with `attribute:` instead of template for attribute checks
-        - Use `condition: numeric_state` instead of template for number comparisons
-        - Use `wait_for_trigger` instead of `wait_template` when waiting for state changes
-        - Use `choose` action instead of template-based service names
-
         TRIGGER TYPES: time, time_pattern, sun, state, numeric_state, event, device, zone, template, and more
         CONDITION TYPES: state, numeric_state, time, sun, template, device, zone, and more
         ACTION TYPES: service calls, delays, wait_for_trigger, wait_template, if/then/else, choose, repeat, parallel