From d3db8377f734080359a6c4df243fb4e48d3a4996 Mon Sep 17 00:00:00 2001
From: Kastrah <abdulkhaliqakinwunmi@gmail.com>
Date: Wed, 28 Jan 2026 04:56:32 +0100
Subject: [PATCH] docs: add sessions health command documentation

---
 docs/cli/sessions.md | 60 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 59 insertions(+), 1 deletion(-)

diff --git a/docs/cli/sessions.md b/docs/cli/sessions.md
index d906bc1de..e283cd0b7 100644
--- a/docs/cli/sessions.md
+++ b/docs/cli/sessions.md
@@ -1,7 +1,8 @@
 ---
-summary: "CLI reference for `moltbot sessions` (list stored sessions + usage)"
+summary: "CLI reference for `moltbot sessions` (list stored sessions + usage) + `moltbot sessions health` (diagnose tool pairing issues)"
 read_when:
   - You want to list stored sessions and see recent activity
+  - You encounter "tool id not found" errors
 ---
 
 # `moltbot sessions`
@@ -14,3 +15,60 @@ moltbot sessions --active 120
 moltbot sessions --json
 ```
 
+# `moltbot sessions health`
+
+Diagnose session health for tool call/result pairing issues. Use this when you encounter errors like:
+
+> `LLM request rejected: invalid params, tool result's tool id(call_function_xxx) not found`
+
+This command checks for:
+- **Orphaned tool results** - tool results without matching tool calls
+- **Unmatched tool calls** - tool calls without results
+- **Duplicate tool results** - multiple results for the same tool call
+
+```bash
+# Check all sessions for issues
+moltbot sessions health
+
+# Show detailed diagnostics for all sessions
+moltbot sessions health --verbose
+
+# Check a specific session by ID
+moltbot sessions health --session-id d7ce8851-6c25-4244-b872-58690b546288
+
+# Use a custom session store
+moltbot sessions health --store /path/to/sessions.json
+```
+
+## Example output
+
+**Healthy session:**
+```
+✅ [agent:main:main] HEALTHY (22 messages)
+```
+
+**Unhealthy session:**
+```
+❌ [agent:main:main] UNHEALTHY
+  - Found 1 orphaned tool result(s) without matching tool call
+  Orphaned IDs: call_function_ynavyw1i6p3e_1
+```
+
+## Troubleshooting
+
+If a session is unhealthy:
+
+1. Clear the session:
+   ```bash
+   rm -f ~/.clawdbot/agents/*/sessions/*.jsonl
+   ```
+
+2. Restart the gateway:
+   ```bash
+   pkill -HUP moltbot-gateway
+   ```
+
+3. Verify health:
+   ```bash
+   moltbot sessions health --verbose
+   ```
\ No newline at end of file