mcp(refactor[instructions]): surface call-site rules in tool descriptions

Follow-up to 6432646 which split ``_BASE_INSTRUCTIONS`` into named
gap-explainer / positive-guidance segments and named the "prefer the
tool description" decision. Phase 1 of the slim-down acts on it:
per-tool rules move from the global card (or invisible module
docstrings) into tool descriptions an agent sees on every
``list_tools`` call.

* ``show_hooks``: docstring now carries the no-set_hook rationale
  (write-hooks survive process death, so they belong in the tmux
  config file, not a transient MCP session). Previously only in the
  ``hook_tools`` module docstring — FastMCP doesn't surface those.
* ``load_buffer``: docstring carries the no-list_buffers /
  clipboard-privacy rationale. Same module-docstring-only problem.
* ``capture_pane``: registered with a ``description=`` override
  pointing at ``snapshot_pane``, ``wait_for_text``, and
  ``search_panes``. The function docstring stays focused on
  parameters for Sphinx; the override carries the agent-facing
  cross-references without bloating the human docstring.
* ``send_keys``: explicit anti-poll guidance naming ``wait_for_text``
  as the server-side blocking primitive.
* ``list_panes`` / ``list_windows``: sharpened metadata-vs-content
  phrasing with the user-trigger language ("panes that contain X").

New parametrized ``test_tool_description_includes`` asserts each tool
is registered AND its description carries the cross-reference, so a
future rename that drops the rule fails loudly instead of silently.

Pure addition — ``_BASE_INSTRUCTIONS`` is unchanged. The redundant
card-level segments come out in a later phase once the call-site
copies have shipped.

Author: tony

src/libtmux_mcp/tools/buffer_tools.py

@@ -176,6 +176,11 @@ def load_buffer(
 ) -> BufferRef:
     """Load text into a new agent-namespaced tmux paste buffer.
 
+    Track the returned BufferRef on subsequent paste_buffer / show_buffer
+    / delete_buffer calls — there is no list_buffers tool, because tmux
+    buffers may include OS clipboard history (passwords, private
+    snippets) and a blanket enumeration would leak that to the agent.
+
     Each call allocates a fresh buffer name — two concurrent calls will
     land in distinct buffers even if they pass the same ``logical_name``.
     Agents MUST use the returned :attr:`BufferRef.buffer_name` on

src/libtmux_mcp/tools/hook_tools.py

@@ -166,6 +166,11 @@ def show_hooks(
 ) -> HookListResult:
     """List configured tmux hooks at the given scope.
 
+    Hooks are read-only by design: tmux hooks survive process death
+    (kill -9, OOM, etc.), so write-hooks belong in your tmux config file,
+    not a transient MCP session. No set_hook / unset_hook tool is exposed
+    for that reason. Use this to inspect what is configured.
+
     ``scope="server"`` enumerates hooks installed via
     ``tmux set-hook -g ...``. tmux splits those globals across two
     options trees by hook category: session-level hooks

src/libtmux_mcp/tools/pane_tools/__init__.py

@@ -80,9 +80,20 @@ def register(mcp: FastMCP) -> None:
     mcp.tool(title="Send Keys", annotations=ANNOTATIONS_SHELL, tags={TAG_MUTATING})(
         send_keys
     )
-    mcp.tool(title="Capture Pane", annotations=ANNOTATIONS_RO, tags={TAG_READONLY})(
-        capture_pane
-    )
+    mcp.tool(
+        title="Capture Pane",
+        annotations=ANNOTATIONS_RO,
+        tags={TAG_READONLY},
+        description=(
+            "Capture the visible contents of a tmux pane (tail-preserving "
+            "truncation at max_lines, default 500). For pane content + "
+            "cursor + mode + scroll state in one call, use snapshot_pane. "
+            "For 'send_keys then wait for output' flows, use wait_for_text "
+            "or wait_for_content_change instead of a capture_pane retry "
+            "loop — server-side blocking is dramatically cheaper in agent "
+            "turns. To find text across many panes, use search_panes."
+        ),
+    )(capture_pane)
     mcp.tool(
         title="Resize Pane", annotations=ANNOTATIONS_MUTATING, tags={TAG_MUTATING}
     )(resize_pane)

