Clarify configuration instructions and enhance bot tools.

advanced_youtube_search_full_llm.yaml

@@ -13,7 +13,7 @@ blueprint:
     - The `scripts/youtube_data_tool.py` script needs to be copied into the `config/pyscript` folder.
     - The `scripts/requirements.txt` file needs to be copied into the `config/pyscript` folder.
     - The mentioned file(s) is/are included in the repository.
-    - Enable two Pyscript configuration options in `config/configuration.yaml` to permit the import of any Python package and to expose hass as a variable.
+    - You need to enable two Pyscript options through the UI or via YAML to allow importing all Python packages and to make hass available as a global variable.
     - A YouTube API key needs to be configured in `config/configuration.yaml` and `config/secrets.yaml`.
 
     ```

create_lunar_events.yaml

@@ -12,7 +12,7 @@ blueprint:
     - The Pyscript integration needs to be installed through HACS and properly configured.
     - The `scripts/date_conversion_tool.py` script needs to be copied into the `config/pyscript` folder.
     - The mentioned file(s) is/are included in the repository.
-    - Enable two Pyscript configuration options in `config/configuration.yaml` to permit the import of any Python package and to expose hass as a variable.
+    - You need to enable two Pyscript options through the UI or via YAML to allow importing all Python packages and to make hass available as a global variable.
 
     ```
     # File configuration.yaml

date_lookup_and_conversion_full_llm.yaml

@@ -12,7 +12,7 @@ blueprint:
     - The Pyscript integration needs to be installed through HACS and properly configured.
     - The `scripts/date_conversion_tool.py` script needs to be copied into the `config/pyscript` folder.
     - The mentioned file(s) is/are included in the repository.
-    - Enable two Pyscript configuration options in `config/configuration.yaml` to permit the import of any Python package and to expose hass as a variable.
+    - You need to enable two Pyscript options through the UI or via YAML to allow importing all Python packages and to make hass available as a global variable.
 
     ```
     # File configuration.yaml

devices_schedules.yaml

@@ -19,7 +19,7 @@ blueprint:
     - The `scripts/common_utilities.py` script need to be copied into the `config/pyscript` folder.
     - This blueprint is a dependency for the `devices_schedules_full_llm.yaml` and the `devices_schedules_restart_handler.yaml` blueprints.
     - The mentioned file(s) is/are included in the repository.
-    - Enable two Pyscript configuration options in `config/configuration.yaml` to permit the import of any Python package and to expose hass as a variable.
+    - You need to enable two Pyscript options through the UI or via YAML to allow importing all Python packages and to make hass available as a global variable.
 
     ```
     # File configuration.yaml

devices_schedules_restart_handler.yaml

@@ -16,7 +16,7 @@ blueprint:
     - The `scripts/common_utilities.py` script need to be copied into the `config/pyscript` folder.
     - The `devices_schedules.yaml` blueprint needs to be installed.
     - The mentioned file(s) is/are included in the repository.
-    - Enable two Pyscript configuration options in `config/configuration.yaml` to permit the import of any Python package and to expose hass as a variable.
+    - You need to enable two Pyscript options through the UI or via YAML to allow importing all Python packages and to make hass available as a global variable.
 
     ```
     # File configuration.yaml

memory_tool_full_llm.yaml

@@ -12,7 +12,7 @@ blueprint:
     - The Pyscript integration needs to be installed through HACS and properly configured.
     - The `scripts/memory.py` script needs to be copied into the `config/pyscript` folder.
     - The mentioned file(s) is/are included in the repository.
-    - Enable two Pyscript configuration options in `config/configuration.yaml` to permit the import of any Python package and to expose hass as a variable.
+    - You need to enable two Pyscript options through the UI or via YAML to allow importing all Python packages and to make hass available as a global variable.
 
     ```
     # File configuration.yaml

memory_tool_local.yaml

@@ -12,7 +12,7 @@ blueprint:
     - The Pyscript integration needs to be installed through HACS and properly configured.
     - The `scripts/memory.py` and `scripts/common_utilities.py` scripts need to be copied into the `config/pyscript` folder.
     - The mentioned file(s) is/are included in the repository.
