@bli-cockpit/mcp 0.1.59 → 0.1.63

package/dist/tool-catalog.js

@@ -0,0 +1,152 @@
+/**
+ * Every `bli-tower` tool, sorted by what calling it DOES (BLI-10432).
+ *
+ * `npm run mcp:smoke` calls every READ and every DRY-RUN against production
+ * and never a WRITE; `tool-catalog.test.ts` fails when a registered tool is in
+ * none of the three lists, so a new tool joins the smoke (or is declared a
+ * write) the day it is registered, not the day somebody notices.
+ *
+ * Deliberately dependency-free: `scripts/smoke.ts` imports this file straight
+ * from `src/` under Node's type stripping, so it may import nothing.
+ */
+/** Tools that change nothing. The smoke calls every one. */
+export const READ_TOOLS = [
+    "get_ticket_timeline",
+    "get_active_tickets",
+    "docs_list",
+    "docs_tree",
+    "docs_read",
+    "docs_sync_status",
+    "msg_channels",
+    "msg_read",
+    "msg_thread",
+    "work_list_issues",
+    "work_get_issue",
+    "work_issue_history",
+    "work_list_projects",
+    "careers_list",
+    "careers_show",
+    "careers_resume_url",
+    "careers_takehome_show",
+    "careers_settings_show",
+    "usage_people",
+    "usage_sessions",
+    "mail_accounts",
+    "mail_inbox",
+    "mail_read",
+    "mail_search",
+    "mail_attachment",
+    "cal_today",
+    "cal_week",
+    "cal_next",
+    "cal_find",
+    "cal_calendars",
+    "jarvis_ask",
+    "jarvis_trace",
+    "jarvis_check",
+    "models_list",
+    "models_card",
+    "models_compare",
+    "brief_read",
+    "brief_history",
+    "brief_status",
+    "notes_folders",
+    "notes_list",
+    "notes_show",
+    "notes_shelf",
+    "notes_shelves",
+    "notes_place",
+    "notes_accounts",
+    "ops_status",
+    "slack_coverage",
+    "slack_read",
+    "memory_profile",
+    "memory_consolidation",
+    "settings_show",
+    "settings_list",
+    "model_show",
+    "team_members",
+    "team_device_list",
+    "scout_board",
+    "workbook_read",
+    "tower_search",
+];
+/**
+ * Tools that write, but answer a dry run that writes nothing. The smoke calls
+ * each one ONLY with its dry-run flag set (`scripts/smoke.ts` says which).
+ */
+export const DRY_RUN_TOOLS = ["ops_recompile", "memory_requeue"];
+/**
+ * Tools that change real data: send mail, post messages, file issues, move
+ * candidates, share calendars. Never called by the smoke; covered by the unit
+ * suites (`write-tools.test.ts` and each family's own).
+ */
+export const WRITE_TOOLS = [
+    "emit_event",
+    "docs_create",
+    "docs_update",
+    "docs_link",
+    "msg_create_channel",
+    "msg_dm",
+    "msg_send",
+    "work_create_issue",
+    "work_update_issue",
+    "work_move_issue",
+    "work_comment_issue",
+    "careers_rescreen",
+    "careers_send_takehome",
+    "careers_invite",
+    "careers_grade",
+    "careers_decide",
+    "careers_takehome_set",
+    "careers_settings_set",
+    "mail_send",
+    "mail_sync",
+    "mail_detach",
+    "cal_create",
+    "cal_share",
+    "cal_sync",
+    "cal_detach",
+    "jarvis_dispatch",
+    "notes_mkdir",
+    "notes_rmdir",
+    "notes_rename",
+    "notes_upload",
+    "notes_paste",
+    "notes_share",
+    "notes_unshare",
+    "notes_move",
+    "notes_sync",
+    "notes_detach",
+    "memory_experience",
+    "scout_start",
+    "scout_dismiss",
+    "scout_undo",
+    "brief_rewrite",
+    "brief_correct",
+    "brief_done",
+    "brief_undone",
+    "settings_set",
+    "settings_delete",
+    "model_set",
+    "team_invite",
+    "team_role",
+    "team_device_revoke",
+];
+/** Reads that spend a model turn. The smoke's `--no-model` leaves these out. */
+export const MODEL_SPENDING_TOOLS = ["jarvis_ask", "jarvis_check"];
+/**
+ * Reads whose answer IS one whole item (a document, a transcript, a thread),
+ * so its size is the item's and not a list the caller failed to narrow. The
+ * smoke does not hold these to the per-half budget.
+ */
+export const SINGLE_ITEM_TOOLS = [
+    "docs_read",
+    "notes_show",
+    "mail_read",
+    "workbook_read",
+    "jarvis_trace",
+    "models_card",
+    "careers_show",
+    "memory_profile",
+];

package/dist/tool-result.d.ts

@@ -36,6 +36,37 @@ export interface DoorSession {
     deviceToken: string;
 }
 export declare function textResult(text: string, structured?: Record<string, unknown>): ToolResult;
+/**
+ * A result whose TEXT half carries the data, not just a headline (BLI-10432).
+ *
+ * MCP clients do not agree on which half of a tool result the model reads.
+ * Claude Code, claude.ai and Claude Desktop hand the model `content` and
+ * render `structuredContent` for the person (or drop it); Codex hands the
+ * model `structuredContent` and drops `content`. So a tool that answered
+ * `"5 document(s)."` in text and the rows in `structuredContent` was blind on
+ * every Claude surface: the model was told five documents exist and never
+ * given one id. Every read is written so EACH half stands alone. Use this when
+ * there is no terser rendering worth writing by hand: the headline, then the
+ * structured half as one line of compact JSON.
+ */
+export declare function dataResult(headline: string, structured: Record<string, unknown>): ToolResult;
+/**
+ * The per-half byte budget a DEFAULT read is held to (BLI-10432): about 8k
+ * tokens. A list over it names how to narrow instead of shipping everything;
+ * a single-item read (one document, one transcript) may exceed it because the
+ * item IS what was asked for. `scripts/smoke.ts` measures every read against
+ * it and the per-call log below warns when a result crosses it.
+ */
+export declare const RESULT_BUDGET_BYTES: number;
+/**
+ * The page a list returns when the caller named no `limit` (BLI-10432).
+ * `work_list_issues` with no limit returned 1,000 issues WITH descriptions,
+ * 4.2 MB, which no agent can afford; a list now answers a page and says when
+ * more exist.
+ */
+export declare const DEFAULT_LIST_LIMIT = 50;
+/** "…, and more exist — pass a larger limit (up to N) or narrow the filter." */
+export declare function moreNote(more: boolean, max: number): string;
 export declare function errorResult(text: string): ToolResult;
 /**
  * The session is loaded fresh per call (a cheap file read) rather than once at
@@ -63,7 +94,16 @@ export type RegisterTool = (name: string, config: {
     description: string;
     inputSchema: Record<string, unknown>;
 }, handler: (args: Record<string, unknown>) => Promise<ToolResult>) => unknown;
-/** The one cast, so no tool family repeats it. */
+/**
+ * The one cast, so no tool family repeats it — and the one place every
+ * agent-door call is logged (BLI-10432): tool, outcome, milliseconds and the
+ * byte size of each half. Metadata only, never an argument or a body. A result
+ * over `RESULT_BUDGET_BYTES` logs as a warning so an oversized read names
+ * itself in the client's MCP log instead of silently eating a context window.
+ * `BLI_MCP_QUIET_TOOL_LOG=1` silences the answered and refused lines (the unit
+ * suites set it, since they exercise refusals on purpose); a handler that
+ * threw always prints.
+ */
 export declare function registrarFor(server: {
     registerTool: (...args: never[]) => unknown;
 }): RegisterTool;
@@ -93,5 +133,16 @@ export declare function queryString(params: URLSearchParams): string;
  * `server.test.ts` walks every registered tool's shape for exactly this.
  */
 export declare const CONFIRM_INPUT: z.ZodOptional<z.ZodBoolean>;
