docs(tools): Add real response examples, fix wrong parameter names

why: Tool pages had request-only examples with no response shapes.
Three examples also had wrong parameter names that would fail if copied.
what:
- Add response examples to 12 tool entries across 4 pages
- Responses derived from real MCP outputs on isolated test socket
- Fix search_panes example: "query" → "pattern"
- Fix wait_for_text example: "text" → "pattern"
- Fix split_window example: "horizontal" → "right"

Author: tony

docs/tools/options.md

@@ -21,6 +21,15 @@ history size, status bar settings, etc.
 }
 ```
 
+Response:
+
+```json
+{
+  "option": "history-limit",
+  "value": "2000"
+}
+```
+
 ```{fastmcp-tool-input} option_tools.show_option
 ```
 
@@ -58,6 +67,16 @@ enabling mouse support, changing status bar format.
 }
 ```
 
+Response:
+
+```json
+{
+  "option": "history-limit",
+  "value": "50000",
+  "status": "set"
+}
+```
+
 ```{fastmcp-tool-input} option_tools.set_option
 ```
 

docs/tools/panes.md

@@ -20,12 +20,26 @@ after running a command, checking output, or verifying state.
 {
   "tool": "capture_pane",
   "arguments": {
-    "session_name": "dev",
+    "pane_id": "%0",
     "start": -50
   }
 }
 ```
 
+Response (string):
+
+```text
+$ echo "Running tests..."
+Running tests...
+$ echo "PASS: test_auth (0.3s)"
+PASS: test_auth (0.3s)
+$ echo "FAIL: test_upload (AssertionError)"
+FAIL: test_upload (AssertionError)
+$ echo "3 tests: 2 passed, 1 failed"
+3 tests: 2 passed, 1 failed
+$
+```
+
 ```{fastmcp-tool-input} pane_tools.capture_pane
 ```
 
@@ -64,12 +78,33 @@ directly.
 {
   "tool": "search_panes",
   "arguments": {
-    "query": "error",
+    "pattern": "FAIL",
     "session_name": "dev"
   }
 }
 ```
 
+Response:
+
+```json
+[
+  {
+    "pane_id": "%0",
+    "pane_current_command": "zsh",
+    "pane_current_path": "/home/user/myproject",
+    "window_id": "@0",
+    "window_name": "editor",
+    "session_id": "$0",
+    "session_name": "dev",
+    "matched_lines": [
+      "FAIL: test_upload (AssertionError)",
+      "3 tests: 2 passed, 1 failed"
+    ],
+    "is_caller": null
+  }
+]
+```
+
 ```{fastmcp-tool-input} pane_tools.search_panes
 ```
 
@@ -92,13 +127,27 @@ expected text may never appear (set a timeout).
 {
   "tool": "wait_for_text",
   "arguments": {
-    "text": "Server started",
-    "session_name": "dev",
+    "pattern": "Server listening",
+    "pane_id": "%2",
     "timeout": 30
   }
 }
 ```
 
+Response:
+
+```json
+{
+  "found": true,
+  "matched_lines": [
+    "Server listening on port 8000"
+  ],
+  "pane_id": "%2",
+  "elapsed_seconds": 0.002,
+  "timed_out": false
+}
+```
+
 ```{fastmcp-tool-input} pane_tools.wait_for_text
 ```
 
@@ -123,11 +172,17 @@ the command executes.
   "tool": "send_keys",
   "arguments": {
     "keys": "npm start",
-    "session_name": "dev"
+    "pane_id": "%2"
   }
 }
 ```
 
+Response (string):
+
+```text
+Keys sent to pane %2
+```
+
 ```{fastmcp-tool-input} pane_tools.send_keys
 ```
 

docs/tools/sessions.md

@@ -22,6 +22,20 @@ which session to target.
 }
 ```
 
+Response:
+
+```json
+[
+  {
+    "session_id": "$0",
+    "session_name": "myproject",
+    "window_count": 2,
+    "session_attached": "0",
+    "session_created": "1774521871"
+  }
+]
+```
+
 ```{fastmcp-tool-input} server_tools.list_sessions
 ```
 
@@ -64,6 +78,18 @@ container — create one before creating windows or panes.
 }
 ```
 
+Response:
+
+```json
+{
+  "session_id": "$1",
+  "session_name": "dev",
+  "window_count": 1,
+  "session_attached": "0",
+  "session_created": "1774521872"
+}
+```
+
 ```{fastmcp-tool-input} server_tools.create_session
 ```
 
@@ -88,6 +114,18 @@ container — create one before creating windows or panes.
 }
 ```
 
+Response:
+
+```json
+{
+  "session_id": "$0",
+  "session_name": "new-name",
+  "window_count": 2,
+  "session_attached": "0",
+  "session_created": "1774521871"
+}
+```
+
 ```{fastmcp-tool-input} session_tools.rename_session
 ```
 

docs/tools/windows.md

@@ -23,6 +23,37 @@ session before selecting a window to work with.
 }
 ```
 
+Response:
+
+```json
+[
+  {
+    "window_id": "@0",
+    "window_name": "editor",
+    "window_index": "1",
+    "session_id": "$0",
+    "session_name": "dev",
+    "pane_count": 2,
+    "window_layout": "c195,80x24,0,0[80x12,0,0,0,80x11,0,13,1]",
+    "window_active": "1",
+    "window_width": "80",
+    "window_height": "24"
+  },
+  {
+    "window_id": "@1",
+    "window_name": "server",
+    "window_index": "2",
+    "session_id": "$0",
+    "session_name": "dev",
+    "pane_count": 1,
+    "window_layout": "b25f,80x24,0,0,2",
+    "window_active": "0",
+    "window_width": "80",
+    "window_height": "24"
+  }
+]
+```
+
 ```{fastmcp-tool-input} session_tools.list_windows
 ```
 
@@ -60,6 +91,23 @@ sending keys or capturing output.
 }
 ```
 
+Response:
+
+```json
+{
+  "window_id": "@2",
+  "window_name": "logs",
+  "window_index": "3",
+  "session_id": "$0",
+  "session_name": "dev",
+  "pane_count": 1,
+  "window_layout": "b25f,80x24,0,0,5",
+  "window_active": "1",
+  "window_width": "80",
+  "window_height": "24"
+}
+```
+
 ```{fastmcp-tool-input} session_tools.create_window
 ```
 
@@ -80,11 +128,30 @@ window.
   "tool": "split_window",
   "arguments": {
     "session_name": "dev",
-    "direction": "horizontal"
+    "direction": "right"
   }
 }
 ```
 
+Response:
+
+```json
+{
+  "pane_id": "%4",
+  "pane_index": "1",
+  "pane_width": "39",
+  "pane_height": "24",
+  "pane_current_command": "zsh",
+  "pane_current_path": "/home/user/myproject",
+  "pane_pid": "3732",
+  "pane_title": "",
+  "pane_active": "0",
+  "window_id": "@0",
+  "session_id": "$0",
+  "is_caller": null
+}
+```
+
 ```{fastmcp-tool-input} window_tools.split_window
 ```