openlore 2.0.7 → 2.0.9

package/dist/cli/commands/mcp.js

@@ -22,14 +22,20 @@ const _pkgVersion = _require('../../../package.json').version;
 import { Command } from 'commander';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, InitializeRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { CallToolRequestSchema, InitializeRequestSchema, ListToolsRequestSchema, McpError, ErrorCode, LATEST_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS, } from '@modelcontextprotocol/sdk/types.js';
+import { validateToolArgs, withToolTimeout, capOutput, classifyToolError, } from '../../core/services/mcp-handlers/tool-guard.js';
 import { sanitizeMcpError, validateDirectory } from '../../core/services/mcp-handlers/utils.js';
 import { createTracker, updateTracker, getFreshnessSignal } from '../../core/services/mcp-handlers/epistemic-lease.js';
 import { emit } from '../../core/services/telemetry.js';
-import { DEFAULT_DRIFT_MAX_FILES } from '../../constants.js';
+import { DEFAULT_DRIFT_MAX_FILES, MCP_TOOL_MAX_BYTES } from '../../constants.js';
 import { handleGetCallGraph, handleGetSubgraph, handleAnalyzeImpact, handleGetLowRiskRefactorCandidates, handleGetLeafFunctions, handleGetCriticalHubs, handleGetGodFunctions, handleGetFileDependencies, handleTraceExecutionPath, } from '../../core/services/mcp-handlers/graph.js';
 import { handleSearchCode, handleSuggestInsertionPoints, handleSearchSpecs, handleListSpecDomains, handleGetSpec, handleUnifiedSearch, } from '../../core/services/mcp-handlers/semantic.js';
 import { handleOrient } from '../../core/services/mcp-handlers/orient.js';
+import { handleSelectTests } from '../../core/services/mcp-handlers/test-impact.js';
+import { handleFindDeadCode } from '../../core/services/mcp-handlers/reachability.js';
+import { handleStructuralDiff } from '../../core/services/mcp-handlers/structural-diff.js';
+import { handleGetChangeCoupling } from '../../core/services/mcp-handlers/change-coupling.js';
+import { handleCheckArchitecture } from '../../core/services/mcp-handlers/architecture.js';
 import { handleGenerateChangeProposal, handleAnnotateStory } from '../../core/services/mcp-handlers/change.js';
 import { handleRecordDecision, handleListDecisions, handleApproveDecision, handleRejectDecision, handleSyncDecisions, } from '../../core/services/mcp-handlers/decisions.js';
 import { handleAnalyzeCodebase, handleGetArchitectureOverview, handleGetRefactorReport, handleGetDuplicateReport, handleGetSignatures, handleGetMapping, handleCheckSpecDrift, handleGetFunctionSkeleton, handleGetFunctionBody, handleGetDecisions, handleGetRouteInventory, handleGetMiddlewareInventory, handleGetSchemaInventory, handleGetUIComponents, handleGetEnvVars, handleGetExternalPackages, handleAuditSpecCoverage, handleGenerateTests, handleGetTestCoverage, handleGetMinimalContext, handleGetCluster, handleDetectChanges, } from '../../core/services/mcp-handlers/analysis.js';
