@oh-my-pi/pi-coding-agent 13.12.6 → 13.12.7

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [13.12.7] - 2026-03-16
+### Changed
+
+- Modified `getSelectedMCPToolNames()` to return only active MCP tools in non-discovery sessions, filtering by tool registry availability
+- Updated `search_tool_bm25` tool instantiation to conditionally create the tool only when MCP discovery mode is enabled and execution hooks are available
+- Changed search results to exclude already-selected MCP tools before applying the limit parameter, allowing discovery of additional tools in subsequent searches
+
+### Fixed
+
+- Fixed MCP tool selection tracking to properly distinguish between discovery-enabled and non-discovery sessions, preventing orphaned tool selections after manual deactivation
+
 ## [13.12.6] - 2026-03-15
 ### Changed
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "13.12.6",
+	"version": "13.12.7",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/can1357/oh-my-pi",
 	"author": "Can Boluk",
@@ -41,12 +41,12 @@
 	},
 	"dependencies": {
 		"@mozilla/readability": "^0.6",
-		"@oh-my-pi/omp-stats": "13.12.6",
-		"@oh-my-pi/pi-agent-core": "13.12.6",
-		"@oh-my-pi/pi-ai": "13.12.6",
-		"@oh-my-pi/pi-natives": "13.12.6",
-		"@oh-my-pi/pi-tui": "13.12.6",
-		"@oh-my-pi/pi-utils": "13.12.6",
+		"@oh-my-pi/omp-stats": "13.12.7",
+		"@oh-my-pi/pi-agent-core": "13.12.7",
+		"@oh-my-pi/pi-ai": "13.12.7",
+		"@oh-my-pi/pi-natives": "13.12.7",
+		"@oh-my-pi/pi-tui": "13.12.7",
+		"@oh-my-pi/pi-utils": "13.12.7",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.18",

package/src/config/settings-schema.ts

@@ -1188,6 +1188,16 @@ export const SETTINGS_SCHEMA = {
 		ui: { tab: "tools", label: "MCP Project Config", description: "Load .mcp.json/mcp.json from project root" },
 	},
 
+	"mcp.discoveryMode": {
+		type: "boolean",
+		default: false,
+		ui: {
+			tab: "tools",
+			label: "MCP Tool Discovery",
+			description: "Hide MCP tools by default and expose them through a tool discovery tool",
+		},
+	},
+
 	"mcp.notifications": {
 		type: "boolean",
 		default: false,
@@ -1463,9 +1473,6 @@ export const SETTINGS_SCHEMA = {
 		ui: { tab: "providers", label: "Exa Websets", description: "Webset management and enrichment tools" },
 	},
 
-	// ────────────────────────────────────────────────────────────────────────
-	// Advanced settings (no UI)
-	// ────────────────────────────────────────────────────────────────────────
 	"commit.mapReduceEnabled": { type: "boolean", default: true },
 
 	"commit.mapReduceMinFiles": { type: "number", default: 4 },

package/src/discovery/claude.ts

@@ -89,6 +89,7 @@ async function loadMCPServers(ctx: LoadContext): Promise<LoadResult<MCPServer>>
 			const serverConfig = config as Record<string, unknown>;
 			return {
 				name,
+				timeout: typeof serverConfig.timeout === "number" ? serverConfig.timeout : undefined,
 				command: serverConfig.command as string | undefined,
 				args: serverConfig.args as string[] | undefined,
 				env: serverConfig.env as Record<string, string> | undefined,

package/src/discovery/codex.ts

@@ -197,6 +197,10 @@ function extractMCPServersFromToml(toml: Record<string, unknown>): Record<string
 		}
 		// Note: validation of transport vs endpoint is handled by mcpCapability.validate()
 
+		// Map Codex tool_timeout_sec (seconds) to MCPServer timeout (milliseconds)
+		if (typeof config.tool_timeout_sec === "number" && config.tool_timeout_sec > 0) {
+			server.timeout = config.tool_timeout_sec * 1000;
+		}
 		result[name] = server;
 	}
 

package/src/discovery/cursor.ts

@@ -65,6 +65,7 @@ function parseMCPServers(
 			transport: ["stdio", "sse", "http"].includes(serverConfig.type as string)
 				? (serverConfig.type as "stdio" | "sse" | "http")
 				: undefined,
+			timeout: typeof serverConfig.timeout === "number" ? serverConfig.timeout : undefined,
 			_source: createSourceMeta(PROVIDER_ID, path, level),
 		});
 	}

package/src/discovery/gemini.ts

@@ -110,6 +110,7 @@ async function loadMCPFromSettings(
 			transport: ["stdio", "sse", "http"].includes(raw.type as string)
 				? (raw.type as "stdio" | "sse" | "http")
 				: undefined,
+			timeout: typeof raw.timeout === "number" ? raw.timeout : undefined,
 			_source: createSourceMeta(PROVIDER_ID, path, level),
 		} as MCPServer);
 	}

package/src/discovery/vscode.ts

@@ -94,6 +94,7 @@ async function loadMCPConfig(
 			transport: ["stdio", "sse", "http"].includes(expanded.transport as string)
 				? (expanded.transport as "stdio" | "sse" | "http")
 				: undefined,
+			timeout: typeof expanded.timeout === "number" ? expanded.timeout : undefined,
 			_source: createSourceMeta(PROVIDER_ID, path, level),
 		};
 

package/src/discovery/windsurf.ts

@@ -54,6 +54,7 @@ function parseServerConfig(
 			url: server.url as string | undefined,
 			headers: server.headers as Record<string, string> | undefined,
 			transport: server.type as "stdio" | "sse" | "http" | undefined,
+			timeout: typeof server.timeout === "number" ? server.timeout : undefined,
 			_source: createSourceMeta(PROVIDER_ID, path, scope),
 		},
 	};

package/src/mcp/discoverable-tool-metadata.ts

