mcp(fix[resources]): lead format-strings reference with subset disclaimer

The ``tmux://reference/format-strings`` resource lists ~25 of tmux's
~200 format variables. Without a clear "this is a subset" signal at
the top, an agent that reads the body and doesn't find e.g.
``#{history_size}`` (one of the 175 omitted strings) may erroneously
conclude that string is unsupported and skip a ``display_message``
call that would have worked. The closing ``man tmux`` line existed
but came after the substantive content — too easy to miss in a
top-down skim.

Adds a leading note declaring the resource a curated cheat sheet,
not the complete catalog, and points readers at ``man tmux`` for
anything not listed. Also softens the ``get_format_string_reference``
docstring's "avoids hallucinated format names" claim — the resource
is now honest about being a subset, so the docstring framing
matches.

Test: ``test_format_string_reference_leads_with_subset_disclaimer``
asserts both that the disclaimer keywords are present AND that the
disclaimer precedes the first format-variable example, so a future
edit can't quietly move the disclaimer to the bottom (recreating the
original problem).

Author: tony

src/libtmux_mcp/resources/reference.py

@@ -27,6 +27,12 @@
 _FORMAT_STRING_REFERENCE = textwrap.dedent("""\
     # tmux format strings
 
+    > **Note:** This is a curated cheat sheet, not the complete catalog.
+    > tmux supports ~200 format variables; this lists the ones agents
+    > most commonly need. Omission here does NOT mean a string is
+    > unsupported — fall back to ``man tmux`` (FORMATS section) for
+    > anything not listed.
+
     Pass via ``display_message(format_string="#{...}")`` or any other
     tool that accepts a tmux format expression.
 
@@ -90,12 +96,15 @@ def register(mcp: FastMCP) -> None:
         mime_type=_MARKDOWN_MIME,
     )
     def get_format_string_reference() -> str:
-        """Return the tmux format-string cheat sheet as Markdown.
-
-        Static reference content. Use this when an agent encounters
-        an unfamiliar ``#{...}`` field — pulling the resource is
-        cheaper than a ``display_message`` round-trip and avoids
-        hallucinated format names.
+        """Return a curated subset of the tmux format-string catalog as Markdown.
+
+        Covers the format variables agents most commonly encounter; for
+        less-common ones, the body itself directs the agent at
+        ``man tmux`` (FORMATS section). The resource is intentionally
+        a subset rather than a mirror — it stays small enough to be
+        cheap to pull, and the disclaimer at the top prevents the
+        false-negative trap where an agent assumes an omitted string
+        is unsupported.
         """
         return _FORMAT_STRING_REFERENCE
 

tests/test_resources.py

@@ -237,6 +237,43 @@ def test_format_string_reference_returns_markdown(
     assert "#{?cond,then,else}" in body
 
 
+def test_format_string_reference_leads_with_subset_disclaimer(
+    reference_resource_functions: dict[str, t.Any],
+) -> None:
+    """The body declares itself a curated subset BEFORE the substantive content.
+
+    Without a leading disclaimer, an agent that reads the resource and
+    doesn't find a format string it knows is valid (e.g.
+    ``#{history_size}``, one of the ~175 omitted strings) may
+    erroneously conclude the string is unsupported and skip a
+    ``display_message`` call that would have worked. The disclaimer
+    must precede the catalog content so an agent skim-reading the top
+    of the body cannot miss it.
+    """
+    fn = reference_resource_functions["tmux://reference/format-strings"]
+    body = fn()
+
+    # Disclaimer keywords must appear in the body...
+    assert "curated" in body.lower(), (
+        "format-string reference must declare itself a curated subset"
+    )
+    assert "man tmux" in body, (
+        "format-string reference must point readers at man tmux for the "
+        "complete catalog"
+    )
+
+    # ...AND must appear *before* the first format-variable example.
+    # Otherwise a top-down skim hits the catalog before the caveat.
+    first_example = body.find("#{pane_id}")
+    disclaimer = body.lower().find("curated")
+    assert disclaimer != -1, "disclaimer absent"
+    assert disclaimer < first_example, (
+        f"disclaimer at offset {disclaimer} comes after first format-variable "
+        f"example at offset {first_example}; readers will see the catalog "
+        f"before the 'this is a subset' caveat"
+    )
+
+
 def test_format_string_reference_advertises_markdown_mime() -> None:
     """tmux://reference/format-strings is registered with text/markdown.