llm-cli-gateway 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to the llm-cli-gateway project.
 
 ## Unreleased
 
+## [2.2.0] - 2026-06-07: MCP tool-surface usability — self-describing tools
+
+### Added
+
+- MCP tool-surface usability (4-seat cross-LLM review): all 37 tools now carry
+  action descriptions (previously none had tool-level descriptions — clients
+  that rank, search, or defer tools by description saw bare names); sync
+  `*_request` descriptions state the prompt/promptParts exactly-one rule and
+  conditional deferral; `job_status`/`job_result` vs `llm_job_*` and the
+  local-only `compare_answers` are disambiguated; session/`sessionId`
+  describes gain per-provider resume semantics parity.
+
+### Fixed
+
+- Codex gateway-bookkeeping sessions are now created with the reserved `gw-`
+  prefix (4 sites), so resuming a gateway ID fails fast with an actionable
+  error instead of reaching `codex exec resume` and dying with "no rollout
+  found" (root cause of real-world resume failures).
+- Server instructions are now built per-server from the same derived gate as
+  tool registration (backend, asyncJobsEnabled, hasStore()), so a
+  `backend = "none"` gateway no longer advertises unregistered
+  `*_request_async`/`llm_job_*` tools.
+- Sync auto-deferral is disabled when async jobs are unavailable — previously
+  a request could defer into an in-memory job whose polling tools were not
+  registered (dead-end jobId).
+
 ## [2.1.0] - 2026-06-07: Grok Build 0.2.32, probe drift acknowledgement, docs currency
 
 ### Added

package/dist/index.d.ts

@@ -44,6 +44,7 @@ declare const logger: {
     debug: (message: string, ...args: any[]) => void;
 };
 type GatewayLogger = typeof logger;
+export declare function buildServerInstructions(asyncJobsEnabled: boolean): string;
 export declare const MAX_TURNS_SCHEMA: z.ZodNumber;
 export declare const MAX_TOKENS_SCHEMA: z.ZodNumber;
 export declare const MAX_PRICE_SCHEMA: z.ZodNumber;

package/dist/index.js

@@ -141,16 +141,21 @@ function loadSkills() {
     return skills;
 }
 const loadedSkills = loadSkills();
-const SERVER_INSTRUCTIONS = `llm-cli-gateway: Multi-LLM orchestration via MCP.
+export function buildServerInstructions(asyncJobsEnabled) {
+    const asyncToolsNote = asyncJobsEnabled ? " | *_request_async (async)" : "";
+    const jobsLine = asyncJobsEnabled ? "Jobs: llm_job_status, llm_job_result, llm_job_cancel\n" : "";
+    const deferralLine = asyncJobsEnabled
+        ? `- Sync auto-defers at ${SYNC_DEADLINE_MS}ms. Poll deferred jobs via llm_job_status/llm_job_result.`
+        : '- Async jobs are DISABLED (persistence.backend = "none"): *_request_async and llm_job_* tools are not registered, and sync requests run to completion (no auto-deferral).';
+    return `llm-cli-gateway: Multi-LLM orchestration via MCP.
 
-Tools: claude_request, codex_request, gemini_request, grok_request, mistral_request (sync) | *_request_async (async) | codex_fork_session (fork a Codex session into a new branch)
+Tools: claude_request, codex_request, gemini_request, grok_request, mistral_request (sync)${asyncToolsNote} | codex_fork_session (fork a Codex session into a new branch)
 Validation: validate_with_models, second_opinion, compare_answers, red_team_review, consensus_check, ask_model, synthesize_validation, list_available_models | job_status/job_result (validation jobs)
-Jobs: llm_job_status, llm_job_result, llm_job_cancel
-Sessions: session_create, session_list, session_set_active, session_get, session_delete, session_clear_all
+${jobsLine}Sessions: session_create, session_list, session_set_active, session_get, session_delete, session_clear_all
 Other: list_models, cli_versions, upstream_contracts (use --probe-installed after CLI upgrades to detect drift), cli_upgrade, approval_list, llm_process_health, llm_request_result (read back any persisted request — sync or async — by correlationId)
 
 Key behaviors:
-- Sync auto-defers at ${SYNC_DEADLINE_MS}ms. Poll deferred jobs via llm_job_status/llm_job_result.
+${deferralLine}
 - Sessions: Claude --continue, Gemini --resume, Grok --resume/--continue, Mistral --resume/--continue (current Vibe defaults session logging on; doctor flags explicit session_logging.enabled=false), Codex \`exec resume <ID>\` / \`exec resume --last\` (all real CLI continuity). For Codex, sessionId must be a real Codex UUID (from ~/.codex/sessions/); gateway-generated gw-* IDs are rejected.
 - Approval gates: opt-in via approvalStrategy:"mcp_managed".
 - Upstream drift detection: After upgrading any provider CLI (especially grok), use the upstream_contracts tool with probeInstalled: true (or the CLI command "llm-cli-gateway contracts --json --probe-installed"). This is the primary reliable way to detect when an installed binary has gained or lost flags compared to the gateway's declared contract. The probe is safe and read-only.
@@ -158,8 +163,9 @@ Key behaviors:
 
 Skills (full docs via MCP resources):
 ${loadedSkills.map(s => `- skills://${s.name} — ${s.description}`).join("\n")}`;
-function newGatewayMcpServer() {
-    return new McpServer({ name: "llm-cli-gateway", version: packageVersion() }, { instructions: SERVER_INSTRUCTIONS });
+}
+function newGatewayMcpServer(asyncJobsEnabled = true) {
+    return new McpServer({ name: "llm-cli-gateway", version: packageVersion() }, { instructions: buildServerInstructions(asyncJobsEnabled) });
 }
 let sessionManager;
 let db = null;
@@ -307,7 +313,10 @@ async function awaitJobOrDefer(cli, args, corrId, idleTimeoutMs, outputFormat, f
         consumeOnComplete();
         throw err;
     }