-    - Enable two Pyscript configuration options in `config/configuration.yaml` to permit the import of any Python package and to expose hass as a variable.
+    - You need to enable two Pyscript options through the UI or via YAML to allow importing all Python packages and to make hass available as a global variable.
 
     ```
     # File configuration.yaml

scripts/telegram_bot_handle_tool.py

@@ -663,7 +663,7 @@ async def get_telegram_updates(
         selector:
           number:
             min: 30
-            max: 60
+            max: 120
             step: 1
         default: 30
       offset:
@@ -684,7 +684,16 @@ async def get_telegram_updates(
     """
     try:
         session = await _ensure_session()
-        return await _get_updates(session, timeout=timeout, offset=offset, limit=limit)
+        response = await _get_updates(
+            session, timeout=timeout, offset=offset, limit=limit
+        )
+        if not response or not response.get("result"):
+            return {
+                "ok": True,
+                "result": [],
+                "description": "No updates found. Please send a message to the bot first to ensure there is data to retrieve.",
+            }
+        return response
     except Exception as error:
         return {"error": f"An unexpected error occurred during processing: {error}"}
 

scripts/zalo_bot_handle_tool.py

@@ -565,17 +565,24 @@ async def get_zalo_updates(timeout: int = 30) -> dict[str, Any]:
     fields:
       timeout:
         name: Timeout
-        description: Server wait time before responding (30-60 seconds).
+        description: Server wait time before responding.
         selector:
           number:
             min: 30
-            max: 60
+            max: 120
             step: 1
         default: 30
     """
     try:
         session = await _ensure_session()
-        return await _get_updates(session, timeout=timeout)
+        response = await _get_updates(session, timeout=timeout)
+        if not response or not response.get("result"):
+            return {
+                "ok": True,
+                "result": [],
+                "description": "No updates found. Please send a message to the bot first to ensure there is data to retrieve.",
+            }
+        return response
     except Exception as error:
         return {"error": f"An unexpected error occurred during processing: {error}"}
 

send_to_telegram_full_llm.yaml

@@ -14,7 +14,7 @@ blueprint:
     - The `scripts/telegram_bot_handle_tool.py` script needs to be copied into the `config/pyscript` folder.
     - The `scripts/requirements.txt` file needs to be copied into the `config/pyscript` folder.
     - The mentioned file(s) is/are included in the repository.
-    - Enable two Pyscript configuration options in `config/configuration.yaml` to permit the import of any Python package and to expose hass as a variable.
+    - You need to enable two Pyscript options through the UI or via YAML to allow importing all Python packages and to make hass available as a global variable.
     - A Telegram bot token needs to be configured in `config/configuration.yaml` and `config/secrets.yaml`.
 
     ```

send_to_zalo_bot_full_llm.yaml

@@ -14,7 +14,7 @@ blueprint:
     - The `scripts/zalo_bot_handle_tool.py` script needs to be copied into the `config/pyscript` folder.
     - The `scripts/requirements.txt` file needs to be copied into the `config/pyscript` folder.
     - The mentioned file(s) is/are included in the repository.
-    - Enable two Pyscript configuration options in `config/configuration.yaml` to permit the import of any Python package and to expose hass as a variable.
+    - You need to enable two Pyscript options through the UI or via YAML to allow importing all Python packages and to make hass available as a global variable.
     - A Zalo bot token needs to be configured in `config/configuration.yaml` and `config/secrets.yaml`.
 
     ```

telegram_bot_webhook.yaml

@@ -16,7 +16,7 @@ blueprint:
     - The `scripts/telegram_bot_handle_tool.py` and `scripts/common_utilities.py` scripts need to be copied into the `config/pyscript` folder.
     - The `scripts/requirements.txt` file needs to be copied into the `config/pyscript` folder.
     - The mentioned file(s) is/are included in the repository.
-    - Enable two Pyscript configuration options in `config/configuration.yaml` to permit the import of any Python package and to expose hass as a variable.
+    - You need to enable two Pyscript options through the UI or via YAML to allow importing all Python packages and to make hass available as a global variable.
     - A Telegram bot token needs to be configured in `config/configuration.yaml` and `config/secrets.yaml`.
 
     ```

traffic_fine_lookup_full_llm.yaml

@@ -13,7 +13,7 @@ blueprint:
     - The `scripts/traffic_fine_lookup_tool.py` script needs to be copied into the `config/pyscript` folder.
     - The `scripts/requirements.txt` file needs to be copied into the `config/pyscript` folder.
     - The mentioned file(s) is/are included in the repository.
-    - Enable two Pyscript configuration options in `config/configuration.yaml` to permit the import of any Python package and to expose hass as a variable.
+    - You need to enable two Pyscript options through the UI or via YAML to allow importing all Python packages and to make hass available as a global variable.
     - A Gemini API key needs to be configured in `config/configuration.yaml` and `config/secrets.yaml`, as it's required for solving CAPTCHAs.
 
     ```

zalo_bot_webhook.yaml

@@ -14,7 +14,7 @@ blueprint:
     - The `scripts/zalo_bot_handle_tool.py` and `scripts/common_utilities.py` scripts need to be copied into the `config/pyscript` folder.
     - The `scripts/requirements.txt` file needs to be copied into the `config/pyscript` folder.
     - The mentioned file(s) is/are included in the repository.
-    - Enable two Pyscript configuration options in `config/configuration.yaml` to permit the import of any Python package and to expose hass as a variable.
+    - You need to enable two Pyscript options through the UI or via YAML to allow importing all Python packages and to make hass available as a global variable.
     - A Zalo bot token needs to be configured in `config/configuration.yaml` and `config/secrets.yaml`.
 
     ```

zalo_custom_bot_webhook.yaml

@@ -15,7 +15,7 @@ blueprint:
     - The `scripts/requirements.txt` file needs to be copied into the `config/pyscript` folder.
     - The mentioned file(s) is/are included in the repository.
     - Update the Webhook URL to the Zalo Bot Server after saving the script.
-    - Enable two Pyscript configuration options in `config/configuration.yaml` to permit the import of any Python package and to expose hass as a variable.
+    - You need to enable two Pyscript options through the UI or via YAML to allow importing all Python packages and to make hass available as a global variable.
 
     ```
     # File configuration.yaml