llm-cli-gateway 2.2.0 → 2.3.0

package/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to the llm-cli-gateway project.
 
 ## Unreleased
 
+## [2.3.0] - 2026-06-08: MCP tool annotations and client safety hints
+
+### Added
+
+- MCP tool annotations for all 37 tools (per MCP spec + tool-design best
+  practice): display `title` plus `readOnlyHint`/`destructiveHint`/
+  `idempotentHint`/`openWorldHint` on every registration. 14 pure-read tools
+  marked read-only/closed-world; `cli_upgrade`, `session_delete`,
+  `session_clear_all`, `llm_job_cancel` marked destructive; every
+  provider-spawning tool (requests, fork, validation) marked open-world with
+  destructive potential (spawned agentic CLIs can modify the environment).
+  Clients can use the hints for confirmation UX and safe auto-approval. New
+  invariant test pins titles, the exact destructive/read-only/open-world
+  sets, and the readOnly+destructive contradiction ban.
+
 ## [2.2.0] - 2026-06-07: MCP tool-surface usability — self-describing tools
 
 ### Added
@@ -247,7 +262,7 @@ to end with a verdaccio reproduction.
 - Consumer `npm ls` exits ELSPROBLEMS: the pinned `tar-stream@3.1.7` sits
   outside `tar-fs`'s `^2.1.4` range. Inherent to the out-of-range pin; disappears
   in 2.0.0 (Phase B / node:sqlite) when the `better-sqlite3 → prebuild-install
-  → tar-fs` chain leaves the prod graph entirely.
+→ tar-fs` chain leaves the prod graph entirely.
 - Local-tarball installs still resolve `tar-stream@2.2.0` (shrinkwrap ignored on
   that path); the audit's advisory carve-out stays until Phase B.
 

package/dist/index.js

@@ -2718,6 +2718,12 @@ export function createGatewayServer(deps = {}) {
             .boolean()
             .default(false)
             .describe("Bypass dedup and force a fresh CLI run even if a recent identical request exists"),
+    }, {
+        title: "Claude Code request",
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
     }, async ({ prompt, promptParts, model, outputFormat, sessionId, continueSession, createNewSession, allowedTools, disallowedTools, dangerouslySkipPermissions, permissionMode, agent, agents, forkSession, systemPrompt, appendSystemPrompt, maxBudgetUsd, maxTurns, effort, excludeDynamicSystemPromptSections, fallbackModel, jsonSchema, addDir, noSessionPersistence, settingSources, settings, tools, worktree, approvalStrategy, approvalPolicy, mcpServers, strictMcpConfig, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, }) => {
         const startTime = Date.now();
         if (systemPrompt !== undefined && appendSystemPrompt !== undefined) {
@@ -3019,6 +3025,12 @@ export function createGatewayServer(deps = {}) {
             .optional()
             .describe("Codex --add-dir <DIR>: additional writable workspace directories. Emitted once per entry on new sessions only; resume inherits the original session's writable-dir policy."),
         worktree: WORKTREE_SCHEMA.optional(),
+    }, {
+        title: "Codex request",
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
     }, async ({ prompt, promptParts, model, fullAuto, sandboxMode, askForApproval, useLegacyFullAutoFlag, dangerouslyBypassApprovalsAndSandbox, approvalStrategy, approvalPolicy, mcpServers, sessionId, resumeLatest, createNewSession, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, outputFormat, outputSchema, search, profile, configOverrides, ephemeral, images, ignoreUserConfig, ignoreRules, workingDir, addDir, worktree, }) => {
         const startTime = Date.now();
         const prep = prepareCodexRequest({
@@ -3191,6 +3203,12 @@ export function createGatewayServer(deps = {}) {
             .max(3_600_000)
             .optional()
             .describe("Idle timeout in ms (min 30s, max 1h, omit=CLI default)"),
+    }, {
+        title: "Fork Codex session",
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
     }, async ({ prompt, sessionId, forkLast, model, sandboxMode, askForApproval, correlationId, idleTimeoutMs, }) => {
         const corrId = correlationId || randomUUID();
         const startTime = Date.now();
@@ -3317,6 +3335,12 @@ export function createGatewayServer(deps = {}) {
             .optional()
             .describe("Emit `--yolo` to auto-approve all actions. Equivalent to approvalMode 'yolo'; routed through the same approval gate. Under mcp_managed the gate still decides."),
         worktree: WORKTREE_SCHEMA.optional(),
+    }, {
+        title: "Gemini request",
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
     }, async ({ prompt, promptParts, model, sessionId, resumeLatest, createNewSession, approvalMode, approvalStrategy, approvalPolicy, mcpServers, allowedTools, includeDirs, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, outputFormat, sandbox, policyFiles, adminPolicyFiles, attachments, skipTrust, yolo, worktree, }) => {
         return handleGeminiRequest({ sessionManager, logger, runtime }, {
             prompt,
@@ -3521,6 +3545,12 @@ export function createGatewayServer(deps = {}) {
             .optional()
             .describe("Grok -w/--worktree: native CLI worktree flag (`true` → bare `--worktree`, string → named). NOT gateway slice λ `worktree`."),
         worktree: WORKTREE_SCHEMA.optional(),
+    }, {
+        title: "Grok request",
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
     }, async ({ prompt, promptParts, model, outputFormat, sessionId, resumeLatest, createNewSession, alwaysApprove, permissionMode, effort, reasoningEffort, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, maxTurns, workingDir, sandbox, rules, systemPromptOverride, allow, deny, compactionMode, compactionDetail, agent, bestOfN, check, disableWebSearch, todoGate, verbatim, agents, promptFile, promptJson, single, experimentalMemory, noAltScreen, noMemory, noPlan, noSubagents, oauth, restoreCode, leaderSocket, nativeWorktree, worktree, }) => {
         return handleGrokRequest({ sessionManager, logger, runtime }, {
             prompt,
@@ -3655,6 +3685,12 @@ export function createGatewayServer(deps = {}) {
             .optional()
             .describe("Vibe --add-dir <DIR>: additional writable workspace directories. Each entry is emitted as its own --add-dir instance (Vibe states this flag may be specified multiple times)."),
         worktree: WORKTREE_SCHEMA.optional(),
+    }, {
+        title: "Mistral Vibe request",
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
     }, async ({ prompt, promptParts, model, outputFormat, sessionId, resumeLatest, createNewSession, permissionMode, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, trust, maxTurns, maxPrice, maxTokens, workingDir, addDir, worktree, }) => {
         return handleMistralRequest({ sessionManager, logger, runtime }, {
             prompt,
@@ -3823,6 +3859,12 @@ export function createGatewayServer(deps = {}) {
                 .boolean()
                 .default(false)
                 .describe("Bypass dedup and force a fresh CLI run even if a recent identical request exists"),
+        }, {
+            title: "Claude Code request (async job)",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
         }, async ({ prompt, promptParts, model, outputFormat, sessionId, continueSession, createNewSession, allowedTools, disallowedTools, dangerouslySkipPermissions, permissionMode, agent, agents, forkSession, systemPrompt, appendSystemPrompt, maxBudgetUsd, maxTurns, effort, excludeDynamicSystemPromptSections, fallbackModel, jsonSchema, addDir, noSessionPersistence, settingSources, settings, tools, worktree, approvalStrategy, approvalPolicy, mcpServers, strictMcpConfig, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, }) => {
             if (systemPrompt !== undefined && appendSystemPrompt !== undefined) {
                 return createErrorResponse("claude", 1, "", correlationId, new Error("systemPrompt and appendSystemPrompt are mutually exclusive; use one or the other (not both)."));
@@ -4035,6 +4077,12 @@ export function createGatewayServer(deps = {}) {
                 .optional()
                 .describe("Codex --add-dir <DIR>: additional writable workspace directories (repeat per entry). New sessions only."),
             worktree: WORKTREE_SCHEMA.optional(),
+        }, {
+            title: "Codex request (async job)",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
         }, async ({ prompt, promptParts, model, fullAuto, sandboxMode, askForApproval, useLegacyFullAutoFlag, dangerouslyBypassApprovalsAndSandbox, approvalStrategy, approvalPolicy, mcpServers, sessionId, resumeLatest, createNewSession, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, outputFormat, outputSchema, search, profile, configOverrides, ephemeral, images, ignoreUserConfig, ignoreRules, workingDir, addDir, worktree, }) => {
             return handleCodexRequestAsync({ sessionManager, asyncJobManager, logger, runtime }, {
                 prompt,
@@ -4138,6 +4186,12 @@ export function createGatewayServer(deps = {}) {
                 .optional()
                 .describe("Emit `--yolo` to auto-approve all actions. Equivalent to approvalMode 'yolo'; routed through the same approval gate. Under mcp_managed the gate still decides."),
             worktree: WORKTREE_SCHEMA.optional(),
+        }, {
+            title: "Gemini request (async job)",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
         }, async ({ prompt, promptParts, model, sessionId, resumeLatest, createNewSession, approvalMode, approvalStrategy, approvalPolicy, mcpServers, allowedTools, includeDirs, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, outputFormat, sandbox, policyFiles, adminPolicyFiles, attachments, skipTrust, yolo, worktree, }) => {
             return handleGeminiRequestAsync({ sessionManager, asyncJobManager, logger, runtime }, {
                 prompt,
@@ -4343,6 +4397,12 @@ export function createGatewayServer(deps = {}) {
                 .optional()
                 .describe("Grok -w/--worktree: native CLI worktree flag (`true` → bare `--worktree`, string → named). NOT gateway slice λ `worktree`."),
             worktree: WORKTREE_SCHEMA.optional(),
+        }, {
+            title: "Grok request (async job)",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
         }, async ({ prompt, promptParts, model, outputFormat, sessionId, resumeLatest, createNewSession, alwaysApprove, permissionMode, effort, reasoningEffort, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, maxTurns, workingDir, sandbox, rules, systemPromptOverride, allow, deny, compactionMode, compactionDetail, agent, bestOfN, check, disableWebSearch, todoGate, verbatim, agents, promptFile, promptJson, single, experimentalMemory, noAltScreen, noMemory, noPlan, noSubagents, oauth, restoreCode, leaderSocket, nativeWorktree, worktree, }) => {
             return handleGrokRequestAsync({ sessionManager, asyncJobManager, logger, runtime }, {
                 prompt,
@@ -4475,6 +4535,12 @@ export function createGatewayServer(deps = {}) {
                 .optional()
                 .describe("Vibe --add-dir <DIR>: additional writable workspace directories. Each entry is emitted as its own --add-dir instance."),
             worktree: WORKTREE_SCHEMA.optional(),
+        }, {
+            title: "Mistral Vibe request (async job)",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
         }, async ({ prompt, promptParts, model, outputFormat, sessionId, resumeLatest, createNewSession, permissionMode, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, trust, maxTurns, maxPrice, maxTokens, workingDir, addDir, worktree, }) => {
             return handleMistralRequestAsync({ sessionManager, asyncJobManager, logger, runtime }, {
                 prompt,
@@ -4505,6 +4571,12 @@ export function createGatewayServer(deps = {}) {
         });
         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"),
+        }, {
+            title: "Async job status",
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
         }, async ({ jobId }) => {
             const job = asyncJobManager.getJobSnapshot(jobId);
             if (!job) {
@@ -4543,6 +4615,12 @@ export function createGatewayServer(deps = {}) {
                 .max(2000000)
                 .default(200000)
                 .describe("Max chars returned per stream"),
+        }, {
+            title: "Async job result",
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
         }, async ({ jobId, maxChars }) => {
             const result = asyncJobManager.getJobResult(jobId, maxChars);
             if (!result) {
@@ -4590,6 +4668,12 @@ export function createGatewayServer(deps = {}) {
         });
         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"),
+        }, {
+            title: "Cancel async job",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
         }, async ({ jobId }) => {
             const cancel = asyncJobManager.cancelJob(jobId);
             if (!cancel.canceled) {
@@ -4636,6 +4720,12 @@ export function createGatewayServer(deps = {}) {
             .boolean()
             .default(false)
             .describe("Include the full persisted prompt text in the result"),
+    }, {
+        title: "Persisted request lookup",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
     }, async ({ correlationId, maxChars, includePrompt }) => {
         const record = readPersistedRequest(flightRecorder, correlationId, {
             maxChars,
@@ -4666,7 +4756,13 @@ export function createGatewayServer(deps = {}) {
             ],
         };
     });
-    server.tool("llm_process_health", "Report gateway process health: async-job manager state plus the resolved persistence configuration and paths.", {}, async () => {
+    server.tool("llm_process_health", "Report gateway process health: async-job manager state plus the resolved persistence configuration and paths.", {}, {
+        title: "Gateway process health",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, async () => {
         const health = asyncJobManager.getJobHealth();
         const persistenceBlock = {
             backend: persistence.backend,
@@ -4702,6 +4798,12 @@ export function createGatewayServer(deps = {}) {
             .enum(["claude", "codex", "gemini", "grok", "mistral"])
             .optional()
             .describe("Optional CLI filter"),
+    }, {
+        title: "Approval decisions",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
     }, async ({ limit, cli }) => {
         const approvals = approvalManager.list(limit, cli);
         return {
@@ -4721,6 +4823,12 @@ export function createGatewayServer(deps = {}) {
         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)"),
+    }, {
+        title: "Provider models",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
     }, async ({ cli }) => {
         const cliInfo = getAvailableCliInfo();
         const result = cli ? { [cli]: cliInfo[cli] } : cliInfo;
@@ -4730,6 +4838,12 @@ export function createGatewayServer(deps = {}) {
         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)"),
+    }, {
+        title: "Provider CLI versions",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
     }, async ({ cli }) => {
         const versions = await getCliVersions(cli);
         return { content: [{ type: "text", text: JSON.stringify({ versions }, null, 2) }] };
@@ -4742,6 +4856,12 @@ export function createGatewayServer(deps = {}) {
             .boolean()
             .default(false)
             .describe("When true, run local --help probes and compare advertised flags against the declared contract. Strongly recommended after any provider CLI upgrade to detect drift."),
+    }, {
+        title: "Provider CLI contracts",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
     }, async ({ cli, probeInstalled }) => {
         const report = buildUpstreamContractReport({ cli, probeInstalled });
         return { content: [{ type: "text", text: JSON.stringify(report, null, 2) }] };
@@ -4764,6 +4884,12 @@ export function createGatewayServer(deps = {}) {
             .max(3_600_000)
             .optional()
             .describe("Upgrade timeout in ms when dryRun=false"),
+    }, {
+        title: "Upgrade provider CLI",
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
     }, async ({ cli, target, dryRun, timeoutMs }) => {
         try {
             const result = await runCliUpgrade({ cli, target, dryRun, timeoutMs, logger });
@@ -4799,6 +4925,12 @@ export function createGatewayServer(deps = {}) {
         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"),
+    }, {
+        title: "Create session record",
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
     }, async ({ cli, description, setAsActive }) => {
         try {
             const session = await sessionManager.createSession(cli, description);
@@ -4830,6 +4962,12 @@ export function createGatewayServer(deps = {}) {
     });
     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)"),
+    }, {
+        title: "List sessions",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
     }, async ({ cli }) => {
         try {
             const sessions = await sessionManager.listSessions(cli);
@@ -4874,6 +5012,12 @@ export function createGatewayServer(deps = {}) {
     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)"),
+    }, {
+        title: "Set active session",
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
     }, async ({ cli, sessionId }) => {
         try {
             const success = await sessionManager.setActiveSession(cli, sessionId || null);
@@ -4911,6 +5055,12 @@ export function createGatewayServer(deps = {}) {
     });
     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"),
+    }, {
+        title: "Delete session",
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
     }, async ({ sessionId }) => {
         try {
             const session = await sessionManager.getSession(sessionId);
@@ -4952,6 +5102,12 @@ export function createGatewayServer(deps = {}) {
     });
     server.tool("session_get", "Get one gateway session record by session ID, including recent request history when available.", {
         sessionId: z.string().describe("Session ID"),
+    }, {
+        title: "Get session",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
     }, async ({ sessionId }) => {
         try {
             const session = await sessionManager.getSession(sessionId);
@@ -5015,6 +5171,12 @@ export function createGatewayServer(deps = {}) {
     });
     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)"),
+    }, {
+        title: "Clear sessions",
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
     }, async ({ cli }) => {
         try {
             const count = await sessionManager.clearAllSessions(cli);

package/dist/validation-tools.js

@@ -57,6 +57,12 @@ export function registerValidationTools(server, deps) {
         judgeModel: providerSchema
             .optional()
             .describe("Optional provider to run an explicit judge synthesis job."),
+    }, {
+        title: "Multi-model validation",
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
     }, async ({ question, models, focus, judgeModel }) => textResponse({
         success: true,
         tool: "validate_with_models",
@@ -73,6 +79,12 @@ export function registerValidationTools(server, deps) {
         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."),
+    }, {
+        title: "Second opinion",
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
     }, async ({ answer, question, model }) => textResponse({
         success: true,
         tool: "second_opinion",
@@ -87,6 +99,12 @@ export function registerValidationTools(server, deps) {
     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."),
+    }, {
+        title: "Compare answers (local)",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
     }, async ({ question, answers }) => textResponse({
         success: true,
         tool: "compare_answers",
@@ -106,6 +124,12 @@ export function registerValidationTools(server, deps) {
             .default("normal")
             .describe("How aggressively to review."),
         models: providerListSchema.describe("Providers to ask for adversarial review."),
+    }, {
+        title: "Red-team review",
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
     }, async ({ content, riskLevel, models }) => textResponse({
         success: true,
         tool: "red_team_review",
@@ -120,6 +144,12 @@ export function registerValidationTools(server, deps) {
     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."),
+    }, {
+        title: "Consensus check",
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
     }, async ({ claim, models }) => textResponse({
         success: true,
         tool: "consensus_check",
@@ -133,6 +163,12 @@ export function registerValidationTools(server, deps) {
     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."),
+    }, {
+        title: "Ask one model",
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
     }, async ({ question, model }) => textResponse({
         success: true,
         tool: "ask_model",
@@ -150,6 +186,12 @@ export function registerValidationTools(server, deps) {
             .min(1)
             .describe("Terminal normalized provider results from job_result."),
         judgeModel: providerSchema.default("codex").describe("Provider to run the judge synthesis."),
+    }, {
+        title: "Synthesize validation",
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
     }, async ({ question, providerResults, judgeModel }) => textResponse({
         success: true,
         tool: "synthesize_validation",
@@ -160,9 +202,21 @@ export function registerValidationTools(server, deps) {
             judgeProvider: judgeModel,
         }),
     }));
-    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("list_available_models", "List models and capabilities for every available provider CLI (takes no arguments; complements per-provider list_models).", {}, {
+        title: "All provider models",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, 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."),
+    }, {
+        title: "Validation job status",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
     }, async ({ jobId }) => {
         const job = deps.asyncJobManager.getJobSnapshot(jobId);
         if (!job) {
@@ -182,6 +236,12 @@ export function registerValidationTools(server, deps) {
             .max(2000000)
             .default(200000)
             .describe("Maximum result size."),
+    }, {
+        title: "Validation job result",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
     }, async ({ jobId, provider, maxChars }) => {
         const result = deps.asyncJobManager.getJobResult(jobId, maxChars);
         if (!result) {

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "llm-cli-gateway",
-  "version": "2.0.0",
+  "version": "2.3.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "llm-cli-gateway",
-      "version": "2.0.0",
+      "version": "2.3.0",
       "license": "MIT",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.29.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-cli-gateway",
-  "version": "2.2.0",
+  "version": "2.3.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",