mcp(test[server]): verify socket_name instruction contract

_BASE_INSTRUCTIONS promised "All tools accept an optional socket_name
parameter" — but list_servers signature is
list_servers(extra_socket_paths: list[str] | None = None) — no
socket_name. The instruction lied to agents, and any contract test
written against the original wording would fail.

Tighten the wording to acknowledge list_servers as the explicit
exception:

  Targeted tmux tools accept an optional socket_name parameter
  (defaults to LIBTMUX_SOCKET env var); list_servers discovers sockets
  via TMUX_TMPDIR plus optional extra_socket_paths instead.

Add two tests in tests/test_server.py:

- test_base_instructions_document_socket_name_contract: locks the
  three new keywords in the wording.
- test_registered_tools_accept_socket_name: enumerates every
  registered tool via FastMCP.list_tools(), introspects each
  FunctionTool's signature, and asserts `socket_name in
  sig.parameters` with `list_servers` as the documented exception.
  Catches future tool drift before it silently makes the agent-facing
  instructions a lie again.

Author: tony

CHANGES

@@ -6,6 +6,22 @@
 _Notes on upcoming releases will be added here_
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+### Tests
+
+- New ``test_registered_tools_accept_socket_name`` introspection test
+  in ``tests/test_server.py`` enumerates every registered tool via
+  ``FastMCP.list_tools()`` and asserts each accepts a ``socket_name``
+  parameter, with ``list_servers`` as the documented exception (it
+  takes ``extra_socket_paths`` instead). Catches future tool drift
+  before it silently makes ``_BASE_INSTRUCTIONS`` lie to agents. The
+  ``_BASE_INSTRUCTIONS`` text itself is tightened from "All tools
+  accept an optional socket_name parameter" to "Targeted tmux tools
+  accept an optional socket_name parameter (defaults to LIBTMUX_SOCKET
+  env var); list_servers discovers sockets via TMUX_TMPDIR plus
+  optional extra_socket_paths instead." A companion content test
+  (``test_base_instructions_document_socket_name_contract``) locks the
+  wording.
+
 ### Scripts
 
 - ``scripts/mcp_swap.py``: ``_claude_project_node`` validates that

src/libtmux_mcp/server.py

@@ -48,8 +48,9 @@
     "Use pane_id (e.g. '%1') as the preferred targeting method - "
     "it is globally unique within a tmux server. "
     "Use send_keys to execute commands and capture_pane to read output. "
-    "All tools accept an optional socket_name parameter for multi-server "
-    "support (defaults to LIBTMUX_SOCKET env var).\n\n"
+    "Targeted tmux tools accept an optional socket_name parameter "
+    "(defaults to LIBTMUX_SOCKET env var); list_servers discovers "
+    "sockets via TMUX_TMPDIR plus optional extra_socket_paths instead.\n\n"
     "IMPORTANT — metadata vs content: list_windows, list_panes, and "
     "list_sessions only search metadata (names, IDs, current command). "
     "To find text that is actually visible in terminals — when users ask "

tests/test_server.py

@@ -173,6 +173,63 @@ def test_base_instructions_document_hook_boundary() -> None:
     assert "tmux config file" in _BASE_INSTRUCTIONS
 
 
+def test_base_instructions_document_socket_name_contract() -> None:
+    """_BASE_INSTRUCTIONS frames the socket_name promise precisely.
+
+    list_servers does NOT accept socket_name (it's the discovery tool —
+    see server_tools.py:263-264 where the signature is
+    ``list_servers(extra_socket_paths=...)``), so the previous "All
+    tools accept socket_name" wording was a lie. The instruction now
+    qualifies "Targeted tmux tools" and explicitly names list_servers
+    as the documented exception, matching what
+    test_registered_tools_accept_socket_name asserts at the schema
+    level.
+    """
+    assert "Targeted tmux tools accept" in _BASE_INSTRUCTIONS
+    assert "list_servers" in _BASE_INSTRUCTIONS
+    assert "extra_socket_paths" in _BASE_INSTRUCTIONS
+
+
+def test_registered_tools_accept_socket_name() -> None:
+    """All registered tools (except list_servers) accept ``socket_name``.
+
+    ``_BASE_INSTRUCTIONS`` promises this with ``list_servers`` as the
+    documented exception (it discovers sockets via
+    ``extra_socket_paths`` instead, see ``server_tools.py:263-264``).
+    If a future tool registration drops ``socket_name``, this test
+    catches the regression instead of silently making the agent-facing
+    instructions a lie.
+    """
+    import asyncio
+    import inspect
+
+    from fastmcp import FastMCP
+    from fastmcp.tools.function_tool import FunctionTool
+
+    from libtmux_mcp.tools import register_tools
+
+    socket_name_exempt = {"list_servers"}
+
+    mcp = FastMCP(name="socket-name-contract")
+    register_tools(mcp)
+
+    tools = asyncio.run(mcp.list_tools())
+    assert tools, "register_tools should have registered at least one tool"
+    for tool in tools:
+        if tool.name in socket_name_exempt:
+            continue
+        assert isinstance(tool, FunctionTool), (
+            f"Tool {tool.name!r} is not a FunctionTool; the registry "
+            f"introspection assumes FastMCP wraps each registered "
+            f"function with FunctionTool"
+        )
+        sig = inspect.signature(tool.fn)
+        assert "socket_name" in sig.parameters, (
+            f"Tool {tool.name!r} omits socket_name; either add it, "
+            f"add to socket_name_exempt, or update _BASE_INSTRUCTIONS"
+        )
+
+
 def test_base_instructions_document_buffer_lifecycle() -> None:
     """_BASE_INSTRUCTIONS explains the buffer lifecycle + no list_buffers.