fix(agent): match tool names across a trailing plural s

Author: bwachman

src/agent/lexical-rank.test.ts

@@ -99,3 +99,98 @@ describe("scoreLexical", () => {
     }
   });
 });
+
+describe("scoreLexical tool names across a trailing plural s", () => {
+  // No fixture name contains this raw query whole, so only the per-token
+  // tiers differ between the scores compared.
+  const rawQuery = "linear issue";
+
+  function nameScore(name: string, query: string): number {
+    return scoreLexical(
+      lexicalFields(name, "", NO_LEXICAL_PARAMS),
+      tokenizeLexical(query),
+      rawQuery,
+    );
+  }
+
+  // `substring` holds the query word only inside a longer name token.
+  function expectFoldedBetween(
+    query: string,
+    names: { substring: string; folded: string; exact: string },
+  ) {
+    const folded = nameScore(names.folded, query);
+    expect(folded).toBeGreaterThan(nameScore(names.substring, query));
+    expect(folded).toBeLessThan(nameScore(names.exact, query));
+  }
+
+  test("a singular query word matches its plural in a name", () => {
+    expectFoldedBetween("issue", {
+      substring: "mcp__acme__issuetracker",
+      folded: "mcp__linear__list_issues",
+      exact: "mcp__linear__list_issue",
+    });
+  });
+
+  test("a plural query word matches its singular in a name", () => {
+    expectFoldedBetween("issues", {
+      substring: "mcp__acme__issuestracker",
+      folded: "mcp__linear__get_issue",
+      exact: "mcp__linear__get_issues",
+    });
+  });
+
+  test("a word given in both forms counts once, as its better spelling", () => {
+    const fields = lexicalFields(
+      "mcp__linear__list_issues",
+      "List issues in Linear",
+      NO_LEXICAL_PARAMS,
+    );
+    expect(
+      scoreLexical(fields, tokenizeLexical("linear issue issues"), rawQuery),
+    ).toBe(scoreLexical(fields, tokenizeLexical("linear issues"), rawQuery));
+  });
+
+  test("a word given in both forms scores the same in either order", () => {
+    // "issue" sits only inside "issuetracker", so only a substring tier
+    // matches, and it matches the singular but not the plural.
+    const fields = lexicalFields(
+      "mcp__acme__issuetracker",
+      "",
+      NO_LEXICAL_PARAMS,
+    );
+    const pluralFirst = scoreLexical(
+      fields,
+      tokenizeLexical("issues issue"),
+      rawQuery,
+    );
+    expect(pluralFirst).toBeGreaterThan(0);
+    expect(pluralFirst).toBe(
+      scoreLexical(fields, tokenizeLexical("issue issues"), rawQuery),
+    );
+  });
+
+  test("a word of three letters keeps its trailing s", () => {
+    const fields = lexicalFields("mcp__acme__get_it", "", NO_LEXICAL_PARAMS);
+    expect(scoreLexical(fields, tokenizeLexical("its"), "its")).toBe(0);
+  });
+
+  test("a plural query word earns no substring credit for its singular", () => {
+    // "users" folds to "user", which sits inside "username"; the substring
+    // tier still looks for "users".
+    const fields = lexicalFields(
+      "mcp__acme__username_lookup",
+      "",
+      NO_LEXICAL_PARAMS,
+    );
+    expect(scoreLexical(fields, tokenizeLexical("users"), "users")).toBe(0);
+  });
+
+  test("a description word does not match a query word that folds to it", () => {
+    const fields = lexicalFields(
+      "mcp__linear__save_issue",
+      "Create a new issue",
+      NO_LEXICAL_PARAMS,
+    );
+    expect(scoreLexical(fields, tokenizeLexical("news"), "news")).toBe(0);
+  });
+});

src/agent/lexical-rank.ts

@@ -1,5 +1,7 @@
 // One shared dependency-free lexical ranker behind tool_search,
 // search_agents, and skill_search. Exact name-token hits weigh most, then
+// name tokens that match across a trailing plural "s" (so "issue" finds
+// list_issues while the spelling the query uses still wins ties), then
 // blob-token hits, then a raw name substring (so "linear" finds
 // mcp__linear__* even though it is not a whole token there), then a raw blob
 // substring. Parameter name and description tokens (tool_search only) weigh
@@ -11,10 +13,21 @@ export function tokenizeLexical(text: string): string[] {
   return text.toLowerCase().match(/[a-z0-9]+/g) ?? [];
 }
 
