docs(tools): Add behavioral guidance to 22 tool docstrings

why: "Use when / Avoid when" guidance existed only in Markdown docs,
invisible to agents at runtime. FastMCP exposes function __doc__ as
MCP tool descriptions — enriching docstrings directly improves agent
tool selection and workflow composition.
what:
- Add 2-3 line behavioral summary to each of 22 tool docstrings
- Covers: use case, common next step, side effects, race conditions
- Key addition: send_keys warns about capture_pane race condition
- Destructive tools note self-kill protection and alternatives
- Max ~100 words per tool to manage context window token cost
- Existing docstring content (params, returns) unchanged

Author: tony

src/libtmux_mcp/tools/env_tools.py

@@ -27,6 +27,8 @@ def show_environment(
 ) -> EnvironmentResult:
     """Show tmux environment variables.
 
+    Use to inspect tmux environment variables that affect child processes.
+
     Parameters
     ----------
     session_name : str, optional
@@ -66,6 +68,9 @@ def set_environment(
 ) -> EnvironmentSetResult:
     """Set a tmux environment variable.
 
+    Use to set variables that will be inherited by new panes and windows.
+    Changes do not affect already-running processes.
+
     Parameters
     ----------
     name : str

src/libtmux_mcp/tools/option_tools.py

@@ -73,6 +73,9 @@ def show_option(
 ) -> OptionResult:
     """Show a tmux option value.
 
+    Use to check tmux configuration values such as history-limit,
+    mouse support, or status bar settings.
+
     Parameters
     ----------
     option : str
@@ -109,6 +112,9 @@ def set_option(
 ) -> OptionSetResult:
     """Set a tmux option value.
 
+    Use to change tmux behavior at runtime. Common uses: adjusting
+    history-limit, enabling mouse support, changing status bar format.
+
     Parameters
     ----------
     option : str

src/libtmux_mcp/tools/pane_tools.py

@@ -40,6 +40,10 @@ def send_keys(
 ) -> str:
     """Send keys (commands or text) to a tmux pane.
 
+    After sending, use wait_for_text to block until the command completes,
+    or capture_pane to read the result. Do not capture_pane immediately —
+    there is a race condition.
+
     Parameters
     ----------
     keys : str
@@ -147,6 +151,8 @@ def resize_pane(
 ) -> PaneInfo:
     """Resize a tmux pane.
 
+    Use when adjusting layout for better readability or to fit content.
+
     Parameters
     ----------
     pane_id : str, optional
@@ -205,6 +211,9 @@ def kill_pane(
 ) -> str:
     """Kill (close) a tmux pane. Requires exact pane_id (e.g. '%5').
 
+    Use to clean up panes no longer needed. To remove an entire window
+    and all its panes, use kill_window instead.
+
     Parameters
     ----------
     pane_id : str
@@ -245,6 +254,8 @@ def set_pane_title(
 ) -> PaneInfo:
     """Set the title of a tmux pane.
 
+    Use titles to label panes for later identification via list_panes or get_pane_info.
+
     Parameters
     ----------
     title : str
@@ -287,6 +298,9 @@ def get_pane_info(
 ) -> PaneInfo:
     """Get detailed information about a tmux pane.
 
+    Use this for metadata (PID, path, dimensions) without reading terminal content.
+    To read what is displayed in the pane, use capture_pane instead.
+
     Parameters
     ----------
     pane_id : str, optional
@@ -326,6 +340,9 @@ def clear_pane(
 ) -> str:
     """Clear the contents of a tmux pane.
 
+    Use before send_keys + capture_pane to get a clean capture without prior output.
+    Note: this is two tmux commands with a brief gap — not fully atomic.
+
     Parameters
     ----------
     pane_id : str, optional

src/libtmux_mcp/tools/server_tools.py

@@ -31,6 +31,9 @@ def list_sessions(
 ) -> list[SessionInfo]:
     """List all tmux sessions.
 
+    Use as the starting point for discovery — call this before targeting
+    specific sessions, windows, or panes.
+
     Parameters
     ----------
     socket_name : str, optional
@@ -61,6 +64,9 @@ def create_session(
 ) -> SessionInfo:
     """Create a new tmux session.
 
+    Check list_sessions first to avoid name conflicts. A new session
+    starts with one window and one pane.
+
     Parameters
     ----------
     session_name : str, optional
@@ -105,6 +111,10 @@ def create_session(
 def kill_server(socket_name: str | None = None) -> str:
     """Kill the tmux server and all its sessions.
 
+    Destroys ALL sessions, windows, and panes on this server. Use kill_session
+    to remove a single session instead. Self-kill protection prevents killing
+    the server running this MCP process.
+
     Parameters
     ----------
     socket_name : str, optional
@@ -134,6 +144,9 @@ def kill_server(socket_name: str | None = None) -> str:
 def get_server_info(socket_name: str | None = None) -> ServerInfo:
     """Get information about the tmux server.
 
+    Use to verify the tmux server is running before other operations.
+    For session-level details, use list_sessions instead.
+
     Parameters
     ----------
     socket_name : str, optional

src/libtmux_mcp/tools/session_tools.py

@@ -81,6 +81,8 @@ def create_window(
 ) -> WindowInfo:
     """Create a new window in a tmux session.
 
+    Creates a window with one pane. Use split_window to add more panes afterward.
+
     Parameters
     ----------
     session_name : str, optional
@@ -137,6 +139,9 @@ def rename_session(
 ) -> SessionInfo:
     """Rename a tmux session.
 
+    Use when a session's purpose has changed. Existing pane_id references
+    remain valid after renaming.
+
     Parameters
     ----------
     new_name : str
@@ -167,6 +172,10 @@ def kill_session(
 ) -> str:
     """Kill a tmux session.
 
+    Destroys the session and all its windows and panes. Use kill_window
+    to remove a single window instead. Self-kill protection prevents
+    killing the session containing this MCP process.
+
     Parameters
     ----------
     session_name : str, optional

src/libtmux_mcp/tools/window_tools.py

@@ -111,6 +111,9 @@ def split_window(
 ) -> PaneInfo:
     """Split a tmux window to create a new pane.
 
+    Creates a new pane by splitting an existing one. Use direction to choose
+    above/below/left/right. Returns the new pane's info including its pane_id.
+
     Parameters
     ----------
     pane_id : str, optional
@@ -188,6 +191,9 @@ def rename_window(
 ) -> WindowInfo:
     """Rename a tmux window.
 
+    Use when a window's purpose has changed. Existing window_id references
+    remain valid after renaming.
+
     Parameters
     ----------
     new_name : str
@@ -227,6 +233,10 @@ def kill_window(
 ) -> str:
     """Kill (close) a tmux window. Requires exact window_id (e.g. '@3').
 
+    Destroys the window and all its panes. Use kill_pane to remove a single
+    pane instead. Self-kill protection prevents killing the window containing
+    this MCP process.
+
     Parameters
     ----------
     window_id : str
@@ -272,6 +282,9 @@ def select_layout(
 ) -> WindowInfo:
     """Set the layout of a tmux window.
 
+    Choose from: even-horizontal, even-vertical, main-horizontal,
+    main-vertical, or tiled. Rearranges all panes in the window.
+
     Parameters
     ----------
     layout : str
@@ -319,6 +332,8 @@ def resize_window(
 ) -> WindowInfo:
     """Resize a tmux window.
 
+    Use to adjust the window dimensions. This affects all panes within the window.
+
     Parameters
     ----------
     window_id : str, optional