@@ -0,0 +1,192 @@
+import type { AgentTool } from "@oh-my-pi/pi-agent-core";
+
+export interface DiscoverableMCPTool {
+	name: string;
+	label: string;
+	description: string;
+	serverName?: string;
+	mcpToolName?: string;
+	schemaKeys: string[];
+}
+
+export interface DiscoverableMCPToolServerSummary {
+	name: string;
+	toolCount: number;
+}
+
+export interface DiscoverableMCPToolSummary {
+	servers: DiscoverableMCPToolServerSummary[];
+	toolCount: number;
+}
+
+export function formatDiscoverableMCPToolServerSummary(server: DiscoverableMCPToolServerSummary): string {
+	const toolLabel = server.toolCount === 1 ? "tool" : "tools";
+	return `${server.name} (${server.toolCount} ${toolLabel})`;
+}
+
+export interface DiscoverableMCPSearchDocument {
+	tool: DiscoverableMCPTool;
+	termFrequencies: Map<string, number>;
+	length: number;
+}
+
+export interface DiscoverableMCPSearchIndex {
+	documents: DiscoverableMCPSearchDocument[];
+	averageLength: number;
+	documentFrequencies: Map<string, number>;
+}
+
+export interface DiscoverableMCPSearchResult {
+	tool: DiscoverableMCPTool;
+	score: number;
+}
+
+const BM25_K1 = 1.2;
+const BM25_B = 0.75;
+const FIELD_WEIGHTS = {
+	name: 6,
+	label: 4,
+	serverName: 2,
+	mcpToolName: 4,
+	description: 2,
+	schemaKey: 1,
+} as const;
+
+export function isMCPToolName(name: string): boolean {
+	return name.startsWith("mcp_");
+}
+
+function getSchemaPropertyKeys(parameters: unknown): string[] {
+	if (!parameters || typeof parameters !== "object" || Array.isArray(parameters)) return [];
+	const properties = (parameters as { properties?: unknown }).properties;
+	if (!properties || typeof properties !== "object" || Array.isArray(properties)) return [];
+	return Object.keys(properties as Record<string, unknown>).sort();
+}
+
+function tokenize(value: string): string[] {
+	return value
+		.replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+		.replace(/[^a-zA-Z0-9]+/g, " ")
+		.toLowerCase()
+		.trim()
+		.split(/\s+/)
+		.filter(token => token.length > 0);
+}
+
+function addWeightedTokens(termFrequencies: Map<string, number>, value: string | undefined, weight: number): void {
+	if (!value) return;
+	for (const token of tokenize(value)) {
+		termFrequencies.set(token, (termFrequencies.get(token) ?? 0) + weight);
+	}
+}
+
+function buildSearchDocument(tool: DiscoverableMCPTool): DiscoverableMCPSearchDocument {
+	const termFrequencies = new Map<string, number>();
+	addWeightedTokens(termFrequencies, tool.name, FIELD_WEIGHTS.name);
+	addWeightedTokens(termFrequencies, tool.label, FIELD_WEIGHTS.label);
+	addWeightedTokens(termFrequencies, tool.serverName, FIELD_WEIGHTS.serverName);
+	addWeightedTokens(termFrequencies, tool.mcpToolName, FIELD_WEIGHTS.mcpToolName);
+	addWeightedTokens(termFrequencies, tool.description, FIELD_WEIGHTS.description);
+	for (const schemaKey of tool.schemaKeys) {
+		addWeightedTokens(termFrequencies, schemaKey, FIELD_WEIGHTS.schemaKey);
+	}
+	const length = Array.from(termFrequencies.values()).reduce((sum, value) => sum + value, 0);
+	return { tool, termFrequencies, length };
+}
+
+export function getDiscoverableMCPTool(tool: AgentTool): DiscoverableMCPTool | null {
+	if (!isMCPToolName(tool.name)) return null;
+	const toolRecord = tool as AgentTool & {
+		label?: string;
+		description?: string;
+		mcpServerName?: string;
+		mcpToolName?: string;
+		parameters?: unknown;
+	};
+	return {
+		name: tool.name,
+		label: typeof toolRecord.label === "string" ? toolRecord.label : tool.name,
+		description: typeof toolRecord.description === "string" ? toolRecord.description : "",
+		serverName: typeof toolRecord.mcpServerName === "string" ? toolRecord.mcpServerName : undefined,
+		mcpToolName: typeof toolRecord.mcpToolName === "string" ? toolRecord.mcpToolName : undefined,
+		schemaKeys: getSchemaPropertyKeys(toolRecord.parameters),
+	};
+}
+
+export function collectDiscoverableMCPTools(tools: Iterable<AgentTool>): DiscoverableMCPTool[] {
+	const discoverable: DiscoverableMCPTool[] = [];
+	for (const tool of tools) {
+		const metadata = getDiscoverableMCPTool(tool);
+		if (metadata) {
+			discoverable.push(metadata);
+		}
+	}
+	return discoverable;
+}
+
+export function summarizeDiscoverableMCPTools(tools: DiscoverableMCPTool[]): DiscoverableMCPToolSummary {
+	const serverToolCounts = new Map<string, number>();
+	for (const tool of tools) {
+		if (!tool.serverName) continue;
+		serverToolCounts.set(tool.serverName, (serverToolCounts.get(tool.serverName) ?? 0) + 1);
+	}
+	const servers = Array.from(serverToolCounts.entries())
+		.sort(([left], [right]) => left.localeCompare(right))
+		.map(([name, toolCount]) => ({ name, toolCount }));
+	return {
+		servers,
+		toolCount: tools.length,
+	};
+}
+
+export function buildDiscoverableMCPSearchIndex(tools: Iterable<DiscoverableMCPTool>): DiscoverableMCPSearchIndex {
+	const documents = Array.from(tools, buildSearchDocument);
+	const averageLength = documents.reduce((sum, document) => sum + document.length, 0) / documents.length || 1;
+	const documentFrequencies = new Map<string, number>();
+	for (const document of documents) {
+		for (const token of new Set(document.termFrequencies.keys())) {
+			documentFrequencies.set(token, (documentFrequencies.get(token) ?? 0) + 1);
+		}
+	}
+	return {
+		documents,
+		averageLength,
+		documentFrequencies,
+	};
+}
+
+export function searchDiscoverableMCPTools(
+	index: DiscoverableMCPSearchIndex,
+	query: string,
+	limit: number,
+): DiscoverableMCPSearchResult[] {
+	const queryTokens = tokenize(query);
+	if (queryTokens.length === 0) {
+		throw new Error("Query must contain at least one letter or number.");
+	}
+	if (index.documents.length === 0) {
+		return [];
+	}
+
+	const queryTermCounts = new Map<string, number>();
+	for (const token of queryTokens) {
+		queryTermCounts.set(token, (queryTermCounts.get(token) ?? 0) + 1);
+	}
+
+	return index.documents
+		.map(document => {
+			let score = 0;
+			for (const [token, queryTermCount] of queryTermCounts) {
+				const termFrequency = document.termFrequencies.get(token) ?? 0;
+				if (termFrequency === 0) continue;
+				const documentFrequency = index.documentFrequencies.get(token) ?? 0;
+				const idf = Math.log(1 + (index.documents.length - documentFrequency + 0.5) / (documentFrequency + 0.5));
+				const normalization = BM25_K1 * (1 - BM25_B + BM25_B * (document.length / index.averageLength));
+				score += queryTermCount * idf * ((termFrequency * (BM25_K1 + 1)) / (termFrequency + normalization));
+			}
+			return { tool: document.tool, score };
+		})
+		.filter(result => result.score > 0)
+		.sort((left, right) => right.score - left.score || left.tool.name.localeCompare(right.tool.name))
+		.slice(0, limit);
+}

