@takara-ai/miru-code 1.1.2 → 1.2.1

package/src/installer/benchmark-mode.ts

@@ -0,0 +1,248 @@
+import { AGENT_TARGETS, type AgentTarget, type InstallAction } from "./agents.ts";
+import { removeTomlBlock, stripJsonComments } from "./config.ts";
+
+export const MCP_BENCHMARK_FLAG = "--benchmark";
+
+const CODEX_MCP_HEADER = "[mcp_servers.miru]";
+
+function codexMcpBlock(enabled: boolean): string {
+  const args = enabled
+    ? `["@takara-ai/miru-code", "${MCP_BENCHMARK_FLAG}"]`
+    : '["@takara-ai/miru-code"]';
+  return `${CODEX_MCP_HEADER}\ncommand = "bunx"\nargs = ${args}\n`;
+}
+
+export function withBenchmarkFlag(list: string[], enabled: boolean): string[] {
+  const without = list.filter((item) => item !== MCP_BENCHMARK_FLAG);
+  return enabled ? [...without, MCP_BENCHMARK_FLAG] : without;
+}
+
+export function listHasBenchmarkFlag(list: unknown): boolean {
+  return Array.isArray(list) && list.some((item) => item === MCP_BENCHMARK_FLAG);
+}
+
+/** Toggle `--benchmark` on a JSON MCP server entry (`args` and/or array `command`). */
+export function applyBenchmarkFlagToMcpEntry(
+  entry: Record<string, unknown>,
+  enabled: boolean,
+): { entry: Record<string, unknown>; changed: boolean; enabled: boolean } {
+  const next: Record<string, unknown> = { ...entry };
+  let changed = false;
+
+  if (Array.isArray(next.args)) {
+    const args = next.args.filter((item): item is string => typeof item === "string");
+    const updated = withBenchmarkFlag(args, enabled);
+    if (JSON.stringify(updated) !== JSON.stringify(args)) {
+      next.args = updated;
+      changed = true;
+    }
+  }
+
+  if (Array.isArray(next.command)) {
+    const command = next.command.filter((item): item is string => typeof item === "string");
+    const updated = withBenchmarkFlag(command, enabled);
+    if (JSON.stringify(updated) !== JSON.stringify(command)) {
+      next.command = updated;
+      changed = true;
+    }
+  }
+
+  return {
+    entry: next,
+    changed,
+    enabled: mcpEntryHasBenchmark(next),
+  };
+}
+
+export function mcpEntryHasBenchmark(entry: Record<string, unknown>): boolean {
+  return listHasBenchmarkFlag(entry.args) || listHasBenchmarkFlag(entry.command);
+}
+
+/**
+ * Keep `--benchmark` on the canonical install entry when the existing MCP
+ * entry already had it (so `miru install` does not silently turn mode off).
+ */
+export function withPreservedBenchmarkFlag(
+  canonical: Record<string, unknown>,
+  existing: Record<string, unknown> | null | undefined,
+): Record<string, unknown> {
+  if (!existing || !mcpEntryHasBenchmark(existing)) {
+    return canonical;
+  }
+  return applyBenchmarkFlagToMcpEntry(canonical, true).entry;
+}
+
+export interface BenchmarkModeTargetResult {
+  agent: string;
+  path: string;
+  action: InstallAction | "enabled" | "disabled" | "missing";
+  enabled: boolean;
+}
+
+async function readJsonObject(path: string): Promise<Record<string, unknown> | null> {
+  if (!(await Bun.file(path).exists())) {
+    return null;
+  }
+  try {
+    const text = stripJsonComments(await Bun.file(path).text());
+    const parsed = JSON.parse(text) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return null;
+    }
+    return parsed as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+async function writeJsonObject(path: string, value: Record<string, unknown>): Promise<void> {
+  await Bun.write(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+async function statusForToml(path: string): Promise<boolean | null> {
+  if (!(await Bun.file(path).exists())) {
+    return null;
+  }
+  const text = await Bun.file(path).text();
+  if (!text.includes(CODEX_MCP_HEADER)) {
+    return null;
+  }
+  return text.includes(`"${MCP_BENCHMARK_FLAG}"`) || text.includes(`'${MCP_BENCHMARK_FLAG}'`);
+}
+
+async function setTomlBenchmark(
+  path: string,
+  enabled: boolean,
+): Promise<InstallAction | "missing"> {
+  if (!(await Bun.file(path).exists())) {
+    return "missing";
+  }
+  const text = await Bun.file(path).text();
+  if (!text.includes(CODEX_MCP_HEADER)) {
+    return "missing";
+  }
+  const current = await statusForToml(path);
+  if (current === enabled) {
+    return "unchanged";
+  }
+
+  // Replace the miru block with the desired args, preserving the rest of the file.
+  await removeTomlBlock(path);
+  const existed = await Bun.file(path).exists();
+  const existing = existed ? await Bun.file(path).text() : "";
+  const base = existing.replace(/\n+$/, "");
+  const block = codexMcpBlock(enabled);
+  const next = base.length > 0 ? `${base}\n\n${block}` : block;
+  await Bun.write(path, next.endsWith("\n") ? next : `${next}\n`);
+  return "updated";
+}
+
+async function statusForJson(agent: AgentTarget): Promise<boolean | null> {
+  const mcp = agent.mcp;
+  if (mcp?.format !== "json") {
+    return null;
+  }
+  const parsed = await readJsonObject(mcp.path);
+  if (!parsed) {
+    return null;
+  }
+  const section = parsed[mcp.key];
+  if (!section || typeof section !== "object" || Array.isArray(section)) {
+    return null;
+  }
+  const entry = (section as Record<string, unknown>)[mcp.memberKey];
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+    return null;
+  }
+  return mcpEntryHasBenchmark(entry as Record<string, unknown>);
+}
+
+async function setJsonBenchmark(
+  agent: AgentTarget,
+  enabled: boolean,
+): Promise<InstallAction | "missing"> {
+  const mcp = agent.mcp;
+  if (mcp?.format !== "json") {
+    return "missing";
+  }
+  const parsed = await readJsonObject(mcp.path);
+  if (!parsed) {
+    return "missing";
+  }
+  const sectionRaw = parsed[mcp.key];
+  if (!sectionRaw || typeof sectionRaw !== "object" || Array.isArray(sectionRaw)) {
+    return "missing";
+  }
+  const section = sectionRaw as Record<string, unknown>;
+  const entryRaw = section[mcp.memberKey];
+  if (!entryRaw || typeof entryRaw !== "object" || Array.isArray(entryRaw)) {
+    return "missing";
+  }
+
+  const applied = applyBenchmarkFlagToMcpEntry(entryRaw as Record<string, unknown>, enabled);
+  if (!applied.changed) {
+    return "unchanged";
+  }
+  section[mcp.memberKey] = applied.entry;
+  parsed[mcp.key] = section;
+  await writeJsonObject(mcp.path, parsed);
+  return "updated";
+}
+
+/** Inspect installed Miru MCP configs for `--benchmark`. */
+export async function getBenchmarkModeStatus(): Promise<BenchmarkModeTargetResult[]> {
+  const results: BenchmarkModeTargetResult[] = [];
+  for (const agent of AGENT_TARGETS) {
+    const mcp = agent.mcp;
+    if (!mcp) {
+      continue;
+    }
+    if (mcp.format === "toml") {
+      const enabled = await statusForToml(mcp.path);
+      results.push({
+        agent: agent.displayName,
+        path: mcp.path,
+        action: enabled == null ? "missing" : enabled ? "enabled" : "disabled",
+        enabled: enabled === true,
+      });
+      continue;
+    }
+    const enabled = await statusForJson(agent);
+    results.push({
+      agent: agent.displayName,
+      path: mcp.path,
+      action: enabled == null ? "missing" : enabled ? "enabled" : "disabled",
+      enabled: enabled === true,
+    });
+  }
+  return results;
+}
+
+/** Enable or disable `--benchmark` on every installed Miru MCP entry. */
+export async function setBenchmarkMode(enabled: boolean): Promise<BenchmarkModeTargetResult[]> {
+  const results: BenchmarkModeTargetResult[] = [];
+  for (const agent of AGENT_TARGETS) {
+    const mcp = agent.mcp;
+    if (!mcp) {
+      continue;
+    }
+    if (mcp.format === "toml") {
+      const action = await setTomlBenchmark(mcp.path, enabled);
+      results.push({
+        agent: agent.displayName,
+        path: mcp.path,
+        action,
+        enabled: action === "missing" ? false : enabled,
+      });
+      continue;
+    }
+    const action = await setJsonBenchmark(agent, enabled);
+    results.push({
+      agent: agent.displayName,
+      path: mcp.path,
+      action,
+      enabled: action === "missing" ? false : enabled,
+    });
+  }
+  return results;
+}

package/src/installer/config.ts

@@ -6,6 +6,11 @@ const CODEX_MCP_BLOCK = `[mcp_servers.miru]
 command = "bunx"
 args = ["@takara-ai/miru-code"]
 `;
+/** Same Codex block with `--benchmark` preserved across reinstall. */
+const CODEX_MCP_BLOCK_BENCHMARK = `[mcp_servers.miru]
+command = "bunx"
+args = ["@takara-ai/miru-code", "--benchmark"]
+`;
 
 /** Strip line and block comments so JSONC configs can be parsed. */
 export function stripJsonComments(text: string): string {
@@ -487,12 +492,19 @@ export async function mergeTomlBlock(path: string): Promise<InstallAction> {
   const existed = await Bun.file(path).exists();
   const existing = existed ? await Bun.file(path).text() : "";
 
-  if (existing.includes(CODEX_MCP_BLOCK.trim())) {
+  const defaultBlock = CODEX_MCP_BLOCK.trim();
+  const benchmarkBlock = CODEX_MCP_BLOCK_BENCHMARK.trim();
+  if (existing.includes(defaultBlock) || existing.includes(benchmarkBlock)) {
     return "unchanged";
   }
 
+  const preserveBenchmark =
+    existing.includes(CODEX_MCP_HEADER) &&
+    (existing.includes('"--benchmark"') || existing.includes("'--benchmark'"));
+  const block = preserveBenchmark ? CODEX_MCP_BLOCK_BENCHMARK : CODEX_MCP_BLOCK;
+
   const base = stripTomlSection(existing, CODEX_MCP_HEADER).replace(/\n+$/, "");
-  const next = base.length > 0 ? `${base}\n\n${CODEX_MCP_BLOCK}` : CODEX_MCP_BLOCK;
+  const next = base.length > 0 ? `${base}\n\n${block}` : block;
   await Bun.write(path, next.endsWith("\n") ? next : `${next}\n`);
   return existed ? "updated" : "created";
 }

package/src/installer/hooks/opencode-plugin.ts

@@ -3,28 +3,12 @@
  * Installed to ~/.config/opencode/plugins/miru-search-guard.ts
  */
 
-const REDIRECT = "Use Miru MCP search (repo = project root) instead of grep/glob/bash exploration.";
+const REDIRECT =
+  "Use Miru MCP (repo = project root): `locate` for exact literals, `search` for meaning-based questions — not grep/glob/bash exploration.";
 
 const GREP_TOOLS = new Set(["grep", "glob", "codesearch", "codebase_search", "search"]);
 const SHELL_TOOLS = new Set(["bash", "shell", "sh"]);
 
-function isLiteral(pattern: string): boolean {
-  const trimmed = pattern.trim();
-  if (!trimmed) {
-    return false;
-  }
-  if (/^[`'"][^`'"]+[`'"]$/.test(trimmed)) {
-    return true;
-  }
-  if (/^[A-Z][A-Z0-9_]{2,}$/.test(trimmed)) {
-    return true;
-  }
-  if (/^[a-zA-Z_][a-zA-Z0-9_.]*$/.test(trimmed) && trimmed.length <= 48) {
-    return true;
-  }
-  return false;
-}
-
 function isExplorationShell(command: string): boolean {
   const cmd = command.trim();
   if (!cmd) {
@@ -43,9 +27,11 @@ function shouldBlock(tool: string, args: Record<string, unknown>): boolean {
   if (name.includes("miru")) {
     return false;
   }
+  if (name === "glob") {
+    return true;
+  }
   if (GREP_TOOLS.has(name)) {
-    const pattern = String(args.pattern ?? args.query ?? args.regex ?? args.needle ?? "");
-    return !isLiteral(pattern);
+    return true;
   }
   if (SHELL_TOOLS.has(name)) {
     const command = String(args.command ?? args.cmd ?? "");

package/src/installer/hooks/search-guard.ts

@@ -2,7 +2,7 @@ import { SEARCH_GUARD_EXPAND_HINT } from "../search-policy.ts";
 
 const REDIRECT_PREFIX =
   "Use Miru MCP instead of built-in search tools (pass project root as `repo`). " +
-  "Grep/Glob/Shell are only for exact literal confirmation or non-code tasks.";
+  "Prefer Miru `locate` for exact literals and `search` for meaning-based questions.";
 
 const MIRU_TOOL_RE = /miru/i;
 
@@ -121,6 +121,9 @@ export function searchGuardBlockReason(
   toolInput: Record<string, unknown>,
 ): string {
   const query = suggestedMiruQuery(toolName, toolInput);
+  if (GREP_TOOL_RE.test(toolName) && isLiteralGrepPattern(grepPatternFromInput(toolInput))) {
+    return `${REDIRECT_PREFIX} Try Miru \`locate\` with literal "${query.replace(/^['"`]|['"`]$/g, "")}". ${SEARCH_GUARD_EXPAND_HINT}`;
+  }
   return `${REDIRECT_PREFIX} Try Miru \`search\` with query "${query}". ${SEARCH_GUARD_EXPAND_HINT}`;
 }
 
@@ -166,10 +169,6 @@ export function evaluateSearchGuard(payload: HookPayload): GuardDecision {
   }
 
   if (GREP_TOOL_RE.test(toolName)) {
-    const pattern = grepPatternFromInput(toolInput);
-    if (isLiteralGrepPattern(pattern)) {
-      return { block: false, reason: "" };
-    }
     return { block: true, reason: searchGuardBlockReason(toolName, toolInput) };
   }
 

package/src/installer/installer.ts

@@ -1,6 +1,7 @@
 import { unlink } from "node:fs/promises";
 import { loadAgentTemplate } from "../agents.ts";
-import { brandTitle, dim, divider, green, hint, success, writeStdout } from "../cli-ui.ts";
+import { clearBenchmarkHistory } from "../benchmark/history.ts";
+import { brandTitle, dim, divider, green, hint, info, success, writeStdout } from "../cli-ui.ts";
 import { ensureCredentials } from "../setup.ts";
 import {
   AGENT_TARGETS,
@@ -10,6 +11,7 @@ import {
   type InstallMode,
   isAgentDetected,
 } from "./agents.ts";
+import { withPreservedBenchmarkFlag } from "./benchmark-mode.ts";
 import {
   mergeJsonMember,
   mergeTomlBlock,
@@ -17,6 +19,7 @@ import {
   removeMarked,
   removeTomlBlock,
   replaceOrAppendMarked,
+  stripJsonComments,
 } from "./config.ts";
 import { mergeHooks, removeHooks } from "./hooks/install.ts";
 import { promptConfirm, promptMultiSelect, requireInteractiveTerminal } from "./prompt.ts";
@@ -54,6 +57,33 @@ const ACTION_ICON: Partial<Record<InstallAction, string>> = {
   error: dim("✗"),
 };
 
+async function readExistingJsonMcpEntry(
+  path: string,
+  sectionKey: string,
+  memberKey: string,
+): Promise<Record<string, unknown> | null> {
+  if (!(await Bun.file(path).exists())) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(stripJsonComments(await Bun.file(path).text())) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return null;
+    }
+    const section = (parsed as Record<string, unknown>)[sectionKey];
+    if (!section || typeof section !== "object" || Array.isArray(section)) {
+      return null;
+    }
+    const entry = (section as Record<string, unknown>)[memberKey];
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      return null;
+    }
+    return entry as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
 async function applyMcp(agent: AgentTarget, mode: InstallMode): Promise<WriteResult | null> {
   const mcp = agent.mcp;
   if (!mcp) {
@@ -66,10 +96,14 @@ async function applyMcp(agent: AgentTarget, mode: InstallMode): Promise<WriteRes
     return { path: mcp.path, action };
   }
 
-  const action =
-    mode === "install"
-      ? await mergeJsonMember(mcp.path, mcp.key, mcp.memberKey, mcp.entry)
-      : await removeJsonMember(mcp.path, mcp.key, mcp.memberKey);
+  if (mode !== "install") {
+    const action = await removeJsonMember(mcp.path, mcp.key, mcp.memberKey);
+    return { path: mcp.path, action };
+  }
+
+  const existing = await readExistingJsonMcpEntry(mcp.path, mcp.key, mcp.memberKey);
+  const entry = withPreservedBenchmarkFlag(mcp.entry, existing);
+  const action = await mergeJsonMember(mcp.path, mcp.key, mcp.memberKey, entry);
   return { path: mcp.path, action };
 }
 
@@ -183,7 +217,7 @@ const INTEGRATIONS: Integration[] = [
     label: "Search hooks",
     description: "blocks built-in search; routes to Miru MCP",
     experimental: true,
-    defaultChecked: true,
+    defaultChecked: false,
     planPath: (agent) => agent.hooksPath,
     apply: applyHooks,
   },
@@ -235,6 +269,18 @@ async function apply(
   writeStdout("");
 }
 
+/** Local Miru state cleaned up during uninstall (global, not per-agent). */
+export async function removeUninstallLocalData(): Promise<{
+  benchmarkHistoryCleared: boolean;
+  benchmarkHistoryPath: string;
+}> {
+  const result = await clearBenchmarkHistory();
+  return {
+    benchmarkHistoryCleared: result.cleared,
+    benchmarkHistoryPath: result.path,
+  };
+}
+
 export async function runInstaller(mode: InstallMode): Promise<void> {
   const install = mode === "install";
   requireInteractiveTerminal(`miru ${mode}`);
@@ -297,6 +343,13 @@ export async function runInstaller(mode: InstallMode): Promise<void> {
 
   await apply(mode, chosenAgents, chosenIntegrations);
 
+  if (!install) {
+    const local = await removeUninstallLocalData();
+    if (local.benchmarkHistoryCleared) {
+      info(`Removed benchmark report ${local.benchmarkHistoryPath}`);
+    }
+  }
+
   success(install ? "Done. Restart agents to apply changes." : "Done. Configuration removed.");
   writeStdout("");
 }

package/src/installer/search-policy.ts

@@ -18,7 +18,7 @@ export function buildSearchPolicyTable(native: NativeToolNames): string {
 | Same file, more context | Miru MCP \`expand\` on \`truncated: true\` | Re-search, ${native.read} whole file |
 | Similar code elsewhere | Miru MCP \`find_related\` | ${native.grep} chains |
 | Search docs or config | Miru \`search\` | ${native.grep} README paths |
-| Exact literal string in a file? | ${native.grep} | Miru |
+| Exact literal string in a file? | Miru MCP \`locate\` | ${native.grep}, Miru \`search\` |
 | Edit a known file:line | ${native.read} (after Miru found it) | ${native.read}-before-search |`;
 }
 
@@ -29,6 +29,7 @@ ${SNIPPET_GUIDANCE}
 
 Use Miru MCP tools:
 - \`search\` — one call per question; pass project root as \`repo\`
+- \`locate\` — exact substring (env var, symbol, error code); prefer \`mode=count\` or \`locations\`
 - \`expand\` — more context in the same file when \`truncated: true\` (\`file_path\` + \`anchor_line\`)
 - \`find_related\` — similar code in other files (hits may also be snippets; use \`expand\` if truncated)
 
@@ -38,7 +39,6 @@ Stop rules:
 - ${native.read} is for editing a path Miru already gave you, not for exploration
 
 Native tools are allowed ONLY when:
-- confirming an exact literal string (env var name, error code, quoted text)
 - reading a file you already located via Miru, to edit it
 - searching outside the indexed repo
 
@@ -49,15 +49,17 @@ export function buildMcpWorkflow(native: NativeToolNames): string {
   return `### MCP workflow
 
 1. Call \`search\` with \`repo\` set to the project root (local path or https:// git URL).
-2. If a hit has \`truncated: true\`, call \`expand\` with \`file_path\` and \`anchor_line\`.
-3. Use \`find_related\` to trace similar code in other files — not for more context in the same file.
-4. ${native.read} via \`absolute_path\` only when editing or when \`expand\` still lacks context.`;
+2. For exact literals, call \`locate\` (prefer \`mode=count\` or \`locations\`).
+3. If a hit has \`truncated: true\`, call \`expand\` with \`file_path\` and \`anchor_line\`.
+4. Use \`find_related\` to trace similar code in other files — not for more context in the same file.
+5. ${native.read} via \`absolute_path\` only when editing or when \`expand\` still lacks context.`;
 }
 
 const CLI_FALLBACK = `### CLI fallback (no MCP in this session)
 
 \`\`\`bash
 miru search "authentication flow" .
+miru locate DATABASE_URL . --mode locations
 miru expand src/auth.ts 42 .
 miru find-related src/auth.ts 42 .
 \`\`\`
@@ -65,7 +67,7 @@ miru find-related src/auth.ts 42 .
 If \`miru\` is not on \`$PATH\`, use \`bunx @takara-ai/miru-code\`.`;
 
 export function buildSubagentBody(native: NativeToolNames): string {
-  return `When Miru MCP is available, use MCP \`search\`, \`expand\`, and \`find_related\` — not ${native.explorationDenied} for exploration.
+  return `When Miru MCP is available, use MCP \`search\`, \`locate\`, \`expand\`, and \`find_related\` — not ${native.explorationDenied} for exploration.
 
 ${buildSearchPolicyBody(native)}
 
@@ -108,7 +110,7 @@ alwaysApply: true
 
 ${SEARCH_POLICY_BODY}
 
-When Miru MCP is connected, call \`search\` once per question. On \`truncated: true\`, call \`expand\` with \`file_path\` and \`anchor_line\`. Never use Cursor SemanticSearch or Grep for codebase questions unless confirming an exact literal.`;
+When Miru MCP is connected, call \`search\` once per question. On \`truncated: true\`, call \`expand\` with \`file_path\` and \`anchor_line\`. Use \`locate\` for exact literals — not Grep. Never use Cursor SemanticSearch for codebase questions.`;
 
 export const SUBAGENT_BODY = buildSubagentBody(DEFAULT_NATIVE_TOOLS);
 
@@ -119,15 +121,28 @@ export const MCP_SERVER_INSTRUCTIONS =
   "Workflow: (1) `search` once per question — do NOT re-search with paraphrases. " +
   "(2) On `truncated: true`, call `expand` with `file_path` and `anchor_line` — do NOT read the whole file. " +
   "(3) `find_related` traces similar code in other files, not more context in the same file. " +
+  "(4) `locate` finds exact substrings (env vars, symbols, error codes) — prefer over Grep; use mode=count or locations when possible. " +
   "Always pass the project root as `repo`. Local repos return `absolute_path` on each hit — use Read only to edit. " +
-  "Native grep is only for confirming a known exact literal (env var name, quoted string) or files outside the indexed repo.";
+  "Native Grep/Glob only outside the indexed repo or for non-code tasks.";
+
+export const MCP_BENCHMARK_SERVER_INSTRUCTIONS =
+  `${MCP_SERVER_INSTRUCTIONS} ` +
+  "BENCHMARK MODE: each `search` and `locate` includes compact `benchmark` {save_pct,miru_tok,grep_tok,saved_tok,rank1}. " +
+  "Call `read_benchmark` for cumulative totals across both. Do not narrate benchmark stats unless the user asks. " +
+  "To leave benchmark mode, tell the user to run `miru benchmark off` and restart the agent.";
 
 export const MCP_SEARCH_TOOL_DESCRIPTION =
   "Your default search for all code search queries in this indexed repo — the best, fastest, and cheapest way to find code; better than any other tool. " +
   "Returns compact snippets (~±15 lines). One call per question is usually enough. " +
-  "Built-in grep is only when you already have an exact literal string to confirm. " +
+  "For exact literals (env vars, symbols, error codes), use `locate` instead. " +
   "When a hit has `truncated: true`, call `expand` with `file_path` and `anchor_line` — not re-search or Read.";
 
+export const MCP_LOCATE_TOOL_DESCRIPTION =
+  "Exact substring locator over the Miru index. Use for known literals (env vars, symbols, error codes, quoted text) — not meaning-based questions (`search`). " +
+  "Returns ALL matches by default as compact {n,files,hits} — do NOT fall back to Grep/rg when n is large. " +
+  "Prefer mode=locations (or count for totals only); use lines when you need matching line text. " +
+  "Optional `limit` only if you intentionally want a sample. In benchmark mode, includes compact token savings vs agent Grep.";
+
 export const MCP_EXPAND_TOOL_DESCRIPTION =
   "More context in the SAME file as a search hit. Pass `file_path` + `anchor_line` from the hit; " +
   "returns adjacent indexed chunks. Use when `truncated: true` — NOT for similar code in other files (use find_related). " +
@@ -137,5 +152,9 @@ export const MCP_FIND_RELATED_TOOL_DESCRIPTION =
   "Find code similar to a file:line in OTHER parts of the codebase. Results may be snippets; use `expand` when `truncated: true`. " +
   "For more context in the same file, use `expand` instead.";
 
+export const MCP_READ_BENCHMARK_TOOL_DESCRIPTION =
+  "Cumulative Miru vs Grep token savings from saved `search` and `locate` calls. Returns compact totals {n,saved,save_pct,miru,grep}. " +
+  "Do not call unless the user asks about savings.";
+
 export const SEARCH_GUARD_EXPAND_HINT =
   "If a hit has `truncated: true`, call `expand` with `file_path` and `anchor_line` — do not re-search or read the whole file.";