+/**
+ * An email address, in a schema every client can compile (BLI-10432).
+ *
+ * `z.string().email()` publishes zod's own address pattern, which opens with
+ * two negative lookaheads (`^(?!\.)(?!.*\.\.)…`). Lookaround is not RE2, and
+ * RE2 is what OpenAI's strict tool schemas and Google's function declarations
+ * compile patterns with, so one `mail_send` in the tool list was enough for a
+ * strict client to refuse the whole server. This pattern is lookaround-free;
+ * the mail and calendar doors validate the address again on the server.
+ */
+export declare const EMAIL_INPUT: z.ZodString;
 /** `null` when the caller confirmed; the refusal itself when they did not. */
 export declare function unconfirmed(args: Record<string, unknown>, sentence: string): ToolResult | null;

package/dist/tool-result.js

@@ -18,6 +18,41 @@ import { loadAgentDoorSession } from "./agent-door-session.js";
 export function textResult(text, structured) {
     return { content: [{ type: "text", text }], ...(structured ? { structuredContent: structured } : {}) };
 }
+/**
+ * A result whose TEXT half carries the data, not just a headline (BLI-10432).
+ *
+ * MCP clients do not agree on which half of a tool result the model reads.
+ * Claude Code, claude.ai and Claude Desktop hand the model `content` and
+ * render `structuredContent` for the person (or drop it); Codex hands the
+ * model `structuredContent` and drops `content`. So a tool that answered
+ * `"5 document(s)."` in text and the rows in `structuredContent` was blind on
+ * every Claude surface: the model was told five documents exist and never
+ * given one id. Every read is written so EACH half stands alone. Use this when
+ * there is no terser rendering worth writing by hand: the headline, then the
+ * structured half as one line of compact JSON.
+ */
+export function dataResult(headline, structured) {
+    return textResult(`${headline}\n${JSON.stringify(structured)}`, structured);
+}
+/**
+ * The per-half byte budget a DEFAULT read is held to (BLI-10432): about 8k
+ * tokens. A list over it names how to narrow instead of shipping everything;
+ * a single-item read (one document, one transcript) may exceed it because the
+ * item IS what was asked for. `scripts/smoke.ts` measures every read against
+ * it and the per-call log below warns when a result crosses it.
+ */
+export const RESULT_BUDGET_BYTES = 32 * 1024;
+/**
+ * The page a list returns when the caller named no `limit` (BLI-10432).
+ * `work_list_issues` with no limit returned 1,000 issues WITH descriptions,
+ * 4.2 MB, which no agent can afford; a list now answers a page and says when
+ * more exist.
+ */
+export const DEFAULT_LIST_LIMIT = 50;
+/** "…, and more exist — pass a larger limit (up to N) or narrow the filter." */
+export function moreNote(more, max) {
+    return more ? ` More exist — pass a larger limit (up to ${max}) or narrow the filter.` : "";
+}
 export function errorResult(text) {
     return { isError: true, content: [{ type: "text", text }] };
 }
@@ -69,9 +104,49 @@ function doorSentence(body, status) {
     const said = [headline ?? message, ...lines].filter(Boolean);
     return said.length > 0 ? said.join(" ") : `Tower answered ${status}.`;
 }
