fix(deck): address PR #759 round-3 review feedback

- Drop "(in-place)" from filter-helper docstrings; callers should
  consume the return value, mutation is an implementation detail.
- Document that deck_get_archived_stacks always returns cards (an
  archived stack without its cards has no audit value); point to
  description_max_length for size control.
- Document that deck_get_cards applies filtering client-side, so it
  is network-equivalent to deck_get_stack(include_cards=True).
- Pin the empty-list contract: a stack with all-archived cards and
  include_archived_cards=False yields cards == [] (loaded but empty),
  not cards is None (explicitly suppressed).
- Add explicit one-character-over-limit truncation test alongside the
  existing exact-boundary test.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

nextcloud_mcp_server/server/deck.py

@@ -57,7 +57,7 @@ def _apply_board_filters(
     include_users: bool,
     include_labels: bool,
 ) -> DeckBoard:
-    """Drop board sub-fields the caller didn't request (in-place)."""
+    """Drop board sub-fields the caller didn't request; returns the board."""
     if not include_acl:
         board.acl = []
     if not include_users:
@@ -74,7 +74,7 @@ def _apply_stack_filters(
     include_archived_cards: bool,
     description_max_length: int | None,
 ) -> DeckStack:
-    """Apply card-shaping filters to a single stack (in-place)."""
+    """Apply card-shaping filters to a single stack; returns the stack."""
     # Note: the upstream Deck API returns archived cards inline within
     # active stacks (the Deck UI filters them frontend-side). Defaulting
     # include_archived_cards to False mirrors that UI behavior — this is
@@ -94,7 +94,7 @@ def _apply_card_filters(
     include_archived_cards: bool,
     description_max_length: int | None,
 ) -> list[DeckCard]:
-    """Apply filters to a flat list of cards. Returns a (possibly new) list."""
+    """Apply filters to a flat list of cards; returns the (possibly new) list."""
     if not include_archived_cards:
         cards = [c for c in cards if not c.archived]
     _truncate_card_descriptions(cards, description_max_length)
@@ -334,6 +334,10 @@ def configure_deck_tools(mcp: FastMCP):
         active board (e.g. cards moved through a "Done" stack and then
         archived via deck_archive_card). The shape mirrors deck_get_stacks.
 
+        Cards are always included on the returned stacks (an archived stack
+        without its cards would have no audit value); pass
+        ``description_max_length`` if you need to keep the response compact.
+
         Args:
             board_id: The ID of the board
             description_max_length: If set, truncate each card's description
@@ -371,6 +375,12 @@ def configure_deck_tools(mcp: FastMCP):
     ) -> ListCardsResponse:
         """Get all cards in a Nextcloud Deck stack.
 
+        Filtering is applied client-side after the API returns the full
+        stack, so ``include_archived_cards=False`` and
+        ``description_max_length`` reduce response size visible to the
+        caller but not network bandwidth — network-wise this tool is
+        equivalent to deck_get_stack(include_cards=True).
+
         Args:
             board_id: The ID of the board
             stack_id: The ID of the stack