mcp(docs[tools/sessions]): document list_servers discovery tool

The new ``list_servers`` tool (added earlier in the branch) wasn't
documented anywhere under ``docs/`` — agents and human readers
discovering the tool from a client's tool list had no docs page to
land on. The conf.py area-map already routes ``server_tools`` →
``sessions``, so the natural home is ``docs/tools/sessions.md``
between ``get_server_info`` and ``create_session``.

Adds the standard four-part section: ``{fastmcp-tool}`` directive,
Use-when / Avoid-when / Side-effects narrative, an example JSON
request + response (including a second example with
``extra_socket_paths`` for the custom-path case), and the
``{fastmcp-tool-input}`` schema directive. Calls out the scope
caveat (custom ``tmux -S /path/...`` daemons are not in the
canonical scan) up front so readers don't reach for the tool in
the wrong situation.

Also adds a grid-item-card to ``docs/tools/index.md`` so the
discovery overview links to the new section.

Author: tony

docs/tools/index.md

@@ -111,6 +111,12 @@ Wait for text to appear in a pane.
 Get tmux server info.
 :::
 
+:::{grid-item-card} list_servers
+:link: list-servers
+:link-type: ref
+Discover live tmux servers under `$TMUX_TMPDIR`.
+:::
+
 :::{grid-item-card} show_option
 :link: show-option
 :link-type: ref

docs/tools/sessions.md

@@ -75,6 +75,76 @@ Response:
 ```{fastmcp-tool-input} server_tools.get_server_info
 ```
 
+---
+
+```{fastmcp-tool} server_tools.list_servers
+```
+
+**Use when** you need to discover other live tmux servers on this
+machine — for example, when an agent's tools were configured for the
+default server but the user is also running a separate tmux for a
+side project.
+
+**Avoid when** you already know the socket name or path you want to
+target — pass it directly to the tool that needs it via `socket_name`.
+
+**Side effects:** None. Readonly. Stale socket files are filtered
+via a kernel-fast UNIX `connect()` probe so the call stays under one
+second even on machines with thousands of orphaned `tmux-<uid>/`
+inodes.
+
+**Scope:** Only servers under `${TMUX_TMPDIR:-/tmp}/tmux-<uid>/` are
+discovered by the canonical scan. Custom `tmux -S /some/path/...`
+daemons that live outside that directory must be supplied via
+`extra_socket_paths`.
+
+**Example:**
+
+```json
+{
+  "tool": "list_servers",
+  "arguments": {}
+}
+```
+
+Response:
+
+```json
+[
+  {
+    "is_alive": true,
+    "socket_name": "default",
+    "socket_path": null,
+    "session_count": 3,
+    "version": "3.6a"
+  },
+  {
+    "is_alive": true,
+    "socket_name": "ci-runner",
+    "socket_path": null,
+    "session_count": 1,
+    "version": "3.6a"
+  }
+]
+```
+
+To include a custom-path daemon:
+
+```json
+{
+  "tool": "list_servers",
+  "arguments": {
+    "extra_socket_paths": ["/home/user/.cache/tmux/socket"]
+  }
+}
+```
+
+Paths that do not exist, are not sockets, or have no listener are
+silently skipped.
+
+```{fastmcp-tool-input} server_tools.list_servers
+```
+
 ## Act
 
 ```{fastmcp-tool} server_tools.create_session