+// Folding also merges real word pairs such as "news" and "new", so it stays
+// on names: in descriptions, a common word like "new" would turn a miss into
+// a false hit. Three-letter words keep their "s", so "its" never becomes "it".
+function foldPlural(token: string): string {
+  return token.length > 3 && token.endsWith("s") ? token.slice(0, -1) : token;
+}
+
+// Under exact (3); 3 + this clears TOOL_SEARCH_SCORE_RATIO * 6 ("issue list").
+const FOLDED_NAME_TOKEN_SCORE = 2.5;
+
 export interface LexicalFields {
   readonly name: string;
   readonly blob: string;
   readonly nameTokens: readonly string[];
+  readonly foldedNameTokens: readonly string[];
   readonly blobTokens: ReadonlySet<string>;
   readonly paramNameTokens: ReadonlySet<string>;
   readonly paramBlobTokens: ReadonlySet<string>;
@@ -40,10 +53,12 @@ export function lexicalFields(
   blob: string,
   params: LexicalParams,
 ): LexicalFields {
+  const nameTokens = tokenizeLexical(name);
   return {
     name,
     blob,
-    nameTokens: tokenizeLexical(name),
+    nameTokens,
+    foldedNameTokens: nameTokens.map(foldPlural),
     blobTokens: new Set(tokenizeLexical(blob)),
     paramNameTokens: new Set(
       tokenizeLexical(params.names.map(splitCamelCase).join(" ")),
@@ -59,6 +74,9 @@ function directTokenScore(
   token: string,
 ): number {
   if (fields.nameTokens.includes(token)) return 3;
+  if (fields.foldedNameTokens.includes(foldPlural(token))) {
+    return FOLDED_NAME_TOKEN_SCORE;
+  }
   if (fields.blobTokens.has(token)) return 1;
   if (name.includes(token)) return 0.75;
   if (blob.includes(token)) return 0.25;
@@ -82,11 +100,26 @@ export function scoreLexical(
   let total = matched;
   // 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.
+  // bonus for every tool that matches that one word. "issue" and "issues"
+  // are one word, scored as whichever spelling matches better. The merge
+  // applies on every tier, so an unrelated pair like "new" and "news" also
+  // counts once against a description; that is accepted.
+  const words = new Map<string, string[]>();
   for (const token of new Set(queryTokens)) {
-    const direct = directTokenScore(fields, name, blob, token);
+    const folded = foldPlural(token);
+    const spellings = words.get(folded);
+    if (spellings === undefined) words.set(folded, [token]);
+    else spellings.push(token);
+  }
+  for (const spellings of words.values()) {
+    const direct = Math.max(
+      ...spellings.map((token) => directTokenScore(fields, name, blob, token)),
+    );
+    const param = Math.max(
+      ...spellings.map((token) => paramTokenScore(fields, token)),
+    );
     matched += direct;
-    total += Math.max(direct, paramTokenScore(fields, token));
+    total += Math.max(direct, param);
   }
   return matched > 0 ? total : 0;
 }

src/agent/tool-search.test.ts

@@ -467,6 +467,68 @@ describe("createToolIndex", () => {
     expect(teamIndex.search("linear team")[0]).toBe("mcp__linear__list_teams");
   });
 
+  // Trimmed from the live Linear MCP catalog and sorted by name, so five
+  // tools that carry the singular "issue" come ahead of list_issues.
+  const linearIssueCatalog: ToolDefinition[] = [
+    mcpDef(
+      "mcp__linear__create_issue_label",
+      "[linear] Create a new Linear issue label. Deprecated: use `save_issue_label`, which can also update labels.",
+    ),
+    mcpDef(
+      "mcp__linear__get_issue",
+      "[linear] Retrieve detailed information about an issue by ID, including attachments, git branch name, and active Triage Intelligence suggestions when the issue is in triage.",
+    ),
+    mcpDef(
+      "mcp__linear__get_issue_status",
+      "[linear] Retrieve detailed information about an issue status in Linear by name or ID",
+    ),
+    mcpDef(
+      "mcp__linear__list_comments",
+      "[linear] List comments on a Linear issue, project, initiative, document, project milestone, or project/initiative status update.",
+    ),
+    mcpDef(
+      "mcp__linear__list_issue_labels",
+      "[linear] List available issue labels in a Linear workspace or team. A retired label carries `retiredAt` and cannot be applied to new issues.",
+    ),
+    mcpDef(
+      "mcp__linear__list_issue_statuses",
+      "[linear] List available issue statuses in a Linear team",
+    ),
+    mcpDef(
+      "mcp__linear__list_issues",
+      "[linear] List issues in the user's Linear workspace, including active Triage Intelligence suggestions for issues in triage.",
+    ),
+    mcpDef(
+      "mcp__linear__list_projects",
+      "[linear] List projects in the user's Linear workspace",
+    ),
+    mcpDef(
+      "mcp__linear__list_teams",
+      "[linear] List teams in the user's Linear workspace, including their parent IDs and hierarchy names",
+    ),
+    mcpDef(
+      "mcp__linear__save_issue",
+      "[linear] Create or update a Linear issue. If `id` is provided, updates the existing issue; otherwise creates a new one.",
+    ),
+  ];
+  const linearIssueIndexes = [
+    createToolIndex(() => linearIssueCatalog),
+    createToolIndex(() => [...linearIssueCatalog].reverse()),
+  ];
+
+  test("a singular query word finds the tool named for its plural", () => {
+    for (const index of linearIssueIndexes) {
+      expect(index.search("issue list")).toContain("mcp__linear__list_issues");
+    }
+  });
+
+  test("a plural query word ranks the tool named for it first", () => {
+    for (const index of linearIssueIndexes) {
+      expect(index.search("list issues")[0]).toBe("mcp__linear__list_issues");
+      expect(index.search("linear issues")[0]).toBe("mcp__linear__list_issues");
+    }
+  });
+
   test("a malformed input schema still scores on name and description", () => {
     const malformedIndex = createToolIndex(() => [
       {