@bli-cockpit/mcp 0.1.59 → 0.1.61

package/README.md

@@ -25,6 +25,75 @@ dead"). `src/verb-census.test.ts` is that rule as a test — it reads the CLI's
 own decision tables and fails when a verb is in neither the twin map, the
 terminal-only list, nor the written follow-up queue.
 
+## MCP or CLI: which one should an agent use?
+
+Both reach the same Tower doors with the same device token and the same
+refusal words, so the choice is about where the agent runs and what it costs.
+
+- **The agent has a shell** (Claude Code, Codex, any terminal agent): use the
+  CLI, `cockpit <noun> <verb>`. Nothing loads into the context window until a
+  command runs, the human-readable output is the tersest form of every read,
+  and a person can run the exact same line to check it.
+- **The agent has no shell** (claude.ai, Claude Desktop chat, IDE chat panes,
+  any connector-only host): use this server. It is the only door those hosts
+  have.
+
+Measured on 2026-09-26 against production, same account, same moment. Bytes
+the model actually reads; tokens are an estimate at about 4 bytes a token.
+
+| Read | `cockpit …` text | `cockpit … --json` | MCP text half (Claude hosts) | MCP structured half (Codex) |
+| --- | ---: | ---: | ---: | ---: |
+| issue list, 20 issues | 2,345 B (~0.6k tok) | 43,964 B (~11k tok) | 3,632 B (~0.9k tok) | 6,865 B (~1.7k tok) |
+| mail inbox, 10 messages | 1,070 B (~0.3k tok) | 12,583 B (~3.1k tok) | 1,475 B (~0.4k tok) | 9,544 B (~2.4k tok) |
+| today's brief | 2,374 B (~0.6k tok) | 4,032 B (~1k tok) | 2,262 B (~0.6k tok) | 2,635 B (~0.7k tok) |
+
+Two costs sit outside the table. The MCP server's tool list is 109 tool
+definitions, 94,985 bytes (~24k tokens); a host that loads every schema up
+front pays that once per session before the first call, and a host that defers
+schemas until a tool is searched for pays a fraction of it. The CLI's
+equivalent is a `--help` read when the agent does not know a verb: 1,769 bytes
+for `cockpit issue list --help`, 8,998 for the whole `cockpit --help`. And
+`--json` is the CLI's most expensive form, because it prints the door's whole
+answer (`issue list --json` carries every description); read the text form
+unless a script needs the fields.
+
+**Which half a host shows the model.** A tool result has a text half
+(`content`) and a structured half (`structuredContent`), and hosts disagree:
+Claude Code, claude.ai and Claude Desktop give the model the text half; Codex
+gives it the structured half and drops the text. Every read on this server is
+written so EACH half stands alone. That was not always true: until BLI-10432,
+`docs_list`, `msg_channels`, `msg_read`, every `careers_*` tool,
+`usage_people`, `usage_sessions` and `memory_consolidation` answered a
+headline such as `5 document(s).` in text, so on a Claude host the model was
+told the data existed and never given it. `src/tool-contract.test.ts` holds
+the rule.
+
+**A default read is affordable.** A list with no `limit` answers a page and
+says when more exist: `docs_list`, `work_list_issues` and `notes_list` return
+50 (`work_list_issues` with no limit used to return 1,000 issues with their
+descriptions, 4.2 MB). `ops_status` returns the fleet and coverage summaries
+and keeps the per-device and per-person rows behind `people: true` (they were
+155 KB of a 175 KB answer). Every door gets 55 seconds, under the 60 seconds a
+stock MCP client waits; `ops_status` and `usage_sessions` routinely take 20-35
+seconds and used to be abandoned at 15. Each call logs one metadata line to
+stderr, the host's MCP log: `[bli-cockpit-mcp tool] info
+{"tool":…,"outcome":…,"ms":…,"text_bytes":…,"structured_bytes":…}`, a `warn`
+when a half crosses 32 KB (`RESULT_BUDGET_BYTES`).
+
+**Schemas every client compiles.** The published input schemas use only the
+portable JSON-schema keywords (no `exclusiveMinimum`, no `propertyNames`) and
+no lookaround in a pattern, because OpenAI's strict mode and Google's function
+declarations compile patterns with RE2, and one refused tool can make a strict
+host refuse the whole server. `src/tool-contract.test.ts` reads the schemas
+from a real server over a real client and fails on either.
+
+**Proving it answers.** `npm run mcp:smoke --workspace=@bli-cockpit/mcp`
+calls every read and dry run in `src/tool-catalog.ts` against the Tower this
+machine is paired with, never a write, and fails a list read over 32 KB a
+half. `--no-model` leaves out the two reads that spend a model turn.
+`src/tool-catalog.test.ts` fails when a registered tool is in none of the
+catalog's read, dry-run and write lists.
+
 ## Every Tower verb, and the tool that does the same thing
 
 The three tables below are GENERATED from `src/verb-census.ts` by

package/dist/agent-door.d.ts

@@ -12,6 +12,18 @@ export interface AgentDoorResponse {
     /** Set only when no JSON answer was produced at all — DNS, TLS, timeout, non-JSON body. */
     transportError: string | null;
 }
+/**
+ * How long a door gets before this server gives up on it (BLI-10432).
+ *
+ * It was 15 s, and two real doors take longer than that on production:
+ * `GET /api/ops/status` (the whole board) answered in 23.5 s and
+ * `GET /api/usage/sessions?task=…` in 24 s on 2026-09-26. `cockpit` sets no
+ * deadline on either, so the CLI answered and the MCP twin reported "Tower
+ * could not be reached" for a door that was simply working. 55 s sits under
+ * the 60 s request deadline the MCP TypeScript client applies by default, so
+ * this server still answers by name before a stock client hangs up on it.
+ */
+export declare const DEFAULT_TIMEOUT_MS = 55000;
 /**
  * The four verbs Tower's agent doors answer to. `PUT` is the CLI floor
  * (`PUT /api/settings/cli-floor`) and `DELETE` is an env blob — both arrived

package/dist/agent-door.js

@@ -3,7 +3,18 @@
  * token (BLI-3706). Deadline-bounded; a transport failure and a door refusal
  * are kept apart, same rule as `packages/cockpit-memory-mcp/src/door.ts`.
  */
-const DEFAULT_TIMEOUT_MS = 15_000;
+/**
+ * How long a door gets before this server gives up on it (BLI-10432).
+ *
+ * It was 15 s, and two real doors take longer than that on production:
+ * `GET /api/ops/status` (the whole board) answered in 23.5 s and
+ * `GET /api/usage/sessions?task=…` in 24 s on 2026-09-26. `cockpit` sets no
+ * deadline on either, so the CLI answered and the MCP twin reported "Tower
+ * could not be reached" for a door that was simply working. 55 s sits under
+ * the 60 s request deadline the MCP TypeScript client applies by default, so
+ * this server still answers by name before a stock client hangs up on it.
+ */
+export const DEFAULT_TIMEOUT_MS = 55_000;
 export async function callAgentDoor(session, fetchImpl, method, path, body, timeoutMs = DEFAULT_TIMEOUT_MS) {
     const url = `${session.dashboardUrl}${path}`;
     const controller = new AbortController();

package/dist/cal-tools.js

@@ -31,7 +31,7 @@
  */
 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";
 /** This machine's zone: what a person means by "today" unless they say otherwise. */
 function localZone() {
     try {
@@ -73,9 +73,9 @@ function windowRenderer(label) {
 export function registerCalTools(server, deps) {
     const register = registrarFor(server);
     const windowInput = {
-        time_zone: z.string().min(1).max(80).optional(),
-        calendar_id: z.string().uuid().optional(),
-        limit: z.number().int().min(1).max(750).optional(),
+        time_zone: z.string().min(1).max(80).optional().describe("An IANA zone, e.g. Asia/Saigon. Default: this machine's zone."),
+        calendar_id: z.string().uuid().optional().describe("One calendar id (cal_calendars). Omit for every calendar you may read."),
+        limit: z.number().int().min(1).max(750).optional().describe("At most this many events."),
     };
     function windowQuery(args) {
         const query = new URLSearchParams({ tz: String(args.time_zone ?? localZone()) });
@@ -94,7 +94,7 @@ export function registerCalTools(server, deps) {
         description: "Every event today across every calendar you may read, in the zone you name (default: this machine's). "
             + "`offset` moves the day — 1 is tomorrow, -1 yesterday. Recurring events are expanded for exactly this day, "
             + "and a series whose rule Tower will not guess at is named rather than dropped.",
-        inputSchema: { ...windowInput, offset: z.number().int().min(-52).max(52).optional() },
+        inputSchema: { ...windowInput, offset: z.number().int().min(-52).max(52).optional().describe("Days from today: 1 is tomorrow, -1 yesterday.") },
     }, async (args) => withSession(deps, async (session) => {
         const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/cal/today${queryString(windowQuery(args))}`);
         if (!response.ok)
