fix(agent): count each query word once in lexical search

Author: bwachman

src/agent/lexical-rank.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  lexicalFields,
+  scoreLexical,
+  tokenizeLexical,
+} from "./lexical-rank.js";
+
+describe("scoreLexical", () => {
+  test("counts a word repeated in the query once", () => {
+    const fields = lexicalFields(
+      "mcp__linear__list_release_notes",
+      "List release notes in the workspace",
+    );
+    // Same raw query on both sides so only the token list differs; the raw
+    // query feeds a separate whole-query substring bonus.
+    const rawQuery = "release notes release";
+    expect(
+      scoreLexical(fields, tokenizeLexical("release notes release"), rawQuery),
+    ).toBe(scoreLexical(fields, tokenizeLexical("release notes"), rawQuery));
+  });
+});

src/agent/lexical-rank.ts

@@ -30,7 +30,10 @@ export function scoreLexical(
   const name = fields.name.toLowerCase();
   const blob = fields.blob.toLowerCase();
   let total = 0;
-  for (const token of queryTokens) {
+  // A model repeats a word because its sentence needs it ("release ID or
+  // release slug"), not to weight it; counting each copy multiplies the
+  // bonus for every tool that matches that one word.
+  for (const token of new Set(queryTokens)) {
     if (fields.nameTokens.includes(token)) total += 3;
     else if (fields.blobTokens.has(token)) total += 1;
     else if (name.includes(token)) total += 0.75;

src/agent/tool-search.test.ts

@@ -112,6 +112,33 @@ const linearCatalog: ToolDefinition[] = [
 
 const linearIndex = createToolIndex(() => linearCatalog);
 
+// Trimmed from the live Linear MCP catalog: release-named tools competing with
+// list_issues, the only one that lists a release's issues.
+const linearReleaseCatalog: ToolDefinition[] = [
+  mcpDef(
+    "mcp__linear__list_issues",
+    '[linear] List issues in the user\'s Linear workspace, including active Triage Intelligence suggestions for issues in triage. For issues assigned to me, use "me" as the assignee. For issues created by me, use "me" as the creator. Use "null" for no assignee.',
+  ),
+  mcpDef(
+    "mcp__linear__get_release",
+    "[linear] Retrieve details of a release by ID or slug.",
+  ),
+  mcpDef(
+    "mcp__linear__get_release_note",
+    "[linear] Retrieve release notes by ID or slug, including markdown content.",
+  ),
+  mcpDef(
+    "mcp__linear__list_release_notes",
+    "[linear] List release notes in the workspace, optionally filtered by pipeline or covered release.",
+  ),
+  mcpDef(
+    "mcp__linear__list_release_pipelines",
+    "[linear] List release pipelines in the workspace.",
+  ),
+];
+
+const linearReleaseIndex = createToolIndex(() => linearReleaseCatalog);
+
 const wideCatalog: ToolDefinition[] = Array.from({ length: 12 }, (_, i) =>
   mcpDef(
     `mcp__linear__op_${String(i).padStart(2, "0")}`,
@@ -311,6 +338,13 @@ describe("createToolIndex", () => {
     expect(ranked.length).toBeGreaterThanOrEqual(1);
     expect(ranked.length).toBeLessThanOrEqual(2);
   });
+
+  test("a word repeated in the query does not bury the tool that answers it", () => {
+    const ranked = linearReleaseIndex.search(
+      "Linear list issues filtered by release ID or release slug",
+    );
+    expect(ranked).toContain("mcp__linear__list_issues");
+  });
 });
 
 describe("createToolSearchTool skills", () => {