trace-mcp 1.21.2 → 1.22.0

package/dist/index.js

@@ -10,10 +10,10 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
   if (typeof require !== "undefined") return require.apply(this, arguments);
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
-var __glob = (map) => (path65) => {
-  var fn2 = map[path65];
+var __glob = (map) => (path66) => {
+  var fn2 = map[path66];
   if (fn2) return fn2();
-  throw new Error("Module not found in bundle: " + path65);
+  throw new Error("Module not found in bundle: " + path66);
 };
 var __esm = (fn2, res) => function __init() {
   return fn2 && (res = (0, fn2[__getOwnPropNames(fn2)[0]])(fn2 = 0)), res;
@@ -149,9 +149,9 @@ var require_backend_impl = __commonJS({
       if (!backend) {
         throw new Error(`no available backend found. ERR: ${errors.map((e) => `[${e.name}] ${e.err}`).join(", ")}`);
       }
-      for (const { name, err: err13 } of errors) {
+      for (const { name, err: err14 } of errors) {
         if (backendHints.includes(name)) {
-          console.warn(`removing requested execution provider "${name}" from session options because it is not available: ${err13}`);
+          console.warn(`removing requested execution provider "${name}" from session options because it is not available: ${err14}`);
         }
       }
       const filteredEps = eps.filter((i) => availableBackendNames.has(typeof i === "string" ? i : i.name));
@@ -2641,18 +2641,18 @@ var require_filesystem = __commonJS({
     var LDD_PATH = "/usr/bin/ldd";
     var SELF_PATH = "/proc/self/exe";
     var MAX_LENGTH = 2048;
-    var readFileSync9 = (path65) => {
-      const fd = fs56.openSync(path65, "r");
+    var readFileSync10 = (path66) => {
+      const fd = fs56.openSync(path66, "r");
       const buffer = Buffer.alloc(MAX_LENGTH);
       const bytesRead = fs56.readSync(fd, buffer, 0, MAX_LENGTH, 0);
       fs56.close(fd, () => {
       });
       return buffer.subarray(0, bytesRead);
     };
-    var readFile = (path65) => new Promise((resolve3, reject) => {
-      fs56.open(path65, "r", (err13, fd) => {
-        if (err13) {
-          reject(err13);
+    var readFile = (path66) => new Promise((resolve3, reject) => {
+      fs56.open(path66, "r", (err14, fd) => {
+        if (err14) {
+          reject(err14);
         } else {
           const buffer = Buffer.alloc(MAX_LENGTH);
           fs56.read(fd, buffer, 0, MAX_LENGTH, 0, (_, bytesRead) => {
@@ -2666,7 +2666,7 @@ var require_filesystem = __commonJS({
     module.exports = {
       LDD_PATH,
       SELF_PATH,
-      readFileSync: readFileSync9,
+      readFileSync: readFileSync10,
       readFile
     };
   }
@@ -2715,7 +2715,7 @@ var require_detect_libc = __commonJS({
     "use strict";
     var childProcess = __require("child_process");
     var { isLinux, getReport } = require_process();
-    var { LDD_PATH, SELF_PATH, readFile, readFileSync: readFileSync9 } = require_filesystem();
+    var { LDD_PATH, SELF_PATH, readFile, readFileSync: readFileSync10 } = require_filesystem();
     var { interpreterPath } = require_elf();
     var cachedFamilyInterpreter;
     var cachedFamilyFilesystem;
@@ -2725,8 +2725,8 @@ var require_detect_libc = __commonJS({
     var safeCommand = () => {
       if (!commandOut) {
         return new Promise((resolve3) => {
-          childProcess.exec(command, (err13, out) => {
-            commandOut = err13 ? " " : out;
+          childProcess.exec(command, (err14, out) => {
+            commandOut = err14 ? " " : out;
             resolve3(commandOut);
           });
         });
@@ -2769,11 +2769,11 @@ var require_detect_libc = __commonJS({
       }
       return null;
     };
-    var familyFromInterpreterPath = (path65) => {
-      if (path65) {
-        if (path65.includes("/ld-musl-")) {
+    var familyFromInterpreterPath = (path66) => {
+      if (path66) {
+        if (path66.includes("/ld-musl-")) {
           return MUSL;
-        } else if (path65.includes("/ld-linux-")) {
+        } else if (path66.includes("/ld-linux-")) {
           return GLIBC;
         }
       }
@@ -2807,7 +2807,7 @@ var require_detect_libc = __commonJS({
       }
       cachedFamilyFilesystem = null;
       try {
-        const lddContent = readFileSync9(LDD_PATH);
+        const lddContent = readFileSync10(LDD_PATH);
         cachedFamilyFilesystem = getFamilyFromLddContent(lddContent);
       } catch (e) {
       }
@@ -2820,8 +2820,8 @@ var require_detect_libc = __commonJS({
       cachedFamilyInterpreter = null;
       try {
         const selfContent = await readFile(SELF_PATH);
-        const path65 = interpreterPath(selfContent);
-        cachedFamilyInterpreter = familyFromInterpreterPath(path65);
+        const path66 = interpreterPath(selfContent);
+        cachedFamilyInterpreter = familyFromInterpreterPath(path66);
       } catch (e) {
       }
       return cachedFamilyInterpreter;
@@ -2832,9 +2832,9 @@ var require_detect_libc = __commonJS({
       }
       cachedFamilyInterpreter = null;
       try {
-        const selfContent = readFileSync9(SELF_PATH);
-        const path65 = interpreterPath(selfContent);
-        cachedFamilyInterpreter = familyFromInterpreterPath(path65);
+        const selfContent = readFileSync10(SELF_PATH);
+        const path66 = interpreterPath(selfContent);
+        cachedFamilyInterpreter = familyFromInterpreterPath(path66);
       } catch (e) {
       }
       return cachedFamilyInterpreter;
@@ -2896,7 +2896,7 @@ var require_detect_libc = __commonJS({
       }
       cachedVersionFilesystem = null;
       try {
-        const lddContent = readFileSync9(LDD_PATH);
+        const lddContent = readFileSync10(LDD_PATH);
         const versionMatch = lddContent.match(RE_GLIBC_VERSION);
         if (versionMatch) {
           cachedVersionFilesystem = versionMatch[1];
@@ -4553,21 +4553,21 @@ var require_sharp = __commonJS({
       `@img/sharp-${runtimePlatform}/sharp.node`,
       "@img/sharp-wasm32/sharp.node"
     ];
-    var path65;
+    var path66;
     var sharp2;
     var errors = [];
-    for (path65 of paths) {
+    for (path66 of paths) {
       try {
-        sharp2 = __require(path65);
+        sharp2 = __require(path66);
         break;
-      } catch (err13) {
-        errors.push(err13);
+      } catch (err14) {
+        errors.push(err14);
       }
     }
-    if (sharp2 && path65.startsWith("@img/sharp-linux-x64") && !sharp2._isUsingX64V2()) {
-      const err13 = new Error("Prebuilt binaries for linux-x64 require v2 microarchitecture");
-      err13.code = "Unsupported CPU";
-      errors.push(err13);
+    if (sharp2 && path66.startsWith("@img/sharp-linux-x64") && !sharp2._isUsingX64V2()) {
+      const err14 = new Error("Prebuilt binaries for linux-x64 require v2 microarchitecture");
+      err14.code = "Unsupported CPU";
+      errors.push(err14);
       sharp2 = null;
     }
     if (sharp2) {
@@ -4575,12 +4575,12 @@ var require_sharp = __commonJS({
     } else {
       const [isLinux, isMacOs, isWindows] = ["linux", "darwin", "win32"].map((os8) => runtimePlatform.startsWith(os8));
       const help = [`Could not load the "sharp" module using the ${runtimePlatform} runtime`];
-      errors.forEach((err13) => {
-        if (err13.code !== "MODULE_NOT_FOUND") {
-          help.push(`${err13.code}: ${err13.message}`);
+      errors.forEach((err14) => {
+        if (err14.code !== "MODULE_NOT_FOUND") {
+          help.push(`${err14.code}: ${err14.message}`);
         }
       });
-      const messages = errors.map((err13) => err13.message).join(" ");
+      const messages = errors.map((err14) => err14.message).join(" ");
       help.push("Possible solutions:");
       if (isUnsupportedNodeRuntime()) {
         const { found, expected } = isUnsupportedNodeRuntime();
@@ -4633,7 +4633,7 @@ var require_sharp = __commonJS({
           "    brew update && brew upgrade vips"
         );
       }
-      if (errors.some((err13) => err13.code === "ERR_DLOPEN_DISABLED")) {
+      if (errors.some((err14) => err14.code === "ERR_DLOPEN_DISABLED")) {
         help.push("- Run Node.js without using the --no-addons flag");
       }
       if (isWindows && /The specified procedure could not be found/.test(messages)) {
@@ -5387,18 +5387,18 @@ var require_input = __commonJS({
         if (this._isStreamInput()) {
           this.on("finish", () => {
             this._flattenBufferIn();
-            sharp2.metadata(this.options, (err13, metadata2) => {
-              if (err13) {
-                callback(is2.nativeError(err13, stack2));
+            sharp2.metadata(this.options, (err14, metadata2) => {
+              if (err14) {
+                callback(is2.nativeError(err14, stack2));
               } else {
                 callback(null, metadata2);
               }
             });
           });
         } else {
-          sharp2.metadata(this.options, (err13, metadata2) => {
-            if (err13) {
-              callback(is2.nativeError(err13, stack2));
+          sharp2.metadata(this.options, (err14, metadata2) => {
+            if (err14) {
+              callback(is2.nativeError(err14, stack2));
             } else {
               callback(null, metadata2);
             }
@@ -5410,9 +5410,9 @@ var require_input = __commonJS({
           return new Promise((resolve3, reject) => {
             const finished = () => {
               this._flattenBufferIn();
-              sharp2.metadata(this.options, (err13, metadata2) => {
-                if (err13) {
-                  reject(is2.nativeError(err13, stack2));
+              sharp2.metadata(this.options, (err14, metadata2) => {
+                if (err14) {
+                  reject(is2.nativeError(err14, stack2));
                 } else {
                   resolve3(metadata2);
                 }
@@ -5426,9 +5426,9 @@ var require_input = __commonJS({
           });
         } else {
           return new Promise((resolve3, reject) => {
-            sharp2.metadata(this.options, (err13, metadata2) => {
-              if (err13) {
-                reject(is2.nativeError(err13, stack2));
+            sharp2.metadata(this.options, (err14, metadata2) => {
+              if (err14) {
+                reject(is2.nativeError(err14, stack2));
               } else {
                 resolve3(metadata2);
               }
@@ -5443,18 +5443,18 @@ var require_input = __commonJS({
         if (this._isStreamInput()) {
           this.on("finish", () => {
             this._flattenBufferIn();
-            sharp2.stats(this.options, (err13, stats2) => {
-              if (err13) {
-                callback(is2.nativeError(err13, stack2));
+            sharp2.stats(this.options, (err14, stats2) => {
+              if (err14) {
+                callback(is2.nativeError(err14, stack2));
               } else {
                 callback(null, stats2);
               }
             });
           });
         } else {
-          sharp2.stats(this.options, (err13, stats2) => {
-            if (err13) {
-              callback(is2.nativeError(err13, stack2));
+          sharp2.stats(this.options, (err14, stats2) => {
+            if (err14) {
+              callback(is2.nativeError(err14, stack2));
             } else {
               callback(null, stats2);
             }
@@ -5466,9 +5466,9 @@ var require_input = __commonJS({
           return new Promise((resolve3, reject) => {
             this.on("finish", function() {
               this._flattenBufferIn();
-              sharp2.stats(this.options, (err13, stats2) => {
-                if (err13) {
-                  reject(is2.nativeError(err13, stack2));
+              sharp2.stats(this.options, (err14, stats2) => {
+                if (err14) {
+                  reject(is2.nativeError(err14, stack2));
                 } else {
                   resolve3(stats2);
                 }
@@ -5477,9 +5477,9 @@ var require_input = __commonJS({
           });
         } else {
           return new Promise((resolve3, reject) => {
-            sharp2.stats(this.options, (err13, stats2) => {
-              if (err13) {
-                reject(is2.nativeError(err13, stack2));
+            sharp2.stats(this.options, (err14, stats2) => {
+              if (err14) {
+                reject(is2.nativeError(err14, stack2));
               } else {
                 resolve3(stats2);
               }
@@ -7475,15 +7475,15 @@ var require_color = __commonJS({
       };
     }
     function wrapConversion(toModel, graph) {
-      const path65 = [graph[toModel].parent, toModel];
+      const path66 = [graph[toModel].parent, toModel];
       let fn2 = conversions_default[graph[toModel].parent][toModel];
       let cur = graph[toModel].parent;
       while (graph[cur].parent) {
-        path65.unshift(graph[cur].parent);
+        path66.unshift(graph[cur].parent);
         fn2 = link(conversions_default[graph[cur].parent][cur], fn2);
         cur = graph[cur].parent;
       }
-      fn2.conversion = path65;
+      fn2.conversion = path66;
       return fn2;
     }
     function route(fromModel) {
@@ -8100,7 +8100,7 @@ var require_channel = __commonJS({
 var require_output = __commonJS({
   "node_modules/sharp/lib/output.js"(exports, module) {
     "use strict";
-    var path65 = __require("path");
+    var path66 = __require("path");
     var is2 = require_is();
     var sharp2 = require_sharp();
     var formats = /* @__PURE__ */ new Map([
@@ -8128,19 +8128,19 @@ var require_output = __commonJS({
     var errJp2Save = () => new Error("JP2 output requires libvips with support for OpenJPEG");
     var bitdepthFromColourCount = (colours) => 1 << 31 - Math.clz32(Math.ceil(Math.log2(colours)));
     function toFile(fileOut, callback) {
-      let err13;
+      let err14;
       if (!is2.string(fileOut)) {
-        err13 = new Error("Missing output file path");
-      } else if (is2.string(this.options.input.file) && path65.resolve(this.options.input.file) === path65.resolve(fileOut)) {
-        err13 = new Error("Cannot use same file for input and output");
-      } else if (jp2Regex.test(path65.extname(fileOut)) && !this.constructor.format.jp2k.output.file) {
-        err13 = errJp2Save();
+        err14 = new Error("Missing output file path");
+      } else if (is2.string(this.options.input.file) && path66.resolve(this.options.input.file) === path66.resolve(fileOut)) {
+        err14 = new Error("Cannot use same file for input and output");
+      } else if (jp2Regex.test(path66.extname(fileOut)) && !this.constructor.format.jp2k.output.file) {
+        err14 = errJp2Save();
       }
-      if (err13) {
+      if (err14) {
         if (is2.fn(callback)) {
-          callback(err13);
+          callback(err14);
         } else {
-          return Promise.reject(err13);
+          return Promise.reject(err14);
         }
       } else {
         this.options.fileOut = fileOut;
@@ -8854,18 +8854,18 @@ var require_output = __commonJS({
         if (this._isStreamInput()) {
           this.on("finish", () => {
             this._flattenBufferIn();
-            sharp2.pipeline(this.options, (err13, data, info) => {
-              if (err13) {
-                callback(is2.nativeError(err13, stack2));
+            sharp2.pipeline(this.options, (err14, data, info) => {
+              if (err14) {
+                callback(is2.nativeError(err14, stack2));
               } else {
                 callback(null, data, info);
               }
             });
           });
         } else {
-          sharp2.pipeline(this.options, (err13, data, info) => {
-            if (err13) {
-              callback(is2.nativeError(err13, stack2));
+          sharp2.pipeline(this.options, (err14, data, info) => {
+            if (err14) {
+              callback(is2.nativeError(err14, stack2));
             } else {
               callback(null, data, info);
             }
@@ -8876,9 +8876,9 @@ var require_output = __commonJS({
         if (this._isStreamInput()) {
           this.once("finish", () => {
             this._flattenBufferIn();
-            sharp2.pipeline(this.options, (err13, data, info) => {
-              if (err13) {
-                this.emit("error", is2.nativeError(err13, stack2));
+            sharp2.pipeline(this.options, (err14, data, info) => {
+              if (err14) {
+                this.emit("error", is2.nativeError(err14, stack2));
               } else {
                 this.emit("info", info);
                 this.push(data);
@@ -8891,9 +8891,9 @@ var require_output = __commonJS({
             this.emit("finish");
           }
         } else {
-          sharp2.pipeline(this.options, (err13, data, info) => {
-            if (err13) {
-              this.emit("error", is2.nativeError(err13, stack2));
+          sharp2.pipeline(this.options, (err14, data, info) => {
+            if (err14) {
+              this.emit("error", is2.nativeError(err14, stack2));
             } else {
               this.emit("info", info);
               this.push(data);
@@ -8908,9 +8908,9 @@ var require_output = __commonJS({
           return new Promise((resolve3, reject) => {
             this.once("finish", () => {
               this._flattenBufferIn();
-              sharp2.pipeline(this.options, (err13, data, info) => {
-                if (err13) {
-                  reject(is2.nativeError(err13, stack2));
+              sharp2.pipeline(this.options, (err14, data, info) => {
+                if (err14) {
+                  reject(is2.nativeError(err14, stack2));
                 } else {
                   if (this.options.resolveWithObject) {
                     resolve3({ data, info });
@@ -8923,9 +8923,9 @@ var require_output = __commonJS({
           });
         } else {
           return new Promise((resolve3, reject) => {
-            sharp2.pipeline(this.options, (err13, data, info) => {
-              if (err13) {
-                reject(is2.nativeError(err13, stack2));
+            sharp2.pipeline(this.options, (err14, data, info) => {
+              if (err14) {
+                reject(is2.nativeError(err14, stack2));
               } else {
                 if (this.options.resolveWithObject) {
                   resolve3({ data, info });
@@ -11561,9 +11561,9 @@ function memoizePromise(key, factory) {
   }
   const promise = factory().then(
     (value) => value,
-    (err13) => {
+    (err14) => {
       cache.delete(key);
-      return Promise.reject(err13);
+      return Promise.reject(err14);
     }
   );
   cache.put(key, promise);
@@ -11750,8 +11750,8 @@ async function storeCachedResource(path_or_repo_id, filename, cache2, cacheKey,
           headers
         }
       )
-    ).catch((err13) => {
-      logger2.warn(`Unable to add response to browser cache: ${err13}.`);
+    ).catch((err14) => {
+      logger2.warn(`Unable to add response to browser cache: ${err14}.`);
     });
   }
 }
@@ -11934,9 +11934,9 @@ async function getModelFile(path_or_repo_id, filename, fatal = true, options = {
         INFLIGHT_LOADS.delete(key);
         return result;
       },
-      (err13) => {
+      (err14) => {
         INFLIGHT_LOADS.delete(key);
-        throw err13;
+        throw err14;
       }
     );
     INFLIGHT_LOADS.set(key, pending);
@@ -14011,8 +14011,8 @@ async function ensureWasmLoaded() {
             ONNX_ENV.wasm.wasmBinary = wasmBinary;
             wasmBinaryLoaded = true;
           }
-        } catch (err13) {
-          logger2.warn("Failed to pre-load WASM binary:", err13);
+        } catch (err14) {
+          logger2.warn("Failed to pre-load WASM binary:", err14);
         }
       })() : Promise.resolve(),
       // Load and cache the WASM factory as a blob URL
@@ -14022,8 +14022,8 @@ async function ensureWasmLoaded() {
           if (wasmFactoryBlob) {
             ONNX_ENV.wasm.wasmPaths.mjs = wasmFactoryBlob;
           }
-        } catch (err13) {
-          logger2.warn("Failed to pre-load WASM factory:", err13);
+        } catch (err14) {
+          logger2.warn("Failed to pre-load WASM factory:", err14);
         }
       })() : Promise.resolve()
     ]);
@@ -21166,14 +21166,14 @@ var init_transformers_node = __esm({
           try {
             const evaluated = this.evaluateBlock(node.body, scope);
             result += evaluated.value;
-          } catch (err13) {
-            if (err13 instanceof ContinueControl) {
+          } catch (err14) {
+            if (err14 instanceof ContinueControl) {
               continue;
             }
-            if (err13 instanceof BreakControl) {
+            if (err14 instanceof BreakControl) {
               break;
             }
-            throw err13;
+            throw err14;
           }
           noIteration = false;
         }
@@ -21378,7 +21378,7 @@ var init_transformers_node = __esm({
             start(controller) {
               stream.on("data", (chunk2) => controller.enqueue(chunk2));
               stream.on("end", () => controller.close());
-              stream.on("error", (err13) => controller.error(err13));
+              stream.on("error", (err14) => controller.error(err14));
             },
             cancel() {
               stream.destroy();
@@ -21655,9 +21655,9 @@ var init_transformers_node = __esm({
               break;
             }
             await new Promise((resolve3, reject) => {
-              fileStream.write(value, (err13) => {
-                if (err13) {
-                  reject(err13);
+              fileStream.write(value, (err14) => {
+                if (err14) {
+                  reject(err14);
                   return;
                 }
                 resolve3();
@@ -21668,7 +21668,7 @@ var init_transformers_node = __esm({
             progress_callback?.({ progress, loaded, total });
           }
           await new Promise((resolve3, reject) => {
-            fileStream.close((err13) => err13 ? reject(err13) : resolve3());
+            fileStream.close((err14) => err14 ? reject(err14) : resolve3());
           });
           await fs3.promises.rename(tmpPath, filePath);
         } catch (error) {
@@ -42998,9 +42998,9 @@ var init_client = __esm({
         this.proc.stderr.on("data", (chunk2) => {
           logger.debug({ lsp: this.command, stderr: chunk2.toString().trim() }, "LSP stderr");
         });
-        this.proc.on("error", (err13) => {
-          logger.warn({ lsp: this.command, error: err13.message }, "LSP process error");
-          this.rejectAll(new Error(`LSP process error: ${err13.message}`));
+        this.proc.on("error", (err14) => {
+          logger.warn({ lsp: this.command, error: err14.message }, "LSP process error");
+          this.rejectAll(new Error(`LSP process error: ${err14.message}`));
         });
         this.proc.on("exit", (code, signal) => {
           logger.debug({ lsp: this.command, code, signal }, "LSP process exited");
@@ -46337,8 +46337,8 @@ var SessionJournal = class _SessionJournal {
     };
     this.entries.push(entry);
     if (tool === "get_symbol" || tool === "get_outline") {
-      const path65 = params.path ?? params.file_path ?? "";
-      if (path65) this.filesRead.add(path65);
+      const path66 = params.path ?? params.file_path ?? "";
+      if (path66) this.filesRead.add(path66);
     }
     if (resultCount === 0 && this.isSearchTool(tool)) {
       this.zeroResultQueries.set(hash, summary);
@@ -47490,6 +47490,7 @@ var COMPACT_CORE_PARAMS = {
   scan_security: ["file_pattern", "rules"],
   check_quality_gates: ["scope"],
   taint_analysis: ["source_symbol_id", "file_pattern"],
+  export_security_context: ["scope", "depth"],
   audit_config: [],
   // Framework
   get_request_flow: ["route", "method"],
@@ -47515,6 +47516,86 @@ var COMPACT_CORE_PARAMS = {
   batch: ["calls"]
 };
 
+// src/server/tool-annotations.ts
+var READ_ONLY = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false
+};
+var INDEX_MUTATING = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false
+};
+var FILE_WRITING = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: false,
+  openWorldHint: false
+};
+var FILE_DESTRUCTIVE = {
+  readOnlyHint: false,
+  destructiveHint: true,
+  idempotentHint: false,
+  openWorldHint: false
+};
+var OUTPUT_WRITING = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false
+};
+var RUNTIME_READ = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: true
+};
+var OVERRIDES = {
+  // ── Refactoring: file-destructive ──
+  apply_codemod: FILE_DESTRUCTIVE,
+  remove_dead_code: FILE_DESTRUCTIVE,
+  // ── Refactoring: file-writing (non-destructive) ──
+  apply_rename: FILE_WRITING,
+  apply_move: FILE_WRITING,
+  change_signature: FILE_WRITING,
+  extract_function: FILE_WRITING,
+  // ── Output generation (writes files but doesn't modify source) ──
+  generate_docs: OUTPUT_WRITING,
+  generate_sbom: OUTPUT_WRITING,
+  visualize_graph: OUTPUT_WRITING,
+  visualize_subproject_topology: OUTPUT_WRITING,
+  // ── Index / store mutation (idempotent) ──
+  reindex: INDEX_MUTATING,
+  register_edit: INDEX_MUTATING,
+  embed_repo: INDEX_MUTATING,
+  subproject_add_repo: INDEX_MUTATING,
+  subproject_sync: INDEX_MUTATING,
+  invalidate_decision: INDEX_MUTATING,
+  index_sessions: INDEX_MUTATING,
+  mine_sessions: INDEX_MUTATING,
+  refresh_co_changes: INDEX_MUTATING,
+  detect_communities: INDEX_MUTATING,
+  // ── Store mutation (not idempotent — creates new records) ──
+  add_decision: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false
+  },
+  // ── Runtime intelligence (reads external OTLP data) ──
+  get_runtime_profile: RUNTIME_READ,
+  get_runtime_call_graph: RUNTIME_READ,
+  get_endpoint_analytics: RUNTIME_READ,
+  get_runtime_deps: RUNTIME_READ
+};
+var DEFAULT_ANNOTATIONS = READ_ONLY;
+function getToolAnnotations(toolName) {
+  return OVERRIDES[toolName] ?? DEFAULT_ANNOTATIONS;
+}
+
 // src/server/tool-gate.ts
 function applyParamOverrides(schema, toolOverrides, sharedOverrides) {
   for (const paramName of Object.keys(schema)) {
@@ -47676,9 +47757,23 @@ function installToolGate(server, config, activePreset, savings, journal, j3, ext
         return result;
       };
     }
+    const annotations = getToolAnnotations(name);
+    const lastIdx = args.length - 1;
+    if (typeof args[lastIdx] === "function") {
+      args.splice(lastIdx, 0, annotations);
+    }
     return _originalTool(...args);
   });
-  return { _originalTool, registeredToolNames, toolHandlers };
+  const annotatedOriginalTool = ((...oArgs) => {
+    const oName = oArgs[0];
+    const ann = getToolAnnotations(oName);
+    const oLastIdx = oArgs.length - 1;
+    if (typeof oArgs[oLastIdx] === "function") {
+      oArgs.splice(oLastIdx, 0, ann);
+    }
+    return _originalTool(...oArgs);
+  });
+  return { _originalTool: annotatedOriginalTool, registeredToolNames, toolHandlers };
 }
 
 // src/tools/register/core.ts
@@ -52474,7 +52569,7 @@ function registerCoreTools(server, ctx) {
   const { store, registry, config, projectRoot, guardPath, j: j3, jh, journal, vectorStore, embeddingService, progress } = ctx;
   server.tool(
     "get_index_health",
-    "Get index status, statistics, health information, and pipeline progress (indexing, summarization, embedding)",
+    "Get index status, statistics, health information, and pipeline progress (indexing, summarization, embedding). Read-only, no side effects. Use to verify the index is ready before running queries. Returns JSON: { totalFiles, totalSymbols, languages, frameworks, pipelineProgress }.",
     {},
     async () => {
       const result = getIndexHealth(store, config);
@@ -52486,7 +52581,7 @@ function registerCoreTools(server, ctx) {
   );
   server.tool(
     "reindex",
-    "Trigger (re)indexing of the project or a subdirectory",
+    "Trigger (re)indexing of the project or a subdirectory. Mutates the local index (SQLite). Use after major file changes; for single-file updates prefer register_edit instead. Idempotent \u2014 safe to re-run. Returns JSON: { status, totalFiles, indexed, skipped, errors, durationMs }.",
     {
       path: z2.string().max(512).optional().describe("Subdirectory to index (default: project root)"),
       force: z2.boolean().optional().describe("Skip hash check and reindex all files")
@@ -52504,7 +52599,7 @@ function registerCoreTools(server, ctx) {
   );
   server.tool(
     "embed_repo",
-    "Precompute and cache symbol embeddings for semantic / hybrid search. Embeddings are also computed lazily on first semantic query, but calling this once after a fresh index avoids the first-query latency spike. Requires AI provider to be enabled in config (ollama/openai). Set force=true to drop and recompute all existing embeddings.",
+    "Precompute and cache symbol embeddings for semantic / hybrid search. Embeddings are also computed lazily on first semantic query, but calling this once after a fresh index avoids the first-query latency spike. Requires AI provider to be enabled in config (ollama/openai). Set force=true to drop and recompute all existing embeddings. Mutates the vector store; idempotent. Use after reindex when you plan to use semantic search. Returns JSON: { status, indexed_this_run, total_embedded, coverage_pct, duration_ms }.",
     {
       batch_size: z2.number().int().min(1).max(500).optional().describe("Symbols per embedding API batch (default 50)"),
       force: z2.boolean().optional().describe("Drop existing embeddings and re-embed everything (default false \u2014 incremental)")
@@ -52559,7 +52654,7 @@ function registerCoreTools(server, ctx) {
   );
   server.tool(
     "register_edit",
-    "Notify trace-mcp that a file was edited. Reindexes the single file and invalidates search caches. Call after Edit/Write to keep index fresh. Also checks for duplicate symbols \u2014 if `_duplication_warnings` appears in the response, you may be recreating existing logic; review the referenced symbols before continuing.",
+    "Notify trace-mcp that a file was edited. Reindexes the single file and invalidates search caches. Call after Edit/Write to keep index fresh \u2014 much lighter than full reindex. Also checks for duplicate symbols \u2014 if `_duplication_warnings` appears in the response, you may be recreating existing logic; review the referenced symbols before continuing. Mutates the index; idempotent. Returns JSON: { status, file, totalFiles, indexed, _duplication_warnings? }.",
     {
       file_path: z2.string().min(1).max(512).describe("Relative path to the edited file")
     },
@@ -52595,7 +52690,7 @@ function registerCoreTools(server, ctx) {
   );
   server.tool(
     "get_project_map",
-    "Get project overview: detected frameworks, languages, file counts, structure. Call with summary_only=true at session start to orient yourself before diving into code.",
+    "Get project overview: detected frameworks, languages, file counts, structure. Read-only, no side effects. Call with summary_only=true at session start to orient yourself before diving into code. Use instead of manual ls/find. Returns JSON: { frameworks, languages, fileCount, symbolCount, structure }.",
     {
       summary_only: z2.boolean().optional().describe("Return only framework list + counts (default false)")
     },
@@ -52607,7 +52702,7 @@ function registerCoreTools(server, ctx) {
   );
   server.tool(
     "get_env_vars",
-    "List environment variable keys from .env files with inferred value types/formats. Never exposes actual values \u2014 only keys, types (string/number/boolean/empty), and formats (url/email/ip/path/uuid/json/base64/csv/dsn/etc). Use to understand project configuration without accessing secrets.",
+    "List environment variable keys from .env files with inferred value types/formats. Never exposes actual values \u2014 only keys, types (string/number/boolean/empty), and formats (url/email/ip/path/uuid/json/base64/csv/dsn/etc). Read-only, no side effects, safe for secrets. Use to understand project configuration without accessing actual values. Returns JSON grouped by file: { [file]: [{ key, type, format, comment }] }.",
     {
       pattern: z2.string().max(256).optional().describe('Filter keys by pattern (e.g. "DB_" or "REDIS")'),
       file: z2.string().max(512).optional().describe("Filter by specific .env file path")
@@ -53702,9 +53797,9 @@ function deduplicateByFile(rawDeps) {
     }
   }
   const result = [];
-  for (const [path65, entry] of fileMap) {
+  for (const [path66, entry] of fileMap) {
     const dep = {
-      path: path65,
+      path: path66,
       edgeTypes: [...entry.edgeTypes],
       depth: entry.depth
     };
@@ -56957,7 +57052,7 @@ function registerNavigationTools(server, ctx) {
   const { store, projectRoot, guardPath, j: j3, jh, savings, vectorStore, embeddingService, reranker, markExplored, decisionStore } = ctx;
   server.tool(
     "get_symbol",
-    "Look up a symbol by symbol_id or FQN and return its source code. Use instead of Read when you need one specific function/class/method \u2014 returns only the symbol, not the whole file.",
+    "Look up a symbol by symbol_id or FQN and return its source code. Use instead of Read when you need one specific function/class/method \u2014 returns only the symbol, not the whole file. For multiple symbols at once, prefer get_context_bundle. Read-only. Returns JSON: { symbol_id, name, kind, fqn, signature, file, line_start, line_end, source }.",
     {
       symbol_id: z3.string().max(512).optional().describe("The symbol_id to look up"),
       fqn: z3.string().max(512).optional().describe("The fully qualified name to look up"),
@@ -56992,7 +57087,7 @@ function registerNavigationTools(server, ctx) {
   );
   server.tool(
     "search",
-    'Search symbols by name, kind, or text. Use instead of Grep when looking for functions, classes, methods, or variables in source code. Supports kind/language/file_pattern filters. Set fuzzy=true for typo-tolerant search (trigram + Levenshtein). For natural-language / conceptual queries set semantic="on" (requires an AI provider configured + embed_repo run once). Set fusion=true for Signal Fusion \u2014 multi-channel ranking (BM25 + PageRank + embeddings + identity match) via Weighted Reciprocal Rank fusion.',
+    'Search symbols by name, kind, or text. Use instead of Grep when looking for functions, classes, methods, or variables in source code. For raw text/string/comment search use search_text instead. For finding who references a known symbol use find_usages instead. Supports kind/language/file_pattern filters. Set fuzzy=true for typo-tolerant search (trigram + Levenshtein). For natural-language / conceptual queries set semantic="on" (requires an AI provider configured + embed_repo run once). Set fusion=true for Signal Fusion \u2014 multi-channel ranking (BM25 + PageRank + embeddings + identity match) via Weighted Reciprocal Rank fusion. Read-only. Returns JSON: { items: [{ symbol_id, name, kind, fqn, signature, file, line, score }], total, search_mode }.',
     {
       query: z3.string().min(1).max(500).describe("Search query"),
       kind: z3.string().max(64).optional().describe("Filter by symbol kind (class, method, function, etc.)"),
@@ -57107,7 +57202,7 @@ function registerNavigationTools(server, ctx) {
   );
   server.tool(
     "get_outline",
-    "Get all symbols for a file (signatures only, no bodies). Use instead of Read to understand a file before editing \u2014 much cheaper in tokens.",
+    "Get all symbols for a file (signatures only, no bodies). Use instead of Read to understand a file before editing \u2014 much cheaper in tokens. For reading one symbol's source, follow up with get_symbol. Read-only. Returns JSON: { path, language, symbols: [{ symbolId, name, kind, signature, lineStart, lineEnd }] }.",
     {
       path: z3.string().max(512).describe("Relative file path")
     },
@@ -57133,7 +57228,7 @@ function registerNavigationTools(server, ctx) {
   );
   server.tool(
     "get_change_impact",
-    "Full change impact report: risk score + mitigations, breaking change detection, enriched dependents (complexity, coverage, exports), module groups, affected tests, co-change hidden couplings. Supports diff-aware mode via symbol_ids to scope analysis to only changed symbols.",
+    "Full change impact report: risk score + mitigations, breaking change detection, enriched dependents (complexity, coverage, exports), module groups, affected tests, co-change hidden couplings. Supports diff-aware mode via symbol_ids to scope analysis to only changed symbols. Use before modifying code to understand blast radius. For quick risk assessment without full report, use assess_change_risk instead. Read-only. Returns JSON: { risk, dependents, affectedTests, breakingChanges, totalAffected }.",
     {
       file_path: z3.string().max(512).optional().describe("Relative file path to analyze"),
       symbol_id: z3.string().max(512).optional().describe("Symbol ID to analyze"),
@@ -57176,7 +57271,7 @@ function registerNavigationTools(server, ctx) {
   );
   server.tool(
     "get_feature_context",
-    "Search code by keyword/topic \u2192 returns ranked source code snippets within a token budget. Use when you need to READ actual code for a concept or feature.",
+    "Search code by keyword/topic \u2192 returns ranked source code snippets within a token budget. Use when you need to READ actual code for a concept or feature. For structured task context with tests and entry points, use get_task_context instead. For symbol metadata without source, use search. Read-only. Returns JSON: { items: [{ symbol_id, name, file, source, score }], token_usage }.",
     {
       description: z3.string().min(1).max(2e3).describe("Natural language description of the feature to find context for"),
       token_budget: z3.number().int().min(100).max(1e5).optional().describe("Max tokens for assembled context (default 4000)")
@@ -57195,7 +57290,7 @@ function registerNavigationTools(server, ctx) {
   );
   server.tool(
     "suggest_queries",
-    "Onboarding helper: shows top imported files, most connected symbols (PageRank), language stats, and example tool calls. Call this first when exploring an unfamiliar project.",
+    "Onboarding helper: shows top imported files, most connected symbols (PageRank), language stats, and example tool calls. Call this first when exploring an unfamiliar project. For a structured project map use get_project_map instead. Read-only. Returns JSON: { topFiles, topSymbols, languageStats, exampleQueries }.",
     {},
     async () => {
       const result = suggestQueries(store);
@@ -57204,7 +57299,7 @@ function registerNavigationTools(server, ctx) {
   );
   server.tool(
     "get_related_symbols",
-    "Find symbols related via co-location (same file), shared importers, and name similarity. Useful for discovering related code when exploring a symbol.",
+    "Find symbols related via co-location (same file), shared importers, and name similarity. Use when exploring a symbol to discover sibling code. For call-graph relationships use get_call_graph instead; for all usages use find_usages. Read-only. Returns JSON: { related: [{ symbol_id, name, kind, file, relation_type, score }] }.",
     {
       symbol_id: z3.string().max(512).describe("Symbol ID to find related symbols for"),
       max_results: z3.number().int().min(1).max(100).optional().describe("Max results (default 20)")
@@ -57219,7 +57314,7 @@ function registerNavigationTools(server, ctx) {
   );
   server.tool(
     "get_context_bundle",
-    "Get a symbol's source code + its import dependencies + optional callers, packed within a token budget. Supports batch queries with shared-import deduplication.",
+    "Get a symbol's source code + its import dependencies + optional callers, packed within a token budget. Supports batch queries with shared-import deduplication. Use instead of chaining get_symbol calls \u2014 deduplicates shared imports across symbols. For a single symbol without imports, get_symbol is lighter. Read-only. Returns JSON: { primary: [{ symbol_id, file, source }], imports: [{ file, source }], token_usage }.",
     {
       symbol_id: z3.string().max(512).optional().describe("Single symbol ID"),
       symbol_ids: z3.array(z3.string().max(512)).max(20).optional().describe("Batch: multiple symbol IDs"),
@@ -57250,7 +57345,7 @@ function registerNavigationTools(server, ctx) {
   );
   server.tool(
     "get_task_context",
-    "All-in-one context for starting a dev task: execution paths, tests, entry points, adapted by task type. Use as your FIRST call when beginning any new task.",
+    "All-in-one context for starting a dev task: execution paths, tests, entry points, adapted by task type. Use as your FIRST call when beginning any new task \u2014 replaces manual chaining of search \u2192 get_symbol \u2192 Read. For narrower feature-code lookup use get_feature_context instead. Read-only. Returns JSON: { symbols: [{ symbol_id, name, file, source }], tests, entryPoints, taskType, token_usage }.",
     {
       task: z3.string().min(1).max(2e3).describe("Natural language description of the task"),
       token_budget: z3.number().int().min(100).max(1e5).optional().describe("Max tokens (default 8000)"),
@@ -58913,7 +59008,7 @@ function registerFrameworkTools(server, ctx) {
   if (has("vue", "nuxt", "inertia")) {
     server.tool(
       "get_component_tree",
-      "Build a component render tree starting from a given .vue file",
+      "Build a component render tree starting from a given .vue file. Use to visualize parent-child component hierarchy. Read-only. Returns JSON: { root, children: [{ component, props, slots, depth }], totalComponents }.",
       {
         component_path: z4.string().max(512).describe("Relative path to the root .vue file"),
         depth: z4.number().int().min(1).max(20).optional().describe("Max tree depth (default 3)"),
@@ -58933,7 +59028,7 @@ function registerFrameworkTools(server, ctx) {
   if (has("express", "nestjs", "laravel", "fastapi", "flask", "drf", "spring", "rails", "fastify", "hono", "trpc")) {
     server.tool(
       "get_request_flow",
-      "Trace request flow for a URL+method: route \u2192 middleware \u2192 controller \u2192 service (Laravel/Express/NestJS/Fastify/Hono/tRPC/FastAPI/Flask/DRF)",
+      "Trace request flow for a URL+method: route \u2192 middleware \u2192 controller \u2192 service (Laravel/Express/NestJS/Fastify/Hono/tRPC/FastAPI/Flask/DRF). Use to understand how a request is handled end-to-end. For middleware-only analysis use get_middleware_chain instead. Read-only. Returns JSON: { route, steps: [{ type, symbol_id, name, file }] }.",
       {
         url: z4.string().max(512).describe("Route URL (e.g. /api/users)"),
         method: z4.string().max(64).optional().describe("HTTP method (default GET)")
@@ -58950,7 +59045,7 @@ function registerFrameworkTools(server, ctx) {
   if (has("express", "nestjs", "fastapi", "flask", "spring")) {
     server.tool(
       "get_middleware_chain",
-      "Trace middleware chain for a route URL (Express/NestJS/FastAPI/Flask)",
+      "Trace middleware chain for a route URL (Express/NestJS/FastAPI/Flask). Use when you only need the middleware stack, not the full request flow. For full route\u2192controller\u2192service flow use get_request_flow instead. Read-only. Returns JSON: { url, middlewares: [{ name, file, order }] }.",
       {
         url: z4.string().max(512).describe("Route URL to trace middleware for")
       },
@@ -58966,7 +59061,7 @@ function registerFrameworkTools(server, ctx) {
   if (has("nestjs")) {
     server.tool(
       "get_module_graph",
-      "Build NestJS module dependency graph (module -> imports -> controllers -> providers -> exports)",
+      "Build NestJS module dependency graph (module -> imports -> controllers -> providers -> exports). Use to understand NestJS module structure and DI wiring. For provider-level DI tree use get_di_tree instead. Read-only. Returns JSON: { module, imports, controllers, providers, exports, edges }.",
       {
         module_name: z4.string().max(256).describe("NestJS module class name (e.g. AppModule)")
       },
@@ -58980,7 +59075,7 @@ function registerFrameworkTools(server, ctx) {
     );
     server.tool(
       "get_di_tree",
-      "Trace NestJS dependency injection tree (what a service injects + who injects it)",
+      "Trace NestJS dependency injection tree (what a service injects + who injects it). Use to understand DI wiring for a specific provider. For module-level graph use get_module_graph instead. Read-only. Returns JSON: { service, injects: [{ name, kind }], injected_by: [{ name, kind }] }.",
       {
         service_name: z4.string().max(256).describe("NestJS service/provider class name")
       },
@@ -58996,7 +59091,7 @@ function registerFrameworkTools(server, ctx) {
   if (has("react-native")) {
     server.tool(
       "get_navigation_graph",
-      "Build React Native navigation tree from screens, navigators, and deep links",
+      "Build React Native navigation tree from screens, navigators, and deep links. Use to understand app navigation structure. For details on a specific screen use get_screen_context instead. Read-only. Returns JSON: { navigators, screens, deepLinks, edges }.",
       {},
       async () => {
         const result = getNavigationGraph(store);
@@ -59008,7 +59103,7 @@ function registerFrameworkTools(server, ctx) {
     );
     server.tool(
       "get_screen_context",
-      "Get full context for a React Native screen: navigator, navigation edges, deep link, platform variants, native modules",
+      "Get full context for a React Native screen: navigator, navigation edges, deep link, platform variants, native modules. Use to understand a specific screen before modifying it. For the full navigation tree use get_navigation_graph instead. Read-only. Returns JSON: { screen, navigator, deepLink, platformVariants, nativeModules, navigationEdges }.",
       {
         screen_name: z4.string().max(256).describe("Screen name (e.g. ProfileScreen or Profile)")
       },
@@ -59024,7 +59119,7 @@ function registerFrameworkTools(server, ctx) {
   if (has("laravel", "mongoose", "sequelize", "prisma", "typeorm", "drizzle", "sqlalchemy")) {
     server.tool(
       "get_model_context",
-      "Get full model context: relationships, schema, and metadata (Eloquent/Mongoose/Sequelize/SQLAlchemy/Prisma/TypeORM/Drizzle)",
+      "Get full model context: relationships, schema, and metadata (Eloquent/Mongoose/Sequelize/SQLAlchemy/Prisma/TypeORM/Drizzle). Use to understand a specific ORM model. For raw table schema without ORM context use get_schema instead. Read-only. Returns JSON: { model, table, relationships: [{ type, related, foreignKey }], fields, metadata }.",
       {
         model_name: z4.string().max(256).describe("Model class name (e.g. User, Post)")
       },
@@ -59038,7 +59133,7 @@ function registerFrameworkTools(server, ctx) {
     );
     server.tool(
       "get_schema",
-      "Get database schema reconstructed from migrations or ORM model definitions",
+      "Get database schema reconstructed from migrations or ORM model definitions. Use to understand table structure. For ORM-level context with relationships use get_model_context instead. Read-only. Returns JSON: { tables: [{ name, columns: [{ name, type, nullable, default }], indexes }] }.",
       {
         table_name: z4.string().max(256).optional().describe("Table/collection/model name (omit for all)")
       },
@@ -59054,7 +59149,7 @@ function registerFrameworkTools(server, ctx) {
   if (has("laravel", "nestjs", "celery", "django", "socketio")) {
     server.tool(
       "get_event_graph",
-      "Get event/signal/task dispatch graph (Laravel events, Django signals, NestJS events, Celery tasks, Socket.io events)",
+      "Get event/signal/task dispatch graph (Laravel events, Django signals, NestJS events, Celery tasks, Socket.io events). Use to understand event-driven architecture and trace event producers/consumers. Read-only. Returns JSON: { events: [{ name, dispatchers, listeners, file }] }.",
       {
         event_name: z4.string().max(256).optional().describe("Filter to a specific event class name")
       },
@@ -59069,7 +59164,7 @@ function registerFrameworkTools(server, ctx) {
   }
   server.tool(
     "find_usages",
-    "Find all places that reference a symbol or file (imports, calls, renders, dispatches). Use instead of Grep for symbol usages \u2014 understands semantic relationships, not just text matches.",
+    "Find all places that reference a symbol or file (imports, calls, renders, dispatches). Use instead of Grep for symbol usages \u2014 understands semantic relationships, not just text matches. For bidirectional call graph use get_call_graph instead. Read-only. Returns JSON: { references: [{ file, line, kind, context }], total }.",
     {
       symbol_id: z4.string().max(512).optional().describe("Symbol ID to find references for"),
       fqn: z4.string().max(512).optional().describe("Fully qualified name to find references for"),
@@ -59103,7 +59198,7 @@ function registerFrameworkTools(server, ctx) {
   );
   server.tool(
     "get_call_graph",
-    "Build a bidirectional call graph centered on a symbol (who calls it + what it calls). Use to understand control flow through a function.",
+    "Build a bidirectional call graph centered on a symbol (who calls it + what it calls). Use to understand control flow through a function. For flat list of all references use find_usages instead. Read-only. Returns JSON: { root: { symbol_id, name, calls: [...], called_by: [...] } }.",
     {
       symbol_id: z4.string().max(512).optional().describe("Symbol ID to center the graph on"),
       fqn: z4.string().max(512).optional().describe("Fully qualified name to center the graph on"),
@@ -59136,7 +59231,7 @@ function registerFrameworkTools(server, ctx) {
   );
   server.tool(
     "get_tests_for",
-    "Find test files and test functions that cover a given symbol or file. Use instead of Glob/Grep \u2014 understands test-to-source mapping, not just filename conventions.",
+    "Find test files and test functions that cover a given symbol or file. Use instead of Glob/Grep \u2014 understands test-to-source mapping, not just filename conventions. For project-wide test coverage gaps use get_untested_symbols instead. Read-only. Returns JSON: { tests: [{ file, testName, symbol_id }], total }.",
     {
       symbol_id: z4.string().max(512).optional().describe("Symbol ID to find tests for"),
       fqn: z4.string().max(512).optional().describe("Fully qualified name to find tests for"),
@@ -59171,7 +59266,7 @@ function registerFrameworkTools(server, ctx) {
   if (has("laravel")) {
     server.tool(
       "get_livewire_context",
-      "Get full context for a Livewire component: properties, actions, events, view, child components",
+      "Get full context for a Livewire component: properties, actions, events, view, child components. Use to understand a specific Livewire component before modifying it. Read-only. Returns JSON: { component, properties, actions, events, view, children }.",
       {
         component_name: z4.string().max(256).describe("Livewire component class name or FQN (e.g. UserProfile or App\\Livewire\\UserProfile)")
       },
@@ -59185,7 +59280,7 @@ function registerFrameworkTools(server, ctx) {
     );
     server.tool(
       "get_nova_resource",
-      "Get full context for a Laravel Nova resource: model, fields, actions, filters, lenses, metrics",
+      "Get full context for a Laravel Nova resource: model, fields, actions, filters, lenses, metrics. Use to understand a Nova admin resource before modifying it. Read-only. Returns JSON: { resource, model, fields, actions, filters, lenses, metrics }.",
       {
         resource_name: z4.string().max(256).describe("Nova resource class name or FQN (e.g. User or App\\Nova\\User)")
       },
@@ -59201,7 +59296,7 @@ function registerFrameworkTools(server, ctx) {
   if (has("zustand-redux")) {
     server.tool(
       "get_state_stores",
-      "List all Zustand stores and Redux Toolkit slices with their state fields, actions/reducers, and dispatch sites",
+      "List all Zustand stores and Redux Toolkit slices with their state fields, actions/reducers, and dispatch sites. Use to understand state management architecture. Read-only. Returns JSON: { stores: [{ type, name, handler, metadata }], dispatches, totalStores, totalDispatches }.",
       {},
       async () => {
         const routes = store.getAllRoutes();
@@ -60049,7 +60144,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_implementations",
-    "Find all classes that implement or extend a given interface or base class",
+    "Find all classes that implement or extend a given interface or base class. Use when you know the interface name. For full hierarchy tree (ancestors + descendants) use get_type_hierarchy instead. Read-only. Returns JSON: { implementations: [{ symbol_id, name, kind, file, line }], total }.",
     {
       name: z5.string().max(256).describe("Interface or base class name (e.g. UserRepositoryInterface)")
     },
@@ -60075,7 +60170,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_api_surface",
-    "List all exported symbols (public API) of a file or matching files",
+    "List all exported symbols (public API) of a file or matching files. Use to understand what a module exposes. For finding unused exports use get_dead_exports instead. Read-only. Returns JSON: { files: [{ path, exports: [{ name, kind, signature }] }] }.",
     {
       file_pattern: z5.string().max(512).optional().describe("Glob-style pattern to filter files (e.g. src/services/*.ts)")
     },
@@ -60086,7 +60181,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_plugin_registry",
-    "List all registered indexer plugins and the edge types they emit",
+    "List all registered indexer plugins and the edge types they emit. Use for debugging indexer behavior or understanding which frameworks are supported. Read-only. Returns JSON: { languagePlugins, frameworkPlugins, edgeTypes }.",
     {},
     async () => {
       const result = getPluginRegistry(store, registry, frameworkNames);
@@ -60095,7 +60190,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_type_hierarchy",
-    "Walk TypeScript class/interface hierarchy: ancestors (what it extends/implements) and descendants (what extends/implements it)",
+    "Walk TypeScript class/interface hierarchy: ancestors (what it extends/implements) and descendants (what extends/implements it). Use to understand inheritance trees. For a flat list of implementations only use get_implementations instead. Read-only. Returns JSON: { name, ancestors: [...], descendants: [...] }.",
     {
       name: z5.string().max(256).describe('Class or interface name (e.g. "LanguagePlugin", "Store")'),
       max_depth: z5.number().int().min(1).max(20).optional().describe("Max traversal depth (default 10)")
@@ -60122,7 +60217,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_dead_exports",
-    "Find exported symbols never imported by any other file \u2014 dead code candidates",
+    "Find exported symbols never imported by any other file \u2014 dead code candidates. Use for quick export-level dead code scan. For deeper multi-signal dead code detection (including call graph) use get_dead_code instead. Read-only. Returns JSON: { deadExports: [{ symbol_id, name, kind, file }], total }.",
     {
       file_pattern: z5.string().max(512).optional().describe('Filter files by glob pattern (e.g. "src/tools/*.ts")')
     },
@@ -60133,7 +60228,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_import_graph",
-    "Show file-level dependency graph: what a file imports and what imports it (requires reindex for ESM edge resolution)",
+    "Show file-level dependency graph: what a file imports and what imports it (requires reindex for ESM edge resolution). Use to understand module dependencies for a specific file. For project-wide coupling analysis use get_coupling; for visual diagram use get_dependency_diagram. Read-only. Returns JSON: { file, imports: [{ path }], importedBy: [{ path }] }.",
     {
       file_path: z5.string().max(512).describe('Relative file path to analyze (e.g. "src/server.ts")')
     },
@@ -60146,7 +60241,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_untested_exports",
-    "Find exported public symbols with no matching test file \u2014 test coverage gaps",
+    "Find exported public symbols with no matching test file \u2014 test coverage gaps. For deeper analysis including non-exported symbols use get_untested_symbols instead. Read-only. Returns JSON: { untested: [{ symbol_id, name, kind, file }], total }.",
     {
       file_pattern: z5.string().max(512).optional().describe('Filter by file glob pattern (e.g. "src/tools/%")')
     },
@@ -60157,7 +60252,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_untested_symbols",
-    'Find ALL symbols (not just exports) lacking test coverage. Classifies as "unreached" (no test file imports the source) or "imported_not_called" (test imports file but never references this symbol). Use for thorough coverage gap analysis.',
+    'Find ALL symbols (not just exports) lacking test coverage. Classifies as "unreached" (no test file imports the source) or "imported_not_called" (test imports file but never references this symbol). Use for thorough coverage gap analysis. For exports-only quick scan use get_untested_exports instead. Read-only. Returns JSON: { untested: [{ symbol_id, name, kind, file, classification }], total }.',
     {
       file_pattern: z5.string().max(512).optional().describe('Filter by file glob pattern (e.g. "src/tools/%")'),
       max_results: z5.number().int().min(1).max(500).optional().describe("Cap on returned items (default: all)")
@@ -60167,12 +60262,12 @@ function registerAnalysisTools(server, ctx) {
       return { content: [{ type: "text", text: jh("get_untested_symbols", result) }] };
     }
   );
-  server.tool("self_audit", "Dead code & coverage audit: dead exports, untested public symbols, heritage debt. Use for cleanup and coverage tasks.", {}, async () => {
+  server.tool("self_audit", "Dead code & coverage audit: dead exports, untested public symbols, heritage debt. Use as a one-shot health check combining dead exports + untested symbols + heritage debt. For individual checks use get_dead_exports, get_untested_symbols, or get_dead_code separately. Read-only. Returns JSON: { deadExports, untestedSymbols, heritageDebt, summary }.", {}, async () => {
     return { content: [{ type: "text", text: j3(selfAudit(store)) }] };
   });
   server.tool(
     "get_coupling",
-    "Coupling analysis: afferent (Ca), efferent (Ce), instability index per file. Shows which modules are stable vs unstable",
+    "Coupling analysis: afferent (Ca), efferent (Ce), instability index per file. Shows which modules are stable vs unstable. Use to identify fragile or overly-depended-on modules. For coupling changes over time use get_coupling_trend instead. Read-only. Returns JSON: [{ file, ca, ce, instability, assessment }].",
     {
       limit: z5.number().int().min(1).max(500).optional().describe("Max results (default: all)"),
       assessment: z5.enum(["stable", "neutral", "unstable", "isolated"]).optional().describe("Filter by stability assessment")
@@ -60186,7 +60281,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_circular_imports",
-    "Find circular dependency chains in the import graph (Kosaraju SCC algorithm)",
+    "Find circular dependency chains in the import graph (Kosaraju SCC algorithm). Use to detect and break dependency cycles. Read-only. Returns JSON: { total_cycles, cycles: [[file1, file2, ...]] }.",
     {},
     async () => {
       const cycles = getDependencyCycles(store);
@@ -60205,7 +60300,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_pagerank",
-    "File importance ranking via PageRank on the import graph. Shows most central/important files",
+    "File importance ranking via PageRank on the import graph. Shows most central/important files. Use to identify architecturally critical files. For combined health metrics use get_project_health instead. Read-only. Returns JSON: [{ file, score }].",
     {
       limit: z5.number().int().min(1).max(200).optional().describe("Max results (default: 50)")
     },
@@ -60216,7 +60311,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_refactor_candidates",
-    "Find functions with high complexity called from many files \u2014 candidates for extraction to shared modules",
+    "Find functions with high complexity called from many files \u2014 candidates for extraction to shared modules. Use during architecture review to identify hotspots worth refactoring. Read-only. Returns JSON: [{ symbol_id, name, file, cyclomatic, callerCount }].",
     {
       min_cyclomatic: z5.number().int().min(1).optional().describe("Min cyclomatic complexity (default: 5)"),
       min_callers: z5.number().int().min(1).optional().describe("Min distinct caller files (default: 2)"),
@@ -60233,7 +60328,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_project_health",
-    "Structural health: coupling instability, dependency cycles, PageRank rankings, refactor candidates. Use for architecture review.",
+    "Structural health: coupling instability, dependency cycles, PageRank rankings, refactor candidates. Use for architecture review as a single aggregated report. For individual metrics use get_coupling, get_circular_imports, or get_pagerank separately. Read-only. Returns JSON: { coupling, cycles, pagerank, refactorCandidates, hotspots }.",
     {},
     async () => {
       const result = getRepoHealth(store);
@@ -60243,7 +60338,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "check_architecture",
-    "Check architectural layer rules: detect forbidden imports between layers (e.g. domain importing infrastructure). Supports auto-detected presets (clean-architecture, hexagonal) or custom layers.",
+    "Check architectural layer rules: detect forbidden imports between layers (e.g. domain importing infrastructure). Supports auto-detected presets (clean-architecture, hexagonal) or custom layers. Use to enforce architectural boundaries. Read-only. Returns JSON: { violations: [{ from, to, rule, file, line }], total, preset }.",
     {
       preset: z5.enum(["clean-architecture", "hexagonal"]).optional().describe("Use a built-in layer preset (auto-detected if omitted)"),
       layers: z5.array(z5.object({
@@ -60272,7 +60367,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_code_owners",
-    "Git-based code ownership: who contributed most to specific files (git shortlog). Requires git.",
+    "Git-based code ownership: who contributed most to specific files (git shortlog). Requires git. Use to identify who to ask about specific files. For symbol-level ownership use get_symbol_owners instead. Read-only. Returns JSON: [{ file, owners: [{ author, commits, percentage }] }].",
     {
       file_paths: z5.array(z5.string().max(512)).min(1).max(20).describe("File paths to check ownership for")
     },
@@ -60290,7 +60385,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_symbol_owners",
-    "Git blame-based symbol ownership: who wrote which lines of a specific symbol. Requires git.",
+    "Git blame-based symbol ownership: who wrote which lines of a specific symbol. Requires git. Use for fine-grained ownership of a specific function/class. For file-level ownership use get_code_owners instead. Read-only. Returns JSON: { symbol_id, owners: [{ author, lines, percentage }] }.",
     {
       symbol_id: z5.string().max(512).describe("Symbol ID to check ownership for")
     },
@@ -60304,7 +60399,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_complexity_trend",
-    "File complexity over git history: cyclomatic complexity at past commits. Shows if a file is getting more or less complex.",
+    "File complexity over git history: cyclomatic complexity at past commits. Shows if a file is getting more or less complex. Requires git. Use to track whether a file is improving or degrading. For current snapshot use get_complexity_report; for symbol-level trends use get_symbol_complexity_trend. Read-only. Returns JSON: { file, snapshots: [{ commit, date, complexity }] }.",
     {
       file_path: z5.string().max(512).describe("File path to analyze"),
       snapshots: z5.number().int().min(2).max(20).optional().describe("Number of historical snapshots (default: 5)")
@@ -60321,7 +60416,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_coupling_trend",
-    "File coupling over git history: Ca/Ce/instability at past commits. Shows if a module is stabilizing or destabilizing.",
+    "File coupling over git history: Ca/Ce/instability at past commits. Shows if a module is stabilizing or destabilizing. Requires git. Use to track module stability over time. For current coupling snapshot use get_coupling instead. Read-only. Returns JSON: { file, snapshots: [{ commit, date, ca, ce, instability }] }.",
     {
       file_path: z5.string().max(512).describe("File path to analyze"),
       since_days: z5.number().int().min(1).optional().describe("Analyze last N days (default: 90)"),
@@ -60342,7 +60437,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_symbol_complexity_trend",
-    "Single symbol complexity over git history: cyclomatic, nesting, params, lines at past commits.",
+    "Single symbol complexity over git history: cyclomatic, nesting, params, lines at past commits. Requires git. Use to track a specific function's complexity evolution. For file-level trends use get_complexity_trend instead. Read-only. Returns JSON: { symbol_id, snapshots: [{ commit, date, cyclomatic, nesting, params, lines }] }.",
     {
       symbol_id: z5.string().min(1).max(512).describe("Symbol ID to analyze (from search or outline)"),
       since_days: z5.number().int().min(1).optional().describe("Analyze last N days (default: all history)"),
@@ -60361,7 +60456,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "check_duplication",
-    "Check if a function/class name already exists elsewhere in the codebase before creating it. Prevents duplicating existing logic. Call with just a name when planning new code, or symbol_id to check an existing symbol. Returns scored matches \u2014 score \u22650.7 means high likelihood of duplication, review the existing symbol before proceeding.",
+    "Check if a function/class name already exists elsewhere in the codebase before creating it. Prevents duplicating existing logic. Call with just a name when planning new code, or symbol_id to check an existing symbol. Returns scored matches \u2014 score \u22650.7 means high likelihood of duplication, review the existing symbol before proceeding. Read-only. Returns JSON: { duplicates: [{ symbol_id, name, file, score }], hasDuplication }.",
     {
       symbol_id: z5.string().max(512).optional().describe("Existing symbol ID to check for duplicates"),
       name: z5.string().max(256).optional().describe("Function/class name to check (when symbol_id not available)"),
@@ -63516,7 +63611,7 @@ function registerGitTools(server, ctx) {
   const detectedFrameworks = registry.getAllFrameworkPlugins().map((p) => p.manifest.name);
   server.tool(
     "get_git_churn",
-    "Per-file git churn: commits, unique authors, frequency, volatility assessment. Requires git.",
+    "Per-file git churn: commits, unique authors, frequency, volatility assessment. Requires git. Use to identify frequently-changed files. For combined churn+complexity hotspots use get_risk_hotspots instead. Read-only. Returns JSON: { results: [{ file, commits, authors, frequency, volatility }], total }.",
     {
       since_days: z6.number().int().min(1).optional().describe("Analyze commits from last N days (default: all history)"),
       limit: z6.number().int().min(1).max(500).optional().describe("Max results (default: 50)"),
@@ -63536,7 +63631,7 @@ function registerGitTools(server, ctx) {
   );
   server.tool(
     "get_risk_hotspots",
-    "Code hotspots: files with both high complexity AND high git churn (Adam Tornhill methodology). Score = complexity \xD7 log(1 + commits). Each entry includes a confidence_level (low/medium/multi_signal) counting how many of the two independent signals fired strongly. Result envelope includes _methodology disclosure and _warnings when git is unavailable.",
+    "Code hotspots: files with both high complexity AND high git churn (Adam Tornhill methodology). Score = complexity \xD7 log(1 + commits). Each entry includes a confidence_level (low/medium/multi_signal) counting how many of the two independent signals fired strongly. Result envelope includes _methodology disclosure and _warnings when git is unavailable. Requires git. Use to prioritize refactoring. For per-file bug prediction use predict_bugs instead. Read-only. Returns JSON: { hotspots: [{ file, score, complexity, commits, confidence_level }], total }.",
     {
       since_days: z6.number().int().min(1).optional().describe("Git churn window in days (default: 90)"),
       limit: z6.number().int().min(1).max(100).optional().describe("Max results (default: 20)"),
@@ -63567,7 +63662,7 @@ function registerGitTools(server, ctx) {
   );
   server.tool(
     "get_dead_code",
-    'Dead code detection. Two modes: (1) "multi-signal" (default) combines import graph, call graph, and barrel export analysis with confidence scores. (2) "reachability" runs forward BFS from auto-detected entry points (tests, package.json main/bin, src/{cli,main,index}, routes, framework-tagged controllers) \u2014 stricter but more accurate when entry points are enumerable. Pass entry_points to add custom roots. Both modes emit _methodology and _warnings.',
+    'Dead code detection. Two modes: (1) "multi-signal" (default) combines import graph, call graph, and barrel export analysis with confidence scores. (2) "reachability" runs forward BFS from auto-detected entry points (tests, package.json main/bin, src/{cli,main,index}, routes, framework-tagged controllers) \u2014 stricter but more accurate when entry points are enumerable. Pass entry_points to add custom roots. Both modes emit _methodology and _warnings. Use for comprehensive dead code analysis. For quick export-only scan use get_dead_exports; to safely remove detected dead code use remove_dead_code. Read-only. Returns JSON: { dead_symbols: [{ symbol_id, name, file, confidence, signals }], total }.',
     {
       file_pattern: z6.string().max(512).optional().describe('Filter by file glob pattern (e.g. "src/tools/%")'),
       threshold: z6.number().min(0).max(1).optional().describe("[multi-signal mode] Min confidence to report (default: 0.5 = at least 2 of 3 signals)"),
@@ -63597,7 +63692,7 @@ function registerGitTools(server, ctx) {
   );
   server.tool(
     "scan_security",
-    "Scan project files for OWASP Top-10 security vulnerabilities using pattern matching. Detects SQL injection (CWE-89), XSS (CWE-79), command injection (CWE-78), path traversal (CWE-22), hardcoded secrets (CWE-798), insecure crypto (CWE-327), open redirects (CWE-601), and SSRF (CWE-918). Skips test files.",
+    "Scan project files for OWASP Top-10 security vulnerabilities using pattern matching. Detects SQL injection (CWE-89), XSS (CWE-79), command injection (CWE-78), path traversal (CWE-22), hardcoded secrets (CWE-798), insecure crypto (CWE-327), open redirects (CWE-601), and SSRF (CWE-918). Skips test files. Use for pattern-based security audit. For data-flow-aware analysis use taint_analysis instead. Read-only. Returns JSON: { findings: [{ rule, severity, cwe, file, line, message }], total, summary }.",
     {
       scope: z6.string().max(512).optional().describe("Directory to scan (default: whole project)"),
       rules: z6.array(z6.enum([
@@ -63631,7 +63726,7 @@ function registerGitTools(server, ctx) {
   );
   server.tool(
     "detect_antipatterns",
-    "Detect performance antipatterns: N+1 query risks, missing eager loading, unbounded queries, event listener leaks, circular model dependencies, missing indexes, memory leaks (unbounded caches, closure leaks). Static analysis across all indexed ORMs (Eloquent, Sequelize, Mongoose, Django, Prisma, TypeORM, Drizzle).",
+    "Detect performance antipatterns: N+1 query risks, missing eager loading, unbounded queries, event listener leaks, circular model dependencies, missing indexes, memory leaks (unbounded caches, closure leaks). Static analysis across all indexed ORMs (Eloquent, Sequelize, Mongoose, Django, Prisma, TypeORM, Drizzle). Use to find performance issues. For code quality issues (TODOs, empty functions) use scan_code_smells instead. Read-only. Returns JSON: { findings: [{ category, severity, file, line, message, suggestion }], total }.",
     {
       category: z6.array(z6.enum([
         "n_plus_one_risk",
@@ -63661,7 +63756,7 @@ function registerGitTools(server, ctx) {
   );
   server.tool(
     "scan_code_smells",
-    "Find deferred work and shortcuts: TODO/FIXME/HACK/XXX comments, empty functions & stubs, hardcoded values (IPs, URLs, credentials, magic numbers, feature flags). Surfaces technical debt that grep alone misses by combining comment scanning, symbol body analysis, and context-aware false-positive filtering.",
+    "Find deferred work and shortcuts: TODO/FIXME/HACK/XXX comments, empty functions & stubs, hardcoded values (IPs, URLs, credentials, magic numbers, feature flags). Surfaces technical debt that grep alone misses by combining comment scanning, symbol body analysis, and context-aware false-positive filtering. Use for code quality audit. For performance-specific antipatterns use detect_antipatterns; for security issues use scan_security. Read-only. Returns JSON: { findings: [{ category, priority, file, line, message }], total, summary }.",
     {
       category: z6.array(z6.enum([
         "todo_comment",
@@ -63695,7 +63790,7 @@ function registerGitTools(server, ctx) {
   );
   server.tool(
     "taint_analysis",
-    "Track flow of untrusted data from sources (HTTP params, env vars, file reads) to dangerous sinks (SQL queries, exec, innerHTML, redirects). Framework-aware: knows Express req.params, Laravel $request->input, Django request.GET, FastAPI Query(), etc. Reports unsanitized flows with CWE IDs and fix suggestions. More accurate than pattern-based scanning \u2014 traces actual data flow paths.",
+    "Track flow of untrusted data from sources (HTTP params, env vars, file reads) to dangerous sinks (SQL queries, exec, innerHTML, redirects). Framework-aware: knows Express req.params, Laravel $request->input, Django request.GET, FastAPI Query(), etc. Reports unsanitized flows with CWE IDs and fix suggestions. More accurate than pattern-based scanning \u2014 traces actual data flow paths. Use for data-flow security analysis. For pattern-based OWASP scanning use scan_security instead. Read-only. Returns JSON: { flows: [{ source, sink, path, sanitized, cwe, suggestion }], total }.",
     {
       scope: z6.string().max(512).optional().describe("Directory to scan (default: whole project)"),
       sources: z6.array(z6.enum([
@@ -63741,7 +63836,7 @@ function registerGitTools(server, ctx) {
   );
   server.tool(
     "generate_sbom",
-    "Generate a Software Bill of Materials (SBOM) from package manifests and lockfiles. Supports npm, Composer, pip, Go, Cargo, Bundler, Maven. Outputs CycloneDX, SPDX, or plain JSON. Includes license compliance warnings for copyleft licenses.",
+    "Generate a Software Bill of Materials (SBOM) from package manifests and lockfiles. Supports npm, Composer, pip, Go, Cargo, Bundler, Maven. Outputs CycloneDX, SPDX, or plain JSON. Includes license compliance warnings for copyleft licenses. Use for supply chain audits or compliance reports. Returns JSON/CycloneDX/SPDX: { components: [{ name, version, license, type }], warnings }.",
     {
       format: z6.enum(["cyclonedx", "spdx", "json"]).optional().describe("Output format (default: json)"),
       include_dev: z6.boolean().optional().describe("Include devDependencies (default: false)"),
@@ -63761,7 +63856,7 @@ function registerGitTools(server, ctx) {
   );
   server.tool(
     "get_artifacts",
-    "Surface non-code knowledge from the index: DB schemas (migrations, ORM models), API specs (routes, OpenAPI endpoints), infrastructure (docker-compose services, K8s resources), CI pipelines (jobs, stages), and config (env vars). All data from the existing index \u2014 no extra I/O.",
+    "Surface non-code knowledge from the index: DB schemas (migrations, ORM models), API specs (routes, OpenAPI endpoints), infrastructure (docker-compose services, K8s resources), CI pipelines (jobs, stages), and config (env vars). All data from the existing index \u2014 no extra I/O. Use to discover infrastructure and config artifacts without reading files. Read-only. Returns JSON: { artifacts: [{ category, kind, name, file }], total }.",
     {
       category: z6.enum(["database", "api", "infra", "ci", "config", "all"]).optional().describe("Filter by artifact category (default: all)"),
       query: z6.string().max(256).optional().describe("Text filter on name/kind/file"),
@@ -63778,7 +63873,7 @@ function registerGitTools(server, ctx) {
   );
   server.tool(
     "plan_batch_change",
-    "Analyze the impact of updating a package/dependency. Shows all affected files, import references, and generates a PR template with checklist. Use before upgrading a dependency to understand blast radius.",
+    "Analyze the impact of updating a package/dependency. Shows all affected files, import references, and generates a PR template with checklist. Use before upgrading a dependency to understand blast radius. Read-only (analysis only, does not modify files). Returns JSON: { package, affectedFiles, importReferences, prTemplate, checklist }.",
     {
       package: z6.string().min(1).max(256).describe('Package name (e.g. "express", "laravel/framework", "react")'),
       from_version: z6.string().max(64).optional().describe("Current version"),
@@ -63800,7 +63895,7 @@ function registerGitTools(server, ctx) {
   );
   server.tool(
     "get_complexity_report",
-    "Get complexity metrics (cyclomatic, max nesting, param count) for symbols in a file or across the project. Useful for identifying complex code before refactoring.",
+    "Get complexity metrics (cyclomatic, max nesting, param count) for symbols in a file or across the project. Use to identify complex code before refactoring. For historical trends use get_complexity_trend instead. Read-only. Returns JSON: { symbols: [{ symbol_id, name, kind, file, line, cyclomatic, max_nesting, param_count }], total }.",
     {
       file_path: z6.string().max(512).optional().describe("File path to report on (omit for project-wide top complex symbols)"),
       min_cyclomatic: z6.number().int().min(1).optional().describe("Min cyclomatic complexity to include (default: 1 for file, 5 for project)"),
@@ -63835,7 +63930,7 @@ function registerGitTools(server, ctx) {
   );
   server.tool(
     "check_rename",
-    "Pre-rename collision detection: checks the symbol's own file and all importing files for existing symbols with the target name",
+    "Pre-rename collision detection: checks the symbol's own file and all importing files for existing symbols with the target name. Use before apply_rename to verify safety. Read-only (does not modify files). Returns JSON: { safe, conflicts: [{ symbol_id, name, file }] }.",
     {
       symbol_id: z6.string().max(512).describe("Symbol ID to rename"),
       target_name: z6.string().min(1).max(256).describe("Proposed new name")
@@ -65701,7 +65796,7 @@ function registerRefactoringTools(server, ctx) {
   const { store, projectRoot, guardPath, j: j3 } = ctx;
   server.tool(
     "apply_rename",
-    "Rename a symbol across all usages (definition + all importing files). Runs collision detection first and aborts on conflicts. Returns the list of edits applied.",
+    'Rename a symbol across all usages (definition + all importing files). Runs collision detection first and aborts on conflicts. Returns the list of edits applied. Modifies source files. Use check_rename first to verify safety; use plan_refactoring with type="rename" to preview edits. Returns JSON: { success, edits: [{ file, old_text, new_text }], filesModified }.',
     {
       symbol_id: z7.string().max(512).describe("Symbol ID to rename (from search or outline)"),
       new_name: z7.string().min(1).max(256).describe("New name for the symbol"),
@@ -65717,7 +65812,7 @@ function registerRefactoringTools(server, ctx) {
   );
   server.tool(
     "remove_dead_code",
-    "Safely remove a dead symbol from its file. Verifies the symbol is actually dead (multi-signal detection or zero incoming edges) before removal. Warns about orphaned imports in other files.",
+    "Safely remove a dead symbol from its file. Verifies the symbol is actually dead (multi-signal detection or zero incoming edges) before removal. Warns about orphaned imports in other files. Destructive \u2014 deletes code from source files. Use get_dead_code first to identify candidates. Returns JSON: { success, removed: { symbol_id, file }, orphanedImports }.",
     {
       symbol_id: z7.string().max(512).describe("Symbol ID to remove (from get_dead_code results)"),
       dry_run: z7.boolean().default(false).describe("Preview changes without applying (default: false)")
@@ -65732,7 +65827,7 @@ function registerRefactoringTools(server, ctx) {
   );
   server.tool(
     "extract_function",
-    "Extract a range of lines into a new named function. Detects parameters (variables from outer scope) and return values (variables used after the range). Supports TypeScript/JavaScript, Python, and Go.",
+    'Extract a range of lines into a new named function. Detects parameters (variables from outer scope) and return values (variables used after the range). Supports TypeScript/JavaScript, Python, and Go. Modifies source files. Use plan_refactoring with type="extract" to preview first. Returns JSON: { success, edits: [{ file, old_text, new_text }], extractedFunction }.',
     {
       file_path: z7.string().max(512).describe("File path (relative to project root)"),
       start_line: z7.number().int().min(1).describe("First line to extract (1-indexed, inclusive)"),
@@ -65752,7 +65847,7 @@ function registerRefactoringTools(server, ctx) {
   );
   server.tool(
     "apply_codemod",
-    "Bulk regex find-and-replace across files. Dry-run by default \u2014 first call shows preview, second call with dry_run=false applies. Use for mechanical changes like adding async/await, renaming patterns, updating imports across many files.",
+    "Bulk regex find-and-replace across files. Dry-run by default \u2014 first call shows preview, second call with dry_run=false applies. Use for mechanical changes like adding async/await, renaming patterns, updating imports across many files. Potentially destructive \u2014 can modify or delete code. Always preview with dry_run=true first. Returns JSON: { success, matchedFiles, changes: [{ file, matches }], applied }.",
     {
       pattern: z7.string().min(1).max(1e3).describe("Regex pattern to match (JavaScript regex syntax)"),
       replacement: z7.string().max(1e3).describe("Replacement string ($1, $2 for capture groups)"),
@@ -65777,7 +65872,7 @@ function registerRefactoringTools(server, ctx) {
   );
   server.tool(
     "apply_move",
-    "Move a symbol to a different file or rename/move a file, updating all import paths across the codebase. Dry-run by default (safe preview).",
+    'Move a symbol to a different file or rename/move a file, updating all import paths across the codebase. Dry-run by default (safe preview). Modifies source files. Use plan_refactoring with type="move" to preview first. Returns JSON: { success, edits: [{ file, old_text, new_text }], filesModified }.',
     {
       symbol_id: z7.string().max(512).optional().describe("Symbol ID to move (mode: symbol)"),
       target_file: z7.string().max(512).optional().describe("Target file path for the symbol (mode: symbol)"),
@@ -65841,7 +65936,7 @@ function registerRefactoringTools(server, ctx) {
   });
   server.tool(
     "change_signature",
-    "Change a function/method signature (add/remove/rename/reorder parameters) and update all call sites. Dry-run by default (safe preview).",
+    'Change a function/method signature (add/remove/rename/reorder parameters) and update all call sites. Dry-run by default (safe preview). Modifies source files. Use plan_refactoring with type="signature" to preview first. Returns JSON: { success, edits: [{ file, old_text, new_text }], callSitesUpdated }.',
     {
       symbol_id: z7.string().max(512).describe("Symbol ID of the function/method to modify"),
       changes: z7.array(signatureChangeSchema).min(1).max(20).describe("Array of changes to apply"),
@@ -65871,7 +65966,7 @@ function registerRefactoringTools(server, ctx) {
   });
   server.tool(
     "plan_refactoring",
-    "Preview any refactoring (rename, move, extract, signature) without applying. Returns all edits as {old_text, new_text} pairs. Use to review changes before applying the real tool.",
+    "Preview any refactoring (rename, move, extract, signature) without applying. Returns all edits as {old_text, new_text} pairs. Read-only (does not modify files). Use to review the blast radius before calling apply_rename, apply_move, change_signature, or extract_function. Returns JSON: { success, type, edits: [{ file, old_text, new_text }], filesAffected }.",
     {
       type: z7.enum(["rename", "move", "extract", "signature"]).describe("Type of refactoring to preview"),
       symbol_id: z7.string().max(512).optional().describe("Symbol ID (for rename, move symbol, signature)"),
@@ -66391,9 +66486,9 @@ var OtlpReceiver = class {
     if (this.options.port === 0) return;
     return new Promise((resolve3, reject) => {
       this.server = createServer((req, res) => this.handleRequest(req, res));
-      this.server.on("error", (err13) => {
-        logger.error({ error: err13 }, "OTLP receiver error");
-        reject(err13);
+      this.server.on("error", (err14) => {
+        logger.error({ error: err14 }, "OTLP receiver error");
+        reject(err14);
       });
       this.server.listen(this.options.port, this.options.host, () => {
         logger.info(
@@ -68006,16 +68101,16 @@ function findShortestPath(store, startNodeId, endNodeId, maxDepth) {
         parent.set(nodeId, { from, edgeType: edge.edge_type_name });
         nextFrontier.push(nodeId);
         if (nodeId === endNodeId) {
-          const path65 = [endNodeId];
+          const path66 = [endNodeId];
           const edgeTypes = [];
           let cur = endNodeId;
           while (cur !== startNodeId) {
             const p = parent.get(cur);
-            path65.unshift(p.from);
+            path66.unshift(p.from);
             edgeTypes.unshift(p.edgeType);
             cur = p.from;
           }
-          return { path: path65, edgeTypes };
+          return { path: path66, edgeTypes };
         }
       }
     }
@@ -68404,14 +68499,14 @@ var FileRepository = class {
   }
   db;
   _stmts;
-  insertFile(path65, language, contentHash, byteLength, workspace, mtimeMs, createNode) {
-    const result = this._stmts.insertFile.run(path65, language, contentHash, byteLength, workspace, mtimeMs);
+  insertFile(path66, language, contentHash, byteLength, workspace, mtimeMs, createNode) {
+    const result = this._stmts.insertFile.run(path66, language, contentHash, byteLength, workspace, mtimeMs);
     const fileId = Number(result.lastInsertRowid);
     createNode("file", fileId);
     return fileId;
   }
-  getFile(path65) {
-    return this._stmts.getFile.get(path65);
+  getFile(path66) {
+    return this._stmts.getFile.get(path66);
   }
   getFileById(id) {
     return this._stmts.getFileById.get(id);
@@ -69269,9 +69364,9 @@ var Store = class {
   domain;
   analytics;
   // --- Files (delegates to FileRepository) ---
-  insertFile(path65, language, contentHash, byteLength, workspace, mtimeMs) {
+  insertFile(path66, language, contentHash, byteLength, workspace, mtimeMs) {
     return this.files.insertFile(
-      path65,
+      path66,
       language,
       contentHash,
       byteLength,
@@ -69280,8 +69375,8 @@ var Store = class {
       (nodeType, refId) => this.graph.createNode(nodeType, refId)
     );
   }
-  getFile(path65) {
-    return this.files.getFile(path65);
+  getFile(path66) {
+    return this.files.getFile(path66);
   }
   getFileById(id) {
     return this.files.getFileById(id);
@@ -70292,6 +70387,7 @@ const preTicks = Math.min(300, Math.max(50, Math.ceil(Math.log(N + 1) * 40)));
 let ticksDone = 0;
 const TICK_BATCH = N > 5000 ? 5 : 15;
 let layoutDone = false;
+let frameRequested = false;
 (function tickBatch() {
   const t0 = performance.now();
   while (ticksDone < preTicks && performance.now() - t0 < 12) { sim.tick(); ticksDone++; }
@@ -70433,7 +70529,6 @@ let highlightSet = null;
 let hoveredNode = null;
 let searchQ = '';
 let animating = false;
-let frameRequested = false;
 
 function scheduleFrame() {
   if (!frameRequested) { frameRequested = true; requestAnimationFrame(frame); }
@@ -72116,7 +72211,7 @@ function registerAdvancedTools(server, ctx) {
     const additionalRepos = config.topology.repos ?? [];
     server.tool(
       "get_service_map",
-      "Get map of all services, their APIs, and inter-service dependencies. Auto-detects services from Docker Compose or treats each repo as a service.",
+      "Get map of all services, their APIs, and inter-service dependencies. Auto-detects services from Docker Compose or treats each repo as a service. Use to understand microservice topology. For subproject-level graph use get_subproject_graph instead. Read-only. Returns JSON: { services: [{ name, endpoints, dependencies }], total }.",
       {
         include_endpoints: z8.boolean().optional().describe("Include full endpoint list per service (default false)")
       },
@@ -72128,7 +72223,7 @@ function registerAdvancedTools(server, ctx) {
     );
     server.tool(
       "get_cross_service_impact",
-      "Analyze cross-service impact of changing an endpoint or event. Shows which services would be affected.",
+      "Analyze cross-service impact of changing an endpoint or event. Shows which services would be affected. Use before modifying a shared endpoint. For within-codebase impact use get_change_impact instead. Read-only. Returns JSON: { service, affectedServices: [{ name, reason }], total }.",
       {
         service: z8.string().min(1).max(256).describe("Service name"),
         endpoint: z8.string().max(512).optional().describe("Endpoint path (e.g. /api/users/{id})"),
@@ -72142,7 +72237,7 @@ function registerAdvancedTools(server, ctx) {
     );
     server.tool(
       "get_api_contract",
-      "Get API contract (OpenAPI/gRPC/GraphQL) for a service. Parses spec files found in the service repo.",
+      "Get API contract (OpenAPI/gRPC/GraphQL) for a service. Parses spec files found in the service repo. Use to inspect a service's public API. For detecting spec-vs-code mismatches use get_contract_drift instead. Read-only. Returns JSON: { service, contract_type, endpoints, schemas }.",
       {
         service: z8.string().min(1).max(256).describe("Service name"),
         contract_type: z8.enum(["openapi", "grpc", "graphql"]).optional().describe("Filter by contract type")
@@ -72155,7 +72250,7 @@ function registerAdvancedTools(server, ctx) {
     );
     server.tool(
       "get_service_deps",
-      "Get external service dependencies: which services this one calls (outgoing) and which call it (incoming).",
+      "Get external service dependencies: which services this one calls (outgoing) and which call it (incoming). Use to understand a single service's dependency profile. For full topology use get_service_map instead. Read-only. Returns JSON: { service, outgoing, incoming }.",
       {
         service: z8.string().min(1).max(256).describe("Service name"),
         direction: z8.enum(["outgoing", "incoming", "both"]).optional().describe("Dependency direction (default both)")
@@ -72168,7 +72263,7 @@ function registerAdvancedTools(server, ctx) {
     );
     server.tool(
       "get_contract_drift",
-      "Detect mismatches between API spec and implementation: endpoints in spec but not in code, or in code but not in spec.",
+      "Detect mismatches between API spec and implementation: endpoints in spec but not in code, or in code but not in spec. Use to verify API contract accuracy. For reading the contract itself use get_api_contract instead. Read-only. Returns JSON: { service, missingInCode, missingInSpec, total }.",
       {
         service: z8.string().min(1).max(256).describe("Service name")
       },
@@ -72180,7 +72275,7 @@ function registerAdvancedTools(server, ctx) {
     );
     server.tool(
       "get_subproject_graph",
-      "Show all subprojects and their cross-repo connections. A subproject is any working repository in your project ecosystem (microservices, frontends, backends, shared libraries, CLI tools, etc.). Displays repos, endpoints, client calls, and inter-repo dependency edges.",
+      "Show all subprojects and their cross-repo connections. A subproject is any working repository in your project ecosystem (microservices, frontends, backends, shared libraries, CLI tools, etc.). Displays repos, endpoints, client calls, and inter-repo dependency edges. Use to understand multi-repo topology. Register repos first with subproject_add_repo. Read-only. Returns JSON: { repos, endpoints, clientCalls, edges }.",
       {},
       async () => {
         const result = getSubprojectGraph(topoStore);
@@ -72190,7 +72285,7 @@ function registerAdvancedTools(server, ctx) {
     );
     server.tool(
       "get_subproject_impact",
-      "Cross-repo impact analysis: find all client code across subprojects that would break if an endpoint changes. Resolves down to symbol level when per-repo indexes exist.",
+      "Cross-repo impact analysis: find all client code across subprojects that would break if an endpoint changes. Resolves down to symbol level when per-repo indexes exist. Use before modifying a shared API endpoint. Read-only. Returns JSON: { endpoint, affectedClients: [{ repo, file, line, callType }], total }.",
       {
         endpoint: z8.string().max(512).optional().describe("Endpoint path pattern (e.g. /api/users)"),
         method: z8.string().max(10).optional().describe("HTTP method filter (e.g. GET, POST)"),
@@ -72204,7 +72299,7 @@ function registerAdvancedTools(server, ctx) {
     );
     server.tool(
       "subproject_add_repo",
-      "Add a repository as a subproject of the current project. A subproject is any working repository in your ecosystem: microservices, frontends, backends, shared libraries, CLI tools. Discovers services, parses API contracts (OpenAPI/gRPC/GraphQL), scans for HTTP client calls, and links them to known endpoints.",
+      "Add a repository as a subproject of the current project. A subproject is any working repository in your ecosystem: microservices, frontends, backends, shared libraries, CLI tools. Discovers services, parses API contracts (OpenAPI/gRPC/GraphQL), scans for HTTP client calls, and links them to known endpoints. Mutates the topology store; idempotent. Use to build multi-repo intelligence. Returns JSON: { added, services, contracts, clientCalls }.",
       {
         repo_path: z8.string().min(1).max(1024).describe("Absolute or relative path to the repository/service"),
         name: z8.string().max(256).optional().describe("Display name for the repo (default: directory basename)"),
@@ -72220,7 +72315,7 @@ function registerAdvancedTools(server, ctx) {
     );
     server.tool(
       "subproject_sync",
-      "Re-scan all subprojects: re-discover services, re-parse contracts, re-scan client calls, and re-link everything.",
+      "Re-scan all subprojects: re-discover services, re-parse contracts, re-scan client calls, and re-link everything. Mutates the topology store; idempotent. Use after code changes in subproject repos. Returns JSON: { synced, services, contracts, clientCalls }.",
       {},
       async () => {
         const result = subprojectSync(topoStore);
@@ -72230,7 +72325,7 @@ function registerAdvancedTools(server, ctx) {
     );
     server.tool(
       "get_subproject_clients",
-      "Find all client calls across subprojects that call a specific endpoint. Shows file, line, call type, and confidence.",
+      "Find all client calls across subprojects that call a specific endpoint. Shows file, line, call type, and confidence. Use to find all consumers of an endpoint before modifying it. Read-only. Returns JSON: { endpoint, clients: [{ repo, file, line, callType, confidence }], total }.",
       {
         endpoint: z8.string().min(1).max(512).describe("Endpoint path to search for (e.g. /api/users)"),
         method: z8.string().max(10).optional().describe("HTTP method filter")
@@ -72243,7 +72338,7 @@ function registerAdvancedTools(server, ctx) {
     );
     server.tool(
       "get_contract_versions",
-      "Show version history for a service API contract with breaking change detection between versions. Compares request/response schemas across snapshots to flag removed fields, type changes, and renames.",
+      "Show version history for a service API contract with breaking change detection between versions. Compares request/response schemas across snapshots to flag removed fields, type changes, and renames. Use to review API evolution. For current spec-vs-code drift use get_contract_drift instead. Read-only. Returns JSON: { service, versions: [{ version, date, breakingChanges }] }.",
       {
         service: z8.string().min(1).max(256).describe("Service name"),
         limit: z8.number().int().min(1).max(50).optional().describe("Max versions to show (default 10)")
@@ -72256,7 +72351,7 @@ function registerAdvancedTools(server, ctx) {
     );
     server.tool(
       "discover_claude_sessions",
-      "Scan ~/.claude/projects for projects Claude Code has touched on this machine, decode each directory name back to its absolute path, and report which ones still exist plus session-file count and last activity. With add_as_subprojects=true, every existing project is registered as a subproject in one call \u2014 useful for spinning up multi-repo intelligence after a fresh clone.",
+      "Scan ~/.claude/projects for projects Claude Code has touched on this machine, decode each directory name back to its absolute path, and report which ones still exist plus session-file count and last activity. With add_as_subprojects=true, every existing project is registered as a subproject in one call \u2014 useful for spinning up multi-repo intelligence after a fresh clone. Reads local filesystem; with add_as_subprojects=true also mutates topology store. Returns JSON: { projects: [{ path, sessions, lastActivity }], total }.",
       {
         scan_root: z8.string().max(1024).optional().describe("Override the scan root (default: ~/.claude/projects)"),
         exclude_current: z8.boolean().optional().describe("Exclude the current project from results (default: true)"),
@@ -72278,7 +72373,7 @@ function registerAdvancedTools(server, ctx) {
     );
     server.tool(
       "visualize_subproject_topology",
-      "Open interactive HTML visualization of the subproject topology: services as nodes, API calls as edges, health/risk indicators per service. Node size = endpoint count, color = health (green/yellow/red).",
+      "Open interactive HTML visualization of the subproject topology: services as nodes, API calls as edges, health/risk indicators per service. Node size = endpoint count, color = health (green/yellow/red). Writes an HTML file to disk. Use for visual architecture review. Returns JSON: { outputPath, services, edges }.",
       {
         output: z8.string().max(512).optional().describe("Output file path (default: /tmp/trace-mcp-subproject-topology.html)"),
         layout: z8.enum(["force", "hierarchical", "radial"]).optional().describe("Graph layout (default force)")
@@ -72300,7 +72395,7 @@ function registerAdvancedTools(server, ctx) {
     runtimeIntelligence.start().catch((e) => logger.error({ error: e }, "Failed to start Runtime Intelligence"));
     server.tool(
       "get_runtime_profile",
-      "Runtime profile for a symbol or route: call count, latency percentiles (p50/p95/p99), error rate, calls per hour. Requires OTLP trace ingestion.",
+      "Runtime profile for a symbol or route: call count, latency percentiles (p50/p95/p99), error rate, calls per hour. Requires OTLP trace ingestion. Read-only, queries external runtime data. Use for performance analysis of specific endpoints. Returns JSON: { symbol_id, callCount, latency: { p50, p95, p99 }, errorRate, callsPerHour }.",
       {
         symbol_id: z8.string().max(512).optional().describe("Symbol ID to profile"),
         fqn: z8.string().max(512).optional().describe("Fully qualified name"),
@@ -72315,7 +72410,7 @@ function registerAdvancedTools(server, ctx) {
     );
     server.tool(
       "get_runtime_call_graph",
-      "Actual call graph from runtime traces (vs static analysis). Shows observed call paths with call counts and latency.",
+      "Actual call graph from runtime traces (vs static analysis). Shows observed call paths with call counts and latency. Requires OTLP trace ingestion. Read-only, queries external runtime data. For static call graph use get_call_graph instead. Returns JSON: { root, calls: [{ symbol, count, latency }] }.",
       {
         symbol_id: z8.string().max(512).optional().describe("Symbol ID as root"),
         fqn: z8.string().max(512).optional().describe("Fully qualified name as root"),
@@ -72330,7 +72425,7 @@ function registerAdvancedTools(server, ctx) {
     );
     server.tool(
       "get_endpoint_analytics",
-      "Per-route analytics: request count, error rate, latency, caller services. Requires OTLP trace ingestion.",
+      "Per-route analytics: request count, error rate, latency, caller services. Requires OTLP trace ingestion. Read-only, queries external runtime data. Use to understand endpoint performance and traffic. Returns JSON: { uri, method, requestCount, errorRate, latency, callerServices }.",
       {
         uri: z8.string().max(512).describe('Route URI (e.g. "/api/users/{id}")'),
         method: z8.string().max(10).optional().describe("HTTP method filter"),
@@ -72344,7 +72439,7 @@ function registerAdvancedTools(server, ctx) {
     );
     server.tool(
       "get_runtime_deps",
-      "Which external services (databases, caches, APIs, queues) does this code actually call at runtime. Based on OTLP traces.",
+      "Which external services (databases, caches, APIs, queues) does this code actually call at runtime. Based on OTLP traces. Read-only, queries external runtime data. Use to discover actual runtime dependencies vs static analysis. Returns JSON: { dependencies: [{ type, name, callCount }] }.",
       {
         symbol_id: z8.string().max(512).optional().describe("Symbol ID"),
         fqn: z8.string().max(512).optional().describe("Fully qualified name"),
@@ -72363,7 +72458,7 @@ function registerAdvancedTools(server, ctx) {
   }
   server.tool(
     "query_by_intent",
-    "Map a business question to domain taxonomy \u2192 returns domain ownership and relevance scores (no source code). Use when you need to know WHICH DOMAIN owns specific functionality.",
+    "Map a business question to domain taxonomy \u2192 returns domain ownership and relevance scores (no source code). Use when you need to know WHICH DOMAIN owns specific functionality. For actual source code use get_feature_context instead. Read-only. Returns JSON: { symbols: [{ symbol_id, domain, relevance }] }.",
     {
       query: z8.string().min(1).max(500).describe("Business-level question about the codebase"),
       limit: z8.number().int().min(1).max(50).optional().describe("Max symbols to return (default 15)")
@@ -72381,7 +72476,7 @@ function registerAdvancedTools(server, ctx) {
   );
   server.tool(
     "get_domain_map",
-    "Get hierarchical map of business domains with key symbols per domain. Auto-builds domain taxonomy on first call using heuristic classification.",
+    "Get hierarchical map of business domains with key symbols per domain. Auto-builds domain taxonomy on first call using heuristic classification. Use to understand business domain boundaries. For specific domain code use get_domain_context instead. Read-only. Returns JSON: { domains: [{ name, children, symbols }] }.",
     {
       depth: z8.number().int().min(1).max(5).optional().describe("Max taxonomy depth (default 3)"),
       include_symbols: z8.boolean().optional().describe("Include top symbols per domain (default true)"),
@@ -72395,7 +72490,7 @@ function registerAdvancedTools(server, ctx) {
   );
   server.tool(
     "get_domain_context",
-    'Get all code related to a specific business domain. Supports "parent/child" notation (e.g. "payments/refunds").',
+    'Get all code related to a specific business domain. Supports "parent/child" notation (e.g. "payments/refunds"). Use to explore code within a domain boundary. For the full domain taxonomy use get_domain_map instead. Read-only. Returns JSON: { domain, symbols: [{ symbol_id, name, file, source }], relatedDomains }.',
     {
       domain: z8.string().min(1).max(256).describe('Domain name (e.g. "payments" or "payments/refunds")'),
       include_related: z8.boolean().optional().describe("Include symbols from related domains (default false)"),
@@ -72409,7 +72504,7 @@ function registerAdvancedTools(server, ctx) {
   );
   server.tool(
     "get_cross_domain_deps",
-    "Show which business domains depend on which. Based on edges between symbols in different domains.",
+    "Show which business domains depend on which. Based on edges between symbols in different domains. Use to understand domain coupling. Read-only. Returns JSON: { dependencies: [{ from, to, edgeCount }] }.",
     {
       domain: z8.string().max(256).optional().describe("Focus on a specific domain (default: all)")
     },
@@ -72421,7 +72516,7 @@ function registerAdvancedTools(server, ctx) {
   );
   server.tool(
     "graph_query",
-    'Trace how named symbols relate in the dependency graph \u2192 returns subgraph + Mermaid diagram. Input must contain symbol/class names (e.g. "How does AuthService reach Database?", "What depends on UserModel?").',
+    'Trace how named symbols relate in the dependency graph \u2192 returns subgraph + Mermaid diagram. Input must contain symbol/class names (e.g. "How does AuthService reach Database?", "What depends on UserModel?"). Use for ad-hoc graph exploration. For structured call graph use get_call_graph instead. Read-only. Returns JSON: { nodes, edges, mermaid }.',
     {
       query: z8.string().min(1).max(500).describe("Natural language question about code relationships"),
       depth: z8.number().int().min(1).max(6).optional().describe("Max traversal depth (default 3)"),
@@ -72435,7 +72530,7 @@ function registerAdvancedTools(server, ctx) {
   );
   server.tool(
     "get_dataflow",
-    "Intra-function dataflow analysis: track how each parameter flows through the function body \u2014 into which calls, where it gets mutated, and what is returned. Phase 1: single function scope.",
+    "Intra-function dataflow analysis: track how each parameter flows through the function body \u2014 into which calls, where it gets mutated, and what is returned. Phase 1: single function scope. Use to understand data transformations within a function. For security-focused data flow use taint_analysis instead. Read-only. Returns JSON: { symbol_id, params: [{ name, flows: [{ target, mutated }] }], returnPaths }.",
     {
       symbol_id: z8.string().max(512).optional().describe("Symbol ID of the function/method to analyze"),
       fqn: z8.string().max(512).optional().describe("Fully qualified name of the function/method"),
@@ -72450,7 +72545,7 @@ function registerAdvancedTools(server, ctx) {
   );
   server.tool(
     "visualize_graph",
-    "Open interactive HTML graph in browser showing file/symbol dependencies. Supports force/hierarchical/radial layouts, community coloring. Use granularity=symbol to see individual functions/classes/methods as nodes instead of files.",
+    "Open interactive HTML graph in browser showing file/symbol dependencies. Supports force/hierarchical/radial layouts, community coloring. Use granularity=symbol to see individual functions/classes/methods as nodes instead of files. Writes an HTML file to disk. For static Mermaid/DOT output use get_dependency_diagram instead. Returns JSON: { outputPath, nodes, edges }.",
     {
       scope: z8.string().min(1).max(512).describe('Scope: file path, directory (e.g. "src/"), or "project"'),
       depth: z8.number().int().min(1).max(5).optional().describe("Max hops from scope (default 2)"),
@@ -72486,7 +72581,7 @@ function registerAdvancedTools(server, ctx) {
   );
   server.tool(
     "get_dependency_diagram",
-    'Render dependency diagram for a file/directory path as Mermaid or DOT. Input: a path like "src/tools/" \u2014 not a question. Trims to max_nodes most important nodes.',
+    'Render dependency diagram for a file/directory path as Mermaid or DOT. Input: a path like "src/tools/" \u2014 not a question. Trims to max_nodes most important nodes. Read-only. For interactive HTML visualization use visualize_graph instead. Returns JSON: { format, diagram, nodes, edges }.',
     {
       scope: z8.string().min(1).max(512).describe('Scope: file path, directory, or "project"'),
       depth: z8.number().int().min(1).max(5).optional().describe("Max hops from scope (default 2)"),
@@ -72501,7 +72596,7 @@ function registerAdvancedTools(server, ctx) {
   );
   server.tool(
     "search_text",
-    "Full-text search across all indexed files. Supports regex, glob file patterns, language filter. Use for finding strings, comments, TODOs, config values, error messages \u2014 anything not captured as a symbol.",
+    "Full-text search across all indexed files. Supports regex, glob file patterns, language filter. Use for finding strings, comments, TODOs, config values, error messages \u2014 anything not captured as a symbol. For symbol search (functions, classes) use search instead. Read-only. Returns JSON: { matches: [{ file, line, text, context }], total_matches }.",
     {
       query: z8.string().min(1).max(1e3).describe("Search string or regex pattern"),
       is_regex: z8.boolean().optional().describe("Treat query as regex (default false)"),
@@ -72532,7 +72627,7 @@ function registerAdvancedTools(server, ctx) {
   );
   server.tool(
     "predict_bugs",
-    "Predict which files are most likely to contain bugs. Multi-signal scoring: git churn, fix-commit ratio, complexity, coupling, PageRank importance, author count. Each prediction includes a numeric score, risk bucket (low/medium/high/critical) AND a confidence_level (low/medium/high/multi_signal) counting how many independent signals actually fired. Result envelope includes _methodology disclosure. Cached for 1 hour; use refresh=true to recompute.",
+    "Predict which files are most likely to contain bugs. Multi-signal scoring: git churn, fix-commit ratio, complexity, coupling, PageRank importance, author count. Each prediction includes a numeric score, risk bucket (low/medium/high/critical) AND a confidence_level (low/medium/high/multi_signal) counting how many independent signals actually fired. Result envelope includes _methodology disclosure. Cached for 1 hour; use refresh=true to recompute. Requires git. Use for proactive bug hunting. For complexity+churn hotspots only use get_risk_hotspots instead. Read-only. Returns JSON: { predictions: [{ file, score, risk, confidence_level, signals }], total }.",
     {
       limit: z8.number().int().min(1).max(200).optional().describe("Max results (default: 50)"),
       min_score: z8.number().min(0).max(1).optional().describe("Min bug probability score to include (default: 0)"),
@@ -72555,7 +72650,7 @@ function registerAdvancedTools(server, ctx) {
   );
   server.tool(
     "detect_drift",
-    "Detect architectural drift: cross-module co-change anomalies (files in different modules that always change together) and shotgun surgery patterns (commits touching 3+ modules). Requires git.",
+    "Detect architectural drift: cross-module co-change anomalies (files in different modules that always change together) and shotgun surgery patterns (commits touching 3+ modules). Requires git. Use to identify hidden coupling across modules. For file-pair co-changes use get_co_changes instead. Read-only. Returns JSON: { anomalies, shotgunSurgery, total }.",
     {
       since_days: z8.number().int().min(1).optional().describe("Analyze commits from last N days (default: 180)"),
       min_confidence: z8.number().min(0).max(1).optional().describe("Min Jaccard confidence for co-change anomalies (default: 0.3)")
@@ -72572,7 +72667,7 @@ function registerAdvancedTools(server, ctx) {
   );
   server.tool(
     "get_tech_debt",
-    "Per-module tech debt score (A\u2013F grade) combining: complexity, coupling instability, test coverage gaps, and git churn. Includes actionable recommendations.",
+    "Per-module tech debt score (A\u2013F grade) combining: complexity, coupling instability, test coverage gaps, and git churn. Includes actionable recommendations. Use for architecture review and prioritizing cleanup. Read-only. Returns JSON: { modules: [{ module, grade, score, factors, recommendations }] }.",
     {
       module: z8.string().max(256).optional().describe('Focus on a specific module path (e.g. "src/tools")'),
       refresh: z8.boolean().optional().describe("Force recomputation (default: false)")
@@ -72591,7 +72686,7 @@ function registerAdvancedTools(server, ctx) {
   );
   server.tool(
     "assess_change_risk",
-    "Before modifying a file or symbol, predict risk level (low/medium/high/critical) with contributing factors and recommended mitigations. Combines blast radius, complexity, git churn, test coverage, and coupling.",
+    "Before modifying a file or symbol, predict risk level (low/medium/high/critical) with contributing factors and recommended mitigations. Combines blast radius, complexity, git churn, test coverage, and coupling. Use as a quick risk check. For full impact report with affected tests and dependents use get_change_impact instead. Read-only. Returns JSON: { risk, level, factors: [{ name, value }], mitigations }.",
     {
       file_path: z8.string().max(512).optional().describe("File path to assess"),
       symbol_id: z8.string().max(512).optional().describe("Symbol ID to assess")
@@ -72613,7 +72708,7 @@ function registerAdvancedTools(server, ctx) {
   );
   server.tool(
     "get_health_trends",
-    "Time-series health metrics for a file or module: bug score, complexity, coupling, churn over time. Populated by predict_bugs runs.",
+    "Time-series health metrics for a file or module: bug score, complexity, coupling, churn over time. Populated by predict_bugs runs. Use to track if a module is improving or degrading. Read-only. Returns JSON: { dataPoints: [{ date, bugScore, complexity, coupling, churn }] }.",
     {
       file_path: z8.string().max(512).optional().describe("File path to check"),
       module: z8.string().max(256).optional().describe("Module path prefix to check"),
@@ -72631,7 +72726,7 @@ function registerAdvancedTools(server, ctx) {
   );
   server.tool(
     "get_workspace_map",
-    "List all detected monorepo workspaces with file counts, symbol counts, and languages. Returns dependency graph between workspaces showing cross-workspace imports.",
+    "List all detected monorepo workspaces with file counts, symbol counts, and languages. Returns dependency graph between workspaces showing cross-workspace imports. Use for monorepo structure overview. For impact of changes on other workspaces use get_cross_workspace_impact instead. Read-only. Returns JSON: { workspaces: [{ name, files, symbols, languages }], dependencies }.",
     {
       include_dependencies: z8.boolean().optional().describe("Include cross-workspace dependency graph (default: true)")
     },
@@ -72662,7 +72757,7 @@ function registerAdvancedTools(server, ctx) {
   );
   server.tool(
     "get_cross_workspace_impact",
-    "Show which workspaces are affected by changes in a given workspace. Lists all cross-workspace edges, affected symbols, and the public API surface consumed by other workspaces.",
+    "Show which workspaces are affected by changes in a given workspace. Lists all cross-workspace edges, affected symbols, and the public API surface consumed by other workspaces. Use before modifying shared code in a monorepo. Read-only. Returns JSON: { workspace, public_api, consumed_by, depends_on, cross_workspace_edges }.",
     {
       workspace: z8.string().max(256).describe("Workspace name to analyze")
     },
@@ -74493,28 +74588,331 @@ function evaluateQualityGates(store, projectRoot, gatesConfig, options = {}) {
   };
 }
 
+// src/tools/quality/security-context-export.ts
+import { readFileSync as readFileSync7 } from "fs";
+import path57 from "path";
+import { ok as ok10 } from "neverthrow";
+var CATEGORY_PATTERNS = [
+  // file_read
+  { pattern: /^(?:readFile|readFileSync|readdir|readdirSync|createReadStream|promises\.readFile)$/, category: "file_read" },
+  { pattern: /^(?:fs\.read|fs\.promises\.read|fsPromises\.read)/, category: "file_read" },
+  // file_write
+  { pattern: /^(?:writeFile|writeFileSync|appendFile|appendFileSync|createWriteStream|promises\.writeFile)$/, category: "file_write" },
+  { pattern: /^(?:unlink|unlinkSync|rm|rmSync|rmdir|rmdirSync|rename|renameSync|copyFile|copyFileSync)$/, category: "file_write" },
+  { pattern: /^(?:fs\.write|fs\.promises\.write|fs\.unlink|fs\.rm|fsPromises\.write)/, category: "file_write" },
+  { pattern: /^(?:mkdir|mkdirSync|promises\.mkdir)$/, category: "file_write" },
+  // network_outbound
+  { pattern: /^(?:fetch|request|got|axios)$/, category: "network_outbound" },
+  { pattern: /^(?:http\.request|https\.request|http\.get|https\.get)$/, category: "network_outbound" },
+  { pattern: /^(?:net\.connect|net\.createConnection|tls\.connect)$/, category: "network_outbound" },
+  { pattern: /^(?:XMLHttpRequest|WebSocket)$/, category: "network_outbound" },
+  // env_read
+  { pattern: /^(?:process\.env|env\.)/, category: "env_read" },
+  { pattern: /^(?:getenv|os\.environ|dotenv)/, category: "env_read" },
+  // shell_exec
+  { pattern: /^(?:exec|execSync|execFile|execFileSync|spawn|spawnSync|fork)$/, category: "shell_exec" },
+  { pattern: /^(?:child_process\.|cp\.)/, category: "shell_exec" },
+  // crypto
+  { pattern: /^(?:createHash|createCipher|createCipheriv|createDecipher|createDecipheriv|createSign|createVerify|createHmac)$/, category: "crypto" },
+  { pattern: /^(?:crypto\.)/, category: "crypto" },
+  // serialization
+  { pattern: /^(?:eval|Function)$/, category: "serialization" },
+  { pattern: /^(?:deserialize|unserialize|pickle\.loads|yaml\.load)$/, category: "serialization" }
+];
+function classifyFunction(name) {
+  for (const { pattern, category } of CATEGORY_PATTERNS) {
+    if (pattern.test(name)) return category;
+  }
+  return null;
+}
+var ANNOTATION_RE = /\{\s*(?:readOnlyHint|destructiveHint|idempotentHint|openWorldHint)\s*:/;
+function parseAnnotations(source, toolCallIndex) {
+  const searchRegion = source.slice(toolCallIndex, toolCallIndex + 2e3);
+  const annotationMatch = searchRegion.match(
+    /\{\s*(readOnlyHint\s*:\s*(true|false)\s*,?\s*)?(destructiveHint\s*:\s*(true|false)\s*,?\s*)?(idempotentHint\s*:\s*(true|false)\s*,?\s*)?(openWorldHint\s*:\s*(true|false)\s*,?\s*)\}/
+  );
+  if (!annotationMatch) return null;
+  const annotations = {};
+  if (annotationMatch[2]) annotations.readOnlyHint = annotationMatch[2] === "true";
+  if (annotationMatch[4]) annotations.destructiveHint = annotationMatch[4] === "true";
+  if (annotationMatch[6]) annotations.idempotentHint = annotationMatch[6] === "true";
+  if (annotationMatch[8]) annotations.openWorldHint = annotationMatch[8] === "true";
+  return Object.keys(annotations).length > 0 ? annotations : null;
+}
+function parseAnnotationsFlexible(source, toolCallIndex) {
+  const searchRegion = source.slice(toolCallIndex, toolCallIndex + 3e3);
+  if (!ANNOTATION_RE.test(searchRegion)) return null;
+  const annotations = {};
+  const hints = ["readOnlyHint", "destructiveHint", "idempotentHint", "openWorldHint"];
+  for (const hint of hints) {
+    const re = new RegExp(`${hint}\\s*:\\s*(true|false)`);
+    const m = searchRegion.match(re);
+    if (m) annotations[hint] = m[1] === "true";
+  }
+  return Object.keys(annotations).length > 0 ? annotations : null;
+}
+function collectCallsFromGraph(node, visited, results) {
+  if (visited.has(node.symbol_id)) return;
+  visited.add(node.symbol_id);
+  const category = classifyFunction(node.name);
+  if (category && node.file && node.line) {
+    results.push({
+      function: node.name,
+      file: node.file,
+      line: node.line,
+      category
+    });
+  }
+  if (node.calls) {
+    for (const callee of node.calls) {
+      collectCallsFromGraph(callee, visited, results);
+    }
+  }
+}
+var SECURITY_CALL_RE = /\b((?:fs|http|https|net|crypto|child_process|cp)\.\w+|fetch|exec|execSync|spawn|spawnSync|eval|require|writeFile\w*|readFile\w*|unlink\w*|request|axios|got)\s*\(/g;
+var ENV_ACCESS_RE = /process\.env\b/g;
+var GENERIC_CALL_RE = /\b([a-zA-Z_$]\w*)\s*\(/g;
+var SKIP_KEYWORDS = /* @__PURE__ */ new Set([
+  "if",
+  "for",
+  "while",
+  "switch",
+  "catch",
+  "return",
+  "typeof",
+  "new",
+  "async",
+  "await",
+  "function",
+  "const",
+  "let",
+  "var",
+  "class",
+  "import",
+  "export",
+  "throw",
+  "delete",
+  "void",
+  "yield",
+  "as",
+  "from"
+]);
+function findHandlerBounds(source, toolCallIndex) {
+  const region = source.slice(toolCallIndex, toolCallIndex + 1e4);
+  const arrowMatch = region.match(/async\s+(?:\([^)]*\)|[^=]*?)\s*=>\s*\{/);
+  const funcMatch = region.match(/async\s+function\s*\([^)]*\)\s*\{/);
+  const match = arrowMatch ?? funcMatch;
+  if (!match || match.index === void 0) return null;
+  const bodyBraceOffset = match.index + match[0].length - 1;
+  const afterBrace = region.slice(bodyBraceOffset);
+  let depth = 1;
+  let end = -1;
+  for (let i = 1; i < afterBrace.length; i++) {
+    if (afterBrace[i] === "{") depth++;
+    else if (afterBrace[i] === "}") {
+      depth--;
+      if (depth === 0) {
+        end = i + 1;
+        break;
+      }
+    }
+  }
+  if (end === -1) end = Math.min(afterBrace.length, 5e3);
+  const absStart = toolCallIndex + bodyBraceOffset;
+  const absEnd = toolCallIndex + bodyBraceOffset + end;
+  return { start: absStart, end: absEnd };
+}
+function scanInlineHandler(source, toolCallIndex, filePath, store, projectRoot, depth) {
+  const bounds = findHandlerBounds(source, toolCallIndex);
+  if (!bounds) return { calls: [], calledSymbolIds: [] };
+  const handlerBody = source.slice(bounds.start, bounds.end);
+  const results = [];
+  const calledSymbolIds = [];
+  let m;
+  const secRe = new RegExp(SECURITY_CALL_RE.source, "g");
+  while ((m = secRe.exec(handlerBody)) !== null) {
+    const funcName = m[1];
+    const category = classifyFunction(funcName);
+    if (category) {
+      const lineOffset = source.slice(0, bounds.start + m.index).split("\n").length;
+      results.push({ function: funcName, file: filePath, line: lineOffset, category });
+    }
+  }
+  const envRe = new RegExp(ENV_ACCESS_RE.source, "g");
+  while ((m = envRe.exec(handlerBody)) !== null) {
+    const lineOffset = source.slice(0, bounds.start + m.index).split("\n").length;
+    results.push({ function: "process.env", file: filePath, line: lineOffset, category: "env_read" });
+  }
+  const genericRe = new RegExp(GENERIC_CALL_RE.source, "g");
+  const seenFuncs = /* @__PURE__ */ new Set();
+  while ((m = genericRe.exec(handlerBody)) !== null) {
+    const funcName = m[1];
+    if (SKIP_KEYWORDS.has(funcName) || seenFuncs.has(funcName)) continue;
+    seenFuncs.add(funcName);
+    const sym = store.getSymbolByName(funcName, "function") ?? store.getSymbolByName(funcName, "method");
+    if (!sym) continue;
+    calledSymbolIds.push(sym.symbol_id);
+    const cgResult = getCallGraph(store, { symbolId: sym.symbol_id }, depth);
+    if (cgResult.isOk() && cgResult.value.root) {
+      const visited = /* @__PURE__ */ new Set();
+      collectCallsFromGraph(cgResult.value.root, visited, results);
+    }
+    const file = sym.file_id ? store.getFileById(sym.file_id) : null;
+    if (file && sym.line_start && sym.line_end) {
+      const symAbsPath = path57.resolve(projectRoot, file.path);
+      try {
+        const symSource = readFileSync7(symAbsPath, "utf-8");
+        const lines = symSource.split("\n");
+        const symBody = lines.slice(sym.line_start - 1, sym.line_end).join("\n");
+        scanSourceForSecurityCalls(symBody, file.path, sym.line_start, results);
+      } catch {
+      }
+    }
+  }
+  return { calls: results, calledSymbolIds };
+}
+function scanSourceForSecurityCalls(body, filePath, startLine, results) {
+  let m;
+  const secRe = new RegExp(SECURITY_CALL_RE.source, "g");
+  while ((m = secRe.exec(body)) !== null) {
+    const funcName = m[1];
+    const category = classifyFunction(funcName);
+    if (category) {
+      const lineOffset = startLine + body.slice(0, m.index).split("\n").length - 1;
+      results.push({ function: funcName, file: filePath, line: lineOffset, category });
+    }
+  }
+  const envRe = new RegExp(ENV_ACCESS_RE.source, "g");
+  while ((m = envRe.exec(body)) !== null) {
+    const lineOffset = startLine + body.slice(0, m.index).split("\n").length - 1;
+    results.push({ function: "process.env", file: filePath, line: lineOffset, category: "env_read" });
+  }
+}
+var PKG_VERSION = true ? "1.22.0" : "0.0.0-dev";
+function exportSecurityContext(store, projectRoot, opts = {}) {
+  const depth = Math.min(opts.depth ?? 3, 5);
+  const warnings = [];
+  const allRoutes = store.getAllRoutes();
+  const toolRoutes = allRoutes.filter((r) => r.method === "TOOL");
+  if (toolRoutes.length === 0) {
+    warnings.push("No MCP tool registrations found in the index. Ensure the project uses @modelcontextprotocol/sdk and has been indexed.");
+  }
+  const toolRegistrations = [];
+  const capabilityMap = {};
+  for (const route of toolRoutes) {
+    const fileRow = route.file_id ? store.getFileById(route.file_id) : null;
+    if (!fileRow) continue;
+    if (opts.scope && !fileRow.path.startsWith(opts.scope)) continue;
+    const absPath = path57.resolve(projectRoot, fileRow.path);
+    let source;
+    try {
+      source = readFileSync7(absPath, "utf-8");
+    } catch {
+      continue;
+    }
+    const toolNameEscaped = route.uri.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const toolCallRe = new RegExp(`\\.tool\\(\\s*['"]${toolNameEscaped}['"]`);
+    const toolCallMatch = toolCallRe.exec(source);
+    const toolCallIndex = toolCallMatch?.index ?? 0;
+    const toolLine = toolCallIndex > 0 ? source.slice(0, toolCallIndex).split("\n").length : route.line ?? 0;
+    const annotations = parseAnnotationsFlexible(source, toolCallIndex) ?? parseAnnotations(source, toolCallIndex);
+    let handlerCalls = [];
+    let handlerResolved = false;
+    if (toolCallIndex > 0) {
+      const scanResult = scanInlineHandler(source, toolCallIndex, fileRow.path, store, projectRoot, depth);
+      handlerCalls = scanResult.calls;
+      handlerResolved = handlerCalls.length > 0 || scanResult.calledSymbolIds.length > 0;
+    }
+    const seen = /* @__PURE__ */ new Set();
+    handlerCalls = handlerCalls.filter((c) => {
+      const key = `${c.function}:${c.file}:${c.line}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+    for (const call of handlerCalls) {
+      if (!capabilityMap[call.file]) capabilityMap[call.file] = /* @__PURE__ */ new Set();
+      capabilityMap[call.file].add(call.category);
+    }
+    toolRegistrations.push({
+      name: route.uri,
+      description: route.name ?? null,
+      file: fileRow.path,
+      line: toolLine,
+      annotations,
+      handler_resolved: handlerResolved,
+      handler_calls: handlerCalls
+    });
+  }
+  const sensitiveFlows = [];
+  const mcpServerFiles = new Set(toolRegistrations.map((t) => t.file));
+  if (mcpServerFiles.size > 0) {
+    const mcpDirs = [...new Set([...mcpServerFiles].map((f) => path57.dirname(f)))];
+    for (const dir of mcpDirs) {
+      const taintResult = taintAnalysis(store, projectRoot, {
+        scope: dir,
+        sources: ["env", "file_read"],
+        includeSanitized: false,
+        limit: 50
+      });
+      if (taintResult.isOk()) {
+        for (const flow of taintResult.value.flows) {
+          sensitiveFlows.push({
+            source: {
+              kind: flow.source.kind,
+              name: flow.source.variable,
+              file: flow.file,
+              line: flow.source.line
+            },
+            sink: {
+              kind: flow.sink.kind,
+              file: flow.file,
+              line: flow.sink.line
+            },
+            hops: flow.path.map((step) => `${flow.file}:${step.line}`)
+          });
+        }
+      }
+    }
+  }
+  const capabilityMapOutput = {};
+  for (const [file, categories] of Object.entries(capabilityMap)) {
+    capabilityMapOutput[file] = [...categories].sort();
+  }
+  return ok10({
+    $schema: "https://skill-scan.dev/schemas/enrichment/v1.json",
+    version: "1",
+    generator: `trace-mcp/${PKG_VERSION}`,
+    generated_at: (/* @__PURE__ */ new Date()).toISOString(),
+    tool_registrations: toolRegistrations,
+    sensitive_flows: sensitiveFlows,
+    capability_map: capabilityMapOutput,
+    warnings
+  });
+}
+
 // src/tools/register/quality.ts
 function registerQualityTools(server, ctx) {
   const { store, registry, config, projectRoot, j: j3 } = ctx;
-  server.tool("get_co_changes", "Find files that frequently change together in git history (temporal coupling).", { file: z10.string().min(1).max(512).describe("File path to analyze"), min_confidence: z10.number().min(0).max(1).optional().describe("Minimum confidence threshold (default 0.3)"), min_count: z10.number().int().min(1).optional().describe("Minimum co-change count (default 3)"), window_days: z10.number().int().min(1).max(730).optional().describe("Git history window in days (default 180)"), limit: z10.number().int().min(1).max(100).optional().describe("Max results (default 20)") }, async ({ file, min_confidence, min_count, window_days, limit: lim }) => {
+  server.tool("get_co_changes", "Find files that frequently change together in git history (temporal coupling). Requires git. Use to discover hidden dependencies between files. For cross-module co-change anomalies use detect_drift instead. Read-only. Returns JSON: { file, coChanges: [{ file, confidence, count }] }.", { file: z10.string().min(1).max(512).describe("File path to analyze"), min_confidence: z10.number().min(0).max(1).optional().describe("Minimum confidence threshold (default 0.3)"), min_count: z10.number().int().min(1).optional().describe("Minimum co-change count (default 3)"), window_days: z10.number().int().min(1).max(730).optional().describe("Git history window in days (default 180)"), limit: z10.number().int().min(1).max(100).optional().describe("Max results (default 20)") }, async ({ file, min_confidence, min_count, window_days, limit: lim }) => {
     const result = getCoChanges(store, { file, minConfidence: min_confidence, minCount: min_count, windowDays: window_days, limit: lim });
     if (result.isErr()) return { content: [{ type: "text", text: j3(formatToolError(result.error)) }], isError: true };
     return { content: [{ type: "text", text: j3(result.value) }] };
   });
-  server.tool("refresh_co_changes", "Rebuild co-change index from git history.", { window_days: z10.number().int().min(1).max(730).optional().describe("Git history window in days (default 180)") }, async ({ window_days }) => {
+  server.tool("refresh_co_changes", "Rebuild co-change index from git history. Mutates the co-change index; idempotent. Use after significant git history changes. Returns JSON: { status, pairs_stored, window_days }.", { window_days: z10.number().int().min(1).max(730).optional().describe("Git history window in days (default 180)") }, async ({ window_days }) => {
     const days = window_days ?? 180;
     const pairs = collectCoChanges(projectRoot, days);
     const count2 = persistCoChanges(store, pairs, projectRoot, days);
     return { content: [{ type: "text", text: j3({ status: "completed", pairs_stored: count2, window_days: days }) }] };
   });
-  server.tool("get_changed_symbols", 'Map a git diff to affected symbols (functions, classes, methods). For PR review. If "since" is omitted, auto-detects main/master as the base.', { since: z10.string().min(1).max(256).optional().describe("Git ref to compare from (SHA, branch, tag). If omitted, auto-detects main/master merge-base"), until: z10.string().max(256).optional().describe("Git ref to compare to (default: HEAD)"), include_blast_radius: z10.boolean().optional().describe("Include blast radius for each changed symbol (default false)"), max_blast_depth: z10.number().int().min(1).max(10).optional().describe("Max blast radius traversal depth (default 3)") }, async ({ since, until, include_blast_radius, max_blast_depth }) => {
+  server.tool("get_changed_symbols", 'Map a git diff to affected symbols (functions, classes, methods). For PR review. If "since" is omitted, auto-detects main/master as the base. Requires git. Use for PR review to see which symbols changed. For full branch comparison with risk assessment use compare_branches instead. Read-only. Returns JSON: { changes: [{ symbol_id, name, kind, file, changeType }], total }.', { since: z10.string().min(1).max(256).optional().describe("Git ref to compare from (SHA, branch, tag). If omitted, auto-detects main/master merge-base"), until: z10.string().max(256).optional().describe("Git ref to compare to (default: HEAD)"), include_blast_radius: z10.boolean().optional().describe("Include blast radius for each changed symbol (default false)"), max_blast_depth: z10.number().int().min(1).max(10).optional().describe("Max blast radius traversal depth (default 3)") }, async ({ since, until, include_blast_radius, max_blast_depth }) => {
     const result = getChangedSymbols(store, projectRoot, { since, until, includeBlastRadius: include_blast_radius, maxBlastDepth: max_blast_depth, defaultBaseBranch: config.git?.defaultBaseBranch });
     if (result.isErr()) return { content: [{ type: "text", text: j3(formatToolError(result.error)) }], isError: true };
     return { content: [{ type: "text", text: j3(result.value) }] };
   });
   server.tool(
     "compare_branches",
-    "Compare two branches at symbol level: what was added, modified, removed. Resolves merge-base automatically, groups by category/file/risk, includes blast radius and risk assessment.",
+    "Compare two branches at symbol level: what was added, modified, removed. Resolves merge-base automatically, groups by category/file/risk, includes blast radius and risk assessment. Requires git. Use for comprehensive PR comparison. For a quick list of changed symbols without risk analysis use get_changed_symbols instead. Read-only. Returns JSON: { branch, base, mergeBase, changes: [{ symbol_id, category, risk }], summary }.",
     {
       branch: z10.string().min(1).max(256).describe('Branch to compare (e.g. "feature/payments")'),
       base: z10.string().max(256).optional().describe('Base branch (default: "main")'),
@@ -74535,28 +74933,28 @@ function registerQualityTools(server, ctx) {
       return { content: [{ type: "text", text: j3(result.value) }] };
     }
   );
-  server.tool("detect_communities", "Run Leiden community detection on the file dependency graph. Identifies tightly-coupled file clusters (modules).", { resolution: z10.number().min(0.1).max(5).optional().describe("Resolution parameter \u2014 higher values produce more communities (default 1.0)") }, async ({ resolution }) => {
+  server.tool("detect_communities", "Run Leiden community detection on the file dependency graph. Identifies tightly-coupled file clusters (modules). Mutates the community index (stores results); idempotent. Use before get_communities or get_community. Returns JSON: { communities: [{ id, files, size }], modularity }.", { resolution: z10.number().min(0.1).max(5).optional().describe("Resolution parameter \u2014 higher values produce more communities (default 1.0)") }, async ({ resolution }) => {
     const result = detectCommunities2(store, resolution ?? 1);
     if (result.isErr()) return { content: [{ type: "text", text: j3(formatToolError(result.error)) }], isError: true };
     return { content: [{ type: "text", text: j3(result.value) }] };
   });
-  server.tool("get_communities", "Get previously detected communities (file clusters). Run detect_communities first.", {}, async () => {
+  server.tool("get_communities", "Get previously detected communities (file clusters). Run detect_communities first. Read-only. Returns JSON: { communities: [{ id, files, size }], total }.", {}, async () => {
     const result = getCommunities(store);
     if (result.isErr()) return { content: [{ type: "text", text: j3(formatToolError(result.error)) }], isError: true };
     return { content: [{ type: "text", text: j3(result.value) }] };
   });
-  server.tool("get_community", "Get details for a specific community: files, inter-community dependencies.", { id: z10.number().int().min(0).describe("Community ID") }, async ({ id }) => {
+  server.tool("get_community", "Get details for a specific community: files, inter-community dependencies. Read-only. Use after detect_communities to drill into a specific cluster. Returns JSON: { id, files, interCommunityDeps }.", { id: z10.number().int().min(0).describe("Community ID") }, async ({ id }) => {
     const result = getCommunityDetail(store, id);
     if (result.isErr()) return { content: [{ type: "text", text: j3(formatToolError(result.error)) }], isError: true };
     return { content: [{ type: "text", text: j3(result.value) }] };
   });
-  server.tool("audit_config", "Scan AI agent config files for stale references, dead paths, and token bloat.", { config_files: z10.array(z10.string().max(512)).optional().describe("Specific config files to audit (default: auto-detect)"), fix_suggestions: z10.boolean().optional().describe("Include fix suggestions (default true)") }, async ({ config_files, fix_suggestions }) => {
+  server.tool("audit_config", "Scan AI agent config files for stale references, dead paths, and token bloat. Read-only. Use periodically to clean up CLAUDE.md and settings. Returns JSON: { issues: [{ file, type, message, suggestion }], total }.", { config_files: z10.array(z10.string().max(512)).optional().describe("Specific config files to audit (default: auto-detect)"), fix_suggestions: z10.boolean().optional().describe("Include fix suggestions (default true)") }, async ({ config_files, fix_suggestions }) => {
     const result = auditConfig(store, projectRoot, { configFiles: config_files, fixSuggestions: fix_suggestions ?? true });
     return { content: [{ type: "text", text: j3(result) }] };
   });
   server.tool(
     "get_control_flow",
-    "Build a Control Flow Graph (CFG) for a function/method: if/else branches, loops, try/catch, returns, throws. Shows logical paths through the code. Outputs Mermaid diagram, ASCII, or JSON.",
+    "Build a Control Flow Graph (CFG) for a function/method: if/else branches, loops, try/catch, returns, throws. Shows logical paths through the code. Outputs Mermaid diagram, ASCII, or JSON. Use to understand branching logic before modifying complex functions. For call-level graph (who calls whom) use get_call_graph instead. Read-only. Returns Mermaid/ASCII/JSON: { nodes, edges, entryPoint, exitPoints }.",
     {
       symbol_id: z10.string().max(512).optional().describe("Symbol ID of the function/method"),
       fqn: z10.string().max(512).optional().describe("Fully qualified name of the function/method"),
@@ -74578,7 +74976,7 @@ function registerQualityTools(server, ctx) {
   );
   server.tool(
     "get_package_deps",
-    "Cross-repo package dependency analysis: find which registered projects depend on a package, or what packages a project publishes. Scans package.json/composer.json/pyproject.toml across all repos in the registry.",
+    "Cross-repo package dependency analysis: find which registered projects depend on a package, or what packages a project publishes. Scans package.json/composer.json/pyproject.toml across all repos in the registry. Use for cross-project dependency mapping. For impact of upgrading a specific package use plan_batch_change instead. Read-only. Returns JSON: { dependents, dependencies, package }.",
     {
       package: z10.string().max(256).optional().describe('Package name to analyze (e.g. "@myorg/shared-utils")'),
       project: z10.string().max(256).optional().describe("Project name \u2014 analyze all packages it publishes"),
@@ -74595,7 +74993,7 @@ function registerQualityTools(server, ctx) {
   );
   server.tool(
     "generate_docs",
-    "Auto-generate project documentation from the code graph. Produces structured docs with architecture, API surface, data models, components, and dependency analysis.",
+    "Auto-generate project documentation from the code graph. Produces structured docs with architecture, API surface, data models, components, and dependency analysis. Writes output file (markdown or HTML). Use when you need a comprehensive documentation snapshot. Returns JSON: { format, sections, outputPath }.",
     {
       scope: z10.enum(["project", "module", "directory"]).optional().describe("Scope (default: project)"),
       path: z10.string().max(512).optional().describe("Path for module/directory scope"),
@@ -74615,7 +75013,7 @@ function registerQualityTools(server, ctx) {
   );
   server.tool(
     "pack_context",
-    "Pack project context into a single document for external LLMs. Intelligent selection by graph importance, fits within token budget. Better than Repomix for focused context. Strategies: most_relevant (default \u2014 feature/PageRank ranked), core_first (PageRank always wins, surfaces architecturally central code), compact (signatures only \u2014 drops source bodies, lets outlines cover much more of the repo per token).",
+    "Pack project context into a single document for external LLMs. Intelligent selection by graph importance, fits within token budget. Better than Repomix for focused context. Strategies: most_relevant (default \u2014 feature/PageRank ranked), core_first (PageRank always wins, surfaces architecturally central code), compact (signatures only \u2014 drops source bodies, lets outlines cover much more of the repo per token). Read-only. Use when sharing project context with external tools. Returns XML/Markdown/JSON with selected code within budget.",
     {
       scope: z10.enum(["project", "module", "feature"]).describe("Scope: project (whole repo), module (subdirectory), feature (NL query)"),
       path: z10.string().max(512).optional().describe("Subdirectory path (for module scope)"),
@@ -74645,7 +75043,7 @@ function registerQualityTools(server, ctx) {
   );
   server.tool(
     "check_quality_gates",
-    "Run configurable quality gate checks against the project. Returns pass/fail for each gate (complexity, coupling, circular imports, dead exports, tech debt, security, antipatterns, code smells). Designed for CI integration \u2014 AI can verify gates pass before committing.",
+    "Run configurable quality gate checks against the project. Returns pass/fail for each gate (complexity, coupling, circular imports, dead exports, tech debt, security, antipatterns, code smells). Designed for CI integration \u2014 AI can verify gates pass before committing. Use before PR/commit to ensure quality standards. Read-only. Returns JSON: { passed, gates: [{ name, status, value, threshold }], summary }.",
     {
       scope: z10.enum(["project", "changed"]).optional().describe('Scope: "project" (all) or "changed" (git diff). Default: project'),
       since: z10.string().max(128).optional().describe('Git ref for "changed" scope (e.g. "main")'),
@@ -74690,6 +75088,21 @@ function registerQualityTools(server, ctx) {
       return { content: [{ type: "text", text: j3(report) }] };
     }
   );
+  server.tool(
+    "export_security_context",
+    "Export security context for MCP server analysis. Generates enrichment JSON for skill-scan: tool registrations with annotations, transitive call graphs classified by security category (file_read, file_write, network_outbound, env_read, shell_exec, crypto, serialization), sensitive data flows, and per-file capability maps. Use to analyze MCP server security before installation. Read-only. Returns JSON: { tool_registrations, sensitive_flows, capability_map, warnings }.",
+    {
+      scope: z10.string().max(512).optional().describe("Limit analysis to directory (relative to project root)"),
+      depth: z10.number().int().min(1).max(5).optional().describe("Call graph traversal depth (default: 3)")
+    },
+    async ({ scope, depth }) => {
+      const result = exportSecurityContext(store, projectRoot, { scope, depth });
+      if (result.isErr()) {
+        return { content: [{ type: "text", text: j3(formatToolError(result.error)) }], isError: true };
+      }
+      return { content: [{ type: "text", text: j3(result.value) }] };
+    }
+  );
 }
 
 // src/tools/register/session.ts
@@ -74697,7 +75110,7 @@ import { z as z13 } from "zod";
 
 // src/tools/ai/ai-tools.ts
 import { z as z11 } from "zod";
-import path57 from "path";
+import path58 from "path";
 function j(value) {
   return JSON.stringify(value);
 }
@@ -74713,7 +75126,7 @@ function symbolToContextItem(sym, file, projectRoot, score = 1) {
 }
 function readSourceSafe(filePath, byteStart, byteEnd, projectRoot, gitignored) {
   try {
-    const absPath = path57.resolve(projectRoot, filePath);
+    const absPath = path58.resolve(projectRoot, filePath);
     return readByteRange(absPath, byteStart, byteEnd, gitignored);
   } catch {
     return null;
@@ -75029,16 +75442,16 @@ function registerAITools(server, ctx) {
 // src/bundles.ts
 init_logger();
 import Database5 from "better-sqlite3";
-import path58 from "path";
+import path59 from "path";
 import fs49 from "fs";
 import crypto6 from "crypto";
-var BUNDLES_DIR = path58.join(TRACE_MCP_HOME, "bundles");
+var BUNDLES_DIR = path59.join(TRACE_MCP_HOME, "bundles");
 function getBundlePath(packageName, version2) {
   const safeName = packageName.replace(/[^a-zA-Z0-9._-]/g, "_");
-  return path58.join(BUNDLES_DIR, `${safeName}-${version2}.bundle.db`);
+  return path59.join(BUNDLES_DIR, `${safeName}-${version2}.bundle.db`);
 }
 function getManifestPath() {
-  return path58.join(BUNDLES_DIR, "manifest.json");
+  return path59.join(BUNDLES_DIR, "manifest.json");
 }
 function loadManifest() {
   const p = getManifestPath();
@@ -75108,8 +75521,8 @@ function searchBundles(bundles, query, opts = {}) {
 
 // src/analytics/analytics-store.ts
 import Database6 from "better-sqlite3";
-import path59 from "path";
-var ANALYTICS_DB_PATH = path59.join(TRACE_MCP_HOME, "analytics.db");
+import path60 from "path";
+var ANALYTICS_DB_PATH = path60.join(TRACE_MCP_HOME, "analytics.db");
 var SCHEMA_SQL = `
 CREATE TABLE IF NOT EXISTS sessions (
   id TEXT PRIMARY KEY,
@@ -75342,9 +75755,9 @@ var AnalyticsStore = class {
 // src/analytics/log-parser.ts
 init_logger();
 import fs50 from "fs";
-import path60 from "path";
+import path61 from "path";
 import os7 from "os";
-var CLAUDE_PROJECTS_DIR = path60.join(os7.homedir(), ".claude", "projects");
+var CLAUDE_PROJECTS_DIR = path61.join(os7.homedir(), ".claude", "projects");
 var CLAW_SESSIONS_DIR_NAME = ".claw/sessions";
 function parseToolName(fullName) {
   const match = fullName.match(/^mcp__([^_]+)__(.+)$/);
@@ -75421,7 +75834,7 @@ function parseSessionFile(filePath, projectPath) {
   try {
     const content = fs50.readFileSync(filePath, "utf-8");
     const lines = content.split("\n").filter((l) => l.trim());
-    const sessionId = path60.basename(filePath, ".jsonl");
+    const sessionId = path61.basename(filePath, ".jsonl");
     const toolCalls = [];
     const toolResults = /* @__PURE__ */ new Map();
     let model = "";
@@ -75542,11 +75955,11 @@ function listProjectDirs() {
   }));
 }
 function listSessionFiles(projectDirName) {
-  const dir = path60.join(CLAUDE_PROJECTS_DIR, projectDirName);
+  const dir = path61.join(CLAUDE_PROJECTS_DIR, projectDirName);
   if (!fs50.existsSync(dir)) return [];
   const entries = fs50.readdirSync(dir, { withFileTypes: true });
   return entries.filter((e) => e.isFile() && e.name.endsWith(".jsonl")).map((e) => {
-    const filePath = path60.join(dir, e.name);
+    const filePath = path61.join(dir, e.name);
     const stat = fs50.statSync(filePath);
     return { filePath, mtime: stat.mtimeMs };
   });
@@ -75560,13 +75973,13 @@ function listAllSessions() {
   }
   const clawProjectPaths = discoverClawProjects();
   for (const projectPath of clawProjectPaths) {
-    const sessionsDir = path60.join(projectPath, CLAW_SESSIONS_DIR_NAME);
+    const sessionsDir = path61.join(projectPath, CLAW_SESSIONS_DIR_NAME);
     if (!fs50.existsSync(sessionsDir)) continue;
     try {
       const entries = fs50.readdirSync(sessionsDir, { withFileTypes: true });
       for (const e of entries) {
         if (!e.isFile() || !e.name.endsWith(".jsonl")) continue;
-        const filePath = path60.join(sessionsDir, e.name);
+        const filePath = path61.join(sessionsDir, e.name);
         try {
           const stat = fs50.statSync(filePath);
           results.push({ filePath, projectPath, client: "claw-code", mtime: stat.mtimeMs });
@@ -75581,25 +75994,25 @@ function listAllSessions() {
 function discoverClawProjects() {
   const paths = /* @__PURE__ */ new Set();
   for (const { projectPath } of listProjectDirs()) {
-    if (fs50.existsSync(path60.join(projectPath, CLAW_SESSIONS_DIR_NAME))) {
+    if (fs50.existsSync(path61.join(projectPath, CLAW_SESSIONS_DIR_NAME))) {
       paths.add(projectPath);
     }
   }
   const cwd = process.cwd();
-  if (fs50.existsSync(path60.join(cwd, CLAW_SESSIONS_DIR_NAME))) {
+  if (fs50.existsSync(path61.join(cwd, CLAW_SESSIONS_DIR_NAME))) {
     paths.add(cwd);
   }
   const home = os7.homedir();
   const commonRoots = ["Projects", "projects", "dev", "workspace", "code", "PhpstormProjects", "WebstormProjects", "src"];
   for (const root of commonRoots) {
-    const rootDir = path60.join(home, root);
+    const rootDir = path61.join(home, root);
     if (!fs50.existsSync(rootDir)) continue;
     try {
       const entries = fs50.readdirSync(rootDir, { withFileTypes: true });
       for (const e of entries) {
         if (!e.isDirectory()) continue;
-        const projectDir = path60.join(rootDir, e.name);
-        if (fs50.existsSync(path60.join(projectDir, CLAW_SESSIONS_DIR_NAME))) {
+        const projectDir = path61.join(rootDir, e.name);
+        if (fs50.existsSync(path61.join(projectDir, CLAW_SESSIONS_DIR_NAME))) {
           paths.add(projectDir);
         }
       }
@@ -76305,7 +76718,7 @@ function formatBenchmarkMarkdown(result) {
 
 // src/analytics/tech-detector.ts
 import fs51 from "fs";
-import path61 from "path";
+import path62 from "path";
 
 // src/analytics/known-packages.ts
 var KNOWN_PACKAGES = {
@@ -77969,7 +78382,7 @@ function detectCoverage(projectRoot, opts = {}) {
   const manifestsFound = [];
   const allDeps = [];
   for (const { file, ecosystem, parser } of MANIFEST_PARSERS) {
-    const filePath = path61.join(projectRoot, file);
+    const filePath = path62.join(projectRoot, file);
     if (!fs51.existsSync(filePath)) continue;
     manifestsFound.push(file);
     const rawDeps = parser(filePath);
@@ -79146,7 +79559,7 @@ function registerSessionTools(server, ctx) {
   }
   server.tool(
     "search_bundles",
-    "Search pre-indexed bundles for symbols from popular libraries (React, Express, etc.). Returns symbol definitions from dependency bundles \u2014 useful for go-to-definition into node_modules/vendor. Install bundles via CLI: `trace-mcp bundles export`.",
+    "Search pre-indexed bundles for symbols from popular libraries (React, Express, etc.). Returns symbol definitions from dependency bundles \u2014 useful for go-to-definition into node_modules/vendor. Install bundles via CLI: `trace-mcp bundles export`. For project source code search use search instead. Read-only. Returns JSON: { results: [{ name, kind, signature, bundle }], bundles_searched }.",
     {
       query: z13.string().min(1).max(256).describe("Symbol name or FQN to search"),
       kind: z13.string().max(64).optional().describe("Filter by symbol kind (function, class, interface, etc.)"),
@@ -79164,7 +79577,7 @@ function registerSessionTools(server, ctx) {
   );
   server.tool(
     "list_bundles",
-    "List installed pre-indexed bundles for dependency libraries. Shows package name, version, symbol/edge counts, and size.",
+    "List installed pre-indexed bundles for dependency libraries. Shows package name, version, symbol/edge counts, and size. Read-only. Returns JSON: { bundles: [{ name, version, symbols, edges, size }], total }.",
     {},
     async () => {
       const bundles = listBundles();
@@ -79173,7 +79586,7 @@ function registerSessionTools(server, ctx) {
   );
   _originalTool(
     "get_preset_info",
-    "Show active tool preset, available presets, and which tools are registered in this session",
+    "Show active tool preset, available presets, and which tools are registered in this session. Read-only. Returns JSON: { active_preset, registered_tools, tool_names, available_presets }.",
     {},
     async () => {
       const presets = listPresets();
@@ -79192,7 +79605,7 @@ function registerSessionTools(server, ctx) {
   );
   _originalTool(
     "get_session_analytics",
-    "Analyze AI agent session logs: token usage, cost breakdown by tool/server, top files, models used. Parses Claude Code JSONL logs automatically.",
+    "Analyze AI agent session logs: token usage, cost breakdown by tool/server, top files, models used. Parses Claude Code JSONL logs automatically. Read-only. For waste detection use get_optimization_report; for cost trends use get_usage_trends. Returns JSON: { sessions, tokens, cost_usd, tools, models, topFiles }.",
     {
       period: z13.enum(["today", "week", "month", "all"]).optional().describe("Time period (default: week)"),
       session_id: z13.string().max(128).optional().describe("Specific session ID to analyze")
@@ -79213,7 +79626,7 @@ function registerSessionTools(server, ctx) {
   );
   _originalTool(
     "get_optimization_report",
-    "Detect token waste patterns in AI agent sessions: repeated file reads, Bash grep instead of search, large file reads, unused trace-mcp tools. Provides savings estimates.",
+    "Detect token waste patterns in AI agent sessions: repeated file reads, Bash grep instead of search, large file reads, unused trace-mcp tools. Provides savings estimates. Read-only. For usage/cost overview use get_session_analytics; for A/B savings comparison use get_real_savings. Returns JSON: { patterns: [{ type, description, savings_estimate }], total_waste }.",
     {
       period: z13.enum(["today", "week", "month", "all"]).optional().describe("Time period (default: week)")
     },
@@ -79233,7 +79646,7 @@ function registerSessionTools(server, ctx) {
   );
   server.tool(
     "benchmark_project",
-    "Synthetic token efficiency benchmark: compare raw file reads vs trace-mcp compact responses across symbol lookup, file exploration, search, and impact analysis scenarios.",
+    "Synthetic token efficiency benchmark: compare raw file reads vs trace-mcp compact responses across symbol lookup, file exploration, search, and impact analysis scenarios. Read-only, no side effects. Use to quantify token savings. Returns JSON: { scenarios: [{ name, raw_tokens, compact_tokens, savings_pct }], summary }.",
     {
       queries: z13.number().int().min(1).max(50).optional().describe("Queries per scenario (default 10)"),
       seed: z13.number().int().optional().describe("Random seed for reproducibility (default 42)"),
@@ -79249,7 +79662,7 @@ function registerSessionTools(server, ctx) {
   );
   _originalTool(
     "get_coverage_report",
-    "Technology profile of the project: detected frameworks/ORMs/UI libs from manifests (package.json, composer.json, etc.), which are covered by trace-mcp plugins, and coverage gaps.",
+    "Technology profile of the project: detected frameworks/ORMs/UI libs from manifests (package.json, composer.json, etc.), which are covered by trace-mcp plugins, and coverage gaps. Read-only. Returns JSON: { detected, covered, gaps }.",
     {},
     async () => {
       try {
@@ -79262,7 +79675,7 @@ function registerSessionTools(server, ctx) {
   );
   _originalTool(
     "get_real_savings",
-    "A/B comparison: how many tokens could be saved by using trace-mcp instead of raw Read/Bash file reads. Per-file breakdown.",
+    "A/B comparison: how many tokens could be saved by using trace-mcp instead of raw Read/Bash file reads. Per-file breakdown. Read-only. For pattern-based waste detection use get_optimization_report instead. Returns JSON: { files: [{ file, raw_tokens, compact_tokens, savings }], total_savings }.",
     {
       period: z13.enum(["today", "week", "month", "all"]).optional().describe("Time period (default: week)")
     },
@@ -79284,7 +79697,7 @@ function registerSessionTools(server, ctx) {
   );
   _originalTool(
     "get_usage_trends",
-    "Daily token usage time-series: sessions, tokens, estimated cost, tool calls per day. For spotting cost spikes.",
+    "Daily token usage time-series: sessions, tokens, estimated cost, tool calls per day. For spotting cost spikes. Read-only. For detailed session breakdown use get_session_analytics instead. Returns JSON: { days, daily: [{ date, sessions, tokens, cost_usd, tool_calls }], totals }.",
     {
       days: z13.number().int().min(1).max(365).optional().describe("Number of days to show (default: 30)")
     },
@@ -79311,7 +79724,7 @@ function registerSessionTools(server, ctx) {
   );
   _originalTool(
     "get_session_stats",
-    "Token savings stats for this session: per-tool call counts, estimated token savings, reduction percentage, dedup savings.",
+    "Token savings stats for this session: per-tool call counts, estimated token savings, reduction percentage, dedup savings. Read-only. Returns JSON: { total_calls, total_raw_tokens, total_compact_tokens, savings_pct, dedup_saved_tokens, per_tool }.",
     {},
     async () => {
       const stats = savings.getFullStats();
@@ -79329,7 +79742,7 @@ function registerSessionTools(server, ctx) {
   );
   server.tool(
     "get_session_journal",
-    "Session history: all tool calls made, files read, zero-result searches, and duplicate queries. Use to avoid repeating work.",
+    "Session history: all tool calls made, files read, zero-result searches, and duplicate queries. Use to avoid repeating work. For a compact snapshot use get_session_snapshot instead. Read-only. Returns JSON: { calls, filesRead, zeroResults, duplicates }.",
     {},
     async () => {
       const summary = journal.getSummary();
@@ -79338,7 +79751,7 @@ function registerSessionTools(server, ctx) {
   );
   server.tool(
     "get_session_snapshot",
-    "Compact session snapshot (~200 tokens) for context recovery after compaction. Returns focus files (by read count), edited files, key searches, and dead ends. Also used by the PreCompact hook to preserve session orientation automatically.",
+    "Compact session snapshot (~200 tokens) for context recovery after compaction. Returns focus files (by read count), edited files, key searches, and dead ends. Also used by the PreCompact hook to preserve session orientation automatically. Read-only. For full journal use get_session_journal; for cross-session context use get_session_resume. Returns JSON: { focusFiles, editedFiles, keySearches, deadEnds }.",
     {
       max_files: z13.number().int().min(1).max(50).optional().describe("Max focus files to include (default: 10)"),
       max_searches: z13.number().int().min(1).max(20).optional().describe("Max key searches to include (default: 5)"),
@@ -79357,7 +79770,7 @@ function registerSessionTools(server, ctx) {
   );
   server.tool(
     "get_session_resume",
-    "Cross-session context carryover: shows what was explored in recent past sessions (files touched, tools used, dead-end searches). Call at session start to orient yourself without re-reading files. Much cheaper than re-exploring the codebase.",
+    "Cross-session context carryover: shows what was explored in recent past sessions (files touched, tools used, dead-end searches). Call at session start to orient yourself without re-reading files. Much cheaper than re-exploring the codebase. Read-only. For decision-aware wake-up use get_wake_up instead. Returns JSON: { sessions: [{ files, tools, deadEnds }], active_decisions }.",
     {
       max_sessions: z13.number().int().min(1).max(20).optional().describe("Number of past sessions to include (default: 5)")
     },
@@ -79376,7 +79789,7 @@ function registerSessionTools(server, ctx) {
   );
   _originalTool(
     "plan_turn",
-    "Opening-move router for new tasks. Combines BM25/PageRank search + session journal (negative evidence + focus signals) + framework-aware insertion-point suggestions + change-risk + turn-budget advisor into ONE call. Returns verdict (exists/partial/missing/ambiguous), confidence, ranked targets with provenance, scaffold hints when missing, and recommended next tool calls. Call this FIRST on a new task to break the empty-result hallucination chain.",
+    "Opening-move router for new tasks. Combines BM25/PageRank search + session journal (negative evidence + focus signals) + framework-aware insertion-point suggestions + change-risk + turn-budget advisor into ONE call. Returns verdict (exists/partial/missing/ambiguous), confidence, ranked targets with provenance, scaffold hints when missing, and recommended next tool calls. Call this FIRST on a new task to break the empty-result hallucination chain. Read-only. For broader task context with source code use get_task_context instead. Returns JSON: { verdict, confidence, targets, scaffoldHints, nextSteps }.",
     {
       task: z13.string().min(1).max(512).describe('Natural-language task description (e.g. "add a webhook endpoint for stripe payments")'),
       intent: z13.enum(["bugfix", "new_feature", "refactor", "understand"]).optional().describe("Optional intent hint; auto-classified from task if omitted"),
@@ -79410,7 +79823,7 @@ function registerSessionTools(server, ctx) {
   );
   _originalTool(
     "batch",
-    "Execute multiple trace-mcp tools in a single MCP request. Returns results for all calls. Use to reduce round-trips when you need several independent queries (e.g., get_outline for 3 files, or search + get_symbol together).",
+    "Execute multiple trace-mcp tools in a single MCP request. Returns results for all calls. Use to reduce round-trips when you need several independent queries (e.g., get_outline for 3 files, or search + get_symbol together). Read-only (delegates to other tools). Returns JSON: { batch_results: [{ tool, result }], total }.",
     {
       calls: z13.array(z13.object({
         tool: z13.string().describe('Tool name (e.g., "get_outline", "get_symbol", "search")'),
@@ -79460,7 +79873,7 @@ import { z as z14 } from "zod";
 
 // src/memory/conversation-miner.ts
 import * as fs52 from "fs";
-import * as path62 from "path";
+import * as path63 from "path";
 init_logger();
 var DECISION_PATTERNS = [
   // Architecture decisions: "decided to", "we'll use", "going with", "chose X over Y"
@@ -79688,7 +80101,7 @@ function mineSessions(decisionStore, opts = {}) {
           file_path: d.file_path,
           tags: d.tags,
           valid_from: d.timestamp,
-          session_id: path62.basename(session.filePath, ".jsonl"),
+          session_id: path63.basename(session.filePath, ".jsonl"),
           source: "mined",
           confidence: d.confidence
         }));
@@ -79714,7 +80127,7 @@ function mineSessions(decisionStore, opts = {}) {
 
 // src/memory/session-indexer.ts
 import * as fs53 from "fs";
-import * as path63 from "path";
+import * as path64 from "path";
 init_logger();
 var MAX_CHUNK_CHARS = 2e3;
 var MIN_MESSAGE_CHARS = 50;
@@ -79755,7 +80168,7 @@ function truncateChunk(text) {
 function indexSessionFile(filePath, projectPath, decisionStore) {
   const content = fs53.readFileSync(filePath, "utf-8");
   const lines = content.split("\n").filter((l) => l.trim());
-  const sessionId = path63.basename(filePath, ".jsonl");
+  const sessionId = path64.basename(filePath, ".jsonl");
   const chunks = [];
   let chunkIndex = 0;
   for (const line of lines) {
@@ -79806,7 +80219,7 @@ function indexSessions(decisionStore, opts = {}) {
       skipped++;
       continue;
     }
-    const sessionId = path63.basename(session.filePath, ".jsonl");
+    const sessionId = path64.basename(session.filePath, ".jsonl");
     if (!opts.force && decisionStore.isSessionIndexed(sessionId)) {
       skipped++;
       continue;
@@ -79831,7 +80244,7 @@ function indexSessions(decisionStore, opts = {}) {
 }
 
 // src/memory/wake-up.ts
-import * as path64 from "path";
+import * as path65 from "path";
 function compactDecision(d) {
   const entry = {
     id: d.id,
@@ -79855,7 +80268,7 @@ function assembleWakeUp(decisionStore, projectRoot, opts = {}) {
   const indexedSessions = decisionStore.getIndexedSessionIds(projectRoot);
   const result = {
     project: {
-      name: path64.basename(projectRoot),
+      name: path65.basename(projectRoot),
       root: projectRoot
     },
     decisions: {
@@ -79899,7 +80312,7 @@ function registerMemoryTools(server, ctx) {
   }
   server.tool(
     "mine_sessions",
-    "Mine Claude Code / Claw Code session logs for architectural decisions, tech choices, bug root causes, and preferences. Extracts decision-like content using pattern matching (no LLM calls). Skips already-mined sessions unless force=true.",
+    "Mine Claude Code / Claw Code session logs for architectural decisions, tech choices, bug root causes, and preferences. Extracts decision-like content using pattern matching (no LLM calls). Skips already-mined sessions unless force=true. Mutates the decision store; idempotent. Use to populate the decision knowledge graph. Returns JSON: { mined, decisions_extracted, sessions_processed }.",
     {
       project_root: z14.string().max(1024).optional().describe("Only mine sessions for this project path (default: all projects)"),
       force: z14.boolean().optional().describe("Re-mine already processed sessions (default: false)"),
@@ -79916,7 +80329,7 @@ function registerMemoryTools(server, ctx) {
   );
   server.tool(
     "add_decision",
-    "Manually record an architectural decision, tech choice, preference, or convention. Links to code symbols/files and optionally to a specific subproject for code-aware memory. Decisions have temporal validity \u2014 they can be invalidated later when they become outdated.",
+    "Manually record an architectural decision, tech choice, preference, or convention. Links to code symbols/files and optionally to a specific subproject for code-aware memory. Decisions have temporal validity \u2014 they can be invalidated later when they become outdated. Mutates the decision store (creates a new record). For automated extraction from session logs use mine_sessions instead. Returns JSON: { added: { id, title, type } }.",
     {
       title: z14.string().min(1).max(200).describe("Short summary of the decision"),
       content: z14.string().min(1).max(5e3).describe("Full decision text \u2014 reasoning, context, tradeoffs"),
@@ -79944,7 +80357,7 @@ function registerMemoryTools(server, ctx) {
   );
   server.tool(
     "query_decisions",
-    'Query the decision knowledge graph. Filter by type, subproject, code symbol, file path, tag, or time. Returns decisions linked to code \u2014 "why was this architecture chosen?" answered with the actual decision record. Use service_name to filter by a specific subproject within the project.',
+    'Query the decision knowledge graph. Filter by type, subproject, code symbol, file path, tag, or time. Returns decisions linked to code \u2014 "why was this architecture chosen?" answered with the actual decision record. Use service_name to filter by a specific subproject within the project. Read-only. Returns JSON: { decisions: [{ id, title, type, content, tags }], total_results }.',
     {
       type: z14.enum(DECISION_TYPES).optional().describe("Filter by decision type"),
       service_name: z14.string().max(256).optional().describe('Filter by subproject name (e.g., "auth-api")'),
@@ -79980,14 +80393,14 @@ function registerMemoryTools(server, ctx) {
   );
   server.tool(
     "invalidate_decision",
-    "Mark a decision as no longer valid. The decision remains in the knowledge graph for historical queries but is excluded from active queries. Use when a decision is superseded or reversed.",
+    "Mark a decision as no longer valid. The decision remains in the knowledge graph for historical queries but is excluded from active queries. Use when a decision is superseded or reversed. Mutates the decision store; idempotent. Returns JSON: { invalidated: { id, title, valid_until } }.",
     {
       id: z14.number().int().min(1).describe("Decision ID to invalidate"),
       valid_until: z14.string().max(30).optional().describe("ISO timestamp when decision became invalid (default: now)")
     },
     async ({ id, valid_until }) => {
-      const ok10 = decisionStore.invalidateDecision(id, valid_until);
-      if (!ok10) {
+      const ok11 = decisionStore.invalidateDecision(id, valid_until);
+      if (!ok11) {
         return { content: [{ type: "text", text: j3({ error: `Decision ${id} not found or already invalidated` }) }], isError: true };
       }
       const updated = decisionStore.getDecision(id);
@@ -79996,7 +80409,7 @@ function registerMemoryTools(server, ctx) {
   );
   server.tool(
     "get_decision_timeline",
-    "Chronological timeline of decisions for a project, symbol, or file. Shows when decisions were made and invalidated \u2014 like git log but for architectural decisions.",
+    "Chronological timeline of decisions for a project, symbol, or file. Shows when decisions were made and invalidated \u2014 like git log but for architectural decisions. Read-only. Use to review decision history. Returns JSON: { timeline: [{ id, title, type, created_at, valid_until }], count }.",
     {
       symbol_id: z14.string().max(512).optional().describe("Filter timeline to decisions about this symbol"),
       file_path: z14.string().max(1024).optional().describe("Filter timeline to decisions about this file"),
@@ -80014,7 +80427,7 @@ function registerMemoryTools(server, ctx) {
   );
   server.tool(
     "get_decision_stats",
-    "Overview of the decision knowledge graph: total decisions, active/invalidated counts, breakdown by type and source. Shows how much institutional knowledge is captured.",
+    "Overview of the decision knowledge graph: total decisions, active/invalidated counts, breakdown by type and source. Shows how much institutional knowledge is captured. Read-only. Returns JSON: { total, active, invalidated, by_type, by_source, sessions_mined }.",
     {},
     async () => {
       const stats = decisionStore.getStats(projectRoot);
@@ -80026,7 +80439,7 @@ function registerMemoryTools(server, ctx) {
   );
   server.tool(
     "index_sessions",
-    'Index conversation content from Claude Code / Claw Code sessions for cross-session search. Stores chunked messages in FTS5 \u2014 enables "what did we discuss about X?" queries across all past sessions. Skips already-indexed sessions unless force=true.',
+    'Index conversation content from Claude Code / Claw Code sessions for cross-session search. Stores chunked messages in FTS5 \u2014 enables "what did we discuss about X?" queries across all past sessions. Skips already-indexed sessions unless force=true. Mutates the session index; idempotent. Use before search_sessions. Returns JSON: { indexed, sessions_processed, chunks_stored }.',
     {
       project_root: z14.string().max(1024).optional().describe("Only index sessions for this project path (default: current project)"),
       force: z14.boolean().optional().describe("Re-index already processed sessions (default: false)")
@@ -80041,7 +80454,7 @@ function registerMemoryTools(server, ctx) {
   );
   server.tool(
     "search_sessions",
-    'Search across all past session conversations. Finds what was discussed, decided, or debugged in previous sessions. Full-text search with porter stemming \u2014 e.g., "why did we switch to GraphQL", "auth middleware bug", "database migration approach".',
+    'Search across all past session conversations. Finds what was discussed, decided, or debugged in previous sessions. Full-text search with porter stemming \u2014 e.g., "why did we switch to GraphQL", "auth middleware bug", "database migration approach". Requires index_sessions to be run first. Read-only. Returns JSON: { results: [{ session_id, text, score }], total_results }.',
     {
       query: z14.string().min(1).max(500).describe("Search query (FTS5 with porter stemming)"),
       limit: z14.number().int().min(1).max(50).optional().describe("Max results (default: 20)")
@@ -80060,7 +80473,7 @@ function registerMemoryTools(server, ctx) {
   );
   server.tool(
     "get_wake_up",
-    "Compact orientation context (~300 tokens) for session start. Returns: project identity, active architectural decisions (linked to code symbols/files), and memory stats. Auto-mines sessions on first call if no decisions exist yet. Like MemPalace wake-up but code-aware \u2014 decisions are tied to the dependency graph.",
+    "Compact orientation context (~300 tokens) for session start. Returns: project identity, active architectural decisions (linked to code symbols/files), and memory stats. Auto-mines sessions on first call if no decisions exist yet. Like MemPalace wake-up but code-aware \u2014 decisions are tied to the dependency graph. Use at session start for context recovery. For cross-session file/tool history use get_session_resume instead. Returns JSON: { project, decisions, stats }.",
     {
       max_decisions: z14.number().int().min(1).max(30).optional().describe("Max recent decisions to include (default: 10)"),
       auto_mine: z14.boolean().optional().describe("Auto-mine sessions if decision store is empty (default: true)")
@@ -81053,7 +81466,7 @@ var DecisionStore = class {
 };
 
 // src/server/server.ts
-var PKG_VERSION = true ? "1.21.2" : "0.0.0-dev";
+var PKG_VERSION2 = true ? "1.22.0" : "0.0.0-dev";
 function j2(value) {
   return JSON.stringify(value, (_key, val) => val === null || val === void 0 ? void 0 : val);
 }
@@ -81169,7 +81582,7 @@ function createServer2(store, registry, config, rootPath, progress) {
   const detectedFrameworks = [...frameworkNames].join(", ") || "none";
   const instructionsVerbosity = config.tools?.instructions_verbosity ?? "full";
   const server = new McpServer(
-    { name: "trace-mcp", version: PKG_VERSION },
+    { name: "trace-mcp", version: PKG_VERSION2 },
     { instructions: buildInstructions(detectedFrameworks, instructionsVerbosity) }
   );
   const savings = new SavingsTracker(projectRoot);