-    if (SYNC_DEADLINE_MS === 0) {
+    const deferralAvailable = runtime.persistence.backend !== "none" &&
+        runtime.persistence.asyncJobsEnabled &&
+        runtime.asyncJobManager.hasStore();
+    if (SYNC_DEADLINE_MS === 0 || !deferralAvailable) {
         const command = cli === "mistral" ? "vibe" : cli;
         try {
             return await executeCli(command, args, {
@@ -2503,7 +2512,7 @@ export async function handleCodexRequestAsync(deps, params) {
                 effectiveSessionId = activeSession.id;
             }
             else {
-                const newSession = await deps.sessionManager.createSession("codex", "Codex Session");
+                const newSession = await deps.sessionManager.createSession("codex", "Codex Session", `${GATEWAY_SESSION_PREFIX}${randomUUID()}`);
                 effectiveSessionId = newSession.id;
             }
         }
@@ -2511,7 +2520,7 @@ export async function handleCodexRequestAsync(deps, params) {
             await deps.sessionManager.updateSessionUsage(params.sessionId);
         }
         else if (params.createNewSession) {
-            const newSession = await deps.sessionManager.createSession("codex", "Codex Session");
+            const newSession = await deps.sessionManager.createSession("codex", "Codex Session", `${GATEWAY_SESSION_PREFIX}${randomUUID()}`);
             effectiveSessionId = newSession.id;
         }
         let worktreeResolution = {};
@@ -2567,10 +2576,10 @@ export function createGatewayServer(deps = {}) {
     void flightRecorder;
     void cacheAwareness;
     const asyncJobsEnabled = persistence.backend !== "none" && persistence.asyncJobsEnabled && asyncJobManager.hasStore();
-    const server = newGatewayMcpServer();
+    const server = newGatewayMcpServer(asyncJobsEnabled);
     registerBaseResources(server, runtime);
     registerValidationTools(server, { asyncJobManager });
-    server.tool("claude_request", {
+    server.tool("claude_request", "Run a Claude Code CLI request synchronously (when async jobs are enabled, auto-defers to a pollable job past the sync deadline; otherwise runs to completion). Requires exactly one of prompt or promptParts.", {
         prompt: z
             .string()
             .min(1, "Prompt cannot be empty")
@@ -2586,8 +2595,14 @@ export function createGatewayServer(deps = {}) {
             .enum(["text", "json", "stream-json"])
             .default("stream-json")
             .describe("Output format (text|json|stream-json). DEFAULT: stream-json — the gateway parses NDJSON usage events to extract input/output/cache_read/cache_creation tokens + cost + model, persists them to the flight recorder for cache_state aggregates, and still returns the assistant text. Override to 'text' only when you truly want unparsed stdout (loses observability)."),
-        sessionId: z.string().optional().describe("Session ID (uses active if omitted)"),
-        continueSession: z.boolean().default(false).describe("Continue active session"),
+        sessionId: z
+            .string()
+            .optional()
+            .describe("Gateway session record to associate (uses the active session if omitted). Claude continuity itself is via continueSession (--continue); this ID is gateway bookkeeping, not a Claude-native session."),
+        continueSession: z
+            .boolean()
+            .default(false)
+            .describe("Continue the most recent Claude conversation in this cwd (emits --continue; real CLI continuity)."),
         createNewSession: z.boolean().default(false).describe("Force new session"),
         allowedTools: z
             .array(z.string())
@@ -2897,7 +2912,7 @@ export function createGatewayServer(deps = {}) {
             performanceMetrics.recordRequest("claude", finalizedDurationMs, wasSuccessful);
         }
     });
-    server.tool("codex_request", {
+    server.tool("codex_request", "Run an OpenAI Codex CLI request synchronously (when async jobs are enabled, auto-defers to a pollable job past the sync deadline; otherwise runs to completion). Requires exactly one of prompt or promptParts.", {
         prompt: z
             .string()
             .min(1, "Prompt cannot be empty")
@@ -3089,7 +3104,7 @@ export function createGatewayServer(deps = {}) {
                     effectiveSessionId = activeSession.id;
                 }
                 else {
-                    const newSession = await sessionManager.createSession("codex", "Codex Session");
+                    const newSession = await sessionManager.createSession("codex", "Codex Session", `${GATEWAY_SESSION_PREFIX}${randomUUID()}`);
                     effectiveSessionId = newSession.id;
                 }
             }
@@ -3097,7 +3112,7 @@ export function createGatewayServer(deps = {}) {
                 await sessionManager.updateSessionUsage(sessionId);
             }
             else if (createNewSession) {
-                const newSession = await sessionManager.createSession("codex", "Codex Session");
+                const newSession = await sessionManager.createSession("codex", "Codex Session", `${GATEWAY_SESSION_PREFIX}${randomUUID()}`);
                 effectiveSessionId = newSession.id;
             }
             logger.info(`[${corrId}] codex_request completed successfully in ${durationMs}ms`);
@@ -3145,7 +3160,7 @@ export function createGatewayServer(deps = {}) {
             performanceMetrics.recordRequest("codex", finalizedDurationMs, wasSuccessful);
         }
     });
-    server.tool("codex_fork_session", {
+    server.tool("codex_fork_session", "Fork an existing Codex session into a new branch (codex fork <ID|--last>) and run a prompt against the fork without mutating the original.", {
         prompt: z
             .string()
             .min(1, "Prompt cannot be empty")
@@ -3232,7 +3247,7 @@ export function createGatewayServer(deps = {}) {
             performanceMetrics.recordRequest("codex", finalizedDurationMs, wasSuccessful);
         }
     });
-    server.tool("gemini_request", {
+    server.tool("gemini_request", "Run a Google Gemini CLI request synchronously (when async jobs are enabled, auto-defers to a pollable job past the sync deadline; otherwise runs to completion). Requires exactly one of prompt or promptParts.", {
         prompt: z
             .string()
             .min(1, "Prompt cannot be empty")
@@ -3244,7 +3259,10 @@ export function createGatewayServer(deps = {}) {
             .string()
             .optional()
             .describe("Model name or alias (e.g. gemini-3-pro-preview, gemini-2.5-flash, pro, flash, latest)"),
-        sessionId: z.string().optional().describe("Session ID or 'latest'"),
+        sessionId: z
+            .string()
+            .optional()
+            .describe("Gemini session ID to resume (emits --resume <id>), or 'latest' for the most recent session in this cwd"),
         resumeLatest: z.boolean().default(false).describe("Resume latest session"),
         createNewSession: z.boolean().default(false).describe("Force new session"),
         approvalMode: z
@@ -3328,7 +3346,7 @@ export function createGatewayServer(deps = {}) {
             worktree,
         });
     });
-    server.tool("grok_request", {
+    server.tool("grok_request", "Run an xAI Grok CLI request synchronously (when async jobs are enabled, auto-defers to a pollable job past the sync deadline; otherwise runs to completion). Requires exactly one of prompt or promptParts.", {
         prompt: z
             .string()
             .min(1, "Prompt cannot be empty")
@@ -3344,7 +3362,7 @@ export function createGatewayServer(deps = {}) {
         sessionId: z
             .string()
             .optional()
-            .describe("Session ID (user-provided CLI handle for --resume)"),
+            .describe("Provider-native session ID to resume (emits --resume <id>; use resumeLatest for --continue)"),
         resumeLatest: z
             .boolean()
             .default(false)
@@ -3557,7 +3575,7 @@ export function createGatewayServer(deps = {}) {
             worktree,
         });
     });
-    server.tool("mistral_request", {
+    server.tool("mistral_request", "Run a Mistral Vibe CLI request synchronously (when async jobs are enabled, auto-defers to a pollable job past the sync deadline; otherwise runs to completion). Requires exactly one of prompt or promptParts.", {
         prompt: z
             .string()
             .min(1, "Prompt cannot be empty")
@@ -3667,7 +3685,7 @@ export function createGatewayServer(deps = {}) {
         });
     });
     if (asyncJobsEnabled) {
-        server.tool("claude_request_async", {
+        server.tool("claude_request_async", "Start a Claude Code CLI request as a durable background job. Poll with llm_job_status, collect with llm_job_result.", {
             prompt: z
                 .string()
                 .min(1, "Prompt cannot be empty")
@@ -3683,8 +3701,14 @@ export function createGatewayServer(deps = {}) {
                 .enum(["text", "json", "stream-json"])
                 .default("stream-json")
                 .describe("Output format (text|json|stream-json). DEFAULT: stream-json — same rationale as claude_request: keeps usage/cache/cost observable for cache_state aggregates. Override to 'text' only when raw stdout is required (loses observability)."),
-            sessionId: z.string().optional().describe("Session ID (uses active if omitted)"),
-            continueSession: z.boolean().default(false).describe("Continue active session"),
+            sessionId: z
+                .string()
+                .optional()
+                .describe("Gateway session record to associate (uses the active session if omitted). Claude continuity itself is via continueSession (--continue); this ID is gateway bookkeeping, not a Claude-native session."),
+            continueSession: z
+                .boolean()
+                .default(false)
+                .describe("Continue the most recent Claude conversation in this cwd (emits --continue; real CLI continuity)."),
             createNewSession: z.boolean().default(false).describe("Force new session"),
             allowedTools: z
                 .array(z.string())
@@ -3920,7 +3944,7 @@ export function createGatewayServer(deps = {}) {
                 return createErrorResponse("claude_request_async", 1, "", corrId, error);
             }
         });
-        server.tool("codex_request_async", {
+        server.tool("codex_request_async", "Start an OpenAI Codex CLI request as a durable background job. Poll with llm_job_status, collect with llm_job_result.", {
             prompt: z
                 .string()
                 .min(1, "Prompt cannot be empty")
@@ -4045,7 +4069,7 @@ export function createGatewayServer(deps = {}) {
                 worktree,
             });
         });
-        server.tool("gemini_request_async", {
+        server.tool("gemini_request_async", "Start a Google Gemini CLI request as a durable background job. Poll with llm_job_status, collect with llm_job_result.", {
             prompt: z
                 .string()
                 .min(1, "Prompt cannot be empty")
@@ -4060,7 +4084,7 @@ export function createGatewayServer(deps = {}) {
             sessionId: z
                 .string()
                 .optional()
-                .describe("Session ID (user-provided CLI handle for --resume)"),
+                .describe("Gemini session ID to resume (emits --resume <id>), or 'latest' for the most recent session in this cwd"),
             resumeLatest: z.boolean().default(false).describe("Resume latest session"),
             createNewSession: z.boolean().default(false).describe("Force new session"),
             approvalMode: z
@@ -4142,7 +4166,7 @@ export function createGatewayServer(deps = {}) {
                 worktree,
             });
         });
-        server.tool("grok_request_async", {
+        server.tool("grok_request_async", "Start an xAI Grok CLI request as a durable background job. Poll with llm_job_status, collect with llm_job_result.", {
             prompt: z
                 .string()
                 .min(1, "Prompt cannot be empty")
@@ -4158,7 +4182,7 @@ export function createGatewayServer(deps = {}) {
             sessionId: z
                 .string()
                 .optional()
-                .describe("Session ID (user-provided CLI handle for --resume)"),
+                .describe("Provider-native session ID to resume (emits --resume <id>; use resumeLatest for --continue)"),
             resumeLatest: z
                 .boolean()
                 .default(false)
@@ -4372,7 +4396,7 @@ export function createGatewayServer(deps = {}) {
                 worktree,
             });
         });
-        server.tool("mistral_request_async", {
+        server.tool("mistral_request_async", "Start a Mistral Vibe CLI request as a durable background job. Poll with llm_job_status, collect with llm_job_result.", {
             prompt: z
                 .string()
                 .min(1, "Prompt cannot be empty")
@@ -4479,7 +4503,7 @@ export function createGatewayServer(deps = {}) {
                 worktree,
             });
         });
-        server.tool("llm_job_status", {
+        server.tool("llm_job_status", "Check lifecycle status (running|completed|failed|canceled|orphaned) of a gateway async or deferred-sync job by jobId.", {
             jobId: z.string().describe("Async job ID from *_request_async"),
         }, async ({ jobId }) => {
             const job = asyncJobManager.getJobSnapshot(jobId);
@@ -4510,7 +4534,7 @@ export function createGatewayServer(deps = {}) {
                 ],
             };
         });
-        server.tool("llm_job_result", {
+        server.tool("llm_job_result", "Retrieve captured stdout/stderr for a gateway async or deferred-sync job by jobId.", {
             jobId: z.string().describe("Async job ID from *_request_async"),
             maxChars: z
                 .number()
@@ -4564,7 +4588,7 @@ export function createGatewayServer(deps = {}) {
                 ],
             };
         });
-        server.tool("llm_job_cancel", {
+        server.tool("llm_job_cancel", "Cancel a running gateway async or deferred-sync job by jobId.", {
             jobId: z.string().describe("Async job ID from *_request_async"),
         }, async ({ jobId }) => {
             const cancel = asyncJobManager.cancelJob(jobId);
@@ -4596,7 +4620,7 @@ export function createGatewayServer(deps = {}) {
             };
         });
     }
-    server.tool("llm_request_result", {
+    server.tool("llm_request_result", "Read back any persisted request (sync or async) from the flight recorder by correlationId, including prompt and response.", {
         correlationId: z
             .string()
             .min(1)
@@ -4642,7 +4666,7 @@ export function createGatewayServer(deps = {}) {
             ],
         };
     });
-    server.tool("llm_process_health", {}, async () => {
+    server.tool("llm_process_health", "Report gateway process health: async-job manager state plus the resolved persistence configuration and paths.", {}, async () => {
         const health = asyncJobManager.getJobHealth();
         const persistenceBlock = {
             backend: persistence.backend,
@@ -4666,7 +4690,7 @@ export function createGatewayServer(deps = {}) {
             ],
         };
     });
-    server.tool("approval_list", {
+    server.tool("approval_list", "List recent MCP-managed approval decisions recorded by the gateway (approvalStrategy: mcp_managed).", {
         limit: z
             .number()
             .int()
@@ -4693,7 +4717,7 @@ export function createGatewayServer(deps = {}) {
             ],
         };
     });
-    server.tool("list_models", {
+    server.tool("list_models", "List models, aliases, and defaults for one provider CLI (claude|codex|gemini|grok|mistral).", {
         cli: z
             .preprocess(value => (value === "" || value === null ? undefined : value), z.enum(["claude", "codex", "gemini", "grok", "mistral"]).optional())
             .describe("CLI filter (claude|codex|gemini|grok|mistral)"),
@@ -4702,7 +4726,7 @@ export function createGatewayServer(deps = {}) {
         const result = cli ? { [cli]: cliInfo[cli] } : cliInfo;
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    server.tool("cli_versions", {
+    server.tool("cli_versions", "Report installed provider CLI versions, availability, and login status for all five providers or one.", {
         cli: z
             .preprocess(value => (value === "" || value === null ? undefined : value), z.enum(["claude", "codex", "gemini", "grok", "mistral"]).optional())
             .describe("CLI filter (claude|codex|gemini|grok|mistral)"),
@@ -4710,7 +4734,7 @@ export function createGatewayServer(deps = {}) {
         const versions = await getCliVersions(cli);
         return { content: [{ type: "text", text: JSON.stringify({ versions }, null, 2) }] };
     });
-    server.tool("upstream_contracts", {
+    server.tool("upstream_contracts", "Return the gateway's declared provider CLI contracts; with probeInstalled true, diff against installed --help surfaces to detect flag drift.", {
         cli: z
             .preprocess(value => (value === "" || value === null ? undefined : value), SESSION_PROVIDER_ENUM.optional())
             .describe("CLI filter (claude|codex|gemini|grok|mistral)"),
@@ -4722,7 +4746,7 @@ export function createGatewayServer(deps = {}) {
         const report = buildUpstreamContractReport({ cli, probeInstalled });
         return { content: [{ type: "text", text: JSON.stringify(report, null, 2) }] };
     });
-    server.tool("cli_upgrade", {
+    server.tool("cli_upgrade", "Plan (dryRun, default true) or execute an upgrade for one provider CLI using its native update mechanism.", {
         cli: z.enum(["claude", "codex", "gemini", "grok", "mistral"]).describe("CLI to upgrade"),
         target: z
             .string()
@@ -4771,7 +4795,7 @@ export function createGatewayServer(deps = {}) {
             };
         }
     });
-    server.tool("session_create", {
+    server.tool("session_create", "Create a gateway session record for a provider CLI. NOTE: this is gateway bookkeeping (gw-* ID), not a provider-native session — Codex resume needs a real Codex UUID.", {
         cli: SESSION_PROVIDER_ENUM.describe("CLI type (claude|codex|gemini|grok|mistral)"),
         description: z.string().optional().describe("Session description"),
         setAsActive: z.boolean().default(true).describe("Set as active session"),
@@ -4804,7 +4828,7 @@ export function createGatewayServer(deps = {}) {
             return createErrorResponse("session_create", 1, "", undefined, error);
         }
     });
-    server.tool("session_list", {
+    server.tool("session_list", "List gateway session records and the active session per CLI, optionally filtered by CLI.", {
         cli: SESSION_PROVIDER_ENUM.optional().describe("CLI filter (claude|codex|gemini|grok|mistral)"),
     }, async ({ cli }) => {
         try {
@@ -4847,7 +4871,7 @@ export function createGatewayServer(deps = {}) {
             return createErrorResponse("session_list", 1, "", undefined, error);
         }
     });
-    server.tool("session_set_active", {
+    server.tool("session_set_active", "Set or clear the active session for a CLI; the active session is used when a request omits sessionId.", {
         cli: SESSION_PROVIDER_ENUM.describe("CLI type (claude|codex|gemini|grok|mistral)"),
         sessionId: z.string().nullable().describe("Session ID (null to clear)"),
     }, async ({ cli, sessionId }) => {
@@ -4885,7 +4909,7 @@ export function createGatewayServer(deps = {}) {
             return createErrorResponse("session_set_active", 1, "", undefined, error);
         }
     });
-    server.tool("session_delete", {
+    server.tool("session_delete", "Delete a gateway session record by ID (also removes any gateway-owned worktree attached to it).", {
         sessionId: z.string().describe("Session ID"),
     }, async ({ sessionId }) => {
         try {
@@ -4926,7 +4950,7 @@ export function createGatewayServer(deps = {}) {
             return createErrorResponse("session_delete", 1, "", undefined, error);
         }
     });
-    server.tool("session_get", {
+    server.tool("session_get", "Get one gateway session record by session ID, including recent request history when available.", {
         sessionId: z.string().describe("Session ID"),
     }, async ({ sessionId }) => {
         try {
@@ -4989,7 +5013,7 @@ export function createGatewayServer(deps = {}) {
             return createErrorResponse("session_get", 1, "", undefined, error);
         }
     });
-    server.tool("session_clear_all", {
+    server.tool("session_clear_all", "Delete all gateway session records, optionally scoped to one CLI.", {
         cli: SESSION_PROVIDER_ENUM.optional().describe("CLI filter (claude|codex|gemini|grok|mistral)"),
     }, async ({ cli }) => {
         try {

package/dist/validation-tools.js

@@ -47,7 +47,7 @@ function findHumanReadableReport(value) {
     return null;
 }
 export function registerValidationTools(server, deps) {
-    server.tool("validate_with_models", {
+    server.tool("validate_with_models", "Ask two or more provider CLIs to independently validate a question. Starts validation jobs — poll with job_status, collect with job_result (not llm_job_*).", {
         question: z.string().min(1).describe("Question or content to validate."),
         models: providerListSchema.describe("Providers to ask. Defaults to Claude and Codex."),
         focus: z
@@ -69,7 +69,7 @@ export function registerValidationTools(server, deps) {
             judgeProvider: judgeModel,
         }),
     }));
-    server.tool("second_opinion", {
+    server.tool("second_opinion", "Ask one provider CLI to review an answer (starts a validation job; poll job_status, collect job_result).", {
         answer: z.string().min(1).describe("Answer to review."),
         question: z.string().optional().describe("Original question, if available."),
         model: providerSchema.default("codex").describe("Provider to ask for the second opinion."),
@@ -84,7 +84,7 @@ export function registerValidationTools(server, deps) {
             providers: [model],
         }),
     }));
-    server.tool("compare_answers", {
+    server.tool("compare_answers", "Summarize agreement/differences between caller-provided answers LOCALLY — does not call any provider.", {
         question: z.string().min(1).describe("Question the answers respond to."),
         answers: z.array(z.string().min(1)).min(2).describe("Two or more answers to compare."),
     }, async ({ question, answers }) => textResponse({
@@ -99,7 +99,7 @@ export function registerValidationTools(server, deps) {
             note: "Use validate_with_models when independent provider review is needed.",
         },
     }));
-    server.tool("red_team_review", {
+    server.tool("red_team_review", "Challenge a plan, answer, or document for risks and failure modes via provider CLIs (starts validation jobs).", {
         content: z.string().min(1).describe("Plan, answer, or document to challenge."),
         riskLevel: z
             .enum(["normal", "high"])
@@ -117,7 +117,7 @@ export function registerValidationTools(server, deps) {
             riskLevel,
         }),
     }));
-    server.tool("consensus_check", {
+    server.tool("consensus_check", "Ask provider CLIs whether they agree or disagree with a claim (starts validation jobs).", {
         claim: z.string().min(1).describe("Claim to check across providers."),
         models: providerListSchema.describe("Providers to ask for agreement or disagreement."),
     }, async ({ claim, models }) => textResponse({
@@ -130,7 +130,7 @@ export function registerValidationTools(server, deps) {
             providers: models,
         }),
     }));
-    server.tool("ask_model", {
+    server.tool("ask_model", "Ask one provider CLI a question through the simplified validation surface (starts a validation job).", {
         question: z.string().min(1).describe("Question for one provider."),
         model: providerSchema.default("claude").describe("Provider to ask."),
     }, async ({ question, model }) => textResponse({
@@ -143,7 +143,7 @@ export function registerValidationTools(server, deps) {
             providers: [model],
         }),
     }));
-    server.tool("synthesize_validation", {
+    server.tool("synthesize_validation", "Run an explicit judge model over already-collected validation results to produce a synthesis.", {
         question: z.string().min(1).describe("Original request that was validated."),
         providerResults: z
             .array(normalizedProviderResultSchema)
@@ -160,8 +160,8 @@ export function registerValidationTools(server, deps) {
             judgeProvider: judgeModel,
         }),
     }));
-    server.tool("list_available_models", {}, async () => textResponse({ success: true, models: getAvailableCliInfo() }));
-    server.tool("job_status", {
+    server.tool("list_available_models", "List models and capabilities for every available provider CLI (takes no arguments; complements per-provider list_models).", {}, async () => textResponse({ success: true, models: getAvailableCliInfo() }));
+    server.tool("job_status", "Check a VALIDATION job's status (jobs started by validate_with_models/ask_model/etc.) — distinct from llm_job_status, which tracks provider request jobs.", {
         jobId: z.string().min(1).describe("Validation job ID."),
     }, async ({ jobId }) => {
         const job = deps.asyncJobManager.getJobSnapshot(jobId);
@@ -170,7 +170,7 @@ export function registerValidationTools(server, deps) {
         }
         return textResponse({ success: true, job });
     });
-    server.tool("job_result", {
+    server.tool("job_result", "Collect a VALIDATION job's normalized provider output — distinct from llm_job_result, which returns raw provider request job output.", {
         jobId: z.string().min(1).describe("Validation job ID."),
         provider: providerSchema
             .optional()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-cli-gateway",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "mcpName": "io.github.verivus-oss/llm-cli-gateway",
   "description": "MCP server providing unified access to Claude Code, Codex, Gemini, Grok, and Mistral Vibe CLIs with session management, retry logic, async job orchestration, durable job results, and cross-LLM validation.",
   "license": "MIT",