fix(agent): put tool_search promotions on the next infer

Holding promoted names off the wire until compact left the model
unable to emit them. Search cards now rank a small N of names with
capped descriptions so the card cannot say call them now.

Author: TheGreatAxios

docs/MCP.md

@@ -92,8 +92,10 @@ global or local `exa` entry disables or overrides it as described above.
 Tools from connected servers are not advertised to the model up front; they are
 registered for dispatch as soon as the server connects (including later in the
 same turn) and surfaced on demand through dynamic tool discovery
-(`tool_search`). Names activated via `tool_search` persist in the session's
-`run.json` and are re-advertised on resume and after rebuilds.
+(`tool_search`). A match is a ranked handful of names plus capped
+descriptions — not full input schemas. Names activated via `tool_search`
+join the next inference tool list (no wait for compact), persist in the
+session's `run.json`, and are re-advertised on resume and after rebuilds.
 
 For integrations a project calls constantly, `pinnedTools` in local
 `.corbits/settings.json` keeps those names on the wire permanently — no

src/agent/lexical-rank.ts

@@ -45,16 +45,23 @@ export function scoreLexical(
 // search_agents, and skill_search. Per-surface scoring (and the agent
 // description bonus) stays at each call site; only the cut is shared. The
 // sort is score-descending and stable, so tied scores keep catalog order
-// identically on every surface.
+// identically on every surface. `minRatio` (0–1) drops scores below
+// top * minRatio before the limit slice, so a specific query keeps the
+// peak cluster instead of filling the N cap with weak cousins.
 export function rankAndCut<T>(
   items: readonly T[],
   scoreItem: (item: T) => number,
   limit: number,
+  minRatio?: number,
 ): T[] {
-  return items
+  const ranked = items
     .map((item) => ({ item, score: scoreItem(item) }))
     .filter((entry) => entry.score > 0)
-    .sort((a, b) => b.score - a.score)
+    .sort((a, b) => b.score - a.score);
+  const top = ranked[0]?.score ?? 0;
+  const floor = minRatio === undefined || top === 0 ? 0 : top * minRatio;
+  return ranked
+    .filter((entry) => entry.score >= floor)
     .slice(0, limit)
     .map((entry) => entry.item);
 }

src/agent/search-scorer-parity.test.ts

@@ -65,12 +65,18 @@ async function skillOrder(query: string): Promise<string[]> {
 describe("search scorer parity", () => {
   test("tool, skill, and agent search rank one catalog the same way", async () => {
     const expected = ["granola-notes", "mygranolahoard", "notebook"];
-    expect(createToolIndex(() => tools, []).search(QUERY)).toEqual(expected);
-    expect(await skillOrder(QUERY)).toEqual(expected);
-    expect(
-      createAgentIndex(() => agents)
-        .search(QUERY)
-        .map((profile) => profile.id),
-    ).toEqual(expected);
+    const skillHits = await skillOrder(QUERY);
+    const agentHits = createAgentIndex(() => agents)
+      .search(QUERY)
+      .map((profile) => profile.id);
+    expect(skillHits).toEqual(expected);
+    expect(agentHits).toEqual(expected);
+    // tool_search uses the same ranker, then keeps only the peak cluster
+    // so a specific query does not fill the N cap with weak cousins.
+    const toolHits = createToolIndex(() => tools, []).search(QUERY);
+    expect(toolHits[0]).toBe(expected[0]);
+    expect(expected.slice(0, toolHits.length)).toEqual(toolHits);
+    expect(toolHits.length).toBeGreaterThan(0);
+    expect(toolHits.length).toBeLessThanOrEqual(expected.length);
   });
 });

src/agent/tool-search.test.ts

@@ -56,6 +56,45 @@ const defs: ToolDefinition[] = [
 
 const index = createToolIndex(() => defs);
 
+function mcpDef(
+  name: string,
+  description: string,
+  extraSchema?: Record<string, unknown>,
+): ToolDefinition {
+  return {
+    name,
+    description,
+    inputSchema: {
+      type: "object",
+      properties: extraSchema ?? {},
+      required: [],
+    },
+  };
+}
+
+const linearCatalog: ToolDefinition[] = [
+  mcpDef("mcp__linear__list_issues", "List issues in Linear"),
+  mcpDef("mcp__linear__get_issue", "Get a Linear issue"),
+  mcpDef("mcp__linear__save_issue", "Save a Linear issue"),
+  mcpDef("mcp__linear__create_issue", "Create a Linear issue"),
+  mcpDef("mcp__linear__delete_issue", "Delete a Linear issue"),
+  mcpDef("mcp__linear__update_issue", "Update a Linear issue"),
+  mcpDef("mcp__linear__archive_issue", "Archive a Linear issue"),
+  mcpDef("mcp__linear__assign_issue", "Assign a Linear issue"),
+  mcpDef("mcp__linear__label_issue", "Label a Linear issue"),
+  mcpDef("mcp__linear__list_comments", "List comments on a Linear issue"),
+  mcpDef("mcp__linear__save_comment", "Save a comment on a Linear issue"),
+  mcpDef("mcp__linear__list_projects", "List Linear projects"),
+  mcpDef("mcp__github__create_issue", "Create a GitHub issue"),
+  mcpDef(
+    "mcp__linear__verbose_issue",
+    `${"A very long Linear issue description. ".repeat(20)}end-marker`,
+    { title: { type: "string" }, teamId: { type: "string" } },
+  ),
+];
+
+const linearIndex = createToolIndex(() => linearCatalog);
+
 describe("createToolIndex", () => {
   test("ranks a name-token match above a description-only match", () => {
     const results = index.search("present");
@@ -235,6 +274,29 @@ describe("createToolIndex", () => {
     expect(allowed.search("pages")).toContain("present");
     expect(allowed.search("linear")).not.toContain("mcp__linear__create_issue");
   });
+
+  test("ranks a save-issue query above list-issue tools", () => {
+    const ranked = linearIndex.search("linear issue save");
+    expect(ranked[0]).toBe("mcp__linear__save_issue");
+    const listPos = ranked.indexOf("mcp__linear__list_issues");
+    if (listPos !== -1) {
+      expect(ranked.indexOf("mcp__linear__save_issue")).toBeLessThan(listPos);
+    }
+  });
+
+  test("caps a broad linear-issue query to a handful of top matches", () => {
+    const ranked = linearIndex.search("linear issue");
+    expect(ranked.length).toBeGreaterThan(1);
+    expect(ranked.length).toBeLessThanOrEqual(5);
+    expect(ranked.every((name) => name.includes("linear"))).toBe(true);
+  });
+
+  test("a specific save query returns one or two tools, not the whole family", () => {
+    const ranked = linearIndex.search("linear issue save");
+    expect(ranked).toContain("mcp__linear__save_issue");
+    expect(ranked.length).toBeGreaterThanOrEqual(1);
+    expect(ranked.length).toBeLessThanOrEqual(2);
+  });
 });
 
 function call(
@@ -268,21 +330,26 @@ describe("createToolSearchTool", () => {
     expect(out).toContain("layout");
   });
 
-  test("surfaces a matched tool's input schema so the model can shape arguments", async () => {
+  test("returns name and capped description without a full input schema", async () => {
     const tool = createToolSearchTool({
-      search: (q) => index.search(q),
-      lookup: (name) => defs.find((d) => d.name === name),
+      search: (q) => linearIndex.search(q),
+      lookup: (name) => linearCatalog.find((d) => d.name === name),
       promote: () => undefined,
     });
-    const out = await call(tool, { query: "issue tracker" });
-    expect(out).toContain("mcp__linear__create_issue");
-    // Parameter names and the required list must appear — this is the whole
-    // point: MCP tools are never in the wire tools array up front, so their
-    // schema reaches the model through the tool_search result this same turn,
-    // ahead of the promoted definition landing on the next infer call.
-    expect(out).toContain("title");
-    expect(out).toContain("teamId");
-    expect(out).toContain("required");
+    const out = await call(tool, { query: "linear issue" });
+    expect(out).toContain("mcp__linear__");
+    expect(out).not.toMatch(/input schema/i);
+    expect(out).not.toContain("teamId");
+    expect(out).not.toContain("end-marker");
+    const descLines = out
+      .split("\n")
+      .filter((line) => line.startsWith("- mcp__"));
+    expect(descLines.length).toBeGreaterThan(0);
+    for (const line of descLines) {
+      expect(line.length).toBeLessThanOrEqual(200);
+    }
+    expect(out).not.toMatch(/call them now/i);
+    expect(out).toMatch(/next (turn|infer)/i);
   });
 
   test("rejects an empty query", async () => {

src/agent/tool-search.ts

@@ -14,9 +14,8 @@ import { sessionModeEnablesSubAgents } from "../config/session-mode.js";
 
 // Tools whose full schema is always advertised to the model. Everything else is
 // registered but discovered on demand via tool_search, which promotes matches
-// onto the call gate at once; the full schema joins the wire set at the next
-// cache-safe boundary. Shared by the system prompt and
-// the advertised-set gate so the two never drift.
+// onto the call gate and the next infer's wire set. Shared by the system prompt
+// and the advertised-set gate so the two never drift.
 //
 // `present` is deliberately absent: most sessions never render a view, and at
 // 2,793 chars it is the second-largest schema on the wire. It stays off the
@@ -149,10 +148,11 @@ export const ADVERTISED_TOOL_NAMES: readonly string[] = [
 
 // Project the live tool registry onto the advertised set: the fixed built-in
 // prefix (its order never changes — this is what keeps the provider cache
-// prefix stable) followed by wire-committed tools (MCP or otherwise) in
-// first-commit order. The wire array is byte-stable turn to turn: callers pass
-// only names committed via flushPromotions at a cache-safe boundary, never the
-// live activation list, so a mid-session discovery cannot append here.
+// prefix stable across no-discovery turns) followed by wire-committed tools
+// (MCP or otherwise) in first-commit order. Callers pass names committed via
+// flushPromotions (on promote, and at cache-safe boundaries), never the live
+// activation list before a flush, so a mid-handler discovery cannot append
+// here until the promoter commits it.
 // `activated` is expected to already be deduped/ordered (see
 // `createActivatedToolTracker`), but names are deduped again here defensively
 // so a caller passing raw matches still can't reorder or duplicate an entry.
@@ -217,7 +217,7 @@ export function createActivatedToolTracker(): ActivatedToolTracker {
 export const toolSearchDefinition: ToolDefinition = {
   name: "tool_search",
   description:
-    "Discover callable tools by capability. Most tools — MCP servers, present, and other integrations — are not callable until this search promotes them. Core tools (read_file, run_shell, web_fetch, web_search, spawn_agent, …) are already on the wire — do not tool_search for them. wait_agents is mounted on exec-primary runs only, so it is not on the wire elsewhere and this search cannot promote it there. Call this with a short description of what you need (e.g. 'issue tracker', 'render layout', 'granola notes') to get matching tools' names, descriptions, and input schemas. Matched tools are promoted and callable on return — invoke them directly, no separate load step.",
+    "Discover callable tools by capability. Most tools — MCP servers, present, and other integrations — are not on the wire until this search promotes them onto the next inference. Core tools (read_file, run_shell, web_fetch, web_search, spawn_agent, …) are already on the wire — do not tool_search for them. wait_agents is mounted on exec-primary runs only, so it is not on the wire elsewhere and this search cannot promote it there. Call this with a short description of what you need (e.g. 'issue tracker', 'render layout', 'granola notes') to get a ranked handful of matching names and short descriptions. Matched tools join the next inference tool list — call them on the next turn, not from this result.",
   inputSchema: {
     type: "object",
     properties: {
@@ -238,6 +238,10 @@ export interface ToolIndex {
 // Rank registered tools against name + description via the shared lexical
 // scorer. Already-advertised tools are always callable so they never rank;
 // the allow list (when set) keeps search from promoting outside it.
+export const TOOL_SEARCH_MAX_RESULTS = 5;
+export const TOOL_SEARCH_SCORE_RATIO = 0.75;
+export const TOOL_SEARCH_DESC_MAX = 160;
+
 export function createToolIndex(
   getDefs: () => readonly ToolDefinition[],
   advertisedNames: readonly string[] = ADVERTISED_TOOL_NAMES,
@@ -257,7 +261,7 @@ export function createToolIndex(
     );
 
   return {
-    search(query: string, limit = 8): string[] {
+    search(query: string, limit = TOOL_SEARCH_MAX_RESULTS): string[] {
       const rawQuery = query.toLowerCase().trim();
       const queryTokens = tokenizeLexical(query);
       if (queryTokens.length === 0) return [];
@@ -268,6 +272,7 @@ export function createToolIndex(
         candidates,
         (def) => score(def, queryTokens, rawQuery),
         limit,
+        TOOL_SEARCH_SCORE_RATIO,
       ).map((def) => def.name);
     },
   };
@@ -276,9 +281,7 @@ export function createToolIndex(
 export interface ToolSearchDeps {
   search: (query: string) => string[];
   lookup: (name: string) => ToolDefinition | undefined;
-  // Promote matches onto the call gate so the model can invoke them this turn
-  // from the result card's schema. Wire declaration follows at the next
-  // cache-safe boundary (compaction fold), never mid-thread.
+  // Promote matches onto the call gate and the next infer's wire set.
   promote: (names: string[]) => void;
   // Resolves to the remaining in-flight MCP handshake count after waiting up
   // to `timeoutMs`. The toolset bounds its own wait; the handler re-races
@@ -311,22 +314,15 @@ export const TOOL_SEARCH_RECONNECT_WAIT_MS = 500;
 
 const ToolSearchArgs = type({ query: "string" });
 
-// Render one discovered tool as name, description, and pretty-printed input
-// schema. The schema is the load-bearing addition: MCP and other unadvertised
-// tools never appear in the wire tools array, so this is the model's only view
-// of their parameter names, types, and required fields.
-function renderToolCard(def: ToolDefinition | undefined, name: string): string {
-  if (def === undefined) return `- ${name}`;
-  const header = `- ${def.name}: ${def.description ?? ""}`;
-  const schema = JSON.stringify(def.inputSchema ?? {}, null, 2);
-  return `${header}\n  input schema:\n${indent(schema, "    ")}`;
+function capDescription(text: string, max = TOOL_SEARCH_DESC_MAX): string {
+  const oneLine = text.replace(/\s+/g, " ").trim();
+  if (oneLine.length <= max) return oneLine;
+  return `${oneLine.slice(0, max - 1)}…`;
 }
 
-function indent(text: string, pad: string): string {
-  return text
-    .split("\n")
-    .map((line) => `${pad}${line}`)
-    .join("\n");
+function renderToolCard(def: ToolDefinition | undefined, name: string): string {
+  if (def === undefined) return `- ${name}`;
+  return `- ${def.name}: ${capDescription(def.description ?? "")}`;
 }
 
 // Race the dependency's pending-count wait against a bound, so a
@@ -398,17 +394,14 @@ export function createToolSearchTool(deps: ToolSearchDeps): AgentTool {
       if (names.length === 0) {
         return `No tools matched "${query}". Try different keywords describing the capability.`;
       }
-      // Matches open on the call gate at once; the full schema joins the wire
-      // declarations at the next cache-safe boundary (compaction fold), never
-      // mid-thread, so the provider's cached prefix stays byte-stable. The
-      // tool result below still carries name, description, AND input schema
-      // so the model can shape arguments and call this same turn, before the
-      // promoted definition is declared on the wire.
+      // Matches open on the call gate and join the next infer's wire set
+      // (promoter flushes at activate). The card is names + capped
+      // descriptions only — full schemas ride the next tools array.
       deps.promote(names);
       const blocks = names.map((name) =>
         renderToolCard(deps.lookup(name), name),
       );
-      return `These tools are available — you can call them now:\n\n${blocks.join("\n\n")}`;
+      return `Promoted onto the next inference tool list. Call them on the next turn:\n\n${blocks.join("\n")}`;
     },
   });
 }