@@ -105,7 +105,7 @@ export function registerCalTools(server, deps) {
         title: "What is on this week",
         description: "Monday to Sunday, across every calendar you may read. The week starts on MONDAY here. `offset` moves it — 1 "
             + "is next week.",
-        inputSchema: { ...windowInput, offset: z.number().int().min(-52).max(52).optional() },
+        inputSchema: { ...windowInput, offset: z.number().int().min(-52).max(52).optional().describe("Weeks from this one: 1 is next week, -1 last week.") },
     }, async (args) => withSession(deps, async (session) => {
         const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/cal/week${queryString(windowQuery(args))}`);
         if (!response.ok)
@@ -117,7 +117,7 @@ export function registerCalTools(server, deps) {
         description: "What is next, counted from RIGHT NOW rather than from midnight — at 23:50 the honest answer is tomorrow's "
             + "09:30, and a day-shaped window would say 'nothing'. Defaults to the next 72 hours; `hours` narrows or widens "
             + "it. An event already running is included, so this also answers 'what am I in?'.",
-        inputSchema: { ...windowInput, hours: z.number().int().min(1).max(720).optional() },
+        inputSchema: { ...windowInput, hours: z.number().int().min(1).max(720).optional().describe("How far ahead to look, in hours. Default 72.") },
     }, async (args) => withSession(deps, async (session) => {
         const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/cal/next${queryString(windowQuery(args))}`);
         if (!response.ok)
@@ -130,9 +130,9 @@ export function registerCalTools(server, deps) {
             + "\"when is standup\". A repeating event is answered with the NEXT time it happens, never with its first "
             + "occurrence two years ago.",
         inputSchema: {
-            query: z.string().min(1).max(400),
-            calendar_id: z.string().uuid().optional(),
-            limit: z.number().int().min(1).max(100).optional(),
+            query: z.string().min(1).max(400).describe("Words to find in an event's title, location or description."),
+            calendar_id: z.string().uuid().optional().describe("One calendar id (cal_calendars). Omit for every calendar you may read."),
+            limit: z.number().int().min(1).max(100).optional().describe("At most this many matches."),
         },
     }, async (args) => withSession(deps, async (session) => {
         const query = new URLSearchParams({ q: String(args.query ?? "") });
@@ -174,14 +174,14 @@ export function registerCalTools(server, deps) {
             + "says so by name. Times are ISO instants, or plain dates with all_day. Requires confirm: true, because "
             + "attendees are emailed by Google the moment this succeeds.",
         inputSchema: {
-            calendar_id: z.string().uuid(),
-            title: z.string().min(1).max(500),
-            starts_at: z.string().min(4).max(40),
-            ends_at: z.string().min(4).max(40),
-            location: z.string().max(1_000).optional(),
-            all_day: z.boolean().optional(),
-            time_zone: z.string().min(1).max(80).optional(),
-            attendees: z.array(z.string().email()).max(100).optional(),
+            calendar_id: z.string().uuid().describe("A google_oauth calendar id you own (cal_calendars)."),
+            title: z.string().min(1).max(500).describe("The event title."),
+            starts_at: z.string().min(4).max(40).describe("An ISO instant, or a YYYY-MM-DD date with all_day."),
+            ends_at: z.string().min(4).max(40).describe("An ISO instant, or a YYYY-MM-DD date with all_day."),
+            location: z.string().max(1_000).optional().describe("Where it happens."),
+            all_day: z.boolean().optional().describe("true: starts_at and ends_at are dates, not instants."),
+            time_zone: z.string().min(1).max(80).optional().describe("An IANA zone for the event. Default: this machine's zone."),
+            attendees: z.array(EMAIL_INPUT).max(100).optional().describe("Email addresses to invite. Google emails each one."),
             meet: z.boolean().optional().describe("Attach a Google Meet room (BLI-3810). If Google refuses, the event is still created and the answer says meet_not_available."),
             confirm: CONFIRM_INPUT,
         },
@@ -217,8 +217,8 @@ export function registerCalTools(server, deps) {
             + "else change it — only the owner writes. Requires confirm: true: making somebody's day visible to nine people "
             + "is not something to do because a sentence sounded like it.",
         inputSchema: {
-            calendar_id: z.string().uuid(),
-            org_visible: z.boolean(),
+            calendar_id: z.string().uuid().describe("A calendar id you own (cal_calendars)."),
+            org_visible: z.boolean().describe("true: everyone at the org may read it. false: private again."),
             confirm: CONFIRM_INPUT,
         },
     }, async (args) => withSession(deps, async (session) => {
@@ -241,7 +241,10 @@ export function registerCalTools(server, deps) {
         description: "Runs one sync pass for a calendar you OWN, instead of waiting for the 15-minute cron. `full: true` ignores the "
             + "sync token / ETag and re-reads everything. The answer is the run's own counts and reason label, which is "
             + "exactly what the ledger row says.",
-        inputSchema: { calendar_id: z.string().uuid(), full: z.boolean().optional() },
+        inputSchema: {
+            calendar_id: z.string().uuid().describe("A calendar id you own (cal_calendars)."),
+            full: z.boolean().optional().describe("true: ignore the sync token and re-read everything."),
+        },
     }, async (args) => withSession(deps, async (session) => {
         const response = await callAgentDoor(session, deps.fetchImpl, "POST", `/api/cal/calendars/${encodeURIComponent(String(args.calendar_id))}/sync${args.full === true ? "?full=1" : ""}`);
         if (!response.ok)
@@ -259,7 +262,7 @@ export function registerCalTools(server, deps) {
         title: "Detach a calendar",
         description: "Removes a calendar and its stored events from Tower. The calendar itself is untouched at Google — this only "
             + "forgets it here. Requires confirm: true.",
-        inputSchema: { calendar_id: z.string().uuid(), confirm: CONFIRM_INPUT },
+        inputSchema: { calendar_id: z.string().uuid().describe("A calendar id you own (cal_calendars)."), confirm: CONFIRM_INPUT },
     }, async (args) => withSession(deps, async (session) => {
         const refusal = unconfirmed(args, "This would detach that calendar and forget its stored events (the calendar itself is untouched at Google).");
         if (refusal)

package/dist/careers-tools.d.ts

@@ -1,5 +1,11 @@
 import { type ToolDeps } from './tool-result.js';
 /**
+ * Every result here is a `dataResult`: the door's body rides in the text half
+ * as well as the structured one. These tools used to answer with one word
+ * ("Applications", "Resume link") in text, so on a Claude-family client, which
+ * shows the model only the text, the resume URL and every applicant were
+ * invisible (BLI-10432).
+ *
  * `careers_*` — the MCP twins of `cockpit careers`, over the same doors.
  *
  * BLI-4460 added the pipeline half: inviting, deciding, the role's take-home

package/dist/careers-tools.js

@@ -1,7 +1,32 @@
 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';
+/** Verbatim from `lib/careers/applications.ts` `PIPELINE_STAGES`. */
+const PIPELINE_STAGES = ['screened', 'invited', 'submitted', 'graded', 'booking_sent', 'passed_on', 'archived'];
+const APPLICATION_ID = z.string().uuid().describe('An application id, as careers_list returns it.');
 /**
+ * One list row without the screening's prose (BLI-10432). The door returns the
+ * whole screening object per row, summary sentences and quoted evidence
+ * included: about 2 KB an applicant, so the door's own 100-row page is ~200 KB.
+ * The list keeps what triage sorts on; careers_show reads the rest.
+ */
+function applicationListRow(row) {
+    const screening = row.screening && typeof row.screening === 'object' ? row.screening : {};
+    const { screening: _screening, ...rest } = row;
+    return {
+        ...rest,
+        score: typeof screening.score === 'number' ? screening.score : null,
+        recommend: typeof screening.recommend === 'string' ? screening.recommend : null,
+        flags: Array.isArray(screening.flags) ? screening.flags : [],
+    };
+}
+/**
+ * Every result here is a `dataResult`: the door's body rides in the text half
+ * as well as the structured one. These tools used to answer with one word
+ * ("Applications", "Resume link") in text, so on a Claude-family client, which
+ * shows the model only the text, the resume URL and every applicant were
+ * invisible (BLI-10432).
+ *
  * `careers_*` — the MCP twins of `cockpit careers`, over the same doors.
  *
  * BLI-4460 added the pipeline half: inviting, deciding, the role's take-home
@@ -17,18 +42,40 @@ import { doorFailureText, errorResult, registrarFor, textResult, withSession } f
  */
 export function registerCareersTools(server, deps) {
     const register = registrarFor(server);
-    register('careers_list', { title: 'List applications', description: 'Super-admin only. Newest applications, bounded to 100 with total and has_more, plus the two thresholds in force.', inputSchema: { role: z.string().optional(), min_score: z.number().min(0).max(100).optional(), since: z.string().optional(), stage: z.string().optional() } }, async (args) => withSession(deps, async (session) => {
+    register('careers_list', {
+        title: 'List applications',
+        description: 'Super-admin only. Newest applications first: id, name, role, stage, screening score, recommendation and flags, with total and has_more, plus the two thresholds in force. Page with limit (default 100, max 200) and offset. The screening prose is not in the list; careers_show reads one application in full.',
+        inputSchema: {
+            role: z.string().min(1).max(200).optional().describe('A role slug, e.g. fde-intern-2027 (the role_slug careers_list returns).'),
+            min_score: z.number().min(0).max(100).optional().describe('Only applications whose screening scored at least this (0-100).'),
+            since: z.string().min(1).max(40).optional().describe('ISO-8601 instant with an offset, e.g. 2026-09-01T00:00:00Z: applied at or after.'),
+            until: z.string().min(1).max(40).optional().describe('ISO-8601 instant with an offset: applied before.'),
+            stage: z.enum(PIPELINE_STAGES).optional().describe('Only applications at this pipeline stage.'),
+            limit: z.number().int().min(1).max(200).optional().describe('At most this many rows. Default 100.'),
+            offset: z.number().int().min(0).max(100_000).optional().describe('Skip this many rows first, for the next page.'),
+        },
+    }, async (args) => withSession(deps, async (session) => {
         const query = new URLSearchParams();
-        for (const key of ['role', 'min_score', 'since', 'stage'])
+        for (const key of ['role', 'min_score', 'since', 'until', 'stage', 'limit', 'offset'])
             if (args[key] !== undefined)
                 query.set(key, String(args[key]));
         const answer = await callAgentDoor(session, deps.fetchImpl, 'GET', `/api/careers/applications?${query}`);
-        return answer.ok ? textResult('Applications', answer.body) : errorResult(doorFailureText('careers_list', answer));
+        if (!answer.ok)
+            return errorResult(doorFailureText('careers_list', answer));
+        const rows = (Array.isArray(answer.body.applications) ? answer.body.applications : []);
+        const body = { ...answer.body, applications: rows.map(applicationListRow) };
+        return dataResult(`${rows.length} of ${String(answer.body.total ?? rows.length)} application(s)${answer.body.has_more === true ? ', more with offset' : ''}.`, body);
     }));
     for (const action of ['show', 'rescreen'])
-        register(`careers_${action}`, { title: `${action} application`, description: `Super-admin only. ${action} one application.`, inputSchema: { id: z.string().uuid() } }, async (args) => withSession(deps, async (session) => {
+        register(`careers_${action}`, {
+            title: action === 'show' ? 'Show one application' : 'Screen one application again',
+            description: action === 'show'
+                ? 'Super-admin only. One application in full: the answers, the screening (score, summary, quoted evidence, flags), stage and grade.'
+                : 'Super-admin only. Runs the screening again for one application and stores the new result. Spends one model call.',
+            inputSchema: { id: APPLICATION_ID },
+        }, async (args) => withSession(deps, async (session) => {
             const answer = await callAgentDoor(session, deps.fetchImpl, action === 'show' ? 'GET' : 'POST', `/api/careers/applications/${encodeURIComponent(String(args.id))}${action === 'rescreen' ? '/rescreen' : ''}`, undefined, 60_000);
-            return answer.ok ? textResult('Application', answer.body) : errorResult(doorFailureText(`careers_${action}`, answer));
+            return answer.ok ? dataResult(action === 'show' ? 'Application' : 'Screened again', answer.body) : errorResult(doorFailureText(`careers_${action}`, answer));
         }));
     // Two names, ONE door (BLI-4460 follow-up). Tower's button says "Send
     // take-home" and this tool said `invite`, so an agent reading the screen and
@@ -43,18 +90,18 @@ export function registerCareersTools(server, deps) {
         register(tool, {
             title: 'Send the take-home',
             description,
-            inputSchema: { id: z.string().uuid() },
+            inputSchema: { id: APPLICATION_ID },
         }, async (args) => withSession(deps, async (session) => {
             const answer = await callAgentDoor(session, deps.fetchImpl, 'POST', `/api/careers/applications/${encodeURIComponent(String(args.id))}/invite`, undefined, 60_000);
-            return answer.ok ? textResult('Invitation sent', answer.body) : errorResult(doorFailureText(tool, answer));
+            return answer.ok ? dataResult('Invitation sent', answer.body) : errorResult(doorFailureText(tool, answer));
         }));
     register('careers_grade', {
         title: 'Re-queue a take-home for grading',
-        description: 'Super-admin only. Puts one submitted or graded application back in the take-home grader\'s queue. The grader runs on Railway every 15 minutes because it clones a repository and reads a video; `now` is answered honestly rather than run here.',
-        inputSchema: { id: z.string().uuid(), now: z.boolean().optional() },
+        description: 'Super-admin only. Puts one submitted or graded application back in the take-home grader\'s queue. The grader runs on Railway every 5 minutes because it clones a repository and reads a video; `now` is answered honestly rather than run here.',
+        inputSchema: { id: APPLICATION_ID, now: z.boolean().optional().describe('Ask for an immediate grade. Answered honestly: the grader only runs on its Railway schedule.') },
     }, async (args) => withSession(deps, async (session) => {
         const answer = await callAgentDoor(session, deps.fetchImpl, 'POST', `/api/careers/applications/${encodeURIComponent(String(args.id))}/grade`, { now: args.now === true }, 60_000);
-        return answer.ok ? textResult('Queued for grading', answer.body) : errorResult(doorFailureText('careers_grade', answer));
+        return answer.ok ? dataResult('Queued for grading', answer.body) : errorResult(doorFailureText('careers_grade', answer));
     }));
     // BLI-4462. The drawer has an "Open resume" button and this surface had no
     // word for it, so an agent could read every screening line about a candidate
@@ -65,7 +112,7 @@ export function registerCareersTools(server, deps) {
     register('careers_resume_url', {
         title: 'Link to a resume',
         description: 'Super-admin only. A signed link to one applicant\'s resume file, the same one the Open resume button uses. THE LINK DIES IN 60 SECONDS: fetch it and read it in the same turn, never store it. An application with no resume on file is refused rather than answered with an empty link.',
-        inputSchema: { id: z.string().uuid() },
+        inputSchema: { id: APPLICATION_ID },
     }, async (args) => withSession(deps, async (session) => {
         const answer = await callAgentDoor(session, deps.fetchImpl, 'GET', `/api/careers/applications/${encodeURIComponent(String(args.id))}/resume-url`);
         if (!answer.ok)
@@ -74,39 +121,39 @@ export function registerCareersTools(server, deps) {
         // `expires_in_seconds`, because 60 with no unit reads as minutes.
         const body = (answer.body ?? {});
         const expires = typeof body.expires_in === 'number' && body.expires_in > 0 ? body.expires_in : 60;
-        return textResult('Resume link', { url: body.url, expires_in_seconds: expires });
+        return dataResult(`Resume link, valid for ${expires} seconds:`, { url: body.url, expires_in_seconds: expires });
     }));
     register('careers_decide', {
         title: 'Decide on an application',
         description: 'Super-admin only. Records the call on one application: `passed_on`, `archived`, or `reopen` to put it back at `screened`.',
-        inputSchema: { id: z.string().uuid(), decision: z.enum(['passed_on', 'archived', 'reopen']) },
+        inputSchema: { id: APPLICATION_ID, decision: z.enum(['passed_on', 'archived', 'reopen']).describe('passed_on, archived, or reopen (back to screened).') },
     }, async (args) => withSession(deps, async (session) => {
         const answer = await callAgentDoor(session, deps.fetchImpl, 'POST', `/api/careers/applications/${encodeURIComponent(String(args.id))}/decide`, { decision: args.decision });
-        return answer.ok ? textResult('Decision recorded', answer.body) : errorResult(doorFailureText('careers_decide', answer));
+        return answer.ok ? dataResult('Decision recorded', answer.body) : errorResult(doorFailureText('careers_decide', answer));
     }));
     register('careers_takehome_show', {
         title: 'Show a role take-home',
         description: 'Super-admin only. The subject, body, artifact link, reviewer rubric and pass score for one role. The rubric is reviewer material and never reaches a candidate.',
-        inputSchema: { role: z.string().min(1).max(200) },
+        inputSchema: { role: z.string().min(1).max(200).describe('A role slug, e.g. fde-intern-2027 (the role_slug careers_list returns).') },
     }, async (args) => withSession(deps, async (session) => {
         const answer = await callAgentDoor(session, deps.fetchImpl, 'GET', `/api/careers/takehomes/${encodeURIComponent(String(args.role))}`);
-        return answer.ok ? textResult('Take-home', answer.body) : errorResult(doorFailureText('careers_takehome_show', answer));
+        return answer.ok ? dataResult('Take-home', answer.body) : errorResult(doorFailureText('careers_takehome_show', answer));
     }));
     register('careers_takehome_set', {
         title: 'Edit a role take-home',
         description: 'Super-admin only. Edits one role\'s take-home. A body must keep the {first_name} and {link} placeholders. A role nobody seeded is refused rather than created.',
         inputSchema: {
-            role: z.string().min(1).max(200),
-            subject: z.string().min(1).max(998).optional(),
-            body_text: z.string().min(1).max(100_000).optional(),
-            artifact_link: z.string().url().max(2_000).optional(),
-            rubric_md: z.string().min(1).max(100_000).optional(),
-            pass_score: z.number().min(0).max(10).optional(),
+            role: z.string().min(1).max(200).describe('A role slug, e.g. fde-intern-2027.'),
+            subject: z.string().min(1).max(998).optional().describe('The invitation email subject.'),
+            body_text: z.string().min(1).max(100_000).optional().describe('The invitation body. Must keep the {first_name} and {link} placeholders.'),
+            artifact_link: z.string().url().max(2_000).optional().describe('A link to the take-home brief or starter repository.'),
+            rubric_md: z.string().min(1).max(100_000).optional().describe('The reviewer rubric, markdown. Never sent to a candidate.'),
+            pass_score: z.number().min(0).max(10).optional().describe('The grade (0-10) that passes.'),
         },
     }, async (args) => withSession(deps, async (session) => {
         const { role, ...patch } = args;
         const answer = await callAgentDoor(session, deps.fetchImpl, 'PUT', `/api/careers/takehomes/${encodeURIComponent(String(role))}`, patch);
-        return answer.ok ? textResult('Take-home saved', answer.body) : errorResult(doorFailureText('careers_takehome_set', answer));
+        return answer.ok ? dataResult('Take-home saved', answer.body) : errorResult(doorFailureText('careers_takehome_set', answer));
     }));
     register('careers_settings_show', {
         title: 'Show the careers settings',
@@ -114,21 +161,21 @@ export function registerCareersTools(server, deps) {
         inputSchema: {},
     }, async () => withSession(deps, async (session) => {
         const answer = await callAgentDoor(session, deps.fetchImpl, 'GET', '/api/careers/settings');
-        return answer.ok ? textResult('Careers settings', answer.body) : errorResult(doorFailureText('careers_settings_show', answer));
+        return answer.ok ? dataResult('Careers settings', answer.body) : errorResult(doorFailureText('careers_settings_show', answer));
     }));
     register('careers_settings_set', {
         title: 'Change the careers settings',
         description: 'Super-admin only. Writes any of the four careers settings. Each takes effect on the next screening, with no deploy.',
         inputSchema: {
-            auto_invite_enabled: z.boolean().optional(),
-            auto_invite_min_score: z.number().min(0).max(100).optional(),
-            attention_min_score: z.number().min(0).max(100).optional(),
-            invite_account_id: z.string().uuid().nullable().optional(),
-            booking_link: z.string().url().max(2000).nullable().optional(),
-            grader_model: z.string().min(3).max(200).optional(),
+            auto_invite_enabled: z.boolean().optional().describe('Send the take-home automatically to applicants over the auto-invite bar.'),
+            auto_invite_min_score: z.number().min(0).max(100).optional().describe('The screening score (0-100) at or over which the take-home goes out automatically.'),
+            attention_min_score: z.number().min(0).max(100).optional().describe('The screening score (0-100) at or over which an applicant is flagged for attention.'),
+            invite_account_id: z.string().uuid().nullable().optional().describe('The mailbox id (mail_accounts) invitations are sent from; null clears it.'),
+            booking_link: z.string().url().max(2000).nullable().optional().describe('The interview booking link sent after a passing grade; null clears it.'),
+            grader_model: z.string().min(3).max(200).optional().describe('The take-home grader model, provider:model (models_list ids).'),
         },
     }, async (args) => withSession(deps, async (session) => {
         const answer = await callAgentDoor(session, deps.fetchImpl, 'PUT', '/api/careers/settings', args);
-        return answer.ok ? textResult('Careers settings saved', answer.body) : errorResult(doorFailureText('careers_settings_set', answer));
+        return answer.ok ? dataResult('Careers settings saved', answer.body) : errorResult(doorFailureText('careers_settings_set', answer));
     }));
 }