fix: harden MCP write tool errors

mcp_server/TOOLS.md

@@ -20,6 +20,42 @@ Do not use them as a substitute for formal work definition inside the domain rep
 
 ---
 
+## MCP/REST Parity and Failure Handling
+
+The MCP server is a thin stateless HTTP client over the FastAPI service. On
+successful writes, MCP tools return the same JSON object shape as the REST
+endpoint they wrap:
+
+| MCP tool | REST endpoint |
+|---|---|
+| `create_workstream(...)` | `POST /workstreams/` |
+| `create_task(...)` | `POST /tasks/` |
+| `update_task_status(...)` | `PATCH /tasks/{task_id}` |
+| `record_decision(...)` | `POST /decisions/` |
+| `add_progress_event(...)` | `POST /progress/` |
+
+For write tools that emit automatic progress events, the progress event is only
+sent after the primary REST write returns a valid object. If the API is
+unreachable, returns an HTTP error, or returns a malformed object, the MCP tool
+returns a JSON error payload instead:
+
+```json
+{
+  "error": "API 404: ...",
+  "tool": "update_task_status",
+  "response": {"error": "API 404: ..."}
+}
+```
+
+That error is intentional and actionable: do not treat it as success. Fall back
+to the corresponding REST `curl` call from the repo instructions, then record a
+normal progress event once the REST write succeeds. If the primary write
+succeeds but its automatic progress event fails, the tool returns an error with
+the successful `write_result` included so the caller can avoid duplicating the
+entity while recording the missing progress event.
+
+---
+
 ## Query Tools (read-only, use freely)
 
 | Tool | Key Args | When to use |