src/libtmux_mcp/tools/pane_tools/io.py

@@ -32,9 +32,11 @@ 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.
+    After sending, use wait_for_text to block until the command completes
+    (server-side, turn-cheap) or capture_pane once you know it has
+    finished. Do not capture_pane in a tight loop — that races with
+    command execution and burns agent turns; wait_for_text is the
+    server-side blocking primitive built for this flow.
 
     Parameters
     ----------

src/libtmux_mcp/tools/session_tools.py

@@ -39,8 +39,9 @@ def list_windows(
 ) -> list[WindowInfo]:
     """List windows in a tmux session, or all windows across sessions.
 
-    Only searches window metadata (name, index, layout). To search
-    the actual text visible in terminal panes, use search_panes instead.
+    Searches window metadata only (name, index, layout). For text
+    visible IN terminals — when users say "panes that contain/mention/show X"
+    — use search_panes instead.
 
     Parameters
     ----------

src/libtmux_mcp/tools/window_tools.py

@@ -50,9 +50,9 @@ def list_panes(
 ) -> list[PaneInfo]:
     """List panes in a tmux window, session, or across the entire server.
 
-    Only searches pane metadata (current command, title, working directory).
-    To search the actual text visible in terminal panes, use search_panes
-    instead.
+    Searches pane metadata only (current command, title, working
+    directory). For text visible IN terminals — when users say "panes
+    that contain/mention/show X" — use search_panes instead.
 
     Parameters
     ----------

tests/test_server.py

@@ -247,6 +247,64 @@ def test_base_instructions_document_buffer_lifecycle() -> None:
     assert "clipboard history" in _BASE_INSTRUCTIONS
 
 
+@pytest.mark.parametrize(
+    ("tool_name", "must_include"),
+    [
+        ("capture_pane", "snapshot_pane"),
+        ("capture_pane", "wait_for_text"),
+        ("capture_pane", "search_panes"),
+        ("show_hooks", "tmux config file"),
+        ("load_buffer", "list_buffers"),
+        ("load_buffer", "clipboard history"),
+        ("send_keys", "wait_for_text"),
+        ("list_panes", "search_panes"),
+        ("list_windows", "search_panes"),
+    ],
+)
+def test_tool_description_includes(tool_name: str, must_include: str) -> None:
+    """Tool descriptions carry cross-references the agent needs at the call site.
+
+    Phase 1 of the BASE_INSTRUCTIONS slim-down: rules that are tool-specific
+    live in tool descriptions (surfaced by FastMCP at every ``list_tools``
+    call), not in the global card or in module docstrings (which FastMCP
+    does not surface). The asserted phrases are the ones an agent would
+    look for when deciding which tool to call:
+
+    * ``capture_pane`` cross-references richer alternatives
+      (``snapshot_pane``, ``wait_for_text``) and the parallel-search tool
+      (``search_panes``).
+    * ``show_hooks`` carries the no-set_hook rationale ("tmux config
+      file") that previously lived only in ``hook_tools``' module
+      docstring.
+    * ``load_buffer`` carries the no-list_buffers / clipboard-privacy
+      rationale that previously lived only in ``buffer_tools``' module
+      docstring.
+    * ``send_keys`` points at ``wait_for_text`` instead of a poll loop.
+    * ``list_panes`` / ``list_windows`` point at ``search_panes`` for
+      content (vs. metadata-only) queries.
+
+    The "tool exists" assertion is a strict upgrade over substring tests
+    on ``_BASE_INSTRUCTIONS``: a future rename that drops the rule fails
+    here instead of silently losing agent-relevant guidance.
+    """
+    import asyncio
+
+    from fastmcp import FastMCP
+
+    from libtmux_mcp.tools import register_tools
+
+    mcp = FastMCP(name="tool-description-contract")
+    register_tools(mcp)
+
+    tools = asyncio.run(mcp.list_tools())
+    by_name = {tool.name: tool for tool in tools}
+    assert tool_name in by_name, f"{tool_name!r} is not registered"
+    description = by_name[tool_name].description or ""
+    assert must_include in description, (
+        f"{tool_name!r} description missing {must_include!r}; got {description!r}"
+    )
+
+
 def test_build_instructions_documents_is_caller_workflow_inside_tmux(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None: