Mcp(feat[filter]): Say what a filter may name

why: A real agent asked for the pane in the window named 'build', guessed
a plain field map for the filter, and was told only "'schema' is missing
or not a string" — which says what broke and not what to send. It spent a
call finding out. The pane model has four fields and none of them is a
window's name, and nothing said so.

what:
- List the pane model's fields in tmux_list_panes's own description, and
  say where to look for anything else
- Answer an unreadable filter with the shape to copy and the fields it
  may name, rather than the parser's own words
- Add FilterModel.fieldNames and relationNames, since what a model may
  name was knowable only from inside the class

Author: tony

CHANGELOG.md

@@ -12,6 +12,15 @@ exact version rather than a range.
 
 ## Unreleased
 
+### Added
+
+- **`FilterModel.fieldNames` and `relationNames` say what a document may name.**
+  The useful thing to tell a caller whose field was not recognised is which ones
+  exist, and nothing outside the class could find that out. `libtmux-mcp` now puts
+  the pane model's fields in `tmux_list_panes`'s own description and repeats them
+  when a filter will not read — measured against a real agent, which guessed a
+  plain field map and spent a call discovering the shape.
+
 ## 0.0.1-alpha.5 — 2026-08-16
 
 ### Added

libtmux-jackson/src/main/java/io/github/libtmux/jackson/FilterModel.java

@@ -4,9 +4,11 @@
 import io.github.libtmux.query.Fields;
 import java.util.Collections;
 import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
 import java.util.List;
 import java.util.Map;
 import java.util.Optional;
+import java.util.Set;
 import java.util.function.Function;
 import org.jspecify.annotations.Nullable;
 
@@ -44,6 +46,24 @@ public String id() {
         return id;
     }
 
+    /**
+     * Every field a document may compare on, in the order the model declared them.
+     *
+     * <p>Public because the useful thing to say about a field nobody recognises is which ones exist.
+     * A caller writing a document by hand — or a model being told why its last one was refused —
+     * cannot otherwise find out without reading this file.
+     */
+    public Set<String> fieldNames() {
+        return fields.keySet();
+    }
+
+    /** Every relation a document may navigate, in the order the model declared them. */
+    public Set<String> relationNames() {
+        Set<String> names = new LinkedHashSet<>(toOne.keySet());
+        names.addAll(toMany.keySet());
+        return Collections.unmodifiableSet(names);
+    }
+
     FieldRef<T, ?> field(String fieldId) {
         FieldRef<T, ?> field = fields.get(fieldId);
         if (field == null) {

libtmux-mcp/src/main/java/io/github/libtmux/mcp/Catalog.java

@@ -9,6 +9,7 @@
 import static io.github.libtmux.mcp.Argument.strings;
 
 import io.github.libtmux.jackson.FilterJson;
+import io.github.libtmux.jackson.LibTmuxModels;
 import java.util.ArrayList;
 import java.util.LinkedHashMap;
 import java.util.List;
@@ -96,7 +97,12 @@ private static void discovery(List<ToolSpec> tools) {
                         "filter",
                         "object",
                         "A " + FilterJson.SCHEMA + " document over the pane model, for example " + EXAMPLE_FILTER
-                                + ". Field names are tmux's own format names. Omit it to list every pane.",
+                                + ". Field names are tmux's own format names, and these are the only ones a pane "
+                                + "document may compare: "
+                                + String.join(", ", LibTmuxModels.pane().fieldNames())
+                                + ". Anything else — a window's name, a pane's path — is in the answer rather "
+                                + "than the filter, so list the panes and choose from what comes back. Omit it "
+                                + "to list every pane.",
                         false,
                         null)),
                 Listings::panes));

libtmux-mcp/src/main/java/io/github/libtmux/mcp/Listings.java

