Merge pull request #1302 from corbitsdev/fix/mcp-search-schema-cards

fix(agent): put input schemas on tool_search cards

Author: TheGreatAxios

docs/MCP.md

@@ -93,7 +93,8 @@ 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`). A match is a ranked handful of names plus capped
-descriptions — not full input schemas. `tool_search` does not promote
+descriptions. The top two cards also include a compact input schema so
+the first call is formable. `tool_search` does not promote
 names onto the next inference or into `run.json`. Calling a discovered
 name declares that one schema on the next infer (promote-on-execute),
 persists it in the session's `run.json`, and re-advertises it on resume

src/agent/environment.ts

@@ -16,6 +16,8 @@ export interface EnvironmentInfo {
   gitDirtyCount?: number;
   gitStatusSummary?: string;
   topLevel?: string;
+  /** Configured MCP server names for this session, when any are present. */
+  mcpServers?: readonly string[];
 }
 
 const GIT_STATUS_LINES = 12;

src/agent/prompts.ts

@@ -55,8 +55,8 @@ export function buildChatRole(
 // blocks, what loads on demand, and the harness-specific tools. Everything a
 // frontier model already knows about being a coding agent is deliberately omitted.
 // `dynamicTools` controls the tool-loading fact: the main chat agent starts with
-// core tools plus the advertised catalog (including skill_search) and loads MCP
-// and other unadvertised tools via tool_search, whereas a sub-agent is
+// core tools plus the advertised catalog and finds MCP and other unadvertised
+// tools via tool_search, whereas a sub-agent is
 // handed its full toolset upfront and has no tool_search — telling it otherwise
 // wastes turns on a tool that does not exist.
 export function buildHarnessFacts(
@@ -95,7 +95,7 @@ export function buildHarnessFacts(
     "- Attached images are native multimodal input; inspect them directly unless file-level forensics are requested.",
     ...(dynamicTools
       ? [
-          "- Core tools plus the advertised catalog (including skill_search) are resident. Use tool_search to load extra capabilities from plugins or integrations when needed.",
+          "- Core tools plus the advertised catalog are resident. Use tool_search to find MCP/plugin tools; the top two cards include the input schema. Call a listed name and it joins the tool list — unused matches stay off it.",
           "- Use search_agents before dispatching named specialists or teams (ids and descriptions by default; include_body=true for the loaded system prompt).",
           "- The user may send follow-up messages while workers run; they are queued. Enter delivers at the next parent tool.boundary; Alt+Enter on session-idle. A long parent tool holds that boundary. Update your plan, spawn or adjust workers, and keep the operator informed.",
         ]
@@ -163,7 +163,7 @@ const GUIDELINE_SUB_BLOCKS: Record<
     ...(ctx.subAgent
       ? []
       : [
-          "- tool_search before assuming a plugin or MCP tool exists; skill_search when choosing among listed skills, use_skill to load a body.",
+          "- tool_search before assuming a plugin or MCP tool exists (top cards include the schema; call a listed name). use_skill to load a skill body.",
         ]),
   ],
   askVsProceed: (ctx) => [
@@ -327,6 +327,11 @@ export function buildEnvironmentContext(env: EnvironmentInfo): string {
     if (env.gitStatusSummary) lines.push(env.gitStatusSummary);
   }
   if (env.topLevel) lines.push(`Top level: ${env.topLevel}`);
+  if (env.mcpServers !== undefined && env.mcpServers.length > 0) {
+    lines.push(
+      `MCP: ${env.mcpServers.join(", ")} — tool_search finds their tools (top hits include schema); call a listed name to use it.`,
+    );
+  }
   lines.push(`Memory file: ${env.cwd}/${SETTINGS_DIR_NAME}/MEMORY.md`);
   lines.push("</env>");
   return lines.join("\n");

src/agent/tool-search.test.ts

@@ -17,6 +17,7 @@ import {
   TOOL_SEARCH_DESC_MAX,
   TOOL_SEARCH_MAX_RESULTS,
   TOOL_SEARCH_LIMIT_MAX,
+  TOOL_SEARCH_SCHEMA_MAX,
   toolSearchDefinition,
   type ToolAvailability,
 } from "./tool-search.js";
@@ -469,16 +470,93 @@ describe("createToolSearchTool", () => {
     expect(listed.every((name) => catalogNames.includes(name))).toBe(true);
   });
 
-  test("returns name and capped description without a full input schema", async () => {
+  test("search cards include the input schema so a first call is formable", async () => {
+    const tool = createToolSearchTool({
+      search: (q) => index.search(q),
+      lookup: (name) => defs.find((d) => d.name === name),
+    });
+    const out = await call(tool, { query: "linear issue create" });
+    expect(out).toContain("mcp__linear__create_issue");
+    expect(out).toContain("title");
+    expect(out).toContain("teamId");
+    expect(advertisedTools(defs).map((d) => d.name)).not.toContain(
+      "mcp__linear__create_issue",
+    );
+  });
+
+  test("only the top two ranked cards include input schema", async () => {
+    const catalog: ToolDefinition[] = Array.from({ length: 5 }, (_, i) => ({
+      name: `mcp__linear__op_${i}`,
+      description: "Linear issue operation",
+      inputSchema: {
+        type: "object",
+        properties: { [`field_${i}`]: { type: "string" } },
+        required: [`field_${i}`],
+      },
+    }));
+    const tool = createToolSearchTool({
+      search: () => catalog.map((d) => d.name),
+      lookup: (name) => catalog.find((d) => d.name === name),
+    });
+    const out = await call(tool, { query: "linear" });
+    expect(listedToolNames(out)).toEqual(catalog.map((d) => d.name));
+    expect(out).toContain("field_0");
+    expect(out).toContain("field_1");
+    expect(out).not.toContain("field_2");
+    expect(out).not.toContain("field_3");
+    expect(out).not.toContain("field_4");
+    expect(out).toContain("mcp__linear__op_2");
+    expect(out).toContain("mcp__linear__op_4");
+  });
+
+  test("tool_search description does not claim matches load on the next turn", () => {
+    expect(toolSearchDefinition.description).not.toMatch(
+      /load on the next turn/i,
+    );
+    expect(toolSearchDefinition.description).toMatch(/schema/i);
+    expect(toolSearchDefinition.description).toMatch(/call a listed name/i);
+  });
+
+  test("an oversized input schema is capped on the card", async () => {
+    const hugeProps = Object.fromEntries(
+      Array.from({ length: 80 }, (_, i) => [
+        `field_${String(i).padStart(2, "0")}`,
+        { type: "string", description: "x".repeat(40) },
+      ]),
+    );
+    const huge: ToolDefinition = {
+      name: "mcp__linear__huge_schema",
+      description: "Linear issue with a large schema",
+      inputSchema: {
+        type: "object",
+        properties: hugeProps,
+        required: ["field_00"],
+      },
+    };
+    const tool = createToolSearchTool({
+      search: () => [huge.name],
+      lookup: () => huge,
+    });
+    const out = await call(tool, { query: "linear huge" });
+    expect(out).toContain("mcp__linear__huge_schema");
+    expect(out).toContain("field_00");
+    const schemaLine = out.split("\n").find((line) => line.startsWith("  {"));
+    expect(schemaLine).toBeDefined();
+    expect(schemaLine?.length ?? 0).toBeLessThanOrEqual(
+      TOOL_SEARCH_SCHEMA_MAX + 2,
+    );
+  });
+
+  test("search does not promote matches and keeps description lines short", async () => {
     const tool = createToolSearchTool({
       search: (q) => linearIndex.search(q),
       lookup: (name) => linearCatalog.find((d) => d.name === name),
     });
+    const before = advertisedTools(linearCatalog).map((d) => d.name);
     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");
+    expect(advertisedTools(linearCatalog).map((d) => d.name)).toEqual(before);
     const descLines = out
       .split("\n")
       .filter((line) => line.startsWith("- mcp__"));
@@ -488,6 +566,7 @@ describe("createToolSearchTool", () => {
     }
     expect(out).not.toMatch(/call them now/i);
     expect(out).not.toMatch(/promoted onto/i);
+    expect(out).not.toMatch(/load on the next turn/i);
     expect(out).toMatch(/call a listed name/i);
   });
 

src/agent/tool-search.ts

@@ -252,7 +252,7 @@ export function createActivatedToolTracker(): ActivatedToolTracker {
 export const toolSearchDefinition: ToolDefinition = {
   name: "tool_search",
   description:
-    "Find tools (MCP servers, integrations) and skills by capability. Matched tools load on the next turn; load a skill body with use_skill.",
+    "Find tools (MCP servers, integrations) and skills by capability. Top two matches include input schema — call a listed name to use it (it then joins the tool list). Unused matches stay off the list. Load a skill body with use_skill.",
   inputSchema: {
     type: "object",
     properties: {
@@ -282,6 +282,8 @@ export const TOOL_SEARCH_MAX_RESULTS = 5;
 export const TOOL_SEARCH_LIMIT_MAX = 20;
 export const TOOL_SEARCH_SCORE_RATIO = 0.75;
 export const TOOL_SEARCH_DESC_MAX = 160;
+export const TOOL_SEARCH_SCHEMA_MAX = 600;
+const TOOL_SEARCH_SCHEMA_CARDS = 2;
 
 export function createToolIndex(
   getDefs: () => readonly ToolDefinition[],
@@ -401,9 +403,48 @@ function capDescription(text: string, max = TOOL_SEARCH_DESC_MAX): string {
   return `${oneLine.slice(0, max - 1)}…`;
 }
 
-function renderToolCard(def: ToolDefinition | undefined, name: string): string {
+function isEmptyInputSchema(schema: unknown): boolean {
+  if (schema === undefined || schema === null) return true;
+  if (typeof schema !== "object") return true;
+  const json = JSON.stringify(schema);
+  return (
+    json === "{}" ||
+    json === '{"type":"object"}' ||
+    json === '{"type":"object","properties":{}}' ||
+    json === '{"type":"object","properties":{},"required":[]}'
+  );
+}
+
+function compactInputSchema(schema: unknown): string | undefined {
+  if (isEmptyInputSchema(schema)) return undefined;
+  const json = JSON.stringify(schema);
+  if (json.length <= TOOL_SEARCH_SCHEMA_MAX) return json;
+  const obj = schema as Record<string, unknown>;
+  const properties = obj.properties;
+  const keys =
+    properties !== undefined &&
+    typeof properties === "object" &&
+    properties !== null
+      ? Object.keys(properties)
+      : [];
+  const required = Array.isArray(obj.required) ? obj.required : [];
+  const stub = JSON.stringify({ properties: keys, required });
+  if (stub.length <= TOOL_SEARCH_SCHEMA_MAX) return stub;
+  return `${stub.slice(0, TOOL_SEARCH_SCHEMA_MAX - 1)}…`;
+}
+
+function renderToolCard(
+  def: ToolDefinition | undefined,
+  name: string,
+  includeSchema: boolean,
+): string {
   if (def === undefined) return `- ${name}`;
-  return `- ${def.name}: ${capDescription(def.description ?? "")}`;
+  const desc = capDescription(def.description ?? "");
+  const schema = includeSchema
+    ? compactInputSchema(def.inputSchema)
+    : undefined;
+  if (schema === undefined) return `- ${def.name}: ${desc}`;
+  return `- ${def.name}: ${desc}\n  ${schema}`;
 }
 
 // Race the dependency's pending-count wait against a bound, so a
@@ -479,11 +520,12 @@ export function createToolSearchTool(deps: ToolSearchDeps): AgentTool {
       if (names.length === 0) {
         return `No tools or skills matched "${query}". Try different keywords describing the capability.`;
       }
-      // Cards only — name + capped description. Search does not open the call
-      // gate or grow the tools array; promote-on-execute declares a name when
-      // the model actually calls it.
-      const blocks = names.map((name) =>
-        renderToolCard(deps.lookup(name), name),
+      // Ranked cards: top TOOL_SEARCH_SCHEMA_CARDS include a compact input
+      // schema so the first call is formable; the rest are name + description.
+      // Search does not open the call gate or grow the tools array;
+      // promote-on-execute declares a name when the model actually calls it.
+      const blocks = names.map((name, i) =>
+        renderToolCard(deps.lookup(name), name, i < TOOL_SEARCH_SCHEMA_CARDS),
       );
       return `Matching tools — call a listed name to use it:\n\n${blocks.join("\n")}${skillBlock}`;
     },

src/exec/runner.ts

@@ -846,6 +846,11 @@ export async function runExec(config: Config): Promise<ExecResult> {
           skills: agentToolset.skills,
           providerName: config.providerName,
           model: config.model,
+          ...(config.mcpServers !== undefined
+            ? {
+                mcpServerNames: config.mcpServers.map((server) => server.name),
+              }
+            : {}),
         })
       ).systemPrompt;
 

src/prompts.test.ts

@@ -1,6 +1,7 @@
 import { expect, test } from "bun:test";
 
 import { buildChatSystemPrompt } from "./agent/prompts.js";
+import type { EnvironmentInfo } from "./agent/environment.js";
 
 test("chat system prompt keeps the routing, spawn-brief, and rules sections", () => {
   const prompt = buildChatSystemPrompt();
@@ -12,3 +13,27 @@ test("chat system prompt keeps the routing, spawn-brief, and rules sections", ()
   }
   expect(prompt).toContain("manage_tasks");
 });
+
+const envBase: EnvironmentInfo = {
+  cwd: "/tmp/proj",
+  platform: "test",
+  arch: "arm64",
+  runtime: "Bun 1.4.2",
+  date: new Date("2026-01-15T00:00:00Z"),
+  isGitRepo: false,
+};
+
+test("environment context lists configured MCP servers", () => {
+  const prompt = buildChatSystemPrompt(undefined, {
+    ...envBase,
+    mcpServers: ["linear", "exa"],
+  });
+  expect(prompt).toContain("MCP: linear, exa");
+  expect(prompt).toContain("tool_search");
+  expect(prompt).toContain("schema");
+});
+
+test("environment context omits MCP when none are configured", () => {
+  const prompt = buildChatSystemPrompt(undefined, envBase);
+  expect(prompt).not.toContain("MCP:");
+});

src/session/runtime-assembly.ts

@@ -319,13 +319,28 @@ export interface SessionChatPromptArgs {
   // Session-start snapshot from createAgentToolset. When provided, skip
   // rediscovery so the prompt listing and skill_search share one catalog.
   skills?: readonly SkillSummary[];
+  // Configured MCP server names to list in the env block so the model
+  // knows to tool_search for them. Omitted or empty = no MCP line.
+  mcpServerNames?: readonly string[];
 }
 
 export interface SessionChatPrompt {
   systemPrompt: string;
   skills: SkillSummary[];
 }
 
+function uniqueMcpServerNames(names: readonly string[] | undefined): string[] {
+  if (names === undefined || names.length === 0) return [];
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const name of names) {
+    if (name.length === 0 || seen.has(name)) continue;
+    seen.add(name);
+    out.push(name);
+  }
+  return out;
+}
+
 /** Load AGENTS.md / SYSTEM.md / env / skills and build the main chat system prompt. */
 export async function loadSessionChatPrompt(
   args: SessionChatPromptArgs,
@@ -343,6 +358,11 @@ export async function loadSessionChatPrompt(
     ...(args.systemPromptExtensions ?? []),
     ...overrides.append,
   ];
+  const mcpServerNames = uniqueMcpServerNames(args.mcpServerNames);
+  const env =
+    mcpServerNames.length > 0
+      ? { ...environment, mcpServers: mcpServerNames }
+      : environment;
   // Family residual on the primary prompt (CL-8310): resolved from the model
   // family policy as an orchestrator — primaries dispatch rather than doing
   // the work directly, so grok/claude primaries stay untouched (their rows
@@ -359,7 +379,7 @@ export async function loadSessionChatPrompt(
   return {
     systemPrompt: buildChatSystemPrompt(
       extensions.length > 0 ? extensions : undefined,
-      environment,
+      env,
       overrides.base,
       skills,
       args.sessionMode,

src/tui/runner/session.ts

@@ -453,6 +453,9 @@ export async function assembleTUISession(
     skills: toolset.skills,
     providerName: config.providerName,
     model: config.model,
+    ...(config.mcpServers !== undefined
+      ? { mcpServerNames: config.mcpServers.map((server) => server.name) }
+      : {}),
   });
 
   const directorHolder: { instance?: ReturnType<typeof createChatDirector> } =