docs: improve tool descriptions for better agent adoption

- Rewrite all 15 tool descriptions with what/why/when structure
- Add concrete examples in add_note and add_reference descriptions
- Emphasize cross-session persistence and knowledge preservation
- Update README.md with current schema and tool list
- Bump version to 0.1.2

Author: ChesterRa

README.md

@@ -55,17 +55,23 @@ CCONTEXT_ROOT=/path/to/project python -m ccontext_mcp
 
 ## Tools
 
-| Tool | Purpose |
-|------|---------|
-| `get_context()` | Get full execution status. **Start here** at session begin. |
-| `update_context()` | Update goal, why, or your agent status |
-| `create_task()` | Create a new task with steps |
-| `update_task()` | Update task/step status |
-| `delete_task()` | Remove a task |
-| `list_tasks()` | List tasks with optional status filter |
-| `add_entry()` | Add a note or reference |
-| `update_entry()` | Update entry content or score |
-| `remove_entry()` | Remove an entry when no longer relevant |
+| Category | Tool | Purpose |
+|----------|------|---------|
+| **Context** | `get_context()` | Your project memory - **call this FIRST** |
+| **Milestones** | `create_milestone()` | Start a new project phase |
+| | `update_milestone()` | Modify milestone details or status |
+| | `complete_milestone()` | Close milestone with outcomes |
+| | `remove_milestone()` | Delete cancelled milestone |
+| **Tasks** | `list_tasks()` | Find tasks by status or assignee |
+| | `create_task()` | Create task with trackable steps |
+| | `update_task()` | Update progress, mark steps done |
+| | `delete_task()` | Remove cancelled task |
+| **Notes** | `add_note()` | Preserve lessons, warnings, decisions |
+| | `update_note()` | Refresh score or update content |
+| | `remove_note()` | Delete obsolete note |
+| **References** | `add_reference()` | Bookmark files or URLs |
+| | `update_reference()` | Refresh score or update details |
+| | `remove_reference()` | Delete obsolete reference |
 
 ## Score-Based Lifecycle
 
@@ -79,10 +85,10 @@ Every note and reference has a **score** (default: 10, range: 1-100).
 
 ```python
 # Important lesson - will persist ~50 get_context() calls
-add_entry(type="note", content="Never use force push on main", score=50)
+add_note(content="Never use force push on main", score=50)
 
 # Temporary reference - will fade after ~10 calls  
-add_entry(type="reference", content="API docs", uri="https://...", score=10)
+add_reference(url="https://api.example.com/docs", note="API docs", score=10)
 ```
 
 ## Directory Structure
@@ -100,23 +106,30 @@ your-project/
 ## context.yaml Schema
 
 ```yaml
-version: "1"
-goal: "Current execution goal - what are we trying to achieve?"
-why: "Decision background - why this approach?"
-agents:
-  AgentA: "Last known status of AgentA"
-  AgentB: "Last known status of AgentB"
+milestones:
+  - id: M1
+    name: "Phase 1: Core Implementation"
+    description: "Build foundation components"
+    status: done  # done | active | pending
+    started: "2024-12-01"
+    completed: "2024-12-07"
+    outcomes: "15 tools implemented, 42 tests passing"
+  - id: M2
+    name: "Phase 2: Integration"
+    description: "Integrate with orchestrators"
+    status: active
+    started: "2024-12-08"
+
 notes:
   - id: N001
-    content: "Important lesson learned"
+    content: "API rate limit is 100/min - batch requests"
     score: 45
-    created: "2024-01-15T10:30:00Z"
+
 references:
   - id: R001
-    content: "Useful documentation"
-    uri: "https://docs.example.com"
-    score: 8
-    expiring: true  # Shows when score <= 0
+    url: "src/core/auth.py"
+    note: "OAuth implementation"
+    score: 30
 ```
 
 ## Task Schema
@@ -144,15 +157,15 @@ One agent maintains its own context, picking up where it left off each session.
 
 ### Multi-Agent Collaboration
 Multiple agents share the same `context/` directory:
-- Each updates their status in `agents` field
-- Shared notes and references
+- Shared milestones show project progress
+- Shared notes preserve collective knowledge
 - Coordinated task management
 
 ### Integration with Orchestrators
 Works well with agent orchestrators (like CCCC) that can:
 - Detect `context/` directory existence
 - Generate appropriate prompts based on context
-- Process progress markers as fallback
+- Guide agents to use ccontext tools
 
 ## Without MCP
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ccontext-mcp"
-version = "0.1.1"
+version = "0.1.2"
 description = "MCP server for AI agents to manage project execution context"
 readme = "README.md"
 license = "MIT"