@@ -129,8 +129,7 @@ static Panes panes(Call call) {
         String note = null;
         Object filter = call.arguments().get("filter");
         if (filter != null) {
-            FilterExpr<Pane> expression = FilterJson.read(JSON.valueToTree(filter), LibTmuxModels.pane());
-            List<Pane> narrowed = panes.stream().filter(expression).toList();
+            List<Pane> narrowed = panes.stream().filter(paneFilter(filter)).toList();
             note = narrowed.isEmpty() && !panes.isEmpty()
                     ? "The filter matched none of the " + panes.size() + " panes on this server. "
                             + "Call again without 'filter' to see them all."
@@ -140,6 +139,26 @@ static Panes panes(Call call) {
         return new Panes(panes.size(), describe(panes, caller), note);
     }
 
+    /**
+     * Reads a filter document, and says what one looks like when it will not read.
+     *
+     * <p>What the parser knows is that a key was missing or a field unrecognised. What a caller
+     * needs is the shape to send and the names it may use — neither of which the parser has any
+     * business knowing, and both of which are free here.
+     */
+    private static FilterExpr<Pane> paneFilter(Object filter) {
+        try {
+            return FilterJson.read(JSON.valueToTree(filter), LibTmuxModels.pane());
+        } catch (RuntimeException e) {
+            throw new IllegalArgumentException("that filter is not a " + FilterJson.SCHEMA + " document: "
+                    + e.getMessage() + ". One looks like " + Catalog.EXAMPLE_FILTER
+                    + " and may compare these fields only: "
+                    + String.join(", ", LibTmuxModels.pane().fieldNames())
+                    + ". To narrow by anything else — a window's name, a pane's path — list the panes "
+                    + "and choose from what comes back.");
+        }
+    }
+
     static List<PaneSummary> describe(List<Pane> panes, Caller caller) {
         return panes.stream()
                 .map(pane -> {

libtmux-mcp/src/test/java/io/github/libtmux/mcp/ToolsAgainstTmuxTest.java

@@ -53,6 +53,42 @@ void aFilterMatchingNothingSaysHowManyThereWere(Server server) {
         assertTrue(String.valueOf(panes.note()).contains("without 'filter'"), String.valueOf(panes.note()));
     }
 
+    /**
+     * A model that guesses the filter's shape gets told the shape, not only that its guess was
+     * wrong. Measured against a real agent, which guessed a plain field map first and had to spend a
+     * call finding out.
+     */
+    @Test
+    void aFilterThatWillNotReadSaysWhatOneLooksLike(Server server) {
+        IllegalArgumentException refused = assertThrows(
+                IllegalArgumentException.class,
+                () -> Listings.panes(TestCalls.on(server, "filter", java.util.Map.of("window_name", "build"))));
+
+        String message = String.valueOf(refused.getMessage());
+        assertTrue(message.contains("libtmux.filter/1"), message);
+        assertTrue(message.contains("\"node\":\"compare\""), "the shape to copy has to be in it: " + message);
+        assertTrue(message.contains("pane_current_command"), "and the fields it may name: " + message);
+    }
+
+    /** A field the pane model does not have is named alongside the ones it does. */
+    @Test
+    void aFieldThePaneModelLacksSaysWhichItHas(Server server) {
+        Object document = java.util.Map.of(
+                "schema",
+                "libtmux.filter/1",
+                "model",
+                "pane",
+                "expr",
+                java.util.Map.of("node", "compare", "field", "window_name", "op", "equals", "value", "build"));
+
+        IllegalArgumentException refused = assertThrows(
+                IllegalArgumentException.class, () -> Listings.panes(TestCalls.on(server, "filter", document)));
+
+        String message = String.valueOf(refused.getMessage());
+        assertTrue(message.contains("pane_active"), message);
+        assertTrue(message.contains("list the panes"), "and where to look instead: " + message);
+    }
+
     @Test
     void whoamiSaysWhichServerAndThatNoPaneIsSpecial(Server server) {
         Listings.Whoami whoami = Listings.whoami(server, Caller.nowhere(), Safety.MUTATING);