fix: cover max-limit hint edge and invalid end_time validation

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AgVydTVw2uzQqdnxZ7jfJv

Author: kingpanther13

src/ha_mcp/tools/error_log_parsing.py

@@ -551,8 +551,19 @@ def _attach_error_log_pagination(
     if unreturned_matches > 0:
         total = data.get("total_lines", unreturned_matches)
         suggested = min(total, MAX_LIMIT)
-        data["pagination_hint"] = (
-            f"{unreturned_matches} more matching lines remain inside this "
-            f"window (no older history exists behind it). Repeat the call "
-            f"with limit={suggested} to retrieve them in one response."
-        )
+        if limit is not None and limit >= suggested:
+            # Raising the limit cannot help: it is already at (or past) the
+            # ceiling, so recommending it would repeat the same request.
+            data["pagination_hint"] = (
+                f"{unreturned_matches} more matching lines remain inside this "
+                f"window (no older history exists behind it), but 'limit' is "
+                f"already at its maximum ({MAX_LIMIT}). Narrow the match set — "
+                "a more specific 'search' or a 'level' filter — so the "
+                "remainder fits in one response."
+            )
+        else:
+            data["pagination_hint"] = (
+                f"{unreturned_matches} more matching lines remain inside this "
+                f"window (no older history exists behind it). Repeat the call "
+                f"with limit={suggested} to retrieve them in one response."
+            )

src/ha_mcp/tools/log_sources.py

@@ -195,7 +195,20 @@ async def _get_logbook(
         )
 
         if end_time:
-            end_dt = datetime.fromisoformat(end_time.replace("Z", "+00:00"))
+            try:
+                end_dt = datetime.fromisoformat(end_time.replace("Z", "+00:00"))
+            except ValueError:
+                # Outside the fetch try-block below, so without this guard the
+                # raw ValueError would bypass the structured ToolError shape.
+                raise_tool_error(
+                    create_error_response(
+                        ErrorCode.VALIDATION_INVALID_PARAMETER,
+                        f"Invalid end_time '{end_time}': not an ISO 8601 timestamp",
+                        suggestions=[
+                            "Use ISO format, e.g. end_time='2026-08-28T01:00:00Z'"
+                        ],
+                    )
+                )
         else:
             end_dt = datetime.now(UTC)
 

tests/src/unit/test_tools_utility_error_log_structured.py

@@ -1122,6 +1122,19 @@ async def test_terminal_window_with_unreturned_matches_hints_a_larger_limit(self
         assert "40 more matching lines remain" in result["pagination_hint"]
         assert "limit=50" in result["pagination_hint"]
 
+    @pytest.mark.asyncio
+    async def test_terminal_window_at_max_limit_hints_narrowing_instead(self):
+        """At limit=MAX_LIMIT the raise-the-limit hint would repeat the same
+        request verbatim; the hint switches to narrowing the match set."""
+        client = _make_client(_numbered_log(MAX_LIMIT + 100), has_more=False)
+        tools = _register_and_collect(client)
+        result = await tools["ha_get_logs"](
+            source="error_log", limit=MAX_LIMIT, search="issue"
+        )
+        assert result["has_more"] is False
+        assert "already at its maximum" in result["pagination_hint"]
+        assert f"limit={MAX_LIMIT} to retrieve" not in result["pagination_hint"]
+
     @pytest.mark.asyncio
     async def test_next_offset_advances_from_the_current_offset(self):
         client = _make_client(_numbered_log(20), has_more=True)

tests/src/unit/test_tools_utility_log_order.py

@@ -6,9 +6,11 @@
 newest-first fix (#1178).
 """
 
+import json
 from unittest.mock import AsyncMock, patch
 
 import pytest
+from fastmcp.exceptions import ToolError
 
 from ha_mcp.client.rest_client import ErrorLogPage, HomeAssistantConnectionError
 from ha_mcp.tools.tools_logs import LogTools
@@ -261,6 +263,23 @@ async def test_tolerates_missing_none_and_non_dict_entries(self):
         assert result["entries"][0]["timestamp"] == 100.0
 
 
+class TestLogbookEndTimeValidation:
+    """source='logbook' — a bad end_time must fail with the structured shape."""
+
+    @pytest.mark.asyncio
+    async def test_invalid_end_time_raises_structured_validation_error(self):
+        """`datetime.fromisoformat` runs before the fetch try-block; without
+        the guard a raw ValueError escapes the ToolError contract."""
+        client = AsyncMock()
+        tools = LogTools(client)
+        with pytest.raises(ToolError) as exc_info:
+            await tools.get_logs(**_call_kwargs(source="logbook", end_time="invalid"))
+        payload = json.loads(str(exc_info.value))
+        assert payload["error"]["code"] == "VALIDATION_INVALID_PARAMETER"
+        assert "end_time" in payload["error"]["message"]
+        client.get_logbook.assert_not_called()
+
+
 class TestSystemMalformedEntries:
     """source='system' — malformed records must not escape the error envelope."""