package/src/prompts/system/system-prompt.md

@@ -155,6 +155,13 @@ You **MUST** use the following tools, as effectively as possible, to complete th
 {{/each}}
 {{/if}}
 
+{{#if mcpDiscoveryMode}}
+### MCP tool discovery
+
+Some MCP tools are intentionally hidden from the initial tool list.
+{{#if hasMCPDiscoveryServers}}Discoverable MCP servers in this session: {{#list mcpDiscoveryServerSummaries join=", "}}{{this}}{{/list}}.{{/if}}
+If the task may involve external systems, SaaS APIs, chat, tickets, databases, deployments, or other non-local integrations, you **SHOULD** call `search_tool_bm25` before concluding no such tool exists.
+{{/if}}
 ## Precedence
 {{#ifAny (includes tools "python") (includes tools "bash")}}
 Pick the right tool for the job:

package/src/prompts/tools/search-tool-bm25.md

@@ -0,0 +1,34 @@
+Search hidden MCP tool metadata when MCP tool discovery is enabled.
+
+Use this tool to discover MCP tools that are loaded into the session but not exposed to the model by default.
+
+{{#if hasDiscoverableMCPServers}}Discoverable MCP servers in this session: {{#list discoverableMCPServerSummaries join=", "}}{{this}}{{/list}}.{{/if}}
+{{#if discoverableMCPToolCount}}Total discoverable MCP tools loaded: {{discoverableMCPToolCount}}.{{/if}}
+Input:
+- `query` — required natural-language or keyword query
+- `limit` — optional maximum number of tools to return and activate (default `8`)
+
+Behavior:
+- Searches hidden MCP tool metadata using BM25-style relevance ranking
+- Matches against MCP tool name, server name, description, and input schema keys
+- Activates the top matching MCP tools for the rest of the current session
+- Repeated searches add to the active MCP tool set; they do not remove earlier selections
+- Newly activated MCP tools become available before the next model call in the same overall turn
+
+Notes:
+- If you are unsure, start with `limit` between 5 and 10 to see a broader set of tools.
+- `query` is matched against MCP tool metadata fields:
+  - `name`
+  - `label`
+  - `server_name`
+  - `mcp_tool_name`
+  - `description`
+  - input schema property keys (`schema_keys`)
+
+This is not repository search, file search, or code search. Use it only for MCP tool discovery.
+
+Returns JSON with:
+- `query`
+- `activated_tools` — MCP tools activated by this search call
+- `match_count` — number of ranked matches returned by the search
+- `total_tools`

package/src/sdk.ts

@@ -65,6 +65,11 @@ import {
 } from "./internal-urls";
 import { disposeAllKernelSessions } from "./ipy/executor";
 import { discoverAndLoadMCPTools, type MCPManager, type MCPToolsLoadResult } from "./mcp";
+import {
+	collectDiscoverableMCPTools,
+	formatDiscoverableMCPToolServerSummary,
+	summarizeDiscoverableMCPTools,
+} from "./mcp/discoverable-tool-metadata";
 import { buildMemoryToolDeveloperInstructions, getMemoryRoot, startMemoryStartupTask } from "./memories";
 import asyncResultTemplate from "./prompts/tools/async-result.md" with { type: "text" };
 import { collectEnvSecrets, loadSecrets, obfuscateMessages, SecretObfuscator } from "./secrets";
@@ -76,6 +81,7 @@ import { closeAllConnections } from "./ssh/connection-manager";
 import { unmountAll } from "./ssh/sshfs-mount";
 import {
 	buildSystemPrompt as buildSystemPromptInternal,
+	buildSystemPromptToolMetadata,
 	loadProjectContextFiles as loadContextFilesInternal,
 } from "./system-prompt";
 import { AgentOutputManager } from "./task/output-manager";
@@ -95,6 +101,7 @@ import {
 	PythonTool,
 	ReadTool,
 	ResolveTool,
+	renderSearchToolBm25Description,
 	setPreferredCodeSearchProvider,
 	setPreferredImageProvider,
 	setPreferredSearchProvider,
@@ -864,6 +871,11 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		getCompactContext: () => session.formatCompactContext(),
 		getTodoPhases: () => session.getTodoPhases(),
 		setTodoPhases: phases => session.setTodoPhases(phases),
+		isMCPDiscoveryEnabled: () => session.isMCPDiscoveryEnabled(),
+		getDiscoverableMCPTools: () => session.getDiscoverableMCPTools(),
+		getDiscoverableMCPSearchIndex: () => session.getDiscoverableMCPSearchIndex(),
+		getSelectedMCPToolNames: () => session.getSelectedMCPToolNames(),
+		activateDiscoveredMCPTools: toolNames => session.activateDiscoveredMCPTools(toolNames),
 		getCheckpointState: () => session.getCheckpointState(),
 		setCheckpointState: state => session.setCheckpointState(state ?? undefined),
 		allocateOutputArtifact: async toolType => {
@@ -1189,6 +1201,13 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	const intentField = settings.get("tools.intentTracing") || $env.PI_INTENT_TRACING === "1" ? INTENT_FIELD : undefined;
 	const rebuildSystemPrompt = async (toolNames: string[], tools: Map<string, AgentTool>): Promise<string> => {
 		toolContextStore.setToolNames(toolNames);
+		const discoverableMCPTools = mcpDiscoveryEnabled ? collectDiscoverableMCPTools(tools.values()) : [];
+		const discoverableMCPSummary = summarizeDiscoverableMCPTools(discoverableMCPTools);
+		const hasDiscoverableMCPTools =
+			mcpDiscoveryEnabled && toolNames.includes("search_tool_bm25") && discoverableMCPTools.length > 0;
+		const promptTools = buildSystemPromptToolMetadata(tools, {
+			search_tool_bm25: { description: renderSearchToolBm25Description(discoverableMCPTools) },
+		});
 		const memoryInstructions = await buildMemoryToolDeveloperInstructions(agentDir, settings);
 
 		// Build combined append prompt: memory instructions + MCP server instructions
@@ -1214,14 +1233,16 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			cwd,
 			skills,
 			contextFiles,
-			tools,
+			tools: promptTools,
 			toolNames,
 			rules: rulebookRules,
 			skillsSettings: settings.getGroup("skills"),
 			appendSystemPrompt: appendPrompt,
 			repeatToolDescriptions,
-			eagerTasks,
 			intentField,
+			mcpDiscoveryMode: hasDiscoverableMCPTools,
+			mcpDiscoveryServerSummaries: discoverableMCPSummary.servers.map(formatDiscoverableMCPToolServerSummary),
+			eagerTasks,
 		});
 
 		if (options.systemPrompt === undefined) {
@@ -1232,15 +1253,17 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				cwd,
 				skills,
 				contextFiles,
-				tools,
+				tools: promptTools,
 				toolNames,
 				rules: rulebookRules,
 				skillsSettings: settings.getGroup("skills"),
 				customPrompt: options.systemPrompt,
 				appendSystemPrompt: appendPrompt,
 				repeatToolDescriptions,
-				eagerTasks,
 				intentField,
+				mcpDiscoveryMode: hasDiscoverableMCPTools,
+				mcpDiscoveryServerSummaries: discoverableMCPSummary.servers.map(formatDiscoverableMCPToolServerSummary),
+				eagerTasks,
 			});
 		}
 		return options.systemPrompt(defaultPrompt);
@@ -1250,9 +1273,17 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	const requestedToolNames = options.toolNames?.map(name => name.toLowerCase()) ?? toolNamesFromRegistry;
 	const normalizedRequested = requestedToolNames.filter(name => toolRegistry.has(name));
 	const includeExitPlanMode = requestedToolNames.includes("exit_plan_mode");
-	const initialToolNames = includeExitPlanMode
+	const mcpDiscoveryEnabled = settings.get("mcp.discoveryMode") ?? false;
+	const requestedActiveToolNames = includeExitPlanMode
 		? normalizedRequested
 		: normalizedRequested.filter(name => name !== "exit_plan_mode");
+	const explicitlyRequestedMCPToolNames = options.toolNames
+		? requestedActiveToolNames.filter(name => name.startsWith("mcp_"))
+		: [];
+	const initialToolNames = mcpDiscoveryEnabled
+		? [...requestedActiveToolNames.filter(name => !name.startsWith("mcp_")), ...explicitlyRequestedMCPToolNames]
+		: [...requestedActiveToolNames];
+	const initialSelectedMCPToolNames = mcpDiscoveryEnabled ? [...explicitlyRequestedMCPToolNames] : [];
 
 	// Custom tools and extension-registered tools are always included regardless of toolNames filter
 	const alwaysInclude: string[] = [
@@ -1260,6 +1291,9 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		...registeredTools.map(t => t.definition.name),
 	];
 	for (const name of alwaysInclude) {
+		if (mcpDiscoveryEnabled && name.startsWith("mcp_")) {
+			continue;
+		}
 		if (toolRegistry.has(name) && !initialToolNames.includes(name)) {
 			initialToolNames.push(name);
 		}
@@ -1440,6 +1474,8 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		onPayload,
 		convertToLlm: convertToLlmFinal,
 		rebuildSystemPrompt,
+		mcpDiscoveryEnabled,
+		initialSelectedMCPToolNames,
 		ttsrManager,
 		obfuscator,
 		asyncJobManager,

package/src/session/agent-session.ts

@@ -87,6 +87,13 @@ import type { Skill, SkillWarning } from "../extensibility/skills";
 import { expandSlashCommand, type FileSlashCommand } from "../extensibility/slash-commands";
 import { resolveLocalUrlToPath } from "../internal-urls";
 import { executePython as executePythonCommand, type PythonResult } from "../ipy/executor";
+import {
+	buildDiscoverableMCPSearchIndex,
+	collectDiscoverableMCPTools,
+	type DiscoverableMCPSearchIndex,
+	type DiscoverableMCPTool,
+	isMCPToolName,
+} from "../mcp/discoverable-tool-metadata";
 import { getCurrentThemeName, theme } from "../modes/theme/theme";
 import { normalizeDiff, normalizeToLF, ParseError, previewPatch, stripBom } from "../patch";
 import type { PlanModeState } from "../plan-mode/state";
@@ -206,6 +213,10 @@ export interface AgentSessionConfig {
 	convertToLlm?: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
 	/** System prompt builder that can consider tool availability */
 	rebuildSystemPrompt?: (toolNames: string[], tools: Map<string, AgentTool>) => Promise<string>;
+	/** Enable hidden-by-default MCP tool discovery for this session. */
+	mcpDiscoveryEnabled?: boolean;
+	/** MCP tool names previously selected via discovery in this session. */
+	initialSelectedMCPToolNames?: string[];
 	/** TTSR manager for time-traveling stream rules */
 	ttsrManager?: TtsrManager;
 	/** Secret obfuscator for deobfuscating streaming edit content */
@@ -400,6 +411,10 @@ export class AgentSession {
 	#convertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
 	#rebuildSystemPrompt: ((toolNames: string[], tools: Map<string, AgentTool>) => Promise<string>) | undefined;
 	#baseSystemPrompt: string;
+	#mcpDiscoveryEnabled = false;
+	#discoverableMCPTools = new Map<string, DiscoverableMCPTool>();
+	#discoverableMCPSearchIndex: DiscoverableMCPSearchIndex | null = null;
+	#selectedMCPToolNames = new Set<string>();
 
 	// TTSR manager for time-traveling stream rules
 	#ttsrManager: TtsrManager | undefined = undefined;
@@ -446,6 +461,10 @@ export class AgentSession {
 		this.#convertToLlm = config.convertToLlm ?? convertToLlm;
 		this.#rebuildSystemPrompt = config.rebuildSystemPrompt;
 		this.#baseSystemPrompt = this.agent.state.systemPrompt;
+		this.#mcpDiscoveryEnabled = config.mcpDiscoveryEnabled ?? false;
+		this.#setDiscoverableMCPTools(this.#collectDiscoverableMCPToolsFromRegistry());
+		this.#selectedMCPToolNames = new Set(config.initialSelectedMCPToolNames ?? []);
+		this.#pruneSelectedMCPToolNames();
 		this.#ttsrManager = config.ttsrManager;
 		this.#obfuscator = config.obfuscator;
 		this.agent.providerSessionState = this.#providerSessionState;
@@ -1604,6 +1623,36 @@ export class AgentSession {
 		return this.#retryAttempt;
 	}
 
+	#collectDiscoverableMCPToolsFromRegistry(): Map<string, DiscoverableMCPTool> {
+		return new Map(collectDiscoverableMCPTools(this.#toolRegistry.values()).map(tool => [tool.name, tool] as const));
+	}
+
+	#setDiscoverableMCPTools(discoverableMCPTools: Map<string, DiscoverableMCPTool>): void {
+		this.#discoverableMCPTools = discoverableMCPTools;
+		this.#discoverableMCPSearchIndex = null;
+	}
+
+	#pruneSelectedMCPToolNames(): void {
+		for (const name of Array.from(this.#selectedMCPToolNames)) {
+			if (!this.#discoverableMCPTools.has(name) || !this.#toolRegistry.has(name)) {
+				this.#selectedMCPToolNames.delete(name);
+			}
+		}
+	}
+
+	#getVisibleMCPToolNames(): string[] {
+		if (!this.#mcpDiscoveryEnabled) {
+			return Array.from(this.#toolRegistry.keys()).filter(name => isMCPToolName(name));
+		}
+		return Array.from(this.#selectedMCPToolNames).filter(
+			name => this.#discoverableMCPTools.has(name) && this.#toolRegistry.has(name),
+		);
+	}
+
+	#getActiveNonMCPToolNames(): string[] {
+		return this.getActiveToolNames().filter(name => !isMCPToolName(name) && this.#toolRegistry.has(name));
+	}
+
 	/**
 	 * Get the names of currently active tools.
 	 * Returns the names of tools currently set on the agent.
@@ -1631,11 +1680,52 @@ export class AgentSession {
 		return Array.from(this.#toolRegistry.keys());
 	}
 
+	isMCPDiscoveryEnabled(): boolean {
+		return this.#mcpDiscoveryEnabled;
+	}
+
+	getDiscoverableMCPTools(): DiscoverableMCPTool[] {
+		return Array.from(this.#discoverableMCPTools.values());
+	}
+
+	getDiscoverableMCPSearchIndex(): DiscoverableMCPSearchIndex {
+		if (!this.#discoverableMCPSearchIndex) {
+			this.#discoverableMCPSearchIndex = buildDiscoverableMCPSearchIndex(this.#discoverableMCPTools.values());
+		}
+		return this.#discoverableMCPSearchIndex;
+	}
+
+	getSelectedMCPToolNames(): string[] {
+		if (!this.#mcpDiscoveryEnabled) {
+			return this.getActiveToolNames().filter(name => isMCPToolName(name) && this.#toolRegistry.has(name));
+		}
+		return Array.from(this.#selectedMCPToolNames).filter(
+			name => this.#discoverableMCPTools.has(name) && this.#toolRegistry.has(name),
+		);
+	}
+
+	async activateDiscoveredMCPTools(toolNames: string[]): Promise<string[]> {
+		const activated: string[] = [];
+		for (const name of toolNames) {
+			if (!isMCPToolName(name) || !this.#discoverableMCPTools.has(name) || !this.#toolRegistry.has(name)) {
+				continue;
+			}
+			this.#selectedMCPToolNames.add(name);
+			activated.push(name);
+		}
+		if (activated.length === 0) {
+			return [];
+		}
+		const nextActive = [...this.#getActiveNonMCPToolNames(), ...this.#getVisibleMCPToolNames()];
+		await this.setActiveToolsByName(nextActive);
+		return [...new Set(activated)];
+	}
+
 	/**
 	 * Set active tools by name.
 	 * Only tools in the registry can be enabled. Unknown tool names are ignored.
 	 * Also rebuilds the system prompt to reflect the new tool set.
-	 * Changes take effect on the next agent turn.
+	 * Changes take effect before the next model call.
 	 */
 	async setActiveToolsByName(toolNames: string[]): Promise<void> {
 		const tools: AgentTool[] = [];
@@ -1647,6 +1737,13 @@ export class AgentSession {
 				validToolNames.push(name);
 			}
 		}
+		if (this.#mcpDiscoveryEnabled) {
+			this.#selectedMCPToolNames = new Set(
+				validToolNames.filter(
+					name => isMCPToolName(name) && this.#discoverableMCPTools.has(name) && this.#toolRegistry.has(name),
+				),
+			);
+		}
 		this.agent.setTools(tools);
 
 		// Rebuild base system prompt with new tool set
@@ -1665,14 +1762,13 @@ export class AgentSession {
 	}
 
 	/**
-	 * Replace MCP tools in the registry and activate the latest MCP tool set immediately.
+	 * Replace MCP tools in the registry and recompute the visible MCP tool set immediately.
 	 * This allows /mcp add/remove/reauth to take effect without restarting the session.
 	 */
 	async refreshMCPTools(mcpTools: CustomTool[]): Promise<void> {
-		const prefix = "mcp_";
 		const existingNames = Array.from(this.#toolRegistry.keys());
 		for (const name of existingNames) {
-			if (name.startsWith(prefix)) {
+			if (isMCPToolName(name)) {
 				this.#toolRegistry.delete(name);
 			}
 		}
@@ -1696,17 +1792,10 @@ export class AgentSession {
 			this.#toolRegistry.set(finalTool.name, finalTool);
 		}
 
-		const currentActive = this.getActiveToolNames().filter(
-			name => !name.startsWith(prefix) && this.#toolRegistry.has(name),
-		);
-		const mcpToolNames = Array.from(this.#toolRegistry.keys()).filter(name => name.startsWith(prefix));
-		const nextActive = [...currentActive];
-		for (const name of mcpToolNames) {
-			if (!nextActive.includes(name)) {
-				nextActive.push(name);
-			}
-		}
+		this.#setDiscoverableMCPTools(this.#collectDiscoverableMCPToolsFromRegistry());
+		this.#pruneSelectedMCPToolNames();
 
+		const nextActive = [...this.#getActiveNonMCPToolNames(), ...this.getSelectedMCPToolNames()];
 		await this.setActiveToolsByName(nextActive);
 	}
 

package/src/system-prompt.ts

@@ -5,6 +5,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import type { AgentTool } from "@oh-my-pi/pi-agent-core";
 import { $env, getGpuCachePath, getProjectDir, hasFsCode, isEnoent, logger } from "@oh-my-pi/pi-utils";
 import { $ } from "bun";
 import { contextFileCapability } from "./capability/context-file";
@@ -315,11 +316,36 @@ export async function loadSystemPromptFiles(options: LoadContextFilesOptions = {
 	return parts.join("\n\n");
 }
 
+export interface SystemPromptToolMetadata {
+	label: string;
+	description: string;
+}
+
+export function buildSystemPromptToolMetadata(
+	tools: Map<string, AgentTool>,
+	overrides: Partial<Record<string, Partial<SystemPromptToolMetadata>>> = {},
+): Map<string, SystemPromptToolMetadata> {
+	return new Map(
+		Array.from(tools.entries(), ([name, tool]) => {
+			const toolRecord = tool as AgentTool & { label?: string; description?: string };
+			const override = overrides[name];
+			return [
+				name,
+				{
+					label: override?.label ?? (typeof toolRecord.label === "string" ? toolRecord.label : ""),
+					description:
+						override?.description ?? (typeof toolRecord.description === "string" ? toolRecord.description : ""),
+				},
+			] as const;
+		}),
+	);
+}
+
 export interface BuildSystemPromptOptions {
 	/** Custom system prompt (replaces default). */
 	customPrompt?: string;
 	/** Tools to include in prompt. */
-	tools?: Map<string, { description: string; label: string }>;
+	tools?: Map<string, SystemPromptToolMetadata>;
 	/** Tool names to include in prompt. */
 	toolNames?: string[];
 	/** Text to append to system prompt. */
@@ -338,6 +364,10 @@ export interface BuildSystemPromptOptions {
 	rules?: Array<{ name: string; description?: string; path: string; globs?: string[] }>;
 	/** Intent field name injected into every tool schema. If set, explains the field in the prompt. */
 	intentField?: string;
+	/** Whether MCP tool discovery is active for this prompt build. */
+	mcpDiscoveryMode?: boolean;
+	/** Discoverable MCP server summaries to advertise when discovery mode is active. */
+	mcpDiscoveryServerSummaries?: string[];
 	/** Encourage the agent to delegate via tasks unless changes are trivial. */
 	eagerTasks?: boolean;
 }
@@ -360,6 +390,8 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		skills: providedSkills,
 		rules,
 		intentField,
+		mcpDiscoveryMode = false,
+		mcpDiscoveryServerSummaries = [],
 		eagerTasks = false,
 	} = options;
 	const resolvedCwd = cwd ?? getProjectDir();
@@ -494,6 +526,9 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		cwd: promptCwd,
 		intentTracing: !!intentField,
 		intentField: intentField ?? "",
+		mcpDiscoveryMode,
+		hasMCPDiscoveryServers: mcpDiscoveryServerSummaries.length > 0,
+		mcpDiscoveryServerSummaries,
 		eagerTasks,
 	};
 	return renderPromptTemplate(resolvedCustomPrompt ? customSystemPromptTemplate : systemPromptTemplate, data);

package/src/tools/index.ts

@@ -8,6 +8,7 @@ import type { InternalUrlRouter } from "../internal-urls";
 import { getPreludeDocs, warmPythonEnvironment } from "../ipy/executor";
 import { checkPythonKernelAvailability } from "../ipy/kernel";
 import { LspTool } from "../lsp";
+import type { DiscoverableMCPSearchIndex, DiscoverableMCPTool } from "../mcp/discoverable-tool-metadata";
 import { EditTool } from "../patch";
 import type { PlanModeState } from "../plan-mode/state";
 import { TaskTool } from "../task";
@@ -35,6 +36,7 @@ import { ReadTool } from "./read";
 import { RenderMermaidTool } from "./render-mermaid";
 import { ResolveTool } from "./resolve";
 import { reportFindingTool } from "./review";
+import { SearchToolBm25Tool } from "./search-tool-bm25";
 import { loadSshTool } from "./ssh";
 import { SubmitResultTool } from "./submit-result";
 import { type TodoPhase, TodoWriteTool } from "./todo-write";
@@ -71,6 +73,7 @@ export * from "./read";
 export * from "./render-mermaid";
 export * from "./resolve";
 export * from "./review";
+export * from "./search-tool-bm25";
 export * from "./ssh";
 export * from "./submit-result";
 export * from "./todo-write";
@@ -85,6 +88,8 @@ export type ContextFileEntry = {
 	depth?: number;
 };
 
+export type { DiscoverableMCPTool } from "../mcp/discoverable-tool-metadata";
+
 /** Session context for tool factories */
 export interface ToolSession {
 	/** Current working directory */
@@ -147,6 +152,16 @@ export interface ToolSession {
 	getTodoPhases?: () => TodoPhase[];
 	/** Replace cached todo phases for this session. */
 	setTodoPhases?: (phases: TodoPhase[]) => void;
+	/** Whether MCP tool discovery is active for this session. */
+	isMCPDiscoveryEnabled?: () => boolean;
+	/** Get hidden-but-discoverable MCP tools for search_tool_bm25 prompts and fallbacks. */
+	getDiscoverableMCPTools?: () => DiscoverableMCPTool[];
+	/** Get the cached discoverable MCP search index for search_tool_bm25 execution. */
+	getDiscoverableMCPSearchIndex?: () => DiscoverableMCPSearchIndex;
+	/** Get MCP tools activated by prior search_tool_bm25 calls. */
+	getSelectedMCPToolNames?: () => string[];
+	/** Merge MCP tool selections into the active session tool set. */
+	activateDiscoveredMCPTools?: (toolNames: string[]) => Promise<string[]>;
 	/** Pending action store for preview/apply workflows */
 	pendingActionStore?: import("./pending-action").PendingActionStore;
 	/** Get active checkpoint state if any. */
@@ -182,6 +197,7 @@ export const BUILTIN_TOOLS: Record<string, ToolFactory> = {
 	todo_write: s => new TodoWriteTool(s),
 	fetch: s => new FetchTool(s),
 	web_search: s => new SearchTool(s),
+	search_tool_bm25: SearchToolBm25Tool.createIf,
 	write: s => new WriteTool(s),
 };
 
@@ -319,6 +335,7 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 		if (name === "inspect_image") return session.settings.get("inspect_image.enabled");
 		if (name === "fetch") return session.settings.get("fetch.enabled");
 		if (name === "web_search") return session.settings.get("web_search.enabled");
+		if (name === "search_tool_bm25") return session.settings.get("mcp.discoveryMode");
 		if (name === "lsp") return session.settings.get("lsp.enabled");
 		if (name === "calc") return session.settings.get("calc.enabled");
 		if (name === "browser") return session.settings.get("browser.enabled");

package/src/tools/renderers.ts

@@ -23,6 +23,7 @@ import { notebookToolRenderer } from "./notebook";
 import { pythonToolRenderer } from "./python";
 import { readToolRenderer } from "./read";
 import { resolveToolRenderer } from "./resolve";
+import { searchToolBm25Renderer } from "./search-tool-bm25";
 import { sshToolRenderer } from "./ssh";
 import { todoWriteToolRenderer } from "./todo-write";
 import { writeToolRenderer } from "./write";
@@ -55,6 +56,7 @@ export const toolRenderers: Record<string, ToolRenderer> = {
 	inspect_image: inspectImageToolRenderer as ToolRenderer,
 	read: readToolRenderer as ToolRenderer,
 	resolve: resolveToolRenderer as ToolRenderer,
+	search_tool_bm25: searchToolBm25Renderer as ToolRenderer,
 	ssh: sshToolRenderer as ToolRenderer,
 	task: taskToolRenderer as ToolRenderer,
 	todo_write: todoWriteToolRenderer as ToolRenderer,

package/src/tools/search-tool-bm25.ts

@@ -0,0 +1,278 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import { type Component, Text } from "@oh-my-pi/pi-tui";
+import { type Static, Type } from "@sinclair/typebox";
+import { renderPromptTemplate } from "../config/prompt-templates";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import {
+	buildDiscoverableMCPSearchIndex,
+	type DiscoverableMCPSearchIndex,
+	type DiscoverableMCPTool,
+	formatDiscoverableMCPToolServerSummary,
+	searchDiscoverableMCPTools,
+	summarizeDiscoverableMCPTools,
+} from "../mcp/discoverable-tool-metadata";
+import type { Theme } from "../modes/theme/theme";
+import searchToolBm25Description from "../prompts/tools/search-tool-bm25.md" with { type: "text" };
+import { renderStatusLine, renderTreeList, truncateToWidth } from "../tui";
+import type { ToolSession } from ".";
+import { formatCount, replaceTabs, TRUNCATE_LENGTHS } from "./render-utils";
+import { ToolError } from "./tool-errors";
+
+const DEFAULT_LIMIT = 8;
+const TOOL_DISCOVERY_TITLE = "Tool Discovery";
+const COLLAPSED_MATCH_LIMIT = 5;
+const MATCH_LABEL_LEN = 72;
+const MATCH_DESCRIPTION_LEN = 96;
+
+const searchToolBm25Schema = Type.Object({
+	query: Type.String({ description: "Search query for hidden MCP tool metadata" }),
+	limit: Type.Optional(
+		Type.Integer({ description: "Max matching tools to activate and return (default 8)", minimum: 1 }),
+	),
+});
+
+type SearchToolBm25Params = Static<typeof searchToolBm25Schema>;
+
+interface SearchToolBm25Match {
+	name: string;
+	label: string;
+	description: string;
+	server_name?: string;
+	mcp_tool_name?: string;
+	schema_keys: string[];
+	score: number;
+}
+
+export interface SearchToolBm25Details {
+	query: string;
+	limit: number;
+	total_tools: number;
+	activated_tools: string[];
+	active_selected_tools: string[];
+	tools: SearchToolBm25Match[];
+}
+
+function formatMatch(tool: DiscoverableMCPTool, score: number): SearchToolBm25Match {
+	return {
+		name: tool.name,
+		label: tool.label,
+		description: tool.description,
+		server_name: tool.serverName,
+		mcp_tool_name: tool.mcpToolName,
+		schema_keys: tool.schemaKeys,
+		score: Number(score.toFixed(6)),
+	};
+}
+
+function buildSearchToolBm25Content(details: SearchToolBm25Details): string {
+	return JSON.stringify({
+		query: details.query,
+		activated_tools: details.activated_tools,
+		match_count: details.tools.length,
+		total_tools: details.total_tools,
+	});
+}
+
+function getDiscoverableMCPToolsForDescription(session: ToolSession): DiscoverableMCPTool[] {
+	try {
+		return session.getDiscoverableMCPTools?.() ?? [];
+	} catch {
+		return [];
+	}
+}
+
+function getDiscoverableMCPSearchIndexForExecution(session: ToolSession): DiscoverableMCPSearchIndex {
+	try {
+		const cached = session.getDiscoverableMCPSearchIndex?.();
+		if (cached) return cached;
+	} catch {}
+	return buildDiscoverableMCPSearchIndex(session.getDiscoverableMCPTools?.() ?? []);
+}
+
+type MCPDiscoveryExecutionSession = ToolSession & {
+	isMCPDiscoveryEnabled: () => boolean;
+	getSelectedMCPToolNames: () => string[];
+	activateDiscoveredMCPTools: (toolNames: string[]) => Promise<string[]>;
+};
+
+function supportsMCPToolDiscoveryExecution(session: ToolSession): session is MCPDiscoveryExecutionSession {
+	return (
+		typeof session.isMCPDiscoveryEnabled === "function" &&
+		typeof session.getSelectedMCPToolNames === "function" &&
+		typeof session.activateDiscoveredMCPTools === "function"
+	);
+}
+
+export function renderSearchToolBm25Description(discoverableTools: DiscoverableMCPTool[] = []): string {
+	const summary = summarizeDiscoverableMCPTools(discoverableTools);
+	return renderPromptTemplate(searchToolBm25Description, {
+		discoverableMCPToolCount: summary.toolCount,
+		discoverableMCPServerSummaries: summary.servers.map(formatDiscoverableMCPToolServerSummary),
+		hasDiscoverableMCPServers: summary.servers.length > 0,
+	});
+}
+
+function renderMatchLines(match: SearchToolBm25Match, theme: Theme): string[] {
+	const safeServerName = match.server_name ? replaceTabs(match.server_name) : undefined;
+	const safeLabel = replaceTabs(match.label);
+	const safeDescription = replaceTabs(match.description.trim());
+	const metaParts: string[] = [];
+	if (safeServerName) metaParts.push(theme.fg("muted", safeServerName));
+	metaParts.push(theme.fg("dim", `score ${match.score.toFixed(3)}`));
+	const metaSep = theme.fg("dim", theme.sep.dot);
+	const metaSuffix = metaParts.length > 0 ? ` ${metaParts.join(metaSep)}` : "";
+	const lines = [`${theme.fg("accent", truncateToWidth(safeLabel, MATCH_LABEL_LEN))}${metaSuffix}`];
+	if (safeDescription) {
+		lines.push(theme.fg("muted", truncateToWidth(safeDescription, MATCH_DESCRIPTION_LEN)));
+	}
+	return lines;
+}
+
+function renderFallbackResult(text: string, theme: Theme): Component {
+	const header = renderStatusLine({ icon: "warning", title: TOOL_DISCOVERY_TITLE }, theme);
+	const bodyLines = (text || "Tool discovery completed")
+		.split("\n")
+		.map(line => theme.fg("dim", truncateToWidth(replaceTabs(line), TRUNCATE_LENGTHS.LINE)));
+	return new Text([header, ...bodyLines].join("\n"), 0, 0);
+}
+
+export class SearchToolBm25Tool implements AgentTool<typeof searchToolBm25Schema, SearchToolBm25Details> {
+	readonly name = "search_tool_bm25";
+	readonly label = "SearchToolBm25";
+	get description(): string {
+		return renderSearchToolBm25Description(getDiscoverableMCPToolsForDescription(this.session));
+	}
+	readonly parameters = searchToolBm25Schema;
+	readonly strict = true;
+
+	constructor(private readonly session: ToolSession) {}
+
+	static createIf(session: ToolSession): SearchToolBm25Tool | null {
+		if (!session.settings.get("mcp.discoveryMode")) return null;
+		return supportsMCPToolDiscoveryExecution(session) ? new SearchToolBm25Tool(session) : null;
+	}
+
+	async execute(
+		_toolCallId: string,
+		params: SearchToolBm25Params,
+		_signal?: AbortSignal,
+		_onUpdate?: AgentToolUpdateCallback<SearchToolBm25Details>,
+		_context?: AgentToolContext,
+	): Promise<AgentToolResult<SearchToolBm25Details>> {
+		if (!supportsMCPToolDiscoveryExecution(this.session)) {
+			throw new ToolError("MCP tool discovery is unavailable in this session.");
+		}
+		if (!this.session.isMCPDiscoveryEnabled()) {
+			throw new ToolError("MCP tool discovery is disabled. Enable mcp.discoveryMode to use search_tool_bm25.");
+		}
+
+		const query = params.query.trim();
+		if (query.length === 0) {
+			throw new ToolError("Query is required and must not be empty.");
+		}
+		const limit = params.limit ?? DEFAULT_LIMIT;
+		if (!Number.isInteger(limit) || limit <= 0) {
+			throw new ToolError("Limit must be a positive integer.");
+		}
+
+		const searchIndex = getDiscoverableMCPSearchIndexForExecution(this.session);
+		const selectedToolNames = new Set(this.session.getSelectedMCPToolNames());
+		let ranked: Array<{ tool: DiscoverableMCPTool; score: number }> = [];
+		try {
+			ranked = searchDiscoverableMCPTools(searchIndex, query, searchIndex.documents.length)
+				.filter(result => !selectedToolNames.has(result.tool.name))
+				.slice(0, limit);
+		} catch (error) {
+			if (error instanceof Error) {
+				throw new ToolError(error.message);
+			}
+			throw error;
+		}
+		const activated =
+			ranked.length > 0 ? await this.session.activateDiscoveredMCPTools(ranked.map(result => result.tool.name)) : [];
+
+		const details: SearchToolBm25Details = {
+			query,
+			limit,
+			total_tools: searchIndex.documents.length,
+			activated_tools: activated,
+			active_selected_tools: this.session.getSelectedMCPToolNames(),
+			tools: ranked.map(result => formatMatch(result.tool, result.score)),
+		};
+
+		return {
+			content: [{ type: "text", text: buildSearchToolBm25Content(details) }],
+			details,
+		};
+	}
+}
+
+export const searchToolBm25Renderer = {
+	renderCall(args: SearchToolBm25Params, _options: RenderResultOptions, uiTheme: Theme): Component {
+		const query = typeof args.query === "string" ? replaceTabs(args.query.trim()) : "";
+		const meta = args.limit ? [`limit:${args.limit}`] : [];
+		return new Text(
+			renderStatusLine(
+				{ icon: "pending", title: TOOL_DISCOVERY_TITLE, description: query || "(empty query)", meta },
+				uiTheme,
+			),
+			0,
+			0,
+		);
+	},
+
+	renderResult(
+		result: { content: Array<{ type: string; text?: string }>; details?: SearchToolBm25Details; isError?: boolean },
+		options: RenderResultOptions,
+		uiTheme: Theme,
+	): Component {
+		if (!result.details) {
+			const fallbackText = result.content
+				.filter(part => part.type === "text")
+				.map(part => part.text)
+				.filter((text): text is string => typeof text === "string" && text.length > 0)
+				.join("\n");
+			return renderFallbackResult(fallbackText, uiTheme);
+		}
+
+		const { details } = result;
+		const meta = [
+			formatCount("match", details.tools.length),
+			`${details.active_selected_tools.length} active`,
+			`${details.total_tools} total`,
+			`limit:${details.limit}`,
+		];
+		const safeQuery = replaceTabs(details.query);
+		const header = renderStatusLine(
+			{
+				icon: details.tools.length > 0 ? "success" : "warning",
+				title: TOOL_DISCOVERY_TITLE,
+				description: truncateToWidth(safeQuery, MATCH_LABEL_LEN),
+				meta,
+			},
+			uiTheme,
+		);
+		if (details.tools.length === 0) {
+			const emptyMessage =
+				details.total_tools === 0 ? "No discoverable MCP tools are currently loaded." : "No matching tools found.";
+			return new Text(`${header}\n${uiTheme.fg("muted", emptyMessage)}`, 0, 0);
+		}
+
+		const lines = [header];
+		const treeLines = renderTreeList(
+			{
+				items: details.tools,
+				expanded: options.expanded,
+				maxCollapsed: COLLAPSED_MATCH_LIMIT,
+				itemType: "tool",
+				renderItem: match => renderMatchLines(match, uiTheme),
+			},
+			uiTheme,
+		);
+		lines.push(...treeLines);
+		return new Text(lines.join("\n"), 0, 0);
+	},
+
+	mergeCallAndResult: true,
+	inline: true,
+};