docs(docstrings): improve tool usage guidance for new Claude sessions (v1.4.1)

- get_wall_posts: clarify mixed content (status posts + activity entries)
- get_activities: expand description and distinguish from get_wall_posts
- like_post: extend post_id examples (wall/, task/, taskList/ IDs)
- get_recipe_categories: add usage notes (IDs, free-tier categories, family-wide)
- add_meal_note: clarify create-only behavior (delete then recreate to update)
- clear_list: move risk warning (default deletes all) to opening line
- create_recipe: verify IMPORTANT confirmation line present

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

CHANGELOG.md

@@ -10,6 +10,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 This project follows Semantic Versioning (SemVer).
 Breaking changes (removed tools, changed parameters) increment the major version.
 
+## [1.4.1] – 2026-04-17
+
+### Improved
+- **Docstring enhancements** — clearer tool usage guidance for new Claude sessions:
+  - `get_wall_posts`: Added note that results include automatic activity entries (task updates, list changes)
+  - `get_activities`: Expanded description and added distinction from `get_wall_posts`
+  - `like_post`: Extended post_id examples to include `task/` and `taskList/` IDs from activities
+  - `get_recipe_categories`: Added usage notes (IDs for create/update, 5 free-tier categories, family-wide scope)
+  - `add_meal_note`: Clarified create-only behavior; to update, delete then recreate
+  - `clear_list`: Moved risk warning (default deletes all tasks) to opening line for visibility
+  - `create_recipe`: Verified IMPORTANT confirmation line present
+
+### Notes
+- No breaking changes; docstring improvements only
+- All tools remain backward compatible
+
 ## [1.4.0] – 2026-04-17
 
 ### Added

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mcp-familywall"
-version = "1.4.0"
+version = "1.4.1"
 description = "MCP server for Family Wall — manage your family's circles, lists, tasks, recipes, and meal plan via Claude"
 readme = "README.md"
 requires-python = ">=3.12"

src/mcp_familywall/server.py

@@ -737,7 +737,18 @@ def delete_category(category_id: str) -> str:
 
 @mcp.tool()
 def get_activities(limit: int = 20) -> str:
-    """Return recent Family Wall wall activities as JSON. limit controls max number of results."""
+    """Return recent Family Wall activity events as JSON.
+
+    Gives task and list activities (task creation/updates, list changes).
+    For wall posts (status updates, photos, comments), use get_wall_posts.
+
+    Args:
+        limit: Maximum number of activities to return (default 20).
+
+    Returns:
+        JSON list of activity objects sorted by date descending,
+        including wall, task, and taskList activity entries.
+    """
     try:
         email, password = get_credentials()
     except RuntimeError as exc:
@@ -1182,7 +1193,10 @@ def delete_task(task_id: str) -> str:
 
 @mcp.tool()
 def clear_list(list_id: str, only_open: bool = False) -> str:
-    """Delete all tasks in a list within a single authenticated session.
+    """Delete all tasks in a list (or only open tasks).
+
+    ⚠️ **Warning**: By default (only_open=False) this deletes all tasks
+    including completed ones. Set only_open=True to keep completed tasks.
 
     IMPORTANT: Ask the user for confirmation before calling this tool.
 
@@ -1193,7 +1207,7 @@ def clear_list(list_id: str, only_open: bool = False) -> str:
         list_id: List metaId from get_lists
             (e.g. ``"taskList/16282169_29775360"``).
         only_open: When ``True`` only incomplete tasks are deleted;
-            completed tasks are kept. Default ``False`` deletes all.
+            completed tasks are kept. Default ``False`` deletes all tasks.
 
     Returns:
         JSON with ``deleted_count`` and ``list_id`` on success,
@@ -1907,7 +1921,10 @@ def like_post(post_id: str, like: bool = True, mood: str = "STAR") -> str:
     IMPORTANT: Ask the user for confirmation before calling this tool.
 
     Args:
-        post_id: Wall post ID from get_activities (e.g. ``wall/23431854_31119189``).
+        post_id: Post metaId from get_wall_posts or get_activities
+            (e.g. ``wall/16282169_31119189`` for wall posts,
+            ``task/16282169_441781324`` for task activities,
+            ``taskList/16282169_123`` for list activities).
         like: ``True`` to add a like (default), ``False`` to remove it.
         mood: Mood type to set or remove. Default is ``"STAR"``.
 
@@ -1984,7 +2001,8 @@ def get_wall_posts(limit: int = 20) -> str:
     """Return recent Family Wall posts as JSON.
 
     Returns posts from the primary circle's wall, sorted by date descending.
-    Includes status posts, activity entries, comments, and like information.
+    Includes status posts, activity entries (task updates, list changes),
+    comments, and like information. Use get_activities for task-focused activity lists.
 
     Args:
         limit: Maximum number of posts to return (default 20).
@@ -2280,6 +2298,10 @@ def _get_raw_recipes() -> list[dict[str, Any]]:
 def get_recipe_categories() -> str:
     """Return all available recipe categories for the family.
 
+    Use the returned IDs directly in create_recipe/update_recipe via category_ids.
+    Always includes 5 standard free-tier categories; categories are family-wide,
+    not recipe-specific.
+
     Returns:
         JSON list of category IDs (e.g. ["category/23431854_2", ...]).
         Always includes the 5 free-tier standard categories if family ID is available.
@@ -3009,7 +3031,8 @@ def add_meal_note(
 
     IMPORTANT: Ask the user for confirmation before calling this tool.
 
-    Creates a ``meal/`` entry for the given date and meal type.
+    Creates a new ``meal/`` entry for the given date and meal type.
+    To update an existing entry, delete it first then create a new one.
     At least one of ``note`` or ``serves`` must be provided.
 
     Args: