opencode-codebase-index 0.15.0 → 0.16.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "codebase-index",
       "description": "Semantic code search and codebase graph tools for Claude Code",
       "source": "./",
-      "version": "0.13.2"
+      "version": "0.16.0"
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codebase-index",
-  "version": "0.13.2",
+  "version": "0.16.0",
   "description": "Semantic code search and codebase graph tools for Claude Code",
   "displayName": "Codebase Index",
   "author": {

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codebase-index",
-  "version": "0.13.2",
+  "version": "0.16.0",
   "description": "Semantic code search and codebase graph tools for Codex",
   "author": {
     "name": "Kenneth",
@@ -37,7 +37,7 @@
     "termsOfServiceURL": "https://github.com/Helweg/opencode-codebase-index/blob/main/LICENSE",
     "brandColor": "#3B82F6",
     "defaultPrompt": [
-      "Use codebase-search skills and MCP tools to find local implementation context before edits."
+      "For repository questions, use index_status when readiness is unknown, then call codebase_context before shell search or broad file reads."
     ]
   }
 }

package/README.md

@@ -115,6 +115,8 @@ pi install ./path/to/opencode-codebase-index
 
 Pi uses the neutral `.codebase-index/` project storage and falls back to existing OpenCode state when present.
 
+The Pi extension injects lightweight routing guidance and exposes `codebase_context` as its preferred first repository tool. It routes conceptual discovery, known-symbol definitions, and dependency paths before broad shell search or file reads.
+
 ## 🧩 Codex Plugin
 Install once for Codex threads and get skill guidance plus MCP tools in one manifest.
 
@@ -144,6 +146,8 @@ npm run dev:link-mcp
 
 After that, the normal `.mcp.json` command also works when Codex starts the plugin from this repository.
 
+The native Codex plugin is important: its session hook and `codebase-search` skill tell Codex to use `index_status` and `codebase_context` before shell exploration. A bare MCP configuration does not provide the same selection reliability. Current Codex `exec` releases may cancel MCP calls in non-interactive mode while waiting for an app-tool approval; use an interactive Codex thread to approve the tool call. This is a Codex client limitation, not an MCP server failure.
+
 ## 🧩 Claude Code Plugin
 Install once for Claude Code sessions and get skill guidance plus MCP tools in one manifest.
 
