Fixed issues reported by agents

roboco/mcp/journal_server.py

@@ -352,53 +352,70 @@ def create_journal_mcp_server(agent_id: str) -> FastMCP:
     client = ApiClient(agent_id)
 
     @mcp.tool()
-    async def roboco_journal_entry(data: JournalEntryInput) -> dict[str, Any]:
+    async def roboco_journal_entry(entry: JournalEntryInput) -> dict[str, Any]:
         """
         Create a general journal entry.
 
         Your journal is personal - use it to track thoughts, progress,
         and document your journey on tasks.
+
+        Args:
+            entry: Journal entry with title, content, entry_type, task_id, tags
         """
-        return await _handle_journal_entry(data, client)
+        return await _handle_journal_entry(entry, client)
 
     @mcp.tool()
-    async def roboco_journal_reflect(data: TaskReflectionInput) -> dict[str, Any]:
+    async def roboco_journal_reflect(reflection: TaskReflectionInput) -> dict[str, Any]:
         """
         Add a task reflection entry.
 
         IMPORTANT: Call this when completing a task. Reflections help build
         institutional memory and track your growth.
+
+        Args:
+            reflection: Reflection with task_id, title, what_done, what_learned,
+                       what_struggled, next_steps
         """
-        return await _handle_reflect(data, client)
+        return await _handle_reflect(reflection, client)
 
     @mcp.tool()
-    async def roboco_journal_decision(data: DecisionLogInput) -> dict[str, Any]:
+    async def roboco_journal_decision(decision: DecisionLogInput) -> dict[str, Any]:
         """
         Log a decision you made.
 
         Use when choosing between approaches. Creates a record of WHY
         you made the decision for future context.
+
+        Args:
+            decision: Decision log with title, context, options, chosen, rationale
         """
-        return await _handle_decision(data, client)
+        return await _handle_decision(decision, client)
 
     @mcp.tool()
-    async def roboco_journal_learning(data: LearningInput) -> dict[str, Any]:
+    async def roboco_journal_learning(learning: LearningInput) -> dict[str, Any]:
         """
         Log something you learned.
 
         Track learnings to build your knowledge base and help future you.
+
+        Args:
+            learning: Learning entry with title, what_learned, how_applied, source
         """
-        return await _handle_learning(data, client)
+        return await _handle_learning(learning, client)
 
     @mcp.tool()
-    async def roboco_journal_struggle(data: StruggleInput) -> dict[str, Any]:
+    async def roboco_journal_struggle(struggle: StruggleInput) -> dict[str, Any]:
         """
         Log a struggle or challenge.
 
         Recording struggles helps track problem-solving patterns and
         create documentation for others.
+
+        Args:
+            struggle: Struggle entry with title, what_struggled,
+                     attempted_solutions, resolution, help_needed
         """
-        return await _handle_struggle(data, client)
+        return await _handle_struggle(struggle, client)
 
     @mcp.tool()
     async def roboco_journal_search(query: str, top_k: int = 5) -> dict[str, Any]:

roboco/mcp/tasks/handlers/_helpers.py

@@ -222,7 +222,20 @@ async def validate_task_start(
 
     if task_status == "claimed" and not task.get("plan"):
         return format_error_response(
-            "NO_PLAN", "Cannot start without a plan. Call roboco_task_plan first."
+            "NO_PLAN",
+            "Cannot start without a plan.",
+            {
+                "required_action": "roboco_task_plan(task_id, approach, steps)",
+                "workflow": "claim → PLAN → start",
+                "example": {
+                    "task_id": task.get("id"),
+                    "approach": "Describe your implementation approach",
+                    "steps": [
+                        {"title": "Step 1", "description": "What to do first"},
+                        {"title": "Step 2", "description": "What to do next"},
+                    ],
+                },
+            },
         )
 
     if task_status == "claimed":

roboco/mcp/tasks/handlers/claim.py

@@ -72,10 +72,11 @@ async def handle_task_claim(
 
     return format_task_response(
         claimed_task,
-        "UNDERSTAND",
-        "Task claimed successfully. "
-        "Read the description and acceptance criteria carefully. "
-        "Ask questions if ANYTHING is unclear - do not guess. "
-        "When ready, create your plan with roboco_task_plan.",
+        "PLAN",
+        "Task claimed. NEXT: Call roboco_task_plan() before you can start.\n"
+        "1. Read the description and acceptance criteria\n"
+        "2. Ask questions if anything is unclear\n"
+        "3. Call roboco_task_plan(task_id, approach, steps)\n"
+        "4. Then call roboco_task_start(task_id)",
         project=project,
     )