@bli-cockpit/mcp 0.1.58 → 0.1.61

package/dist/docs-msg-tools.js

@@ -11,7 +11,25 @@
  */
 import { z } from "zod";
 import { callAgentDoor } from "./agent-door.js";
-import { doorFailureText, errorResult, registrarFor, textResult, withSession, } from "./tool-result.js";
+import { DEFAULT_LIST_LIMIT, doorFailureText, errorResult, moreNote, registrarFor, textResult, withSession, } from "./tool-result.js";
+/** A canonical uuid: a ref that already IS an id needs no list read to resolve. */
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
+/** The door's own ceiling on `?limit=` (`/api/docs/documents` `DOCUMENT_LIST_MAX_LIMIT`). */
+const DOCS_LIST_MAX = 1000;
+/**
+ * The tree as the text half prints it: id, title, slug, children. The door
+ * also sends visibility, source and a timestamp per node, which nothing here
+ * promised and which made the structured half 48 KB for 226 documents
+ * (BLI-10432). `docs_list` carries those fields for a flat read.
+ */
+function slimTree(nodes) {
+    return nodes.map((node) => ({
+        id: node.id,
+        title: node.title,
+        slug: node.slug ?? null,
+        children: slimTree(Array.isArray(node.children) ? node.children : []),
+    }));
+}
 /** Indented lines, deepest last — the same shape `cockpit docs tree` prints. */
 function renderDocTree(nodes, depth) {
     return nodes
@@ -25,6 +43,27 @@ function renderDocTree(nodes, depth) {
 function countTree(nodes) {
     return nodes.reduce((count, node) => count + 1 + countTree(node.children ?? []), 0);
 }
+/**
+ * The fields `docs_list` promises, and only those. The door's row also carries
+ * `created_by`, `updated_by`, `created_at`, `import_truncated` and
+ * `missing_block_count`: 105 KB for 226 documents before this (BLI-10432).
+ */
+function docListRow(row) {
+    return {
+        id: row.id,
+        slug: row.slug ?? null,
+        title: row.title,
+        visibility: row.visibility,
+        source: row.source ?? null,
+        parent_id: row.parent_id ?? null,
+        updated_at: row.updated_at,
+        body_chars: row.body_chars ?? null,
+    };
+}
+function docListLine(row) {
+    return `${row.id}  ${row.slug ?? "-"}  ${row.title}  [${row.visibility}${row.source ? `, ${row.source}` : ""}, `
+        + `${row.body_chars ?? "?"} chars, parent ${row.parent_id ?? "root"}, updated ${row.updated_at}]`;
+}
 /**
  * `docs_list`'s narrowing, as the door's own query parameters (BLI-3737).
  * The list itself is metadata only — asking for a whole library used to cost
@@ -39,10 +78,18 @@ export function docsListPath(args) {
         params.set("query", args.query);
     if (typeof args.limit === "number" && Number.isInteger(args.limit))
         params.set("limit", String(args.limit));
+    // No limit named: one page plus one row, so "more exist" is read off the
+    // door instead of guessed from a full page (BLI-10432).
+    else if (args.limit === undefined)
+        params.set("limit", String(DEFAULT_LIST_LIMIT + 1));
     const search = params.toString();
     return search.length > 0 ? `/api/docs/documents?${search}` : "/api/docs/documents";
 }
 async function resolveDocumentId(deps, session, ref) {
+    // An id needs no lookup: the read itself answers 404 by name when it is
+    // wrong. Only a slug costs the whole-library list read (BLI-10432).
+    if (UUID_PATTERN.test(ref))
+        return { status: "ok", id: ref };
     const response = await callAgentDoor(session, deps.fetchImpl, "GET", "/api/docs/documents");
     if (!response.ok)
         return { status: "list_failed", text: doorFailureText("docs_list", response) };
@@ -59,24 +106,33 @@ async function resolveChannelId(deps, session, ref) {
     const match = channels.find((channel) => channel.id === ref || channel.name === bare);
     return match ? { status: "ok", id: match.id } : { status: "not_found" };
 }
+/** One message as a line: id (msg_thread's `thread_parent_id`), time, author, text. */
+function messageLine(message) {
+    return `${String(message.id ?? "?")}  ${String(message.created_at ?? "?")}  `
+        + `${String(message.agent_label ?? message.user_id ?? "?")}  ${String(message.content ?? "")}`;
+}
 export function registerDocsMsgTools(server, deps) {
     const register = registrarFor(server);
     register("docs_list", {
         title: "List Tower documents",
         description: "Every document you may read: id, slug, title, visibility, source, parent_id and body_chars (how long the body is). "
             + "Never a document's body — call docs_read for that. Narrow before reading: parent_id (a document id, or \"root\" for the "
-            + "top of the tree), query (a case-insensitive substring matched in the database over title AND body, never fuzzy), limit (1-1000).",
+            + "top of the tree), query (a case-insensitive substring matched in the database over title AND body, never fuzzy), "
+            + `limit (1-1000, default ${DEFAULT_LIST_LIMIT}; the answer says when more exist).`,
         inputSchema: {
             parent_id: z.string().min(1).max(64).optional().describe('A document id to list under, or "root" for the top of the tree.'),
             query: z.string().min(1).max(200).optional().describe("Keep only documents whose title or body contains this text."),
-            limit: z.number().int().min(1).max(1000).optional().describe("At most this many documents."),
+            limit: z.number().int().min(1).max(1000).optional().describe(`At most this many documents. Default ${DEFAULT_LIST_LIMIT}.`),
         },
     }, async (args) => withSession(deps, async (session) => {
         const response = await callAgentDoor(session, deps.fetchImpl, "GET", docsListPath(args));
         if (!response.ok)
             return errorResult(doorFailureText("docs_list", response));
-        const documents = response.body.documents ?? [];
-        return textResult(`${documents.length} document(s).`, { documents });
+        const all = (Array.isArray(response.body.documents) ? response.body.documents : []);
+        const more = args.limit === undefined && all.length > DEFAULT_LIST_LIMIT;
+        const rows = more ? all.slice(0, DEFAULT_LIST_LIMIT) : all;
+        const lines = rows.map(docListLine).join("\n");
+        return textResult(`${rows.length} document(s).${moreNote(more, DOCS_LIST_MAX)}${lines ? `\n${lines}` : ""}`, { documents: rows.map(docListRow), more });
     }));
     register("docs_tree", {
         title: "Read the Tower document tree",
@@ -87,9 +143,9 @@ export function registerDocsMsgTools(server, deps) {
         const response = await callAgentDoor(session, deps.fetchImpl, "GET", "/api/docs/tree");
         if (!response.ok)
             return errorResult(doorFailureText("docs_tree", response));
-        const tree = (Array.isArray(response.body.tree) ? response.body.tree : []);
+        const tree = slimTree((Array.isArray(response.body.tree) ? response.body.tree : []));
         const rendered = renderDocTree(tree, 0);
-        return textResult(`${countTree(tree)} document(s).${rendered ? `\n${rendered}` : ""}`, { tree });
+        return textResult(`${countTree(tree)} document(s), each as "title (slug or id)"; docs_read takes either.${rendered ? `\n${rendered}` : ""}`, { tree });
     }));
     register("docs_read", {
         title: "Read a Tower document",
@@ -112,10 +168,10 @@ export function registerDocsMsgTools(server, deps) {
         title: "Create a Tower document",
         description: "Creates a new document. Omitting body creates an empty one, matching the browser's own default.",
         inputSchema: {
-            title: z.string().min(1).max(200),
-            body_markdown: z.string().max(200_000).optional(),
-            parent_id: z.string().uuid().optional(),
-            visibility: z.enum(["org", "private"]).optional(),
+            title: z.string().min(1).max(200).describe("The document's title."),
+            body_markdown: z.string().max(200_000).optional().describe("The body, markdown. Omit for an empty document."),
+            parent_id: z.string().uuid().optional().describe("A document id to nest this one under. Omit for the top of the tree."),
+            visibility: z.enum(["org", "private"]).optional().describe("org: everyone signed in may read it. private: only you."),
         },
     }, async (args) => withSession(deps, async (session) => {
         const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/docs/documents", {
@@ -135,10 +191,10 @@ export function registerDocsMsgTools(server, deps) {
             + "pass change. Emptying a document that holds text needs allow_empty: true.",
         inputSchema: {
             id: z.string().min(1).max(200).describe("A document id, or its slug."),
-            title: z.string().min(1).max(200).optional(),
-            body_markdown: z.string().max(200_000).optional(),
-            visibility: z.enum(["org", "private"]).optional(),
-            parent_id: z.string().uuid().nullable().optional(),
+            title: z.string().min(1).max(200).optional().describe("A new title."),
+            body_markdown: z.string().max(200_000).optional().describe("The WHOLE new body, markdown. It replaces the old one; it is not appended."),
+            visibility: z.enum(["org", "private"]).optional().describe("org: everyone signed in may read it. private: only you."),
+            parent_id: z.string().uuid().nullable().optional().describe("Move it under this document id; null moves it to the top of the tree."),
             allow_empty: z
                 .boolean()
                 .optional()
@@ -169,21 +225,40 @@ export function registerDocsMsgTools(server, deps) {
     }));
     register("msg_channels", {
         title: "List Tower channels",
-        description: "Every channel you are a member of.",
+        description: "Every channel you are a member of: id, name (a direct message has none and lists its participants instead), "
+            + "private, and description. msg_read takes the id or the name.",
         inputSchema: {},
     }, async () => withSession(deps, async (session) => {
         const response = await callAgentDoor(session, deps.fetchImpl, "GET", "/api/msg/channels");
         if (!response.ok)
             return errorResult(doorFailureText("msg_channels", response));
-        const channels = response.body.channels ?? [];
-        return textResult(`${channels.length} channel(s).`, { channels });
+        const channels = (Array.isArray(response.body.channels) ? response.body.channels : []);
+        const rows = channels.map((channel) => ({
+            id: channel.id,
+            name: channel.name ?? null,
+            description: channel.description ?? null,
+            is_private: channel.is_private === true,
+            is_dm: channel.is_dm === true,
+            ...(channel.is_dm === true ? { dm_participants: channel.dm_participants ?? [] } : {}),
+            archived_at: channel.archived_at ?? null,
+        }));
+        const lines = rows
+            .map((row) => {
+            const label = row.is_dm
+                ? `DM with ${JSON.stringify(row.dm_participants ?? [])}`
+                : `#${String(row.name ?? "?")}${row.is_private ? " (private)" : ""}`;
+            return `${String(row.id)}  ${label}${row.archived_at ? " [archived]" : ""}`
+                + `${row.description ? `  ${String(row.description)}` : ""}`;
+        })
+            .join("\n");
+        return textResult(`${rows.length} channel(s).${lines ? `\n${lines}` : ""}`, { channels: rows });
     }));
     register("msg_read", {
         title: "Read a Tower channel",
         description: "Recent messages of one channel, newest first. `channel` is a channel id, or its name with or without a leading #.",
         inputSchema: {
-            channel: z.string().min(1).max(200),
-            limit: z.number().int().min(1).max(200).optional(),
+            channel: z.string().min(1).max(200).describe("A channel id, or its name with or without a leading #."),
+            limit: z.number().int().min(1).max(200).optional().describe("At most this many messages, newest first."),
         },
     }, async (args) => withSession(deps, async (session) => {
         const ref = String(args.channel ?? "");
@@ -196,15 +271,19 @@ export function registerDocsMsgTools(server, deps) {
         const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/msg/channels/${encodeURIComponent(resolved.id)}/messages${query}`);
         if (!response.ok)
             return errorResult(doorFailureText("msg_read", response));
-        const messages = response.body.messages ?? [];
-        return textResult(`${messages.length} message(s) in ${ref}.`, { channelId: resolved.id, messages });
+        const messages = (Array.isArray(response.body.messages) ? response.body.messages : []);
+        // The text half carries the messages themselves, each with its id,
+        // which is what msg_thread takes. It used to say only "2 message(s)",
+        // so a Claude-family client never saw one (BLI-10432).
+        const lines = messages.map(messageLine).join("\n");
+        return textResult(`${messages.length} message(s) in ${ref}, newest first; each line is id, time, author, text.${lines ? `\n${lines}` : ""}`, { channelId: resolved.id, messages });
     }));
     register("msg_thread", {
         title: "Read a Tower message thread",
         description: "The replies under one message, oldest first. `thread_parent_id` is the id of the message the thread hangs "
             + "off — msg_read returns it. `channel` is a channel id, or its name with or without a leading #.",
         inputSchema: {
-            channel: z.string().min(1).max(200),
+            channel: z.string().min(1).max(200).describe("A channel id, or its name with or without a leading #."),
             thread_parent_id: z.string().uuid().describe("The id of the message the replies hang off."),
         },
     }, async (args) => withSession(deps, async (session) => {
@@ -221,11 +300,7 @@ export function registerDocsMsgTools(server, deps) {
         const messages = (Array.isArray(response.body.messages) ? response.body.messages : []);
         // Oldest first: a thread reads as a conversation, unlike the channel
         // list, which the door returns newest-first.
-        const lines = [...messages]
-            .reverse()
-            .map((message) => `${String(message.created_at ?? "?")}  ${String(message.agent_label ?? message.user_id ?? "?")}  `
-            + `${String(message.content ?? "")}`)
-            .join("\n");
+        const lines = [...messages].reverse().map(messageLine).join("\n");
         return textResult(`${messages.length} repl${messages.length === 1 ? "y" : "ies"} in ${ref}.${lines ? `\n${lines}` : ""}`, { channelId: resolved.id, threadParentId: parent, messages });
     }));
     register("msg_create_channel", {
@@ -233,9 +308,9 @@ export function registerDocsMsgTools(server, deps) {
         description: "Creates a channel and returns its id. `private` means membership decides who may read it. `member_emails` names who joins at birth BY EMAIL — an address Tower does not carry refuses the whole create, so no half-built channel is left behind.",
         inputSchema: {
             name: z.string().min(1).max(80).describe("The channel name. A leading # is accepted and dropped."),
-            description: z.string().max(500).optional(),
-            private: z.boolean().optional(),
-            member_emails: z.array(z.string().min(3).max(320)).max(200).optional(),
+            description: z.string().max(500).optional().describe("One line saying what the channel is for."),
+            private: z.boolean().optional().describe("true: only members may read it. Default false."),
+            member_emails: z.array(z.string().min(3).max(320)).max(200).optional().describe("Email addresses of the people who join at birth. You join either way."),
         },
     }, async (args) => withSession(deps, async (session) => {
         const raw = String(args.name ?? "");
@@ -281,9 +356,9 @@ export function registerDocsMsgTools(server, deps) {
         title: "Send a Tower message",
         description: "Posts a message to one channel. `channel` is a channel id, or its name with or without a leading #.",
         inputSchema: {
-            channel: z.string().min(1).max(200),
-            content: z.string().min(1).max(8_000),
-            thread_parent_id: z.string().uuid().optional(),
+            channel: z.string().min(1).max(200).describe("A channel id, or its name with or without a leading #."),
+            content: z.string().min(1).max(8_000).describe("The message text."),
+            thread_parent_id: z.string().uuid().optional().describe("Reply in the thread under this message id (msg_read prints ids)."),
         },
     }, async (args) => withSession(deps, async (session) => {
         const ref = String(args.channel ?? "");

package/dist/mail-tools.js

@@ -26,12 +26,12 @@
  */
 import { z } from "zod";
 import { callAgentDoor } from "./agent-door.js";
-import { CONFIRM_INPUT, doorFailureText, errorResult, queryString, registrarFor, textResult, unconfirmed, withSession, } from "./tool-result.js";
+import { CONFIRM_INPUT, EMAIL_INPUT, doorFailureText, errorResult, queryString, registrarFor, textResult, unconfirmed, withSession, } from "./tool-result.js";
 function messageLine(message) {
     const from = message.from_address?.address ?? "(no sender)";
     return `${message.is_unread ? "*" : " "} ${message.internal_date.slice(0, 16)}  ${from}  ${message.subject ?? "(no subject)"}  [thread ${message.thread_id ?? "?"}]`;
 }
-const ADDRESS = z.string().email().max(320);
+const ADDRESS = EMAIL_INPUT.describe("An email address.");
 export function registerMailTools(server, deps) {
     const register = registrarFor(server);
     register("mail_accounts", {
@@ -56,11 +56,11 @@ export function registerMailTools(server, deps) {
         description: "Messages across every mailbox you may read, newest first. Never a body — call mail_read on a thread for that. "
             + "`account_id` narrows to one mailbox; `unread` and `label` filter; `before` (an ISO instant) pages backwards.",
         inputSchema: {
-            account_id: z.string().uuid().optional(),
-            unread: z.boolean().optional(),
-            label: z.string().min(1).max(100).optional(),
-            before: z.string().min(1).max(40).optional(),
-            limit: z.number().int().min(1).max(200).optional(),
+            account_id: z.string().uuid().optional().describe("One mailbox id (mail_accounts). Omit for every mailbox you may read."),
+            unread: z.boolean().optional().describe("true: unread messages only."),
+            label: z.string().min(1).max(100).optional().describe("Only messages carrying this provider label, e.g. INBOX or IMPORTANT."),
+            before: z.string().min(1).max(40).optional().describe("An ISO instant: messages received before it, for the next page back."),
+            limit: z.number().int().min(1).max(200).optional().describe("At most this many messages, newest first."),
         },
     }, async (args) => withSession(deps, async (session) => {
         const query = new URLSearchParams();
@@ -84,30 +84,51 @@ export function registerMailTools(server, deps) {
     }));
     register("mail_read", {
         title: "Read one conversation",
-        description: "One thread with every message's text body, oldest first. Thread ids come from mail_inbox or mail_search. "
-            + "Read the thread before saying what somebody wrote — a snippet is the first 240 characters and nothing more.",
-        inputSchema: { thread_id: z.string().uuid() },
+        description: "One thread with every message's text body, oldest first, and each message's attachments by id (the id "
+            + "mail_attachment takes). Thread ids come from mail_inbox or mail_search. Read the thread before saying what "
+            + "somebody wrote — a snippet is the first 240 characters and nothing more.",
+        inputSchema: { thread_id: z.string().uuid().describe("A thread id, as mail_inbox or mail_search print it.") },
     }, async (args) => withSession(deps, async (session) => {
         const threadId = String(args.thread_id ?? "");
-        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/mail/threads/${encodeURIComponent(threadId)}`);
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", 
+        // `?attachments=1` adds each message's attachment pointers. Without
+        // it no tool here ever showed an attachment id, so mail_attachment
+        // could not be reached from an agent at all (BLI-10432).
+        `/api/mail/threads/${encodeURIComponent(threadId)}?attachments=1`);
         if (!response.ok)
             return errorResult(doorFailureText("mail_read", response));
         const thread = response.body.thread;
         const messages = (Array.isArray(response.body.messages) ? response.body.messages : []);
+        const attachments = (response.body.attachments && typeof response.body.attachments === "object"
+            ? response.body.attachments
+            : {});
         const rendered = messages
-            .map((message) => `--- ${message.internal_date} ${message.from_address?.address ?? "(no sender)"} [${message.id}]\n`
-            + (message.body_text ?? message.snippet ?? "(no text body — this message is HTML only)").trim())
+            .map((message) => {
+            const files = (attachments[message.id] ?? [])
+                .map((file) => `\n  attachment ${file.id}  ${file.filename ?? "(unnamed)"}  ${file.mime_type ?? "?"}  ${file.size_bytes ?? "?"} bytes${file.is_inline ? "  (inline)" : ""}`)
+                .join("");
+            return `--- ${message.internal_date} ${message.from_address?.address ?? "(no sender)"} [${message.id}]\n`
+                + (message.body_text ?? message.snippet ?? "(no text body — this message is HTML only)").trim()
+                + files;
+        })
             .join("\n\n");
-        return textResult(`${thread?.subject ?? "(no subject)"} — ${thread?.account_address ?? "?"}, ${messages.length} message(s)\n\n${rendered}`, { thread, messages });
+        // The HTML body is the text body again with markup, and nothing on
+        // this surface renders it; its length stays so an HTML-only message
+        // still says it has one.
+        const slim = messages.map(({ body_html: html, ...rest }) => ({
+            ...rest,
+            body_html_chars: typeof html === "string" ? html.length : 0,
+        }));
+        return textResult(`${thread?.subject ?? "(no subject)"} — ${thread?.account_address ?? "?"}, ${messages.length} message(s)\n\n${rendered}`, { thread, messages: slim, attachments });
     }));
     register("mail_search", {
         title: "Search your mail",
         description: "Full text over the subject and plain-text body of every message you may read. Quoted phrases and OR work the way "
             + "they do in a search box. Returns headers only; call mail_read on a hit's thread to read it.",
         inputSchema: {
-            query: z.string().min(1).max(400),
-            account_id: z.string().uuid().optional(),
-            limit: z.number().int().min(1).max(200).optional(),
+            query: z.string().min(1).max(400).describe("Words to find. Quoted phrases and OR work."),
+            account_id: z.string().uuid().optional().describe("One mailbox id (mail_accounts). Omit for every mailbox you may read."),
+            limit: z.number().int().min(1).max(200).optional().describe("At most this many matches, newest first."),
         },
     }, async (args) => withSession(deps, async (session) => {
         const query = new URLSearchParams({ q: String(args.query ?? "") });
@@ -129,12 +150,12 @@ export function registerMailTools(server, deps) {
             + "that is never something to guess. `in_reply_to_message_id` (a message id from mail_read) threads the reply. "
             + "This actually sends mail to real people: confirm must be true.",
         inputSchema: {
-            account_id: z.string().uuid(),
-            to: z.array(ADDRESS).min(1).max(50),
-            cc: z.array(ADDRESS).max(50).optional(),
-            subject: z.string().max(998),
-            text: z.string().min(1).max(500_000),
-            in_reply_to_message_id: z.string().uuid().optional(),
+            account_id: z.string().uuid().describe("The mailbox it goes out from (mail_accounts). Never guessed."),
+            to: z.array(ADDRESS).min(1).max(50).describe("Recipient email addresses."),
+            cc: z.array(ADDRESS).max(50).optional().describe("Copied email addresses."),
+            subject: z.string().max(998).describe("The subject line."),
+            text: z.string().min(1).max(500_000).describe("The plain-text body."),
+            in_reply_to_message_id: z.string().uuid().optional().describe("A message id from mail_read: send this as a reply in that thread."),
             confirm: CONFIRM_INPUT,
         },
     }, async (args) => withSession(deps, async (session) => {
@@ -160,7 +181,7 @@ export function registerMailTools(server, deps) {
         title: "Describe an attachment",
         description: "The filename, mime type and size of one attachment. Attachments are POINTERS in Tower — nothing is stored — and "
             + "the bytes are not returned here: `cockpit mail attachment <id> --out <path>` downloads the file at a terminal.",
-        inputSchema: { attachment_id: z.string().uuid() },
+        inputSchema: { attachment_id: z.string().uuid().describe("An attachment id, as mail_read lists it.") },
     }, async (args) => withSession(deps, async (session) => {
         const id = String(args.attachment_id ?? "");
         const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/mail/attachments/${encodeURIComponent(id)}?meta=1`);
@@ -174,7 +195,7 @@ export function registerMailTools(server, deps) {
         title: "Read a mailbox now",
         description: "Runs one sync pass on one mailbox instead of waiting for the 15-minute cron, and answers with what landed or the "
             + "reason it did not (token_revoked, history_gap, auth_failed, quota…). Only the mailbox's OWNER may do this.",
-        inputSchema: { account_id: z.string().uuid() },
+        inputSchema: { account_id: z.string().uuid().describe("A mailbox id you own (mail_accounts).") },
     }, async (args) => withSession(deps, async (session) => {
         const id = String(args.account_id ?? "");
         const response = await callAgentDoor(session, deps.fetchImpl, "POST", `/api/mail/accounts/${encodeURIComponent(id)}/sync`);
@@ -190,7 +211,7 @@ export function registerMailTools(server, deps) {
         title: "Detach a mailbox",
         description: "Removes a mailbox from Tower along with its stored mail and its credential. The mail itself is untouched at the "
             + "provider — this unhooks Tower, it does not delete anybody's email. Irreversible here: confirm must be true.",
-        inputSchema: { account_id: z.string().uuid(), confirm: CONFIRM_INPUT },
+        inputSchema: { account_id: z.string().uuid().describe("A mailbox id you own (mail_accounts)."), confirm: CONFIRM_INPUT },
     }, async (args) => withSession(deps, async (session) => {
         const refusal = unconfirmed(args, "Detaching removes this mailbox's stored mail from Tower.");
         if (refusal)

package/dist/memory-consolidation-tools.js

@@ -16,6 +16,20 @@
 import { z } from "zod";
 import { callAgentDoor } from "./agent-door.js";
 import { doorFailureText, errorResult, queryString, registrarFor, textResult, withSession, } from "./tool-result.js";
+/** `{merge: 2, rewrite: 1}` as `merge 2, rewrite 1`; `none` when empty. */
+function counts(value) {
+    if (!value || typeof value !== "object")
+        return "none";
+    const entries = Object.entries(value);
+    return entries.length === 0 ? "none" : entries.map(([key, count]) => `${key} ${String(count)}`).join(", ");
+}
+function runLine(run) {
+    const cost = typeof run.costUsd === "number" ? `$${run.costUsd.toFixed(4)}` : "$?";
+    return `${String(run.startedAt ?? "?")}  ${String(run.containerTag ?? "?")}  ${String(run.mode ?? "?")}  `
+        + `clusters ${String(run.clusters ?? 0)}; proposed ${counts(run.proposed)}; applied ${counts(run.applied)}; `
+        + `refused ${counts(run.refused)}; ${cost}${run.model ? ` ${String(run.model)}` : ""}`
+        + `${run.reason ? `  (${String(run.reason)})` : ""}`;
+}
 export function registerMemoryConsolidationTools(server, deps) {
     registrarFor(server)("memory_consolidation", {
         title: "Read the nightly memory consolidation runs",
@@ -44,10 +58,14 @@ export function registerMemoryConsolidationTools(server, deps) {
         const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/memory/consolidation${queryString(params)}`);
         if (!response.ok)
             return errorResult(doorFailureText("memory_consolidation", response));
-        const runs = Array.isArray(response.body.runs) ? response.body.runs : [];
+        const runs = (Array.isArray(response.body.runs) ? response.body.runs : []);
         const reason = typeof response.body.reason === "string" ? response.body.reason : "runs_read";
+        // One line per run in the text half. It used to carry only the count,
+        // so a Claude-family client never saw a run (BLI-10432).
+        const lines = runs.map(runLine).join("\n");
         return textResult(runs.length === 0
             ? `No consolidation runs are visible (${reason}). The pass is a nightly cron and its receipts are readable by a super_admin; this is the access rule answering, not an outage.`
-            : `${runs.length} consolidation run${runs.length === 1 ? "" : "s"}. report = proposals only, nothing on the shelf changed; apply = accepted edits written as supersessions, which never delete anything.`, response.body);
+            : `${runs.length} consolidation run${runs.length === 1 ? "" : "s"}. report = proposals only, nothing on the shelf changed; apply = accepted edits written as supersessions, which never delete anything.`
+                + `\n${lines}`, response.body);
     }));
 }

package/dist/memory-experience-tools.js

@@ -7,7 +7,11 @@ export function registerMemoryExperienceTools(server, deps) {
     registrarFor(server)("memory_experience", {
         title: "Log a memory-store experience",
         description: "Append an experience receipt locally and post to Tower. Offline receipts ship on the next collector sync. Copy the recall marker: [bli] = BLI Memory, ◪ = Supermemory. Opinions only; never prompts, memory bodies or secrets.",
-        inputSchema: { store: z.enum(["bli", "supermemory", "both"]), verdict: z.enum(["win", "loss", "noise"]), reason: z.string().min(1).max(500) },
+        inputSchema: {
+            store: z.enum(["bli", "supermemory", "both"]).describe("Which store the recall came from: [bli] is BLI Memory, ◪ is Supermemory."),
+            verdict: z.enum(["win", "loss", "noise"]).describe("win: it shaped the answer. loss: it misled or was missing. noise: it came back and did not matter."),
+            reason: z.string().min(1).max(500).describe("Why, in one line. Never a prompt, a memory body or a secret."),
+        },
     }, async (args) => {
         const entry = await appendExperience({ store: args.store, verdict: args.verdict, reason: String(args.reason) }, { homeDir: deps.homeDir, agent: "MCP", project: "workspace" });
         const delivery = await shipExperience(entry, async (body) => {

package/dist/models-tools.js

@@ -28,7 +28,7 @@ export function registerModelsTools(server, deps) {
         description: "Every model Tower knows about: the provider's documented context window, price per million, reasoning "
             + "modes and tool support, beside our measured latency, observed tokens/s and last probe verdict. "
             + "`STALE:<field>` means a measurement contradicted the documentation, with the command that re-reads the "
-            + "provider. Read-only.",
+            + "provider. One line per model; models_card reads one model in full. Read-only.",
         inputSchema: {},
     }, async () => withSession(deps, async (session) => {
         const response = await callAgentDoor(session, deps.fetchImpl, "GET", "/api/models/cards");
@@ -39,10 +39,23 @@ export function registerModelsTools(server, deps) {
         const lines = (Array.isArray(body.lines) ? body.lines : []);
         const stale = cards.filter((card) => (card.stale?.length ?? 0) > 0).map((card) => card.id ?? "?");
         const unreadable = (Array.isArray(body.unreadable) ? body.unreadable : []);
+        // The structured half is the shelf's INDEX, the same facts the lines
+        // print. Whole cards (documented, measured and bench blocks) were 39 KB
+        // for 14 models on 2026-09-26, and models_card reads one in full
+        // (BLI-10432).
+        const index = cards.map((card) => ({
+            id: card.id ?? null,
+            display_name: card.display_name ?? null,
+            provider: card.provider ?? null,
+            model: card.model ?? null,
+            status: card.status ?? null,
+            slots: card.slots ?? null,
+            stale: (card.stale ?? []).map((entry) => entry.field ?? "?"),
+        }));
         return textResult(`${cards.length} model card(s)`
             + `${stale.length > 0 ? `, ${stale.length} stale: ${stale.join(", ")}` : ", none stale"}`
             + `${unreadable.length > 0 ? `, ${unreadable.length} unreadable: ${unreadable.join(", ")}` : ""}`
-            + `${lines.length > 0 ? `\n${lines.join("\n")}` : ""}`, { cards, stale, unreadable });
+            + `${lines.length > 0 ? `\n${lines.join("\n")}` : ""}`, { cards: index, lines, stale, unreadable });
     }));
     register("models_card", {
         title: "Read one model card",

package/dist/note-folder-tools.js

@@ -4,8 +4,11 @@ import { registrarFor, withSession, textResult, errorResult, doorFailureText } f
 export function registerNoteFolderTools(server, deps) {
     const register = registrarFor(server);
     register("notes_folders", {
-        title: "List note folders", description: "The folder tree with caller-visible note counts.",
-        inputSchema: { tree: z.boolean().optional() },
+        // `tree` was declared here and never read: the door answers one shape,
+        // flat folders with their paths, and a knob that changes nothing is a
+        // description that lies (BLI-10432).
+        title: "List note folders", description: "Every note folder you may see, as a flat list of paths with the note count in each, plus how many notes sit at the root.",
+        inputSchema: {},
     }, async () => withSession(deps, async (session) => {
         const response = await callAgentDoor(session, deps.fetchImpl, "GET", "/api/notes/folders");
         if (!response.ok)
@@ -14,7 +17,7 @@ export function registerNoteFolderTools(server, deps) {
     }));
     register("notes_mkdir", {
         title: "Create a note folder", description: "Create a path, including missing ancestors. Existing paths are reused.",
-        inputSchema: { path: z.string().min(1).max(2000) },
+        inputSchema: { path: z.string().min(1).max(2000).describe("A slash-separated folder path, e.g. Clients/Blue Pearl.") },
     }, async (args) => withSession(deps, async (session) => {
         const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/notes/folders", { path: args.path });
         if (!response.ok)
@@ -23,7 +26,7 @@ export function registerNoteFolderTools(server, deps) {
     }));
     register("notes_rmdir", {
         title: "Delete an empty note folder", description: "Delete a folder by path. Refuses any folder with notes or children.",
-        inputSchema: { path: z.string().min(1).max(2000) },
+        inputSchema: { path: z.string().min(1).max(2000).describe("The folder's slash-separated path, as notes_folders lists it.") },
     }, async (args) => withSession(deps, async (session) => {
         const listed = await callAgentDoor(session, deps.fetchImpl, "GET", "/api/notes/folders");
         if (!listed.ok)
@@ -40,7 +43,10 @@ export function registerNoteFolderTools(server, deps) {
     }));
     register("notes_rename", {
         title: "Rename a note folder", description: "Rename a folder by path, updating every descendant path.",
-        inputSchema: { path: z.string().min(1).max(2000), name: z.string().min(1).max(120) },
+        inputSchema: {
+            path: z.string().min(1).max(2000).describe("The folder's slash-separated path, as notes_folders lists it."),
+            name: z.string().min(1).max(120).describe("The folder's new last segment. Its descendants move with it."),
+        },
     }, async (args) => withSession(deps, async (session) => {
         const listed = await callAgentDoor(session, deps.fetchImpl, "GET", "/api/notes/folders");
         if (!listed.ok)

package/dist/notes-account-tools.js

@@ -50,7 +50,7 @@ export function registerNotesAccountTools(server, deps) {
         description: "Reads the meetings this notetaker has recorded since the last pass and files them as meeting notes. "
             + "Answers with the run's own counts and reason label, which is exactly what the ledger row says. "
             + "The half-hourly cron does this unasked; this is the button for when you do not want to wait.",
-        inputSchema: { account_id: z.string().uuid() },
+        inputSchema: { account_id: z.string().uuid().describe("A notetaker account id (notes_accounts).") },
     }, async (args) => withSession(deps, async (session) => {
         const response = await callAgentDoor(session, deps.fetchImpl, "POST", `/api/notes/accounts/${encodeURIComponent(String(args.account_id))}/sync`);
         if (!response.ok)
@@ -64,7 +64,7 @@ export function registerNotesAccountTools(server, deps) {
         title: "Detach a notetaker",
         description: "Removes a notetaker account and its stored key from Tower. The account itself is untouched at the provider, "
             + "and the meetings it already filed stay where they are. Requires confirm: true.",
-        inputSchema: { account_id: z.string().uuid(), confirm: CONFIRM_INPUT },
+        inputSchema: { account_id: z.string().uuid().describe("A notetaker account id (notes_accounts)."), confirm: CONFIRM_INPUT },
     }, async (args) => withSession(deps, async (session) => {
         const refusal = unconfirmed(args, "This would detach that notetaker and forget its stored key (the account itself is untouched at the provider, and the meetings it filed stay).");
         if (refusal)

package/dist/notes-tools.js

@@ -18,7 +18,7 @@ import { registerNoteFolderTools } from "./note-folder-tools.js";
  */
 import { z } from "zod";
 import { callAgentDoor } from "./agent-door.js";
-import { doorFailureText, errorResult, registrarFor, textResult, queryString, withSession, } from "./tool-result.js";
+import { DEFAULT_LIST_LIMIT, doorFailureText, errorResult, registrarFor, textResult, queryString, withSession, } from "./tool-result.js";
 /**
  * The door's own words for "this answer is narrower than the browser's", or
  * "" when it was not narrowed. Never rephrased here.
@@ -48,7 +48,7 @@ const LIBRARY_FILTERS = {
     kind: z.string().min(1).max(100).optional().describe("Only this meeting kind."),
     since: z.string().min(1).max(20).optional().describe("YYYY-MM-DD — meetings on or after this date."),
     until: z.string().min(1).max(20).optional().describe("YYYY-MM-DD — meetings on or before this date."),
-    limit: z.number().int().min(1).max(500).optional(),
+    limit: z.number().int().min(1).max(500).optional().describe("At most this many notes."),
 };
 export function registerNotesTools(server, deps) {
     registerNoteFolderTools(server, deps);
@@ -56,10 +56,17 @@ export function registerNotesTools(server, deps) {
     register("notes_list", {
         title: "List Tower meeting notes",
         description: "The meeting-notes library you may read, grouped by shelf: id, date, kind, participants and file name. "
+            + `Newest ${DEFAULT_LIST_LIMIT} unless you pass limit (up to 500); the answer says when more exist. `
             + "Never a note's text — call notes_show for one. Says when the answer is narrower than a browser's.",
         inputSchema: LIBRARY_FILTERS,
     }, async (args) => withSession(deps, async (session) => {
-        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/notes/library${queryString(libraryQuery(args))}`);
+        // A page by default: the whole library was 136 notes and 58 KB on
+        // 2026-09-26, mostly participant lists (BLI-10432). The door reports
+        // `more` itself, so nothing here guesses.
+        const params = libraryQuery(args);
+        if (args.limit === undefined)
+            params.set("limit", String(DEFAULT_LIST_LIMIT));
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/notes/library${queryString(params)}`);
         if (!response.ok)
             return errorResult(doorFailureText("notes_list", response));
         const body = response.body;
@@ -100,7 +107,7 @@ export function registerNotesTools(server, deps) {
         title: "Your own Tower notes shelf",
         description: "The notes THIS machine's owner put in, with the per-note counts (statements, open to the team, kept back) "
             + "when the server knows them. Says so when it does not, rather than printing zeros.",
-        inputSchema: { limit: z.number().int().min(1).max(500).optional() },
+        inputSchema: { limit: z.number().int().min(1).max(500).optional().describe("At most this many notes.") },
     }, async (args) => withSession(deps, async (session) => {
         const params = new URLSearchParams();
         if (typeof args.limit === "number")