src/ccontext_mcp/tools.py

@@ -25,72 +25,79 @@
 # =============================================================================
 
 TOOL_DESCRIPTIONS = {
-    # Context
+    # Context - THE entry point
     "get_context": (
-        "**Start here!** Get the project's execution context before doing any work. "
-        "Returns milestones (project phases), active tasks, important notes, and references. "
-        "Call this first to understand the full picture."
+        "Your project's execution memory - call this FIRST before starting any work. "
+        "Shows: where the project is (milestones), current work (active task), "
+        "accumulated wisdom (notes), and key locations (references). "
+        "Essential to avoid duplicating work or missing critical information."
     ),
 
-    # Milestone tools
+    # Milestone tools - project timeline
     "create_milestone": (
-        "Create a new project milestone/phase. Use when starting a new major phase of work. "
-        "Include a clear name and detailed description of what this phase will accomplish."
+        "Start a new project phase that persists across sessions. "
+        "Use when beginning major work (e.g., 'Phase 1: Core Implementation'). "
+        "Milestones create a timeline showing project evolution."
     ),
     "update_milestone": (
-        "Update an existing milestone's name, description, or status. "
-        "Use to track progress or refine the scope of a phase."
+        "Modify a milestone's details or advance its status (pending→active→done). "
+        "Use when scope changes or when starting work on a pending phase."
     ),
     "complete_milestone": (
-        "Mark a milestone as done and record its outcomes. "
-        "Use when a phase is finished to document what was accomplished."
+        "Close a milestone and record what was accomplished. "
+        "Outcomes become permanent project history visible to future sessions."
     ),
     "remove_milestone": (
-        "Remove a milestone that's no longer needed. "
-        "Use for cancelled phases or mistakes."
+        "Delete a cancelled or mistaken milestone. "
+        "Completed milestones should be kept as project history."
     ),
 
-    # Task tools
+    # Task tools - work tracking
     "list_tasks": (
-        "Query tasks by status (planned/active/done) or assignee. "
-        "Use to find what needs to be done or check progress."
+        "Find tasks by status (planned/active/done) or assignee. "
+        "Use to see what work exists and check progress across sessions."
     ),
     "create_task": (
-        "Create a new task when starting work that involves multiple steps. "
-        "Tasks help track progress on specific deliverables."
+        "Break down work into trackable steps that persist across sessions. "
+        "Use when starting work that spans multiple actions or needs progress tracking."
     ),
     "update_task": (
-        "Update task status, name, goal, or mark steps as done. "
-        "Keep tasks current so progress is visible."
+        "Update task progress - change status, mark steps done, or modify details. "
+        "Keeps execution state accurate for session handoffs and work resumption."
     ),
     "delete_task": (
-        "Remove a task that's no longer needed (cancelled or created by mistake)."
+        "Remove a cancelled or mistaken task. "
+        "Completed tasks auto-archive after 7 days - no need to delete them."
     ),
 
-    # Note tools
+    # Note tools - knowledge preservation
     "add_note": (
-        "Record important discoveries, lessons learned, or warnings. "
-        "High-score notes (50-100) persist longer. Use for knowledge that future work needs."
+        "Preserve important knowledge for future sessions - lessons, warnings, decisions. "
+        "High scores (50-100) persist longer; low scores decay and auto-archive. "
+        "Example: 'API rate limit is 100/min - batch requests to avoid throttling'"
     ),
     "update_note": (
-        "Update a note's content or renew its score to keep it visible longer. "
-        "Use when information is still relevant but score is low."
+        "Refresh a note's score to prevent decay, or update its content. "
+        "Use when a note is still valuable but its score is getting low."
     ),
     "remove_note": (
-        "Delete a note that's no longer relevant."
+        "Delete an obsolete note immediately. "
+        "Prefer letting low-value notes decay naturally via score system."
     ),
 
-    # Reference tools
+    # Reference tools - navigation bookmarks
     "add_reference": (
-        "Record a useful file location or URL with a description. "
-        "High-score references persist longer. Use for important code locations or docs."
+        "Bookmark important file paths or URLs for quick navigation. "
+        "High scores persist longer. Use for: key source files, API docs, configs. "
+        "Example: 'src/core/auth.py - OAuth implementation'"
     ),
     "update_reference": (
-        "Update a reference or renew its score. "
-        "Use to keep important references visible."
+        "Refresh a reference's score to prevent decay, or update its details. "
+        "Use when a reference is still valuable but its score is getting low."
     ),
     "remove_reference": (
-        "Delete a reference that's no longer relevant."
+        "Delete an obsolete reference immediately. "
+        "Prefer letting outdated references decay naturally via score system."
     ),
 }