@@ -40,6 +46,11 @@ export { handleGetCallGraph, handleGetSubgraph, handleAnalyzeImpact, handleGetLo
 // ============================================================================
 // TOOL DEFINITIONS
 // ============================================================================
+// Spec 28 — the `directory` param is the one input every tool shares (50×). Its
+// description was a verbatim 38-char repeat on each tool; a single short shared
+// constant trims that lossless repeat from the cached tools/list prefix without
+// dropping the one fact that matters (it must be absolute, not relative).
+const DIR_DESC = 'Absolute project path';
 export const TOOL_DEFINITIONS = [
     {
         name: 'orient',
@@ -53,7 +64,7 @@ export const TOOL_DEFINITIONS = [
             properties: {
                 directory: {
                     type: 'string',
-                    description: 'Absolute path to the project directory',
+                    description: DIR_DESC,
                 },
                 task: {
                     type: 'string',
@@ -63,6 +74,14 @@ export const TOOL_DEFINITIONS = [
                     type: 'number',
                     description: 'Number of relevant functions to return (default: 5)',
                 },
+                tokenBudget: {
+                    type: 'number',
+                    description: 'Optional: cap relevantFunctions to ~this many tokens (highest-scored kept, exact duplicates collapsed); each item carries an `expand` handle for get_function_body',
+                },
+                lean: {
+                    type: 'boolean',
+                    description: 'Return only the navigation core (relevantFunctions + callPaths + specDomains); drop provenance/change-coupling/insertion-points/specs/decisions enrichment (each reachable via expand handles or dedicated tools). Lower per-call cost for shallow "who/where" lookups.',
+                },
             },
             required: ['directory', 'task'],
         },
@@ -91,8 +110,8 @@ export const TOOL_DEFINITIONS = [
     {
         name: 'get_architecture_overview',
         description: 'USE THIS WHEN: onboarding to an unknown codebase, or before planning a large feature. ' +
-            'Returns domain clusters, cross-cluster dependencies, global entry points, and critical hubs — ' +
-            'faster than reading package.json + directory tree yourself. Run analyze_codebase first.',
+            'Returns domain clusters, cross-cluster dependencies, global entry points, and critical hubs. ' +
+            'Run analyze_codebase first.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -125,14 +144,13 @@ export const TOOL_DEFINITIONS = [
         name: 'get_call_graph',
         description: 'Return the call graph for a project: hub functions (high fan-in), ' +
             'entry points (no internal callers), and architectural layer violations. ' +
-            'Supports TypeScript, JavaScript, Python, Go, Rust, Ruby, Java, C++. ' +
             'Run analyze_codebase first.',
         inputSchema: {
             type: 'object',
             properties: {
                 directory: {
                     type: 'string',
-                    description: 'Absolute path to the project directory',
+                    description: DIR_DESC,
                 },
             },
             required: ['directory'],
@@ -144,7 +162,7 @@ export const TOOL_DEFINITIONS = [
             'Detects Type 1 (exact clones — identical after whitespace/comment normalization), ' +
             'Type 2 (structural clones — same structure with renamed variables), and ' +
             'Type 3 (near-clones with Jaccard similarity ≥ 0.7 on token n-grams). ' +
-            'No LLM calls required. Run analyze_codebase first.',
+            'Run analyze_codebase first.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -166,7 +184,7 @@ export const TOOL_DEFINITIONS = [
             properties: {
                 directory: {
                     type: 'string',
-                    description: 'Absolute path to the project directory',
+                    description: DIR_DESC,
                 },
                 filePattern: {
                     type: 'string',
@@ -189,7 +207,7 @@ export const TOOL_DEFINITIONS = [
             properties: {
                 directory: {
                     type: 'string',
-                    description: 'Absolute path to the project directory',
+                    description: DIR_DESC,
                 },
                 functionName: {
                     type: 'string',
@@ -227,7 +245,7 @@ export const TOOL_DEFINITIONS = [
             properties: {
                 directory: {
                     type: 'string',
-                    description: 'Absolute path to the project directory',
+                    description: DIR_DESC,
                 },
                 entryFunction: {
                     type: 'string',
@@ -260,7 +278,7 @@ export const TOOL_DEFINITIONS = [
             properties: {
                 directory: {
                     type: 'string',
-                    description: 'Absolute path to the project directory',
+                    description: DIR_DESC,
                 },
                 domain: {
                     type: 'string',
@@ -325,7 +343,7 @@ export const TOOL_DEFINITIONS = [
             properties: {
                 directory: {
                     type: 'string',
-                    description: 'Absolute path to the project directory',
+                    description: DIR_DESC,
                 },
                 symbol: {
                     type: 'string',
@@ -339,6 +357,107 @@ export const TOOL_DEFINITIONS = [
             required: ['directory', 'symbol'],
         },
     },
+    {
+        name: 'select_tests',
+        description: 'USE THIS WHEN: you changed code and want to know which tests to run — ' +
+            '"which tests cover parseConfig?", "what should I run for this diff?". ' +
+            'Walks the call graph BACKWARD from the change to every test that transitively reaches it, ' +
+            'with the reaching path per test. Deterministic, offline, no test run. ' +
+            'It is an over-approximate PRIORITIZER (run these first), not a sound replacement for the full ' +
+            'suite — the response states its confidence and coverage. Run analyze_codebase first.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                directory: { type: 'string', description: DIR_DESC },
+                changedSymbols: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Changed function/method names. Provide this OR diffRef.',
+                },
+                diffRef: {
+                    type: 'string',
+                    description: 'Git ref to diff the working tree against (e.g. "HEAD", "main"). Provide this OR changedSymbols.',
+                },
+                maxDepth: { type: 'number', description: 'Backward reachability depth (default 12)' },
+            },
+            required: ['directory'],
+        },
+    },
+    {
+        name: 'find_dead_code',
+        description: 'USE THIS WHEN: "what code is unreachable / dead?", "is anything calling X?", or ' +
+            '"what becomes dead if I delete X?". Cross-language mark-and-sweep reachability from roots ' +
+            '(tests, imported symbols, route handlers, main) over the call graph. ' +
+            'Pass ifDeleted to get the downstream-only-reachable set for a symbol. ' +
+            'Results are confidence-tagged CANDIDATES, never deletion authority — dynamic dispatch, DI, ' +
+            'and external consumers cause false positives, stated in the response. Run analyze_codebase first.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                directory: { type: 'string', description: DIR_DESC },
+                ifDeleted: { type: 'string', description: 'Symbol name — returns what becomes dead if it is deleted (delete-impact mode)' },
+                maxResults: { type: 'number', description: 'Max candidate-dead results (default 100)' },
+                filePattern: { type: 'string', description: 'Only report candidates whose file path contains this substring' },
+            },
+            required: ['directory'],
+        },
+    },
+    {
+        name: 'structural_diff',
+        description: 'USE THIS WHEN reviewing or refactoring a change: "what changed structurally?", ' +
+            '"whose callers are now stale?". A graph diff (complement to git diff) between two states ' +
+            '(working tree vs a ref, or two refs): functions/edges added & removed, signature changes, ' +
+            'and the existing callers now STALE because a callee signature moved under them. ' +
+            'Rename/move ambiguity is flagged, not guessed. Deterministic, offline. Run analyze_codebase ' +
+            'first for stale-caller analysis.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                directory: { type: 'string', description: DIR_DESC },
+                baseRef: { type: 'string', description: 'Old state to diff against (default "HEAD")' },
+                headRef: { type: 'string', description: 'New state (a git ref). Omit to use the working tree.' },
+                maxResults: { type: 'number', description: 'Cap reported items per category (default 200)' },
+            },
+            required: ['directory'],
+        },
+    },
+    {
+        name: 'get_change_coupling',
+        description: 'USE THIS WHEN: "what changes together with this file?" or "what is the most volatile code?". ' +
+            'Mined from local git history (not the call graph): co-change coupling surfaces invisible ' +
+            'coupling with no import/call edge (the config + parser that move in lockstep), and ' +
+            'volatility/churn flags risky high-change code. Pass a file for its coupling, or omit for the ' +
+            'most-volatile overview. Advisory signal (correlation, not causation); bulk commits filtered. ' +
+            'Run analyze_codebase first.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                directory: { type: 'string', description: DIR_DESC },
+                file: { type: 'string', description: 'A file to query its coupling/volatility. Omit for the most-volatile overview.' },
+                limit: { type: 'number', description: 'Cap results (default 20)' },
+            },
+            required: ['directory'],
+        },
+    },
+    {
+        name: 'check_architecture',
+        description: 'USE THIS BEFORE adding an import to check it against the repo\'s architecture rules, or to ' +
+            'list current architecture violations. Opt-in and inert unless the repo declares rules in ' +
+            '.openlore/architecture.json (layers / forbidden / allowedOnly) or via an "Invariant:" marker ' +
+            'in a synced ADR. Pre-edit mode: pass {from, to} ("may a file under <from> import <to>?") for a ' +
+            'deterministic allowed/denied + the governing rule + why, BEFORE you write the code. Scan mode: ' +
+            'pass only {directory} for the full current-violations report. Cross-language, offline, ' +
+            'deterministic; complements (does not replace) CI linters. Run analyze_codebase first.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                directory: { type: 'string', description: DIR_DESC },
+                from: { type: 'string', description: 'Pre-edit mode: the file that would gain the import (relative or absolute). Requires "to".' },
+                to: { type: 'string', description: 'Pre-edit mode: the target file path or exported symbol being imported. Requires "from".' },
+            },
+            required: ['directory'],
+        },
+    },
     {
         name: 'get_low_risk_refactor_candidates',
         description: 'Return the safest functions to refactor first: low fan-in (few callers), ' +
@@ -350,7 +469,7 @@ export const TOOL_DEFINITIONS = [
             properties: {
                 directory: {
                     type: 'string',
-                    description: 'Absolute path to the project directory',
+                    description: DIR_DESC,
                 },
                 limit: {
                     type: 'number',
@@ -375,7 +494,7 @@ export const TOOL_DEFINITIONS = [
             properties: {
                 directory: {
                     type: 'string',
-                    description: 'Absolute path to the project directory',
+                    description: DIR_DESC,
                 },
                 limit: {
                     type: 'number',
@@ -405,7 +524,7 @@ export const TOOL_DEFINITIONS = [
             properties: {
                 directory: {
                     type: 'string',
-                    description: 'Absolute path to the project directory',
+                    description: DIR_DESC,
                 },
                 limit: {
                     type: 'number',
@@ -431,7 +550,7 @@ export const TOOL_DEFINITIONS = [
             properties: {
                 directory: {
                     type: 'string',
-                    description: 'Absolute path to the project directory',
+                    description: DIR_DESC,
                 },
                 filePath: {
                     type: 'string',
@@ -452,7 +571,7 @@ export const TOOL_DEFINITIONS = [
             properties: {
                 directory: {
                     type: 'string',
-                    description: 'Absolute path to the project directory',
+                    description: DIR_DESC,
                 },
                 filePath: {
                     type: 'string',
@@ -478,7 +597,7 @@ export const TOOL_DEFINITIONS = [
             properties: {
                 directory: {
                     type: 'string',
-                    description: 'Absolute path to the project directory',
+                    description: DIR_DESC,
                 },
                 description: {
                     type: 'string',
@@ -509,7 +628,7 @@ export const TOOL_DEFINITIONS = [
             properties: {
                 directory: {
                     type: 'string',
-                    description: 'Absolute path to the project directory',
+                    description: DIR_DESC,
                 },
                 query: {
                     type: 'string',
@@ -527,6 +646,10 @@ export const TOOL_DEFINITIONS = [
                     type: 'number',
                     description: 'Only return functions with at least this many callers (hub filter)',
                 },
+                tokenBudget: {
+                    type: 'number',
+                    description: 'Optional: cap results to ~this many tokens (highest-scored kept, exact duplicates collapsed); each hit carries an `expand` handle for get_function_body',
+                },
             },
             required: ['directory', 'query'],
         },
@@ -538,7 +661,7 @@ export const TOOL_DEFINITIONS = [
         inputSchema: {
             type: 'object',
             properties: {
-                directory: { type: 'string', description: 'Absolute path to the project directory' },
+                directory: { type: 'string', description: DIR_DESC },
             },
             required: ['directory'],
         },
@@ -554,7 +677,7 @@ export const TOOL_DEFINITIONS = [
             properties: {
                 directory: {
                     type: 'string',
-                    description: 'Absolute path to the project directory',
+                    description: DIR_DESC,
                 },
                 query: {
                     type: 'string',
@@ -589,7 +712,7 @@ export const TOOL_DEFINITIONS = [
             properties: {
                 directory: {
                     type: 'string',
-                    description: 'Absolute path to the project directory',
+                    description: DIR_DESC,
                 },
                 query: {
                     type: 'string',
@@ -624,7 +747,7 @@ export const TOOL_DEFINITIONS = [
         inputSchema: {
             type: 'object',
             properties: {
-                directory: { type: 'string', description: 'Absolute path to the project directory' },
+                directory: { type: 'string', description: DIR_DESC },
                 domain: {
                     type: 'string',
                     description: 'Domain name as returned by list_spec_domains (e.g. "auth", "analyzer")',
@@ -642,7 +765,7 @@ export const TOOL_DEFINITIONS = [
         inputSchema: {
             type: 'object',
             properties: {
-                directory: { type: 'string', description: 'Absolute path to the project directory' },
+                directory: { type: 'string', description: DIR_DESC },
                 filePath: {
                     type: 'string',
                     description: 'File path relative to the project directory, e.g. "src/auth/jwt.ts"',
@@ -664,7 +787,7 @@ export const TOOL_DEFINITIONS = [
         inputSchema: {
             type: 'object',
             properties: {
-                directory: { type: 'string', description: 'Absolute path to the project directory' },
+                directory: { type: 'string', description: DIR_DESC },
                 filePath: {
                     type: 'string',
                     description: 'File path relative to the project root, e.g. "src/core/analyzer/vector-index.ts"',
@@ -691,7 +814,7 @@ export const TOOL_DEFINITIONS = [
             properties: {
                 directory: {
                     type: 'string',
-                    description: 'Absolute path to the project directory',
+                    description: DIR_DESC,
                 },
                 description: {
                     type: 'string',
@@ -725,7 +848,7 @@ export const TOOL_DEFINITIONS = [
             properties: {
                 directory: {
                     type: 'string',
-                    description: 'Absolute path to the project directory',
+                    description: DIR_DESC,
                 },
                 storyFilePath: {
                     type: 'string',
@@ -750,7 +873,7 @@ export const TOOL_DEFINITIONS = [
         inputSchema: {
             type: 'object',
             properties: {
-                directory: { type: 'string', description: 'Absolute path to the project directory' },
+                directory: { type: 'string', description: DIR_DESC },
                 query: {
                     type: 'string',
                     description: 'Optional text filter — returns only ADRs whose title or content contains this string',
@@ -771,7 +894,7 @@ export const TOOL_DEFINITIONS = [
         inputSchema: {
             type: 'object',
             properties: {
-                directory: { type: 'string', description: 'Absolute path to the project directory' },
+                directory: { type: 'string', description: DIR_DESC },
             },
             required: ['directory'],
         },
@@ -788,7 +911,7 @@ export const TOOL_DEFINITIONS = [
         inputSchema: {
             type: 'object',
             properties: {
-                directory: { type: 'string', description: 'Absolute path to the project directory' },
+                directory: { type: 'string', description: DIR_DESC },
             },
             required: ['directory'],
         },
@@ -804,7 +927,7 @@ export const TOOL_DEFINITIONS = [
         inputSchema: {
             type: 'object',
             properties: {
-                directory: { type: 'string', description: 'Absolute path to the project directory' },
+                directory: { type: 'string', description: DIR_DESC },
             },
             required: ['directory'],
         },
@@ -820,7 +943,7 @@ export const TOOL_DEFINITIONS = [
         inputSchema: {
             type: 'object',
             properties: {
-                directory: { type: 'string', description: 'Absolute path to the project directory' },
+                directory: { type: 'string', description: DIR_DESC },
             },
             required: ['directory'],
         },
@@ -837,7 +960,7 @@ export const TOOL_DEFINITIONS = [
         inputSchema: {
             type: 'object',
             properties: {
-                directory: { type: 'string', description: 'Absolute path to the project directory' },
+                directory: { type: 'string', description: DIR_DESC },
             },
             required: ['directory'],
         },
@@ -852,7 +975,7 @@ export const TOOL_DEFINITIONS = [
         inputSchema: {
             type: 'object',
             properties: {
-                directory: { type: 'string', description: 'Absolute path to the project directory' },
+                directory: { type: 'string', description: DIR_DESC },
             },
             required: ['directory'],
         },
@@ -869,7 +992,7 @@ export const TOOL_DEFINITIONS = [
         inputSchema: {
             type: 'object',
             properties: {
-                directory: { type: 'string', description: 'Absolute path to the project directory' },
+                directory: { type: 'string', description: DIR_DESC },
                 maxUncovered: {
                     type: 'number',
                     description: 'Maximum uncovered functions to return (default: 50)',
@@ -897,7 +1020,7 @@ export const TOOL_DEFINITIONS = [
             properties: {
                 directory: {
                     type: 'string',
-                    description: 'Absolute path to the project directory',
+                    description: DIR_DESC,
                 },
                 domains: {
                     type: 'array',
@@ -934,7 +1057,7 @@ export const TOOL_DEFINITIONS = [
             properties: {
                 directory: {
                     type: 'string',
-                    description: 'Absolute path to the project directory',
+                    description: DIR_DESC,
                 },
                 domains: {
                     type: 'array',
@@ -959,7 +1082,7 @@ export const TOOL_DEFINITIONS = [
         inputSchema: {
             type: 'object',
             properties: {
-                directory: { type: 'string', description: 'Absolute path to the project directory' },
+                directory: { type: 'string', description: DIR_DESC },
                 functionName: { type: 'string', description: 'Exact function or method name' },
                 filePath: {
                     type: 'string',
@@ -979,7 +1102,7 @@ export const TOOL_DEFINITIONS = [
         inputSchema: {
             type: 'object',
             properties: {
-                directory: { type: 'string', description: 'Absolute path to the project directory' },
+                directory: { type: 'string', description: DIR_DESC },
                 functionName: { type: 'string', description: 'Function name to look up the community for' },
             },
             required: ['directory', 'functionName'],
@@ -996,7 +1119,7 @@ export const TOOL_DEFINITIONS = [
         inputSchema: {
             type: 'object',
             properties: {
-                directory: { type: 'string', description: 'Absolute path to the project directory' },
+                directory: { type: 'string', description: DIR_DESC },
                 base: {
                     type: 'string',
                     description: 'Git ref to diff against (default: HEAD). Use "HEAD~1" for last commit, "main" for branch diff.',
@@ -1015,7 +1138,7 @@ export const TOOL_DEFINITIONS = [
         inputSchema: {
             type: 'object',
             properties: {
-                directory: { type: 'string', description: 'Absolute path to the project directory' },
+                directory: { type: 'string', description: DIR_DESC },
                 title: { type: 'string', description: 'Short imperative statement, e.g. "Use UUIDs for decision IDs"' },
                 rationale: { type: 'string', description: 'Why this decision was made' },
                 consequences: { type: 'string', description: 'What changes as a result (optional)' },
@@ -1046,7 +1169,7 @@ export const TOOL_DEFINITIONS = [
         inputSchema: {
             type: 'object',
             properties: {
-                directory: { type: 'string', description: 'Absolute path to the project directory' },
+                directory: { type: 'string', description: DIR_DESC },
                 status: {
                     type: 'string',
                     enum: ['draft', 'consolidated', 'verified', 'phantom', 'approved', 'rejected', 'synced'],
@@ -1066,7 +1189,7 @@ export const TOOL_DEFINITIONS = [
         inputSchema: {
             type: 'object',
             properties: {
-                directory: { type: 'string', description: 'Absolute path to the project directory' },
+                directory: { type: 'string', description: DIR_DESC },
                 id: { type: 'string', description: '8-character decision ID from list_decisions' },
                 note: { type: 'string', description: 'Optional review note' },
             },
@@ -1079,7 +1202,7 @@ export const TOOL_DEFINITIONS = [
         inputSchema: {
             type: 'object',
             properties: {
-                directory: { type: 'string', description: 'Absolute path to the project directory' },
+                directory: { type: 'string', description: DIR_DESC },
                 id: { type: 'string', description: '8-character decision ID from list_decisions' },
                 note: { type: 'string', description: 'Optional reason for rejection' },
             },
@@ -1096,7 +1219,7 @@ export const TOOL_DEFINITIONS = [
         inputSchema: {
             type: 'object',
             properties: {
-                directory: { type: 'string', description: 'Absolute path to the project directory' },
+                directory: { type: 'string', description: DIR_DESC },
                 dryRun: { type: 'boolean', description: 'Preview without writing files (default: false)' },
                 id: { type: 'string', description: 'Sync only this specific decision ID (default: all approved)' },
             },
@@ -1116,7 +1239,7 @@ const TOOL_ANNOTATIONS = {
     orient: _RO, analyze_codebase: _RWI, get_architecture_overview: _RO,
     get_refactor_report: _RO, get_call_graph: _RO, get_duplicate_report: _RO,
     get_signatures: _RO, get_subgraph: _RO, trace_execution_path: _RO,
-    get_mapping: _RO, check_spec_drift: _RO, analyze_impact: _RO,
+    get_mapping: _RO, check_spec_drift: _RO, analyze_impact: _RO, select_tests: _RO, find_dead_code: _RO, structural_diff: _RO, get_change_coupling: _RO, check_architecture: _RO,
     get_low_risk_refactor_candidates: _RO, get_leaf_functions: _RO,
     get_critical_hubs: _RO, get_function_skeleton: _RO, get_god_functions: _RO,
     suggest_insertion_points: _RO, search_code: _RO, list_spec_domains: _RO,
@@ -1129,6 +1252,21 @@ const TOOL_ANNOTATIONS = {
     detect_changes: _RO, record_decision: _RW, list_decisions: _RO,
     approve_decision: _RWI, reject_decision: _RWI, sync_decisions: _RWI,
 };
+// Tools that touch external entities (LLM / network) → openWorldHint: true.
+// Everything else is local, deterministic, closed-world analysis.
+const OPEN_WORLD_TOOLS = new Set(['generate_tests', 'generate_change_proposal', 'annotate_story']);
+/** Human-readable title from a snake_case tool name (spec-11 annotations). */
+function toolTitle(name) {
+    return name.split('_').map(w => (w ? w[0].toUpperCase() + w.slice(1) : w)).join(' ');
+}
+/** Full MCP `annotations` for a tool: read/write hints + title + openWorldHint (spec-11). */
+export function toolAnnotations(name) {
+    return {
+        title: toolTitle(name),
+        ...(TOOL_ANNOTATIONS[name] ?? _RO),
+        openWorldHint: OPEN_WORLD_TOOLS.has(name),
+    };
+}
 const MINIMAL_TOOLS = new Set([
     'orient', 'search_code', 'record_decision', 'detect_changes', 'check_spec_drift',
 ]);
@@ -1184,7 +1322,7 @@ async function startMcpServer(options = {}) {
     const { version: pkgVersion } = _require('../../../package.json');
     const server = new Server({ name: 'openlore', version: pkgVersion }, { capabilities: { tools: {} } });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: activeTools.map(t => ({ ...t, annotations: TOOL_ANNOTATIONS[t.name] })),
+        tools: activeTools.map(t => ({ ...t, annotations: toolAnnotations(t.name) })),
     }));
     // Per-session epistemic lease tracker — re-initialized when directory changes.
     let tracker;
@@ -1197,8 +1335,16 @@ async function startMcpServer(options = {}) {
     server.setRequestHandler(InitializeRequestSchema, async (request) => {
         agentName = request.params.clientInfo?.name ?? 'unknown';
         agentVersion = request.params.clientInfo?.version ?? 'unknown';
+        // Protocol negotiation (spec-12): echo the client's requested version when we
+        // support it (per the SDK's pinned set), else offer our latest supported one.
+        const requested = request.params.protocolVersion;
+        const protocolVersion = SUPPORTED_PROTOCOL_VERSIONS.includes(requested)
+            ? requested
+            : LATEST_PROTOCOL_VERSION;
         return {
-            protocolVersion: request.params.protocolVersion,
+            protocolVersion,
+            // Honest capabilities: only `tools`. No `listChanged` — the tool list is
+            // static per session, so we don't advertise a capability we don't implement.
             capabilities: { tools: {} },
             serverInfo: { name: 'openlore', version: _pkgVersion },
         };
@@ -1225,6 +1371,17 @@ async function startMcpServer(options = {}) {
         const _dir = args.directory;
         const directory = typeof _dir === 'string' ? _dir : '';
         const _t0 = Date.now();
+        // Input validation (spec-10) against the tool's own declared inputSchema, before
+        // dispatch. Invalid args become a JSON-RPC -32602 error (spec-12), not an
+        // isError tool result — a malformed request is a protocol error, not a tool failure.
+        {
+            const toolDef = TOOL_DEFINITIONS.find(t => t.name === name);
+            const argError = toolDef ? validateToolArgs(args, toolDef.inputSchema) : null;
+            if (argError) {
+                emit(directory, 'mcp', { event: 'tool_error', tool: name, ms: Date.now() - _t0, agent: agentName, code: 'INVALID_ARGS', error: argError });
+                throw new McpError(ErrorCode.InvalidParams, `Invalid arguments for "${name}": ${argError}`);
+            }
+        }
         try {
             const filePath = args.filePath;
             // Init (or re-init when project directory changes between calls)
@@ -1236,205 +1393,240 @@ async function startMcpServer(options = {}) {
             if (tracker && directory)
                 updateTracker(tracker, name, directory, typeof filePath === 'string' ? filePath : undefined);
             let result;
-            if (name === 'orient') {
-                const { task, limit = 5 } = args;
-                result = await handleOrient(directory, task, limit);
-                if (result && typeof result === 'object') {
-                    const r = result;
-                    emit(directory, 'orient', {
-                        event: 'orient_call',
-                        agent: agentName,
-                        functions: Array.isArray(r['relevantFunctions']) ? r['relevantFunctions'].length : 0,
-                        files: Array.isArray(r['relevantFiles']) ? r['relevantFiles'].length : 0,
-                        spec_domains: Array.isArray(r['specDomains']) ? r['specDomains'].length : 0,
-                        insertion_points: Array.isArray(r['insertionPoints']) ? r['insertionPoints'].length : 0,
-                    });
+            let _unknownTool = false;
+            // Per-tool timeout (spec-10): race the dispatch against the tool's budget so a
+            // pathological hang can never wedge the server. Slow tools (analysis, LLM) have
+            // generous overrides in MCP_TOOL_TIMEOUT_OVERRIDES.
+            await withToolTimeout((async () => {
+                if (name === 'orient') {
+                    const { task, limit = 5, tokenBudget, lean } = args;
+                    result = await handleOrient(directory, task, limit, tokenBudget, lean);
+                    if (result && typeof result === 'object') {
+                        const r = result;
+                        emit(directory, 'orient', {
+                            event: 'orient_call',
+                            agent: agentName,
+                            functions: Array.isArray(r['relevantFunctions']) ? r['relevantFunctions'].length : 0,
+                            files: Array.isArray(r['relevantFiles']) ? r['relevantFiles'].length : 0,
+                            spec_domains: Array.isArray(r['specDomains']) ? r['specDomains'].length : 0,
+                            insertion_points: Array.isArray(r['insertionPoints']) ? r['insertionPoints'].length : 0,
+                        });
+                    }
                 }
-            }
-            else if (name === 'analyze_codebase') {
-                const { directory, force = false } = args;
-                result = await handleAnalyzeCodebase(directory, force);
-            }
-            else if (name === 'get_architecture_overview') {
-                const { directory } = args;
-                result = await handleGetArchitectureOverview(directory);
-            }
-            else if (name === 'get_refactor_report') {
-                const { directory } = args;
-                result = await handleGetRefactorReport(directory);
-            }
-            else if (name === 'get_call_graph') {
-                const { directory } = args;
-                result = await handleGetCallGraph(directory);
-            }
-            else if (name === 'get_signatures') {
-                const { directory, filePattern } = args;
-                result = await handleGetSignatures(directory, filePattern);
-            }
-            else if (name === 'get_subgraph') {
-                const { directory, functionName, direction = 'downstream', maxDepth = 3, format = 'json' } = args;
-                result = await handleGetSubgraph(directory, functionName, direction, maxDepth, format);
-            }
-            else if (name === 'trace_execution_path') {
-                const { directory, entryFunction, targetFunction, maxDepth = 6, maxPaths = 10 } = args;
-                result = await handleTraceExecutionPath(directory, entryFunction, targetFunction, maxDepth, maxPaths);
-            }
-            else if (name === 'get_mapping') {
-                const { directory, domain, orphansOnly } = args;
-                result = await handleGetMapping(directory, domain, orphansOnly);
-            }
-            else if (name === 'analyze_impact') {
-                const { directory, symbol, depth = 2 } = args;
-                result = await handleAnalyzeImpact(directory, symbol, depth);
-            }
-            else if (name === 'get_low_risk_refactor_candidates') {
-                const { directory, limit = 5, filePattern } = args;
-                result = await handleGetLowRiskRefactorCandidates(directory, limit, filePattern);
-            }
-            else if (name === 'get_leaf_functions') {
-                const { directory, limit = 20, filePattern, sortBy = 'fanIn' } = args;
-                result = await handleGetLeafFunctions(directory, limit, filePattern, sortBy);
-            }
-            else if (name === 'get_critical_hubs') {
-                const { directory, limit = 10, minFanIn = 3 } = args;
-                result = await handleGetCriticalHubs(directory, limit, minFanIn);
-            }
-            else if (name === 'get_duplicate_report') {
-                const { directory } = args;
-                result = await handleGetDuplicateReport(directory);
-            }
-            else if (name === 'get_function_skeleton') {
-                const { directory, filePath } = args;
-                result = await handleGetFunctionSkeleton(directory, filePath);
-            }
-            else if (name === 'get_god_functions') {
-                const { directory, filePath, fanOutThreshold = 8 } = args;
-                result = await handleGetGodFunctions(directory, filePath, fanOutThreshold);
-            }
-            else if (name === 'check_spec_drift') {
-                const { directory, base = 'auto', files = [], domains = [], failOn = 'warning', maxFiles = DEFAULT_DRIFT_MAX_FILES } = args;
-                result = await handleCheckSpecDrift(directory, base, files, domains, failOn, maxFiles);
-            }
-            else if (name === 'search_code') {
-                const { directory, query, limit = 10, language, minFanIn } = args;
-                result = await handleSearchCode(directory, query, limit, language, minFanIn);
-            }
-            else if (name === 'suggest_insertion_points') {
-                const { directory, description, limit = 5, language } = args;
-                result = await handleSuggestInsertionPoints(directory, description, limit, language);
-            }
-            else if (name === 'search_specs') {
-                const { directory, query, limit = 10, domain, section } = args;
-                result = await handleSearchSpecs(directory, query, limit, domain, section);
-            }
-            else if (name === 'search_unified') {
-                const { directory, query, limit = 10, language, domain, section } = args;
-                result = await handleUnifiedSearch(directory, query, limit, language, domain, section);
-            }
-            else if (name === 'list_spec_domains') {
-                const { directory } = args;
-                result = await handleListSpecDomains(directory);
-            }
-            else if (name === 'get_spec') {
-                const { directory, domain } = args;
-                result = await handleGetSpec(directory, domain);
-            }
-            else if (name === 'get_function_body') {
-                const { directory, filePath, functionName } = args;
-                result = await handleGetFunctionBody(directory, filePath, functionName);
-            }
-            else if (name === 'get_file_dependencies') {
-                const { directory, filePath, direction = 'both' } = args;
-                result = await handleGetFileDependencies(directory, filePath, direction);
-            }
-            else if (name === 'generate_change_proposal') {
-                const { directory, description, slug, storyContent } = args;
-                result = await handleGenerateChangeProposal(directory, description, slug, storyContent);
-            }
-            else if (name === 'annotate_story') {
-                const { directory, storyFilePath, description } = args;
-                result = await handleAnnotateStory(directory, storyFilePath, description);
-            }
-            else if (name === 'get_decisions') {
-                const { directory, query } = args;
-                result = await handleGetDecisions(directory, query);
-            }
-            else if (name === 'get_route_inventory') {
-                const { directory } = args;
-                result = await handleGetRouteInventory(directory);
-            }
-            else if (name === 'get_middleware_inventory') {
-                const { directory } = args;
-                result = await handleGetMiddlewareInventory(directory);
-            }
-            else if (name === 'get_schema_inventory') {
-                const { directory } = args;
-                result = await handleGetSchemaInventory(directory);
-            }
-            else if (name === 'get_ui_components') {
-                const { directory } = args;
-                result = await handleGetUIComponents(directory);
-            }
-            else if (name === 'get_env_vars') {
-                const { directory } = args;
-                result = await handleGetEnvVars(directory);
-            }
-            else if (name === 'get_external_packages') {
-                const { directory } = args;
-                result = await handleGetExternalPackages(directory);
-            }
-            else if (name === 'audit_spec_coverage') {
-                const { directory, maxUncovered = 50, hubThreshold = 5 } = args;
-                result = await handleAuditSpecCoverage(directory, maxUncovered, hubThreshold);
-            }
-            else if (name === 'generate_tests') {
-                const { directory, domains, framework, useLlm, dryRun } = args;
-                result = await handleGenerateTests({ directory, domains, framework, useLlm, dryRun });
-            }
-            else if (name === 'get_test_coverage') {
-                const { directory, domains, minCoverage } = args;
-                result = await handleGetTestCoverage({ directory, domains, minCoverage });
-            }
-            else if (name === 'get_minimal_context') {
-                const { directory, functionName, filePath } = args;
-                result = await handleGetMinimalContext(directory, functionName, filePath);
-            }
-            else if (name === 'get_cluster') {
-                const { directory, functionName } = args;
-                result = await handleGetCluster(directory, functionName);
-            }
-            else if (name === 'detect_changes') {
-                const { directory, base } = args;
-                result = await handleDetectChanges(directory, base);
-            }
-            else if (name === 'record_decision') {
-                const { directory, title, rationale, consequences, affectedFiles, supersedes, scope } = args;
-                result = await handleRecordDecision(directory, title, rationale, consequences, affectedFiles, supersedes, scope);
-            }
-            else if (name === 'list_decisions') {
-                const { directory, status } = args;
-                result = await handleListDecisions(directory, status);
-            }
-            else if (name === 'approve_decision') {
-                const { directory, id, note } = args;
-                result = await handleApproveDecision(directory, id, note);
-            }
-            else if (name === 'reject_decision') {
-                const { directory, id, note } = args;
-                result = await handleRejectDecision(directory, id, note);
-            }
-            else if (name === 'sync_decisions') {
-                const { directory, dryRun = false, id } = args;
-                result = await handleSyncDecisions(directory, dryRun, id);
-            }
-            else {
+                else if (name === 'analyze_codebase') {
+                    const { directory, force = false } = args;
+                    result = await handleAnalyzeCodebase(directory, force);
+                }
+                else if (name === 'get_architecture_overview') {
+                    const { directory } = args;
+                    result = await handleGetArchitectureOverview(directory);
+                }
+                else if (name === 'get_refactor_report') {
+                    const { directory } = args;
+                    result = await handleGetRefactorReport(directory);
+                }
+                else if (name === 'get_call_graph') {
+                    const { directory } = args;
+                    result = await handleGetCallGraph(directory);
+                }
+                else if (name === 'get_signatures') {
+                    const { directory, filePattern } = args;
+                    result = await handleGetSignatures(directory, filePattern);
+                }
+                else if (name === 'get_subgraph') {
+                    const { directory, functionName, direction = 'downstream', maxDepth = 3, format = 'json' } = args;
+                    result = await handleGetSubgraph(directory, functionName, direction, maxDepth, format);
+                }
+                else if (name === 'trace_execution_path') {
+                    const { directory, entryFunction, targetFunction, maxDepth = 6, maxPaths = 10 } = args;
+                    result = await handleTraceExecutionPath(directory, entryFunction, targetFunction, maxDepth, maxPaths);
+                }
+                else if (name === 'get_mapping') {
+                    const { directory, domain, orphansOnly } = args;
+                    result = await handleGetMapping(directory, domain, orphansOnly);
+                }
+                else if (name === 'analyze_impact') {
+                    const { directory, symbol, depth = 2 } = args;
+                    result = await handleAnalyzeImpact(directory, symbol, depth);
+                }
+                else if (name === 'select_tests') {
+                    const { directory, changedSymbols, diffRef, maxDepth } = args;
+                    result = await handleSelectTests({ directory, changedSymbols, diffRef, maxDepth });
+                }
+                else if (name === 'find_dead_code') {
+                    const { directory, ifDeleted, maxResults, filePattern } = args;
+                    result = await handleFindDeadCode({ directory, ifDeleted, maxResults, filePattern });
+                }
+                else if (name === 'structural_diff') {
+                    const { directory, baseRef, headRef, maxResults } = args;
+                    result = await handleStructuralDiff({ directory, baseRef, headRef, maxResults });
+                }
+                else if (name === 'get_change_coupling') {
+                    const { directory, file, limit } = args;
+                    result = await handleGetChangeCoupling({ directory, file, limit });
+                }
+                else if (name === 'check_architecture') {
+                    const { directory, from, to } = args;
+                    result = await handleCheckArchitecture({ directory, from, to });
+                }
+                else if (name === 'get_low_risk_refactor_candidates') {
+                    const { directory, limit = 5, filePattern } = args;
+                    result = await handleGetLowRiskRefactorCandidates(directory, limit, filePattern);
+                }
+                else if (name === 'get_leaf_functions') {
+                    const { directory, limit = 20, filePattern, sortBy = 'fanIn' } = args;
+                    result = await handleGetLeafFunctions(directory, limit, filePattern, sortBy);
+                }
+                else if (name === 'get_critical_hubs') {
+                    const { directory, limit = 10, minFanIn = 3 } = args;
+                    result = await handleGetCriticalHubs(directory, limit, minFanIn);
+                }
+                else if (name === 'get_duplicate_report') {
+                    const { directory } = args;
+                    result = await handleGetDuplicateReport(directory);
+                }
+                else if (name === 'get_function_skeleton') {
+                    const { directory, filePath } = args;
+                    result = await handleGetFunctionSkeleton(directory, filePath);
+                }
+                else if (name === 'get_god_functions') {
+                    const { directory, filePath, fanOutThreshold = 8 } = args;
+                    result = await handleGetGodFunctions(directory, filePath, fanOutThreshold);
+                }
+                else if (name === 'check_spec_drift') {
+                    const { directory, base = 'auto', files = [], domains = [], failOn = 'warning', maxFiles = DEFAULT_DRIFT_MAX_FILES } = args;
+                    result = await handleCheckSpecDrift(directory, base, files, domains, failOn, maxFiles);
+                }
+                else if (name === 'search_code') {
+                    const { directory, query, limit = 10, language, minFanIn, tokenBudget } = args;
+                    result = await handleSearchCode(directory, query, limit, language, minFanIn, tokenBudget);
+                }
+                else if (name === 'suggest_insertion_points') {
+                    const { directory, description, limit = 5, language } = args;
+                    result = await handleSuggestInsertionPoints(directory, description, limit, language);
+                }
+                else if (name === 'search_specs') {
+                    const { directory, query, limit = 10, domain, section } = args;
+                    result = await handleSearchSpecs(directory, query, limit, domain, section);
+                }
+                else if (name === 'search_unified') {
+                    const { directory, query, limit = 10, language, domain, section } = args;
+                    result = await handleUnifiedSearch(directory, query, limit, language, domain, section);
+                }
+                else if (name === 'list_spec_domains') {
+                    const { directory } = args;
+                    result = await handleListSpecDomains(directory);
+                }
+                else if (name === 'get_spec') {
+                    const { directory, domain } = args;
+                    result = await handleGetSpec(directory, domain);
+                }
+                else if (name === 'get_function_body') {
+                    const { directory, filePath, functionName } = args;
+                    result = await handleGetFunctionBody(directory, filePath, functionName);
+                }
+                else if (name === 'get_file_dependencies') {
+                    const { directory, filePath, direction = 'both' } = args;
+                    result = await handleGetFileDependencies(directory, filePath, direction);
+                }
+                else if (name === 'generate_change_proposal') {
+                    const { directory, description, slug, storyContent } = args;
+                    result = await handleGenerateChangeProposal(directory, description, slug, storyContent);
+                }
+                else if (name === 'annotate_story') {
+                    const { directory, storyFilePath, description } = args;
+                    result = await handleAnnotateStory(directory, storyFilePath, description);
+                }
+                else if (name === 'get_decisions') {
+                    const { directory, query } = args;
+                    result = await handleGetDecisions(directory, query);
+                }
+                else if (name === 'get_route_inventory') {
+                    const { directory } = args;
+                    result = await handleGetRouteInventory(directory);
+                }
+                else if (name === 'get_middleware_inventory') {
+                    const { directory } = args;
+                    result = await handleGetMiddlewareInventory(directory);
+                }
+                else if (name === 'get_schema_inventory') {
+                    const { directory } = args;
+                    result = await handleGetSchemaInventory(directory);
+                }
+                else if (name === 'get_ui_components') {
+                    const { directory } = args;
+                    result = await handleGetUIComponents(directory);
+                }
+                else if (name === 'get_env_vars') {
+                    const { directory } = args;
+                    result = await handleGetEnvVars(directory);
+                }
+                else if (name === 'get_external_packages') {
+                    const { directory } = args;
+                    result = await handleGetExternalPackages(directory);
+                }
+                else if (name === 'audit_spec_coverage') {
+                    const { directory, maxUncovered = 50, hubThreshold = 5 } = args;
+                    result = await handleAuditSpecCoverage(directory, maxUncovered, hubThreshold);
+                }
+                else if (name === 'generate_tests') {
+                    const { directory, domains, framework, useLlm, dryRun } = args;
+                    result = await handleGenerateTests({ directory, domains, framework, useLlm, dryRun });
+                }
+                else if (name === 'get_test_coverage') {
+                    const { directory, domains, minCoverage } = args;
+                    result = await handleGetTestCoverage({ directory, domains, minCoverage });
+                }
+                else if (name === 'get_minimal_context') {
+                    const { directory, functionName, filePath } = args;
+                    result = await handleGetMinimalContext(directory, functionName, filePath);
+                }
+                else if (name === 'get_cluster') {
+                    const { directory, functionName } = args;
+                    result = await handleGetCluster(directory, functionName);
+                }
+                else if (name === 'detect_changes') {
+                    const { directory, base } = args;
+                    result = await handleDetectChanges(directory, base);
+                }
+                else if (name === 'record_decision') {
+                    const { directory, title, rationale, consequences, affectedFiles, supersedes, scope } = args;
+                    result = await handleRecordDecision(directory, title, rationale, consequences, affectedFiles, supersedes, scope);
+                }
+                else if (name === 'list_decisions') {
+                    const { directory, status } = args;
+                    result = await handleListDecisions(directory, status);
+                }
+                else if (name === 'approve_decision') {
+                    const { directory, id, note } = args;
+                    result = await handleApproveDecision(directory, id, note);
+                }
+                else if (name === 'reject_decision') {
+                    const { directory, id, note } = args;
+                    result = await handleRejectDecision(directory, id, note);
+                }
+                else if (name === 'sync_decisions') {
+                    const { directory, dryRun = false, id } = args;
+                    result = await handleSyncDecisions(directory, dryRun, id);
+                }
+                else {
+                    _unknownTool = true;
+                }
+            })(), name);
+            if (_unknownTool) {
                 return {
                     content: [{ type: 'text', text: `Unknown tool: ${name}` }],
                     isError: true,
                 };
             }
-            emit(directory, 'mcp', { event: 'tool_call', tool: name, ms: Date.now() - _t0, agent: agentName, agent_version: agentVersion });
-            const text = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+            const rawText = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+            // Output cap (spec-10): truncate deterministically with a how-to-narrow note
+            // rather than silently dropping data or blowing the agent's context.
+            const { text, truncated } = capOutput(rawText, MCP_TOOL_MAX_BYTES);
+            emit(directory, 'mcp', {
+                event: 'tool_call', tool: name, ms: Date.now() - _t0, agent: agentName, agent_version: agentVersion,
+                bytes: Buffer.byteLength(text, 'utf8'), outcome: truncated ? 'truncated' : 'ok',
+            });
             const signal = tracker ? getFreshnessSignal(tracker) : null;
             // Freshness signal is a separate content item — never concatenated into
             // the result body — so structured outputs (JSON, patches) are not corrupted.
@@ -1446,9 +1638,17 @@ async function startMcpServer(options = {}) {
             return { content };
         }
         catch (err) {
-            emit(directory, 'mcp', { event: 'tool_error', tool: name, ms: Date.now() - _t0, agent: agentName, error: sanitizeMcpError(err) });
+            // A thrown McpError is a protocol-level error (e.g. -32602) — let the SDK
+            // serialize it as a JSON-RPC error response, not a tool isError result.
+            if (err instanceof McpError)
+                throw err;
+            // Error normalization (spec-10): a stable code taxonomy, distinguishing
+            // "repo not analyzed yet" (actionable) from real failures and timeouts.
+            const code = classifyToolError(err);
+            const message = sanitizeMcpError(err);
+            emit(directory, 'mcp', { event: 'tool_error', tool: name, ms: Date.now() - _t0, agent: agentName, code, outcome: 'error', error: message });
             return {
-                content: [{ type: 'text', text: `Tool error: ${sanitizeMcpError(err)}` }],
+                content: [{ type: 'text', text: `Tool error [${code}]: ${message}` }],
                 isError: true,
             };
         }