-/** The one cast, so no tool family repeats it. */
+/**
+ * The one cast, so no tool family repeats it — and the one place every
+ * agent-door call is logged (BLI-10432): tool, outcome, milliseconds and the
+ * byte size of each half. Metadata only, never an argument or a body. A result
+ * over `RESULT_BUDGET_BYTES` logs as a warning so an oversized read names
+ * itself in the client's MCP log instead of silently eating a context window.
+ * `BLI_MCP_QUIET_TOOL_LOG=1` silences the answered and refused lines (the unit
+ * suites set it, since they exercise refusals on purpose); a handler that
+ * threw always prints.
+ */
 export function registrarFor(server) {
-    return server.registerTool.bind(server);
+    const register = server.registerTool.bind(server);
+    return (name, config, handler) => register(name, config, async (args) => {
+        const started = Date.now();
+        let result;
+        try {
+            result = await handler(args);
+        }
+        catch (error) {
+            // A handler that throws would surface as a bare protocol error with no
+            // reason label; name it, log it, and answer by name instead.
+            const reason = error instanceof Error ? error.message.split("\n")[0] ?? "unknown" : String(error);
+            logToolCall("error", { tool: name, outcome: "threw", ms: Date.now() - started, reason: reason.slice(0, 200) });
+            return errorResult(`${name} failed inside the bli-tower server (tool_threw): ${reason}`);
+        }
+        const textBytes = Buffer.byteLength(result.content.map((part) => part.text).join(""));
+        const structuredBytes = result.structuredContent ? Buffer.byteLength(JSON.stringify(result.structuredContent)) : 0;
+        const oversized = Math.max(textBytes, structuredBytes) > RESULT_BUDGET_BYTES;
+        logToolCall(result.isError || oversized ? "warn" : "info", {
+            tool: name,
+            outcome: result.isError ? "refused" : oversized ? "answered_oversized" : "answered",
+            ms: Date.now() - started,
+            text_bytes: textBytes,
+            structured_bytes: structuredBytes,
+        });
+        return result;
+    });
+}
+function logToolCall(level, fields) {
+    if (level !== "error" && process.env.BLI_MCP_QUIET_TOOL_LOG === "1")
+        return;
+    // stdout is the MCP transport; every log line goes to stderr.
+    process.stderr.write(`[bli-cockpit-mcp tool] ${level} ${JSON.stringify(fields)}\n`);
 }
 /** `?a=1&b=2`, or "" when nothing was asked for. Never a bare `?`. */
 export function queryString(params) {
@@ -108,6 +183,21 @@ export const CONFIRM_INPUT = z
     .boolean()
     .optional()
     .describe("Must be true. This act is deliberate and is refused without it — the same rule as the CLI's --yes.");
+/**
+ * An email address, in a schema every client can compile (BLI-10432).
+ *
+ * `z.string().email()` publishes zod's own address pattern, which opens with
+ * two negative lookaheads (`^(?!\.)(?!.*\.\.)…`). Lookaround is not RE2, and
+ * RE2 is what OpenAI's strict tool schemas and Google's function declarations
+ * compile patterns with, so one `mail_send` in the tool list was enough for a
+ * strict client to refuse the whole server. This pattern is lookaround-free;
+ * the mail and calendar doors validate the address again on the server.
+ */
+export const EMAIL_INPUT = z
+    .string()
+    .min(3)
+    .max(320)
+    .regex(/^[^\s@]+@[^\s@]+\.[^\s@]+$/u, "an email address");
 /** `null` when the caller confirmed; the refusal itself when they did not. */
 export function unconfirmed(args, sentence) {
     if (args.confirm === true)

package/dist/usage-tools.js

@@ -1,11 +1,22 @@
 import { z } from "zod";
 import { callAgentDoor } from "./agent-door.js";
-import { doorFailureText, errorResult, registrarFor, textResult, withSession } from "./tool-result.js";
+import { dataResult, doorFailureText, errorResult, registrarFor, withSession } from "./tool-result.js";
+// Both reads answer with `dataResult`: the text half used to carry only the
+// coverage sentence, so a Claude-family client (which shows the model the text
+// half alone) could say how many sessions were counted and never whose they
+// were or what they cost (BLI-10432).
+const WINDOW_BOUND = "<n>d (1 to 365), <n>h (1 to 8760), or an ISO timestamp";
 export function registerUsageTools(server, deps) {
     registrarFor(server)("usage_people", {
         title: "Read usage by person",
-        description: "Per-person Claude Code and Codex token usage, list-price equivalent, and extraction coverage.",
-        inputSchema: { minConfidence: z.enum(["high", "medium", "low"]).optional(), groupBy: z.enum(["repo", "task_type", "topic", "ticket"]).optional(), since: z.string().optional().describe("<n>d (1 to 365), <n>h (1 to 8760), or an ISO timestamp. Default 30d; invalid values return invalid_usage_window."), until: z.string().optional(), include_automated: z.boolean().optional() },
+        description: "Per-person Claude Code and Codex token usage, list-price equivalent (not actual spend), and extraction coverage, over a window (default the last 30 days). groupBy adds a per-person breakdown; groupBy topic or ticket lists the labels usage_sessions takes as subject or task.",
+        inputSchema: {
+            minConfidence: z.enum(["high", "medium", "low"]).optional().describe("With groupBy task_type or topic: only labels at or above this confidence."),
+            groupBy: z.enum(["repo", "task_type", "topic", "ticket"]).optional().describe("Break each person's usage down by repo, task type, topic or ticket."),
+            since: z.string().min(1).max(40).optional().describe(`${WINDOW_BOUND}. Default 30d; invalid values return invalid_usage_window.`),
+            until: z.string().min(1).max(40).optional().describe(`${WINDOW_BOUND}. Default now.`),
+            include_automated: z.boolean().optional().describe("Count automated (scripted, non-interactive) sessions too. Off by default."),
+        },
     }, async (args) => withSession(deps, async (session) => {
         const query = new URLSearchParams({ since: String(args.since ?? "30d") });
         if (args.until)
@@ -32,15 +43,31 @@ export function registerUsageTools(server, deps) {
         const priceLabel = typeof response.body.api_list_price_equivalent_label === "string"
             ? ` ${response.body.api_list_price_equivalent_label}.`
             : "";
-        return textResult(`${coverage?.sessions_extracted ?? 0} of ${coverage?.sessions_observed ?? 0} sessions extracted.${why} ${coverage?.sessions_counted_at_upload ?? 0} of ${coverage?.sessions_observed ?? 0} sessions counted at upload, ${coverage?.sessions_counted_by_server ?? 0} by server backfill, ${coverage?.sessions_counted_by_ladder ?? 0} by the ladder.${args.groupBy === "task_type" ? ` ${coverage?.sessions_labelled ?? 0} of ${coverage?.sessions_observed ?? 0} sessions labelled by topic.` : ""}${priceLabel}`, response.body);
+        return dataResult(`${coverage?.sessions_extracted ?? 0} of ${coverage?.sessions_observed ?? 0} sessions extracted.${why} ${coverage?.sessions_counted_at_upload ?? 0} of ${coverage?.sessions_observed ?? 0} sessions counted at upload, ${coverage?.sessions_counted_by_server ?? 0} by server backfill, ${coverage?.sessions_counted_by_ladder ?? 0} by the ladder.${args.groupBy === "task_type" ? ` ${coverage?.sessions_labelled ?? 0} of ${coverage?.sessions_observed ?? 0} sessions labelled by topic.` : ""}${priceLabel}`, response.body);
     }));
     registrarFor(server)("usage_sessions", {
         title: "Read task or subject sessions",
-        description: "List task or subject sessions with titles, tokens and work types; read digest windows on demand with session.",
-        inputSchema: { task: z.string().regex(/^BLI-[0-9]+$/).optional(), subject: z.string().optional(), repo: z.string().optional(), since: z.string().optional(), until: z.string().optional(), include_automated: z.boolean().optional(), session: z.string().optional(), fromWindow: z.number().int().positive().optional() },
+        description: "The sessions behind one ticket or one topic: titles, tokens and work types. Name exactly one of task (a BLI-#### id) or subject (a TOPIC label, as usage_people with groupBy topic lists it; not a person). Or pass session (a session id) alone to read that session's digest windows, ten at a time from fromWindow. This read can take 25 seconds.",
+        inputSchema: {
+            task: z.string().regex(/^BLI-[0-9]+$/).optional().describe("A ticket id, e.g. BLI-4258: the sessions labelled with it."),
+            subject: z.string().min(1).max(300).optional().describe("A topic label exactly as usage_people groupBy topic prints it. Not a person or an email."),
+            repo: z.string().min(1).max(200).optional().describe("Only sessions in this repo label."),
+            person: z.string().min(1).max(64).optional().describe("Only this person's sessions, by user id (usage_people user_id)."),
+            subtopic: z.string().min(1).max(300).optional().describe("Only sessions with this subtopic label."),
+            since: z.string().min(1).max(40).optional().describe(`${WINDOW_BOUND}. Default 30d.`),
+            until: z.string().min(1).max(40).optional().describe(`${WINDOW_BOUND}. Default now.`),
+            include_automated: z.boolean().optional().describe("Count automated sessions too. Off by default."),
+            session: z.string().min(1).max(200).optional().describe("A session id: read its digest windows instead of listing sessions."),
+            fromWindow: z.number().int().min(1).optional().describe("With session: the first window number to read. Default 1."),
+        },
     }, async (args) => withSession(deps, async (session) => {
+        // The door answers a bare 400 `subject_and_valid_window_required` when
+        // neither is named; say what to pass instead of "Tower answered 400".
+        if (args.session === undefined && args.task === undefined && (typeof args.subject !== "string" || args.subject.trim() === "")) {
+            return errorResult("usage_sessions needs task (a BLI-#### id), subject (a topic label from usage_people groupBy topic) or session (a session id) (task_or_subject_required). Nothing was read.");
+        }
         const query = new URLSearchParams();
-        for (const key of ["task", "subject", "repo", "since", "until", "session", "fromWindow"])
+        for (const key of ["task", "subject", "repo", "person", "subtopic", "since", "until", "session", "fromWindow"])
             if (args[key] !== undefined)
                 query.set(key, String(args[key]));
         if (args.include_automated)
@@ -48,6 +75,11 @@ export function registerUsageTools(server, deps) {
         const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/usage/sessions?${query}`);
         if (!response.ok)
             return errorResult(doorFailureText("usage_sessions", response));
-        return textResult("Subject sessions and requested digest windows.", response.body);
+        if (args.session !== undefined) {
+            const windows = Array.isArray(response.body.windows) ? response.body.windows.length : 0;
+            return dataResult(`${windows} digest window(s) of session ${String(args.session)}.`, response.body);
+        }
+        const sessions = Array.isArray(response.body.sessions) ? response.body.sessions.length : 0;
+        return dataResult(`${sessions} session(s) for ${args.task ? `task ${String(args.task)}` : `topic "${String(args.subject)}"`}.`, response.body);
     }));
 }

package/dist/verb-census.js

@@ -234,6 +234,8 @@ export const MCP_TWINS = {
     "docs read": { tool: "docs_read", door: "GET /api/docs/documents/[id]" },
     "docs create": { tool: "docs_create", door: "POST /api/docs/documents" },
     "docs update": { tool: "docs_update", door: "PATCH /api/docs/documents/[id]" },
+    "docs link": { tool: "docs_link", door: "PUT /api/docs/documents/[id]/notion-link" },
+    "docs sync-status": { tool: "docs_sync_status", door: "GET /api/docs/notion-sync" },
     "msg channels": { tool: "msg_channels", door: "GET /api/msg/channels" },
     "msg create": { tool: "msg_create_channel", door: "POST /api/msg/channels" },
     "msg dm": { tool: "msg_dm", door: "POST /api/msg/channels (dm)" },

package/dist/work-tools.js

@@ -16,7 +16,7 @@
  */
 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";
 /** The closed state vocabulary, verbatim from `lib/work/api-doors.ts` `WORK_ISSUE_STATES`. */
 export const WORK_ISSUE_STATES = [
     "backlog",
@@ -26,6 +26,27 @@ export const WORK_ISSUE_STATES = [
     "done",
     "canceled",
 ];
+/** `/api/work/issues`' own ceiling, and the most a caller may ask for here. */
+const ISSUE_LIST_MAX = 1000;
+/**
+ * The fields `work_list_issues` promises. The door's row carries the whole
+ * description and a dozen bookkeeping columns; with no limit that was 1,000
+ * issues and 4.2 MB, 3.3 MB of it descriptions the tool said it never
+ * returned (BLI-10432). work_get_issue reads one issue in full.
+ */
+function issueListRow(row) {
+    return {
+        id: row.id,
+        identifier: row.identifier,
+        title: row.title,
+        state: row.state,
+        priority: row.priority ?? null,
+        assignee_id: row.assignee_id ?? null,
+        project_id: row.project_id ?? null,
+        parent_id: row.parent_id ?? null,
+        updated_at: row.updated_at ?? null,
+    };
+}
 /**
  * A row the Linear import could not give state names to says which it is.
  * Printing "(none) -> (none)" is honest and useless; naming the gap keeps
@@ -57,13 +78,15 @@ export function registerWorkTools(server, deps) {
     const register = registrarFor(server);
     register("work_list_issues", {
         title: "List Tower issues",
-        description: "Issues you may see, most recently updated first. Filter by state, assignee (\"me\", \"unassigned\", or a uuid) "
-            + "or project (name or uuid). Never a description — call work_get_issue for one issue's full text.",
+        description: "Issues you may see, most recently updated first: identifier, state, title, priority, assignee, project. "
+            + "Filter by state, assignee (\"me\", \"unassigned\", or a uuid) or project (name or uuid). "
+            + `Default ${DEFAULT_LIST_LIMIT} issues; the answer says when more exist. `
+            + "Never a description — call work_get_issue for one issue's full text.",
         inputSchema: {
-            state: z.enum(WORK_ISSUE_STATES).optional(),
+            state: z.enum(WORK_ISSUE_STATES).optional().describe("Only issues in this state."),
             assignee: z.string().min(1).max(100).optional().describe('"me", "unassigned", or a person\'s uuid.'),
             project: z.string().min(1).max(200).optional().describe("A project name or uuid."),
-            limit: z.number().int().min(1).max(1000).optional(),
+            limit: z.number().int().min(1).max(ISSUE_LIST_MAX).optional().describe(`At most this many issues. Default ${DEFAULT_LIST_LIMIT}.`),
         },
     }, async (args) => withSession(deps, async (session) => {
         const query = new URLSearchParams();
@@ -71,8 +94,9 @@ export function registerWorkTools(server, deps) {
             query.set("state", String(args.state));
         if (args.assignee)
             query.set("assignee_id", String(args.assignee));
-        if (args.limit)
-            query.set("limit", String(args.limit));
+        // No limit named: one page plus one row, so "more exist" is read off
+        // the door rather than guessed from a full page.
+        query.set("limit", String(args.limit ?? DEFAULT_LIST_LIMIT + 1));
         if (args.project) {
             const resolved = await resolveProjectId(deps, session, String(args.project));
             if (resolved.status === "list_failed")
@@ -86,9 +110,14 @@ export function registerWorkTools(server, deps) {
         const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/work/issues${suffix ? `?${suffix}` : ""}`);
         if (!response.ok)
             return errorResult(doorFailureText("work_list_issues", response));
-        const issues = (Array.isArray(response.body.issues) ? response.body.issues : []);
-        const lines = issues.map((issue) => `${issue.identifier}  ${issue.state}  ${issue.title}`).join("\n");
-        return textResult(`${issues.length} issue(s).${lines ? `\n${lines}` : ""}`, { issues });
+        const all = (Array.isArray(response.body.issues) ? response.body.issues : []);
+        const more = args.limit === undefined && all.length > DEFAULT_LIST_LIMIT;
+        const issues = more ? all.slice(0, DEFAULT_LIST_LIMIT) : all;
+        const lines = issues
+            .map((issue) => `${issue.identifier}  ${issue.state}  ${issue.title}`
+            + `  [p${issue.priority ?? 0}, assignee ${issue.assignee_id ?? "none"}, project ${issue.project_id ?? "none"}]`)
+            .join("\n");
+        return textResult(`${issues.length} issue(s).${moreNote(more, ISSUE_LIST_MAX)}${lines ? `\n${lines}` : ""}`, { issues: issues.map(issueListRow), more });
     }));
     register("work_get_issue", {
         title: "Read a Tower issue",
@@ -114,8 +143,8 @@ export function registerWorkTools(server, deps) {
         title: "File a Tower issue",
         description: "Files a new issue and returns the BLI-#### identifier it was given. Use this the way you would file a Linear ticket.",
         inputSchema: {
-            title: z.string().min(1).max(300),
-            description: z.string().max(200_000).optional(),
+            title: z.string().min(1).max(300).describe("The issue title."),
+            description: z.string().max(200_000).optional().describe("The issue body, markdown."),
             project: z.string().min(1).max(200).optional().describe("A project name or uuid."),
             priority: z.number().int().min(0).max(4).optional().describe("0 none, 1 urgent, 2 high, 3 medium, 4 low."),
             assignee: z.string().min(1).max(100).optional().describe('"me" or a person\'s uuid.'),
@@ -149,9 +178,9 @@ export function registerWorkTools(server, deps) {
             + "State does NOT move here — call work_move_issue, which records the move.",
         inputSchema: {
             id: ISSUE_REF,
-            title: z.string().min(1).max(300).optional(),
-            description: z.string().max(200_000).nullable().optional(),
-            priority: z.number().int().min(0).max(4).optional(),
+            title: z.string().min(1).max(300).optional().describe("A new title."),
+            description: z.string().max(200_000).nullable().optional().describe("The WHOLE new body, markdown; null clears it."),
+            priority: z.number().int().min(0).max(4).optional().describe("0 none, 1 urgent, 2 high, 3 medium, 4 low."),
             assignee: z.string().min(1).max(100).nullable().optional().describe('"me", a uuid, or null to unassign.'),
             project: z.string().min(1).max(200).optional().describe("A project name or uuid."),
         },
@@ -183,7 +212,7 @@ export function registerWorkTools(server, deps) {
         title: "Move a Tower issue",
         description: "Moves an issue to a new state and records the move in its history. This is how an issue's state changes; "
             + "there is no other door.",
-        inputSchema: { id: ISSUE_REF, state: z.enum(WORK_ISSUE_STATES) },
+        inputSchema: { id: ISSUE_REF, state: z.enum(WORK_ISSUE_STATES).describe("The state to move it to.") },
     }, async (args) => withSession(deps, async (session) => {
         const ref = String(args.id ?? "");
         const response = await callAgentDoor(session, deps.fetchImpl, "POST", `/api/work/issues/${encodeURIComponent(ref)}/state`, {
@@ -197,7 +226,7 @@ export function registerWorkTools(server, deps) {
     register("work_comment_issue", {
         title: "Comment on a Tower issue",
         description: "Posts a comment. Comments are append-only — nothing here edits or deletes one.",
-        inputSchema: { id: ISSUE_REF, body_markdown: z.string().min(1).max(50_000) },
+        inputSchema: { id: ISSUE_REF, body_markdown: z.string().min(1).max(50_000).describe("The comment, markdown.") },
     }, async (args) => withSession(deps, async (session) => {
         const ref = String(args.id ?? "");
         const response = await callAgentDoor(session, deps.fetchImpl, "POST", `/api/work/issues/${encodeURIComponent(ref)}/comments`, { body_markdown: args.body_markdown });
@@ -213,7 +242,7 @@ export function registerWorkTools(server, deps) {
             + "\"(none) -> (none)\".",
         inputSchema: {
             id: ISSUE_REF,
-            limit: z.number().int().min(1).max(500).optional(),
+            limit: z.number().int().min(1).max(500).optional().describe("At most this many changes."),
         },
     }, async (args) => withSession(deps, async (session) => {
         const ref = String(args.id ?? "");
@@ -232,7 +261,7 @@ export function registerWorkTools(server, deps) {
     register("work_list_projects", {
         title: "List Tower projects",
         description: "The projects issues are filed under. Use a project's name with work_list_issues or work_create_issue.",
-        inputSchema: { include_archived: z.boolean().optional() },
+        inputSchema: { include_archived: z.boolean().optional().describe("true: archived projects too.") },
     }, async (args) => withSession(deps, async (session) => {
         const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/work/projects${args.include_archived ? "?include_archived=true" : ""}`);
         if (!response.ok)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/mcp",
-  "version": "0.1.59",
+  "version": "0.1.63",
   "private": false,
   "description": "bli-tower: an MCP server over BLI Cockpit's agent doors: JARVIS (jarvis_*), documents (docs_*), channels (msg_*), issues (work_*), the daily page (brief_*), meeting notes (notes_*), the ops board (ops_status/slack_*), settings/team/model, Scout and the workbook, plus the legacy event-stream tools (emit_event, get_ticket_timeline, get_active_tickets).",
   "type": "module",