feat: Flip exception_to_structured_error default to raise_error=True (#518)

Now that all tools are migrated to use ToolError, flip the default
behavior of exception_to_structured_error to raise by default.

This completes the ToolError migration - all error paths now signal
errors at the MCP protocol level with isError=true.

https://claude.ai/code/session_01MvDDV6qmWosBfGhmTLYzo8

Author: claude

src/ha_mcp/tools/helpers.py

@@ -88,46 +88,43 @@ def exception_to_structured_error(
     error: Exception,
     context: dict[str, Any] | None = None,
     *,
-    raise_error: Literal[False] = False,
-) -> dict[str, Any]: ...
+    raise_error: Literal[True] = True,
+) -> NoReturn: ...
 
 
 @overload
 def exception_to_structured_error(
     error: Exception,
     context: dict[str, Any] | None = None,
     *,
-    raise_error: Literal[True],
-) -> NoReturn: ...
+    raise_error: Literal[False],
+) -> dict[str, Any]: ...
 
 
 def exception_to_structured_error(
     error: Exception,
     context: dict[str, Any] | None = None,
     *,
-    raise_error: bool = False,
+    raise_error: bool = True,
 ) -> dict[str, Any]:
     """
     Convert an exception to a structured error response.
 
     This function maps common exception types to appropriate error codes
-    and creates informative error responses.
+    and creates informative error responses. By default, it raises a ToolError
+    to signal the error at the MCP protocol level (isError=true).
 
     Args:
         error: The exception to convert
         context: Additional context to include in the response
-        raise_error: If True, raises ToolError with the structured error.
-                    If False (default), returns the error dict.
-
-                    NOTE: The default will change to True in a future PR once
-                    all tools are updated to use ToolError. New code should
-                    explicitly pass raise_error=True for forward compatibility.
+        raise_error: If True (default), raises ToolError with the structured error.
+                    If False, returns the error dict for further modification.
 
     Returns:
         Structured error response dictionary (only if raise_error=False)
 
     Raises:
-        ToolError: If raise_error=True, raises with JSON-serialized error
+        ToolError: If raise_error=True (default), raises with JSON-serialized error
     """
     error_str = str(error).lower()
     error_msg = str(error)

tests/src/unit/test_tool_error_signaling.py

@@ -75,18 +75,10 @@ def test_preserves_all_error_fields(self):
 class TestExceptionToStructuredError:
     """Tests for the exception_to_structured_error function."""
 
-    def test_returns_dict_by_default(self):
-        """exception_to_structured_error should return dict by default."""
-        result = exception_to_structured_error(ValueError("test error"))
-
-        assert isinstance(result, dict)
-        assert result["success"] is False
-        assert "error" in result
-
-    def test_raises_tool_error_when_explicit(self):
-        """exception_to_structured_error should raise ToolError when raise_error=True."""
+    def test_raises_tool_error_by_default(self):
+        """exception_to_structured_error should raise ToolError by default."""
         with pytest.raises(ToolError):
-            exception_to_structured_error(ValueError("test error"), raise_error=True)
+            exception_to_structured_error(ValueError("test error"))
 
     def test_returns_dict_when_raise_error_false(self):
         """exception_to_structured_error should return dict when raise_error=False."""