@@ -225,7 +229,19 @@ Use the same semantic search from any MCP-compatible client. Index once, search
    npx -y --package opencode-codebase-index opencode-codebase-index-mcp
    ```
 
-The MCP server exposes all 12 tools (`codebase_search`, `codebase_peek`, `find_similar`, `implementation_lookup`, `call_graph`, `call_graph_path`, `pr_impact`, `index_codebase`, `index_status`, `index_health_check`, `index_metrics`, `index_logs`) and 5 prompts (`search`, `find`, `definition`, `index`, `status`).
+The MCP server exposes all 13 tools (`codebase_context`, `codebase_search`, `codebase_peek`, `find_similar`, `implementation_lookup`, `call_graph`, `call_graph_path`, `pr_impact`, `index_codebase`, `index_status`, `index_health_check`, `index_metrics`, `index_logs`) and 5 prompts (`search`, `find`, `definition`, `index`, `status`).
+
+The tools carry self-routing descriptions so clients can choose the lightweight path without relying on separate documentation:
+
+1. `codebase_context` as the preferred single entry point for repository questions
+2. `index_status` when index readiness is unknown
+3. `codebase_peek` for direct low-token conceptual discovery
+4. `implementation_lookup` for direct known-symbol definition lookup
+5. `codebase_search` only when full semantic content is needed
+6. `grep` for exact identifiers or exhaustive matches
+7. `call_graph` / `call_graph_path` for direct graph queries
+
+The server also publishes this workflow through the standard MCP initialization `instructions` field. Client behavior remains client-controlled: an MCP server can describe and recommend its tools, but cannot force an agent host to read server instructions or invoke a tool before filesystem search. Clients that ignore MCP instructions still receive the routing guidance in each tool description.
 
 The MCP dependencies (`@modelcontextprotocol/sdk`, `zod`) ship with the package so published `npx --package opencode-codebase-index` launches work in clean MCP clients.
 
@@ -254,9 +270,9 @@ src/api/checkout.ts:89      (Route handler for /pay)
 
 | Scenario | Tool | Why |
 |----------|------|-----|
-| Don't know the function name | `codebase_search` | Semantic search finds by meaning |
-| Exploring unfamiliar codebase | `codebase_search` | Discovers related code across files |
-| Just need to find locations | `codebase_peek` | Returns metadata only, saves ~90% tokens |
+| Don't know the function name | `codebase_context` (MCP) | Routes conceptual questions to low-token discovery first |
+| Exploring unfamiliar codebase | `codebase_context` (MCP) | Discovers related code and then guides to definitions or graph queries |
+| Just need to find locations | `codebase_peek` (or `codebase_context`) | Returns metadata only, saves ~90% tokens |
 | Need the authoritative definition site | `implementation_lookup` | Prioritizes real implementation definitions over docs/tests |
 | Understand code flow | `call_graph` | Find callers/callees of any function |
 | Trace dependency paths | `call_graph_path` | Find the shortest known call path between two symbols |
@@ -264,7 +280,7 @@ src/api/checkout.ts:89      (Route handler for /pay)
 | Need ALL matches | `grep` | Semantic returns top N only |
 | Mixed discovery + precision | `/find` (hybrid) | Best of both worlds |
 
-**Rule of thumb**: `codebase_peek` to find locations → `Read` to examine → `grep` for precision. For symbol-definition questions, use `implementation_lookup` first.
+**Rule of thumb**: `codebase_context` to route discovery first. Then `Read` to examine exact content and `grep` for precision. For symbol-definition questions, use `implementation_lookup` first.
 
 ## 🧭 OMO CodeGraph Compatibility
 
@@ -281,7 +297,7 @@ Recent OMO releases include a built-in CodeGraph MCP and make it part of the def
 
 Recommended OMO workflow:
 
-1. Start broad with `codebase_peek` when the prompt is conceptual, such as "where is auth enforced?" or "payment validation flow".
+1. Start broad with `codebase_context` when the prompt is conceptual, such as "where is auth enforced?" or "payment validation flow".
 2. Use `implementation_lookup` once you have a symbol or concept that should resolve to a definition.
 3. Use OMO CodeGraph, `call_graph`, or `call_graph_path` after locating the relevant symbol to check blast radius and dependency flow.
 4. Keep `grep` for exact identifiers and exhaustive text matches.
@@ -424,9 +440,18 @@ The following files/folders are excluded from indexing by default:
 
 The plugin exposes these tools to the OpenCode agent:
 
+`codebase_context` is MCP-server-only.
+
+### `codebase_context`
+*MCP-only entrypoint for combined routing*
+**Preferred first tool for repository questions.** Routes to the lowest-token indexed operation that matches the query: conceptual discovery, definition lookup, callers/callees, or symbol-to-symbol paths.
+- **Use for**: New questions about behavior, locating symbols, or tracing direct call relationships.
+- **Example**: `"Where is the payment validation logic?"`
+- **Workflow**: If the query is conceptual, it may return locations first. For exact behavior text, follow with `codebase_search`.
+
 ### `codebase_search`
-**The primary tool.** Searches code by describing behavior.
-- **Use for**: Discovery, understanding flows, finding logic when you don't know the names.
+**Behavioral semantic retrieval with full content.** Searches code by describing behavior.
+- **Use for**: Discovery when you already want full matching snippets and are ready to inspect implementation text.
 - **Example**: `"find the middleware that sanitizes input"`
 - **Ranking path**: hybrid retrieval → fusion (`search.fusionStrategy`) → deterministic rerank (`search.rerankTopN`) → filters
 - **Blame filters**: when `indexing.gitBlame.enabled` is `true`, filter with `blameAuthor`, `blameSha`, or `blameSince`.

package/dist/cli.cjs

@@ -8998,10 +8998,19 @@ var Indexer = class {
     });
     const embeddingStartTime = import_perf_hooks.performance.now();
     const embeddingQuery = stripFilePathHint(query);
-    const embedding = await this.getQueryEmbedding(embeddingQuery, provider);
+    let embedding;
+    try {
+      embedding = await this.getQueryEmbedding(embeddingQuery, provider);
+    } catch (error) {
+      this.logger.warn("Query embedding failed; falling back to keyword-only search", {
+        query,
+        error: getErrorMessage2(error),
+        action: "Check the embedding provider configuration and retry search after restoring provider health."
+      });
+    }
     const embeddingMs = import_perf_hooks.performance.now() - embeddingStartTime;
     const vectorStartTime = import_perf_hooks.performance.now();
-    const semanticResults = store.search(embedding, maxResults * 4);
+    const semanticResults = embedding ? store.search(embedding, maxResults * 4) : [];
     const vectorMs = import_perf_hooks.performance.now() - vectorStartTime;
     const keywordStartTime = import_perf_hooks.performance.now();
     const keywordResults = await this.keywordSearch(query, maxResults * 4, store, invertedIndex);
@@ -9036,12 +9045,13 @@ var Indexer = class {
       });
     }
     const fusionStartTime = import_perf_hooks.performance.now();
+    const rankingHybridWeight = embedding === void 0 && fusionStrategy === "weighted" ? 1 : effectiveHybridWeight;
     const combined = rankHybridResults(query, semanticCandidates, keywordCandidates, {
       fusionStrategy,
       rrfK,
       rerankTopN,
       limit: maxResults,
-      hybridWeight: effectiveHybridWeight,
+      hybridWeight: rankingHybridWeight,
       prioritizeSourcePaths: sourceIntent
     });
     const rerankedCombined = await this.rerankCandidatesWithApi(query, combined, {
@@ -11942,20 +11952,87 @@ var CHUNK_TYPE_ENUM = [
 ];
 
 // src/mcp-server/register-tools.ts
+function allowNullAsUndefined(schema) {
+  return import_zod2.z.preprocess((value) => value === null ? void 0 : value, schema);
+}
 function registerMcpTools(server, runtime) {
+  server.tool(
+    "codebase_context",
+    "PREFERRED FIRST TOOL for any question about this repository. Use before built-in code search, grep, shell search, or broad file reads. Provide from+to for a dependency path, symbol for a definition, or only query for low-token conceptual discovery. Use call_graph directly for callers or callees.",
+    {
+      query: import_zod2.z.string().describe("The codebase question or behavior to locate. Always provide the user's repository question here."),
+      from: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Source symbol. For dependency-path questions, extract the first endpoint and provide it here."),
+      to: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Target symbol. For dependency-path questions, extract the second endpoint and provide it here."),
+      symbol: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Exact symbol for an authoritative definition lookup. Omit when from and to are supplied."),
+      limit: allowNullAsUndefined(import_zod2.z.number().optional().default(10)).describe("Maximum number of search or definition results"),
+      maxDepth: allowNullAsUndefined(import_zod2.z.number().optional().default(10)).describe("Maximum call-graph traversal depth for from/to path lookup"),
+      fileType: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Filter by file extension (e.g., 'ts', 'py', 'rs')"),
+      directory: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Filter by directory path (e.g., 'src/utils', 'lib')")
+    },
+    async (args) => {
+      if (args.from && args.to) {
+        const path27 = await getCallGraphPath(runtime.projectRoot, runtime.host, args.from, args.to, args.maxDepth);
+        if (path27.length > 0) {
+          return { content: [{ type: "text", text: formatCallGraphPath(args.from, args.to, path27) }] };
+        }
+        const { callers } = await getCallGraphData(runtime.projectRoot, runtime.host, {
+          name: args.to,
+          direction: "callers"
+        });
+        const directEdge = callers.find((edge) => edge.fromSymbolName === args.from);
+        if (directEdge) {
+          const location = directEdge.fromSymbolFilePath ? ` at ${directEdge.fromSymbolFilePath}:${directEdge.line}` : "";
+          return {
+            content: [{
+              type: "text",
+              text: `Direct path: ${args.from} --${directEdge.callType}--> ${args.to}${location} (edge is ${directEdge.isResolved ? "resolved" : "unresolved"}).`
+            }]
+          };
+        }
+        return { content: [{ type: "text", text: formatCallGraphPath(args.from, args.to, path27) }] };
+      }
+      if (args.symbol) {
+        const results2 = await implementationLookup(runtime.projectRoot, runtime.host, args.symbol, {
+          limit: args.limit ?? 10,
+          fileType: args.fileType,
+          directory: args.directory
+        });
+        return { content: [{ type: "text", text: formatDefinitionLookup(results2, args.symbol) }] };
+      }
+      const results = await searchCodebase(runtime.projectRoot, runtime.host, args.query, {
+        limit: args.limit ?? 10,
+        fileType: args.fileType,
+        directory: args.directory,
+        metadataOnly: true
+      });
+      if (results.length === 0) {
+        return { content: [{ type: "text", text: "No matching code found. Try a different query or run index_codebase first." }] };
+      }
+      return {
+        content: [{
+          type: "text",
+          text: `Found ${results.length} locations for "${args.query}":
+
+${formatCodebasePeek(results)}
+
+Use implementation_lookup for an authoritative definition, or call call_graph/call_graph_path once you have a symbol.`
+        }]
+      };
+    }
+  );
   server.tool(
     "codebase_search",
-    "Search codebase by MEANING, not keywords. Returns full code content. For just finding WHERE code is (saves ~90% tokens), use codebase_peek instead.",
+    "FULL-CONTENT semantic retrieval. Use after codebase_peek when you need implementation text, not as the default first step. For exact identifiers or exhaustive matches use grep instead.",
     {
       query: import_zod2.z.string().describe("Natural language description of what code you're looking for. Describe behavior, not syntax."),
-      limit: import_zod2.z.number().optional().default(5).describe("Maximum number of results to return"),
-      fileType: import_zod2.z.string().optional().describe("Filter by file extension (e.g., 'ts', 'py', 'rs')"),
-      directory: import_zod2.z.string().optional().describe("Filter by directory path (e.g., 'src/utils', 'lib')"),
-      chunkType: import_zod2.z.enum(CHUNK_TYPE_ENUM).optional().describe("Filter by code chunk type"),
-      contextLines: import_zod2.z.number().optional().describe("Number of extra lines to include before/after each match (default: 0)"),
-      blameAuthor: import_zod2.z.string().optional().describe("Filter by git blame author name or email"),
-      blameSha: import_zod2.z.string().optional().describe("Filter by git blame commit SHA or prefix"),
-      blameSince: import_zod2.z.string().optional().describe("Filter to chunks last changed on or after this date")
+      limit: allowNullAsUndefined(import_zod2.z.number().optional().default(5)).describe("Maximum number of results to return"),
+      fileType: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Filter by file extension (e.g., 'ts', 'py', 'rs')"),
+      directory: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Filter by directory path (e.g., 'src/utils', 'lib')"),
+      chunkType: allowNullAsUndefined(import_zod2.z.enum(CHUNK_TYPE_ENUM).optional()).describe("Filter by code chunk type"),
+      contextLines: allowNullAsUndefined(import_zod2.z.number().optional()).describe("Number of extra lines to include before/after each match (default: 0)"),
+      blameAuthor: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Filter by git blame author name or email"),
+      blameSha: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Filter by git blame commit SHA or prefix"),
+      blameSince: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Filter to chunks last changed on or after this date")
     },
     async (args) => {
       const results = await searchCodebase(runtime.projectRoot, runtime.host, args.query, {
@@ -11978,16 +12055,16 @@ ${formatSearchResults(results, "score")}` }] };
   );
   server.tool(
     "codebase_peek",
-    "Quick lookup of code locations by meaning. Returns only metadata (file, line, name, type) WITHOUT code content. Saves ~90% tokens vs codebase_search.",
+    "DIRECT LOW-TOKEN semantic location lookup for unfamiliar-code discovery. Prefer codebase_context when the request may involve definitions or graph navigation; use this specialized tool when you only need conceptual locations.",
     {
       query: import_zod2.z.string().describe("Natural language description of what code you're looking for."),
-      limit: import_zod2.z.number().optional().default(10).describe("Maximum number of results to return"),
-      fileType: import_zod2.z.string().optional().describe("Filter by file extension (e.g., 'ts', 'py', 'rs')"),
-      directory: import_zod2.z.string().optional().describe("Filter by directory path (e.g., 'src/utils', 'lib')"),
-      chunkType: import_zod2.z.enum(CHUNK_TYPE_ENUM).optional().describe("Filter by code chunk type"),
-      blameAuthor: import_zod2.z.string().optional().describe("Filter by git blame author name or email"),
-      blameSha: import_zod2.z.string().optional().describe("Filter by git blame commit SHA or prefix"),
-      blameSince: import_zod2.z.string().optional().describe("Filter to chunks last changed on or after this date")
+      limit: allowNullAsUndefined(import_zod2.z.number().optional().default(10)).describe("Maximum number of results to return"),
+      fileType: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Filter by file extension (e.g., 'ts', 'py', 'rs')"),
+      directory: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Filter by directory path (e.g., 'src/utils', 'lib')"),
+      chunkType: allowNullAsUndefined(import_zod2.z.enum(CHUNK_TYPE_ENUM).optional()).describe("Filter by code chunk type"),
+      blameAuthor: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Filter by git blame author name or email"),
+      blameSha: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Filter by git blame commit SHA or prefix"),
+      blameSince: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Filter to chunks last changed on or after this date")
     },
     async (args) => {
       const results = await searchCodebase(runtime.projectRoot, runtime.host, args.query, {
@@ -12012,11 +12089,11 @@ Use Read tool to examine specific files.` }] };
   );
   server.tool(
     "index_codebase",
-    "Index the codebase for semantic search. Creates vector embeddings of code chunks. Incremental - only re-indexes changed files. Run before first codebase_search.",
+    "Create or refresh the semantic index. Call index_status first when readiness is unknown, then use this tool only if the index is missing, stale, or incompatible. Incremental by default; force=true rebuilds everything.",
     {
-      force: import_zod2.z.boolean().optional().default(false).describe("Force reindex even if already indexed"),
-      estimateOnly: import_zod2.z.boolean().optional().default(false).describe("Only show cost estimate without indexing"),
-      verbose: import_zod2.z.boolean().optional().default(false).describe("Show detailed info about skipped files and parsing failures")
+      force: allowNullAsUndefined(import_zod2.z.boolean().optional().default(false)).describe("Force reindex even if already indexed"),
+      estimateOnly: allowNullAsUndefined(import_zod2.z.boolean().optional().default(false)).describe("Only show cost estimate without indexing"),
+      verbose: allowNullAsUndefined(import_zod2.z.boolean().optional().default(false)).describe("Show detailed info about skipped files and parsing failures")
     },
     async (args) => {
       const result = await runIndexCodebase(runtime.projectRoot, runtime.host, args);
@@ -12031,7 +12108,7 @@ Use Read tool to examine specific files.` }] };
   );
   server.tool(
     "index_status",
-    "Check the status of the codebase index. Shows whether the codebase is indexed, how many chunks are stored, and the embedding provider being used.",
+    "START HERE once per repository task when index readiness or freshness is unknown. Reports whether semantic retrieval is ready, chunk counts, compatibility, and the embedding provider. If ready, continue with codebase_peek or implementation_lookup; otherwise run index_codebase.",
     {},
     async () => {
       const status = await getIndexStatus(runtime.projectRoot, runtime.host);
@@ -12063,9 +12140,13 @@ Use Read tool to examine specific files.` }] };
     "index_logs",
     "Get recent debug logs from the codebase indexer. Requires debug.enabled=true in config.",
     {
-      limit: import_zod2.z.number().optional().default(20).describe("Maximum number of log entries to return"),
-      category: import_zod2.z.enum(["search", "embedding", "cache", "gc", "branch", "general"]).optional().describe("Filter by log category"),
-      level: import_zod2.z.enum(["error", "warn", "info", "debug"]).optional().describe("Filter by minimum log level")
+      limit: allowNullAsUndefined(import_zod2.z.number().optional().default(20)).describe("Maximum number of log entries to return"),
+      category: allowNullAsUndefined(
+        import_zod2.z.enum(["search", "embedding", "cache", "gc", "branch", "general"]).optional()
+      ).describe("Filter by log category"),
+      level: allowNullAsUndefined(
+        import_zod2.z.enum(["error", "warn", "info", "debug"]).optional()
+      ).describe("Filter by minimum log level")
     },
     async (args) => {
       const result = await getIndexLogs(runtime.projectRoot, runtime.host, args);
@@ -12074,14 +12155,14 @@ Use Read tool to examine specific files.` }] };
   );
   server.tool(
     "find_similar",
-    "Find code similar to a given snippet. Use for duplicate detection, pattern discovery, or refactoring prep.",
+    "Use when you already have a code snippet and need analogous implementations, duplicates, patterns, or refactoring candidates. For a natural-language concept without example code, start with codebase_peek instead.",
     {
       code: import_zod2.z.string().describe("The code snippet to find similar code for"),
-      limit: import_zod2.z.number().optional().default(10).describe("Maximum number of results to return"),
-      fileType: import_zod2.z.string().optional().describe("Filter by file extension (e.g., 'ts', 'py', 'rs')"),
-      directory: import_zod2.z.string().optional().describe("Filter by directory path (e.g., 'src/utils', 'lib')"),
-      chunkType: import_zod2.z.enum(CHUNK_TYPE_ENUM).optional().describe("Filter by code chunk type"),
-      excludeFile: import_zod2.z.string().optional().describe("Exclude results from this file path")
+      limit: allowNullAsUndefined(import_zod2.z.number().optional().default(10)).describe("Maximum number of results to return"),
+      fileType: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Filter by file extension (e.g., 'ts', 'py', 'rs')"),
+      directory: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Filter by directory path (e.g., 'src/utils', 'lib')"),
+      chunkType: allowNullAsUndefined(import_zod2.z.enum(CHUNK_TYPE_ENUM).optional()).describe("Filter by code chunk type"),
+      excludeFile: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Exclude results from this file path")
     },
     async (args) => {
       const results = await findSimilarCode(runtime.projectRoot, runtime.host, args.code, {
@@ -12101,12 +12182,12 @@ ${formatSearchResults(results)}` }] };
   );
   server.tool(
     "implementation_lookup",
-    "Jump to symbol definition. Find WHERE something is defined. Returns the authoritative source location(s). Prefers real implementation files over tests, docs, examples, and fixtures.",
+    "FIRST TOOL only for known-symbol definition questions. Returns authoritative source locations and prefers implementations over tests, docs, examples, and fixtures. Do not use for callers, callees, dependency paths, or code flow; use codebase_context with direction or from/to for those questions.",
     {
       query: import_zod2.z.string().describe("Symbol name or natural language description (e.g., 'validateToken', 'where is the payment handler defined')"),
-      limit: import_zod2.z.number().optional().default(5).describe("Maximum number of results"),
-      fileType: import_zod2.z.string().optional().describe("Filter by file extension (e.g., 'ts', 'py')"),
-      directory: import_zod2.z.string().optional().describe("Filter by directory path (e.g., 'src/utils')")
+      limit: allowNullAsUndefined(import_zod2.z.number().optional().default(5)).describe("Maximum number of results"),
+      fileType: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Filter by file extension (e.g., 'ts', 'py')"),
+      directory: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Filter by directory path (e.g., 'src/utils')")
     },
     async (args) => {
       const results = await implementationLookup(runtime.projectRoot, runtime.host, args.query, {
@@ -12119,12 +12200,16 @@ ${formatSearchResults(results)}` }] };
   );
   server.tool(
     "call_graph",
-    "Query the call graph to find callers or callees of a function/method. Use to understand code flow and dependencies. Supports relationship types: Call, MethodCall, Constructor, Import, Inherits, Implements.",
+    "Use after identifying a symbol to find its direct callers or callees and understand code flow. Use implementation_lookup first if the symbol or definition is still ambiguous. Supports relationship types: Call, MethodCall, Constructor, Import, Inherits, Implements.",
     {
       name: import_zod2.z.string().describe("Function or method name to query"),
-      direction: import_zod2.z.enum(["callers", "callees"]).default("callers").describe("Direction: 'callers' finds who calls this function, 'callees' finds what this function calls"),
-      symbolId: import_zod2.z.string().optional().describe("Symbol ID (required for 'callees' direction)"),
-      relationshipType: import_zod2.z.enum(["Call", "MethodCall", "Constructor", "Import", "Inherits", "Implements"]).optional().describe("Filter by relationship type. Omit to show all.")
+      direction: allowNullAsUndefined(
+        import_zod2.z.enum(["callers", "callees"]).default("callers")
+      ).describe("Direction: 'callers' finds who calls this function, 'callees' finds what this function calls"),
+      symbolId: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Symbol ID (required for 'callees' direction)"),
+      relationshipType: allowNullAsUndefined(
+        import_zod2.z.enum(["Call", "MethodCall", "Constructor", "Import", "Inherits", "Implements"]).optional()
+      ).describe("Filter by relationship type. Omit to show all.")
     },
     async (args) => {
       if (args.direction === "callees") {
@@ -12140,11 +12225,11 @@ ${formatSearchResults(results)}` }] };
   );
   server.tool(
     "call_graph_path",
-    "Find the shortest connection path between two symbols in the call graph. Returns the chain of calls connecting them.",
+    "Use after identifying both endpoint symbols to find the shortest known call path between them. Use codebase_peek or implementation_lookup first when either endpoint is unknown.",
     {
       from: import_zod2.z.string().describe("Source function/method name (starting point)"),
       to: import_zod2.z.string().describe("Target function/method name (destination)"),
-      maxDepth: import_zod2.z.number().optional().default(10).describe("Maximum traversal depth (default: 10)")
+      maxDepth: allowNullAsUndefined(import_zod2.z.number().optional().default(10)).describe("Maximum traversal depth (default: 10)")
     },
     async (args) => {
       const path27 = await getCallGraphPath(runtime.projectRoot, runtime.host, args.from, args.to, args.maxDepth);
@@ -12153,14 +12238,16 @@ ${formatSearchResults(results)}` }] };
   );
   server.tool(
     "pr_impact",
-    "Analyze the impact of a pull request or branch by examining changed files, affected symbols, transitive callers, communities touched, hub nodes, and risk level. Use to understand blast radius before merging.",
+    "FIRST TOOL for pull-request or branch blast-radius questions. Analyzes changed files, affected symbols, transitive dependencies, communities, hub nodes, conflicts, and risk before merging.",
     {
-      pr: import_zod2.z.number().optional().describe("Pull request number to analyze"),
-      branch: import_zod2.z.string().optional().describe("Branch name to analyze (defaults to current branch)"),
-      maxDepth: import_zod2.z.number().optional().default(5).describe("Maximum traversal depth for transitive callers (default: 5)"),
-      hubThreshold: import_zod2.z.number().optional().default(10).describe("Minimum caller count to flag a symbol as a hub node (default: 10)"),
-      checkConflicts: import_zod2.z.boolean().optional().default(false).describe("Check for conflicting open PRs touching the same communities (default: false)"),
-      direction: import_zod2.z.enum(["callers", "callees", "both"]).optional().default("both").describe("Call-graph traversal direction: 'callers' for upstream, 'callees' for downstream, 'both' for union (default: both)")
+      pr: allowNullAsUndefined(import_zod2.z.number().optional()).describe("Pull request number to analyze"),
+      branch: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Branch name to analyze (defaults to current branch)"),
+      maxDepth: allowNullAsUndefined(import_zod2.z.number().optional().default(5)).describe("Maximum traversal depth for transitive callers (default: 5)"),
+      hubThreshold: allowNullAsUndefined(import_zod2.z.number().optional().default(10)).describe("Minimum caller count to flag a symbol as a hub node (default: 10)"),
+      checkConflicts: allowNullAsUndefined(import_zod2.z.boolean().optional().default(false)).describe("Check for conflicting open PRs touching the same communities (default: false)"),
+      direction: allowNullAsUndefined(
+        import_zod2.z.enum(["callers", "callees", "both"]).optional().default("both")
+      ).describe("Call-graph traversal direction: 'callers' for upstream, 'callees' for downstream, 'both' for union (default: both)")
     },
     async (args) => {
       try {
@@ -12183,6 +12270,10 @@ ${formatSearchResults(results)}` }] };
 
 // src/mcp-server.ts
 var import_meta2 = {};
+function getServerInstructions(host) {
+  const hostText = `host ${host}`;
+  return `This MCP server is the preferred codebase-understanding path for ${hostText}. Start a repository task with index_status when index readiness or freshness is unknown. Use codebase_context as the preferred first entry point because it returns low-token locations first and routes to definitions or call-graph helpers when symbol intent is present. Use codebase_peek for direct conceptual location lookup, implementation_lookup for known-symbol definition questions, and codebase_search only when full semantic code content is needed. For exact identifiers or exhaustive matches, use grep. After identifying symbols, use call_graph or call_graph_path to trace dependencies. If the index is unavailable, run index_codebase, then retry the retrieval tool.`;
+}
 function getPackageVersion() {
   const raw = JSON.parse((0, import_fs15.readFileSync)(new URL("../package.json", import_meta2.url), "utf-8"));
   if (raw && typeof raw === "object" && "version" in raw && typeof raw.version === "string") {
@@ -12194,6 +12285,8 @@ function createMcpServer(projectRoot, config, host = "opencode") {
   const server = new import_mcp.McpServer({
     name: "opencode-codebase-index",
     version: getPackageVersion()
+  }, {
+    instructions: getServerInstructions(host)
   });
   initializeTools(projectRoot, config, host);
   registerMcpTools(server, {