From e029c3ed0add2ba55cc9c68b2bc3920e56d32888 Mon Sep 17 00:00:00 2001
From: Armin Ronacher <armin.ronacher@active-4.com>
Date: Wed, 30 Sep 2026 17:20:47 +0200
Subject: [PATCH] feat(coding-agent): stop waiting for MCP servers on the first
 prompt

The first prompt waits only for servers with direct tools. Other servers
connect in the background; codemode scripts, tool_search, and the
resource tools wait for the servers they need. codemode and tool_search
are activated from the config.

Tool declarations no longer depend on connected servers: the codemode
description leaves out deferred tools, and the tool_search description
no longer lists sources. Servers are listed in an mcp_servers system
prompt section instead, set in before_agent_start from the config and
connected state, so changes are appended to the conversation.

describeNamespace() and searchTools() accept mcp__dev-radius,
mcp__dev_radius, dev-radius, and dev_radius.

closes #10212
---
 packages/coding-agent/CHANGELOG.md            |   7 +-
 packages/coding-agent/docs/cli.md             |   2 +-
 packages/coding-agent/docs/extensions.md      |   2 +-
 packages/coding-agent/docs/mcp.md             |   8 +-
 packages/coding-agent/src/core/mcp-servers.ts |   4 +-
 .../src/extensions/codemode/execute.ts        |  17 +-
 .../src/extensions/codemode/tool.ts           |  47 ++--
 .../coding-agent/src/extensions/mcp/cli.ts    |   2 +-
 .../coding-agent/src/extensions/mcp/index.ts  | 254 ++++++++++++++---
 .../src/extensions/tool-search/tool.ts        |  31 +--
 .../coding-agent/test/mcp-extension.test.ts   |  44 +++
 .../test/suite/agent-session-mcp.test.ts      | 261 +++++++++++++++---
 .../coding-agent/test/tool-search.test.ts     |  43 +--
 13 files changed, 550 insertions(+), 172 deletions(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 68721de9e..11bb59036 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -4,13 +4,14 @@
 
 ### Added
 
-- Added a `description` field for MCP servers (`pi mcp add --description`), shown next to the server in the `codemode` and `tool_search` descriptions, and a `describeNamespace(name)` codemode helper that returns a namespace's instructions and tool names.
+- Added a `description` field for MCP servers (`pi mcp add --description`), shown with the server in the system prompt and used to rank its tools in tool search, and a `describeNamespace(name)` codemode helper that returns a namespace's instructions and tool names. `describeNamespace()` and `searchTools()` accept a namespace as `mcp__dev-radius`, `mcp__dev_radius`, `dev-radius`, or `dev_radius`.
 - Added an `oauth.clientName` setting for MCP servers (`pi mcp add --oauth-client-name`) to change the client name sent during OAuth client registration, for servers such as Figma that only accept known clients ([#10226](https://github.com/earendil-works/pi/issues/10226)).
 
 ### Changed
 
-- MCP servers with the default `codemode` exposure no longer list their tools in the `codemode` description; scripts find them with `searchTools()`. `codemode-deferred` is now an alias for `codemode`. Use `direct` exposure for tools the model should see without searching ([#10212](https://github.com/earendil-works/pi/issues/10212)).
-- The `codemode` description no longer includes tool counts or MCP server instructions, so it no longer changes when a server's tool list changes. Scripts read server instructions with `describeNamespace()` ([#10212](https://github.com/earendil-works/pi/issues/10212)).
+- MCP servers with the default `codemode` exposure no longer appear in the `codemode` description; scripts find them with `searchTools()`. `codemode-deferred` is now an alias for `codemode`. Use `direct` exposure for tools the model should see without searching ([#10212](https://github.com/earendil-works/pi/issues/10212)).
+- The `codemode` description no longer includes deferred tools, tool counts, or MCP server instructions, so it no longer changes when MCP servers connect or change their tools. The `tool_search` description no longer lists the servers whose tools it can load, for the same reason. Servers are listed instead in an `mcp_servers` system prompt section with a one-line summary, updated at the start of each prompt; a changed section is appended to the conversation. Scripts read server instructions with `describeNamespace()` ([#10212](https://github.com/earendil-works/pi/issues/10212)).
+- The first prompt no longer waits for MCP servers without `direct` tools. They connect in the background and are waited for when a codemode script names them, a script searches tools, or `tool_search` runs ([#10212](https://github.com/earendil-works/pi/issues/10212)).
 
 ### Fixed
 
diff --git a/packages/coding-agent/docs/cli.md b/packages/coding-agent/docs/cli.md
index f9636193a..8e1300390 100644
--- a/packages/coding-agent/docs/cli.md
+++ b/packages/coding-agent/docs/cli.md
@@ -171,7 +171,7 @@ A script may start with an options line such as `// @options: {"max_output_token
 
 While `codemode` is active, `codemode.mode` in [settings](settings.md#tools) decides how the other tools are presented. With `on` (default) declared tools keep being declared and their descriptions show how to call them from scripts. With `only` they are hidden from the model and listed in the `codemode` description instead, so the model calls them through scripts.
 
-The `codemode` description lists the callable tools with their TypeScript declarations, grouped by namespace (for example one MCP server). Tools with `deferred` exposure, which includes MCP tools with the default `codemode` exposure, are not listed; their namespace is listed with its description. Declarations share a budget of 3000 estimated tokens (`codemode.inlineBudget` in [settings](settings.md#tools)), and the description says whether the list is complete. Scripts find the rest with `await searchTools(query, { limit, namespace })`, which ranks tools with BM25, and `await describeTool(name)`, or by filtering `ALL_TOOLS`. `await describeNamespace(name)` returns a namespace's description, its instructions (for MCP servers, the server instructions), and the names of its tools.
+The `codemode` description lists the callable tools with their TypeScript declarations, grouped by namespace (for example one MCP server). Tools with `deferred` exposure, which includes MCP tools with the default `codemode` exposure, are not listed and do not affect the description, so it stays the same while MCP servers connect. Declarations share a budget of 3000 estimated tokens (`codemode.inlineBudget` in [settings](settings.md#tools)). Scripts find the rest with `await searchTools(query, { limit, namespace })`, which ranks tools with BM25, and `await describeTool(name)`, or by filtering `ALL_TOOLS`. `await describeNamespace(name)` returns a namespace's description, its instructions (for MCP servers, the server instructions), and the names of its tools.
 
 Tools with an output schema resolve to structured values: `bash` to `{ output, truncated, full_output_path?, exit_code, wall_time_seconds }`, also for non-zero exit codes, and MCP tools to their `CallToolResult`. Other tools resolve to their text output. The `output` of `bash` is not limited to the 2000 lines or 50KB the model sees: it holds up to 1 MiB, and longer output keeps its first and last 512 KiB around an omission marker, with `truncated` set and the full output in `full_output_path`.
 
diff --git a/packages/coding-agent/docs/extensions.md b/packages/coding-agent/docs/extensions.md
index b5ee0d690..9ecc4d995 100644
--- a/packages/coding-agent/docs/extensions.md
+++ b/packages/coding-agent/docs/extensions.md
@@ -177,7 +177,7 @@ pi.on("tool_call", async (event, ctx) => {
 });
 ```
 
-A tool that orchestrates other tools can adjust what the model sees while it is active with `prepareLoadout(loadout)`. It runs whenever the active tools change and receives the declared tools, the callable tools, and every registered tool with its exposure and namespace. It returns replacement `descriptions` for declared tools (including its own) and `hiddenDeclarations`: active tools whose declarations requests leave out while they stay active and callable. `codemode` and `tool_search` use only this hook, `exposure`, and `ctx.executeTool()`, so another tool can implement the same behavior under a different name.
+A tool that orchestrates other tools can adjust what the model sees while it is active with `prepareLoadout(loadout)`. It runs whenever the active tools change and receives the declared tools, the callable tools, and every registered tool with its exposure and namespace. It returns replacement `descriptions` for declared tools (including its own) and `hiddenDeclarations`: active tools whose declarations requests leave out while they stay active and callable. `codemode` uses only this hook, `exposure`, and `ctx.executeTool()`, so another tool can implement the same behavior under a different name.
 
 ### Activate tools dynamically
 
diff --git a/packages/coding-agent/docs/mcp.md b/packages/coding-agent/docs/mcp.md
index 9435f1a1f..073481d55 100644
--- a/packages/coding-agent/docs/mcp.md
+++ b/packages/coding-agent/docs/mcp.md
@@ -58,7 +58,7 @@ Both server types support:
 - `timeout`: per-request timeout in seconds (default 60). Progress notifications reset it.
 - `enabled: false`: keep the entry without connecting to it.
 - `exposure` and `toolExposure`: control how tools reach the model (see [Control tool exposure](#control-tool-exposure)).
-- `description`: what the server offers, in a sentence. The `codemode` and `tool_search` descriptions show it next to the server, so the model knows what to search for.
+- `description`: what the server offers, in a sentence. It lists the server in the system prompt (see [Control tool exposure](#control-tool-exposure)), tool search ranks the server's tools by it, and codemode's `describeNamespace()` returns it. Without it, the first line of the server instructions is used once the server connects.
 
 Keep personal servers and servers with credentials in the user-level file. Use the project file only for servers the project requires, and only in trusted projects.
 
@@ -87,7 +87,7 @@ Run `pi mcp list` to connect to every enabled server and print its state, tools,
 
 Pi reports configuration errors, failed connections, and required sign-ins once after startup. Server logging notifications are appended to `~/.pi/agent/mcp.log` as `<time> [<server>] <level> <logger>: <message>`. The file moves to `mcp.log.1` after it grows past 5 MB.
 
-Pi connects when a session starts. The first prompt waits up to 10 seconds for startup connections; tools from slower servers become available when they connect. HTTP network errors and transient statuses (408, 429, and 5xx) are retried twice. A dropped connection is shown as disconnected and reconnects on the next call. When a server announces a changed tool list, new tools are added and withdrawn tools become unreachable.
+Pi connects every enabled server in the background when a session starts. A server's tools appear once it connects; the `codemode` description does not list them, so it does not change when servers connect. The first prompt waits up to 10 seconds only for servers with `direct` tools, which must be declared in its request. Other servers are waited for when they are needed: a codemode script waits for the servers it names (`mcp__<server>`) and, when it calls `searchTools()` or reads `ALL_TOOLS`, for all of them; `tool_search` and the resource tools also wait for all of them. HTTP network errors and transient statuses (408, 429, and 5xx) are retried twice. A dropped connection is shown as disconnected and reconnects on the next call. When a server announces a changed tool list, new tools are added and withdrawn tools become unreachable.
 
 Stopping a stdio server closes its stdin, sends SIGTERM, then sends SIGKILL to its process group. This also stops servers launched through wrappers such as `npx` or `uvx`.
 
@@ -153,13 +153,15 @@ Each server tool is registered as `mcp__<server>__<tool>`. The server's `exposur
 
 | Exposure | Behavior | Typical use |
 |---|---|---|
-| `codemode` (default) | Callable from [`codemode`](cli.md#tools) scripts, but neither declared to the model nor listed one by one. The codemode description lists the server with its `description`; scripts find tools with `searchTools()`, `describeTool()`, or `ALL_TOOLS`. | General MCP servers, especially when scripts should combine or filter calls. |
+| `codemode` (default) | Callable from [`codemode`](cli.md#tools) scripts, but neither declared to the model nor listed in the codemode description. Scripts find tools with `searchTools()`, `describeTool()`, or `ALL_TOOLS`. | General MCP servers, especially when scripts should combine or filter calls. |
 | `deferred` | Not declared until [`tool_search`](cli.md#tools) loads a match for the next model call. | Large servers whose tools should be called directly after discovery. |
 | `direct` | Declared to the model like a built-in tool and also callable from codemode. | Small, frequently used tool sets. |
 | `hidden` | Registered but unreachable. | Servers or tools that should remain unavailable. |
 
 `codemode-deferred` is accepted as an alias for `codemode`.
 
+Servers with `codemode` or `deferred` tools are listed in the `mcp_servers` section of the system prompt, with how their tools are reached and one line from the configured `description` or, once connected, from the server instructions. Pi updates the section when a prompt starts, after waiting for servers with `direct` tools. When it changed, for example because a server connected and its summary became available, Pi appends the new section to the conversation instead of changing tool declarations, so earlier messages stay cached. `describeNamespace()` and the `namespace` option of `searchTools()` accept `mcp__dev-radius`, `mcp__dev_radius`, `dev-radius`, or `dev_radius`.
+
 Pi activates `codemode` when a server with `codemode` exposure connects. It activates `tool_search` for a server with `deferred` exposure. To make the model see a tool without searching, give it `direct` exposure with `toolExposure`.
 
 `toolExposure` overrides the server exposure for individual tools. Keys are exact server tool names or patterns where `*` matches any characters. Exact names win over patterns; among patterns, the first match wins. A server with `hidden` exposure can expose only selected tools:
diff --git a/packages/coding-agent/src/core/mcp-servers.ts b/packages/coding-agent/src/core/mcp-servers.ts
index fa221f742..70e1b190b 100644
--- a/packages/coding-agent/src/core/mcp-servers.ts
+++ b/packages/coding-agent/src/core/mcp-servers.ts
@@ -25,8 +25,8 @@ interface McpServerConfigBase {
 	/** Default: `codemode`. */
 	exposure?: McpExposure;
 	/**
-	 * What the server offers, in a sentence. The codemode and `tool_search` descriptions show it next to
-	 * the server's namespace, so the model knows what to search for without connecting first.
+	 * What the server offers, in a sentence. The `mcp_servers` system prompt section lists the server
+	 * with it, tool search ranks the server's tools by it, and codemode's `describeNamespace()` returns it.
 	 */
 	description?: string;
 	/**
diff --git a/packages/coding-agent/src/extensions/codemode/execute.ts b/packages/coding-agent/src/extensions/codemode/execute.ts
index f5781fe32..e970f734d 100644
--- a/packages/coding-agent/src/extensions/codemode/execute.ts
+++ b/packages/coding-agent/src/extensions/codemode/execute.ts
@@ -319,6 +319,17 @@ export async function executeCodemode(
 	};
 }
 
+/**
+ * Whether `query` names the namespace: its name, its script identifier (`mcp__dev-radius` is
+ * `mcp__dev_radius`), or the part after its last `__` in either form (`dev-radius`, `dev_radius`).
+ */
+function isNamespaceName(namespace: string, query: string): boolean {
+	const id = toCodemodeIdentifier(namespace);
+	const queryId = toCodemodeIdentifier(query);
+	const suffix = (name: string) => (name.includes("__") ? name.slice(name.lastIndexOf("__") + 2) : undefined);
+	return namespace === query || id === queryId || suffix(namespace) === query || suffix(id) === queryId;
+}
+
 /**
  * `searchTools()`, `describeTool()`, and `describeNamespace()`: ranked search and lookup over the
  * script's nested tools and their namespaces.
@@ -347,7 +358,7 @@ function createDiscoveryGlobals(
 				}
 				const documents = tools.flatMap((tool) => {
 					const toolNamespace = options.getToolNamespace?.(tool.name);
-					if (namespace && toolNamespace?.name !== namespace) return [];
+					if (namespace && (!toolNamespace || !isNamespaceName(toolNamespace.name, namespace))) return [];
 					return [createToolSearchDocument(tool, toolNamespace)];
 				});
 				return ranker.rank(query, documents, limit).map((match) => entry(match.name));
@@ -375,13 +386,13 @@ function createDiscoveryGlobals(
 				const names: string[] = [];
 				for (const tool of tools) {
 					const toolNamespace = options.getToolNamespace?.(tool.name);
-					if (toolNamespace?.name !== name) continue;
+					if (!toolNamespace || !isNamespaceName(toolNamespace.name, name)) continue;
 					namespace ??= toolNamespace;
 					names.push(toCodemodeIdentifier(tool.name));
 				}
 				if (!namespace) return undefined;
 				return {
-					name,
+					name: namespace.name,
 					...(namespace.description ? { description: namespace.description } : {}),
 					...(namespace.instructions ? { instructions: namespace.instructions } : {}),
 					tools: names,
diff --git a/packages/coding-agent/src/extensions/codemode/tool.ts b/packages/coding-agent/src/extensions/codemode/tool.ts
index 06e9a4e00..602aeea3c 100644
--- a/packages/coding-agent/src/extensions/codemode/tool.ts
+++ b/packages/coding-agent/src/extensions/codemode/tool.ts
@@ -217,7 +217,7 @@ export const MODEL_GLOBAL_DECLARATIONS: readonly Omit<CodemodeTool, "execute">[]
 	},
 ];
 
-const DEFERRED_TOOLS_GUIDANCE = `Some deferred nested tools may be omitted from this description. They are still available on the global \`tools\` object and listed in \`ALL_TOOLS\`.
+const DEFERRED_TOOLS_GUIDANCE = `Some nested tools may be omitted from this description, such as deferred tools and MCP tools. They are still available on the global \`tools\` object and listed in \`ALL_TOOLS\`.
 To find one, call \`await searchTools(query)\` (pass \`{ namespace }\` to search one namespace), or filter \`ALL_TOOLS\` by \`name\` and \`description\`. \`await describeNamespace(name)\` returns a namespace's usage instructions and the names of its tools.`;
 
 /** Default for {@link CodemodeDescriptionOptions.inlineBudget}, in estimated tokens. */
@@ -265,7 +265,6 @@ interface CatalogEntry {
 	name: string;
 	section: string;
 	cost: number;
-	deferred: boolean;
 }
 
 interface CatalogGroup {
@@ -280,9 +279,8 @@ interface CatalogGroup {
  * represented before any namespace is complete.
  */
 function selectCatalog(groups: readonly CatalogGroup[], budget: number | undefined): Set<string> {
-	const listable = groups.map((group) => group.entries.filter((entry) => !entry.deferred));
-	if (budget === undefined) return new Set(listable.flat().map((entry) => entry.name));
-	const queues = listable.map((entries) => [...entries].sort((a, b) => a.cost - b.cost));
+	if (budget === undefined) return new Set(groups.flatMap((group) => group.entries.map((entry) => entry.name)));
+	const queues = groups.map((group) => [...group.entries].sort((a, b) => a.cost - b.cost));
 	const shown = new Set<string>();
 	let remaining = budget;
 	let active = queues.filter((queue) => queue.length > 0);
@@ -300,17 +298,19 @@ function selectCatalog(groups: readonly CatalogGroup[], budget: number | undefin
 }
 
 /**
- * Model-facing description: the helper list, guidance for omitted tools, the shared MCP types when
- * MCP tools are callable, the `models` API, and one section per tool, grouped by namespace. Tool
- * sections are limited to `inlineBudget`; every namespace is listed with its description either
- * way, and the listing states whether it is complete. It carries no tool counts or namespace
- * instructions, so it stays the same when a server's tool list changes.
+ * Model-facing description: the helper list, guidance for finding tools that are not listed, the
+ * shared MCP types when listed tools need them, the `models` API, and one section per listed tool,
+ * grouped by namespace. Deferred tools are never listed and do not affect the description at all, so
+ * it stays the same while MCP servers connect or change their tools. Tool sections are limited to
+ * `inlineBudget`.
  */
 export function createCodemodeDescription(
 	tools: readonly AgentTool<any>[],
 	options: CodemodeDescriptionOptions = {},
 ): string {
-	const declarations = getCodemodeCallableTools(tools).map(toCodemodeDeclaration);
+	const declarations = getCodemodeCallableTools(tools)
+		.filter((tool) => !options.deferred?.has(tool.name))
+		.map(toCodemodeDeclaration);
 	const groups = new Map<string, CatalogGroup>([["", { namespace: undefined, entries: [] }]]);
 	for (const declaration of declarations) {
 		const namespace = options.namespaces?.get(declaration.name);
@@ -318,22 +318,20 @@ export function createCodemodeDescription(
 		const group = groups.get(key) ?? { namespace, entries: [] };
 		groups.set(key, group);
 		const section = renderToolSection(declaration);
-		group.entries.push({
-			name: declaration.name,
-			section,
-			cost: Math.ceil(section.length / CHARS_PER_TOKEN),
-			deferred: options.deferred?.has(declaration.name) === true,
-		});
+		group.entries.push({ name: declaration.name, section, cost: Math.ceil(section.length / CHARS_PER_TOKEN) });
 	}
 	const ordered = [...groups.values()].sort((a, b) =>
 		a.namespace === undefined ? -1 : b.namespace === undefined ? 1 : a.namespace.name.localeCompare(b.namespace.name),
 	);
 	const shown = selectCatalog(ordered, options.inlineBudget);
-	const complete = shown.size === declarations.length;
 
-	const sections = [DESCRIPTION_INTRO];
-	if (!complete) sections.push(DEFERRED_TOOLS_GUIDANCE);
-	if (declarations.some((declaration) => mcpStructuredContentSchema(declaration.outputSchema) !== undefined)) {
+	const sections = [DESCRIPTION_INTRO, DEFERRED_TOOLS_GUIDANCE];
+	if (
+		declarations.some(
+			(declaration) =>
+				shown.has(declaration.name) && mcpStructuredContentSchema(declaration.outputSchema) !== undefined,
+		)
+	) {
 		sections.push(`Shared MCP Types:\n\`\`\`ts\n${MCP_TYPESCRIPT_PREAMBLE}\n\`\`\``);
 	}
 	if (options.models) {
@@ -345,14 +343,11 @@ export function createCodemodeDescription(
 	}
 	if (declarations.length === 0) return sections.join("\n\n");
 
-	const toolSections = [
-		complete
-			? "Nested tools: COMPLETE list."
-			: "Nested tools: PARTIAL list. Find the tools that are not listed with `searchTools()`.",
-	];
+	const toolSections = ["Nested tools:"];
 	for (const { namespace, entries } of ordered) {
 		const visible = entries.filter((entry) => shown.has(entry.name));
 		if (namespace) {
+			// Only tools that did not fit the budget are counted as not listed here.
 			const listing =
 				visible.length === entries.length
 					? ""
diff --git a/packages/coding-agent/src/extensions/mcp/cli.ts b/packages/coding-agent/src/extensions/mcp/cli.ts
index 6a8e7ec7a..77aa6bafa 100644
--- a/packages/coding-agent/src/extensions/mcp/cli.ts
+++ b/packages/coding-agent/src/extensions/mcp/cli.ts
@@ -66,7 +66,7 @@ Options for add:
   --oauth-client-name <name>
                           Client name sent when registering with the OAuth server
   --exposure <mode>       codemode (default), deferred, direct, or hidden
-  --description <text>    What the server offers, shown to the model with its tools
+  --description <text>    What the server offers, shown in the system prompt
 
 Other options:
   --json                  Print the list as JSON
diff --git a/packages/coding-agent/src/extensions/mcp/index.ts b/packages/coding-agent/src/extensions/mcp/index.ts
index 900f1dc12..07abfadce 100644
--- a/packages/coding-agent/src/extensions/mcp/index.ts
+++ b/packages/coding-agent/src/extensions/mcp/index.ts
@@ -3,12 +3,13 @@
  *
  * Connects the servers from `mcp.json` and the servers extensions register with
  * `pi.registerMcpServer()` when a session starts, and servers registered later right away. A server
- * in `mcp.json` takes precedence over a registered server of the same name. Tools are registered as
- * `mcp__<server>__<tool>`. By default (`"exposure": "codemode"`) the tools are only callable from
- * codemode scripts, which keeps MCP tool lists out of the model's tool declarations and the codemode
- * description: the description lists the server's namespace with its configured `description`, and
- * scripts find the tools with `searchTools()` and the server instructions with
- * `describeNamespace()`. The codemode tool is activated for that unless `autoEnableCodemode` is
+ * in `mcp.json` takes precedence over a registered server of the same name. Connections run in the
+ * background: the first prompt waits only for servers with `direct` tools, and codemode scripts,
+ * `tool_search`, and the resource tools wait for the servers they need when they run. Tools are
+ * registered as `mcp__<server>__<tool>`. By default (`"exposure": "codemode"`) the tools are only
+ * callable from codemode scripts, which keeps MCP tools out of the model's tool declarations and
+ * the codemode description: scripts find the tools with `searchTools()` and the server instructions
+ * with `describeNamespace()`. The codemode tool is activated for that unless `autoEnableCodemode` is
  * false. `"deferred"` declares the tools to the model once the `tool_search` tool loads them, and
  * activates `tool_search` instead of codemode.
  * `"exposure": "direct"` declares them to the model right away, and `"hidden"` makes them
@@ -26,6 +27,7 @@
  */
 
 import { join, resolve } from "node:path";
+import { toCodemodeIdentifier } from "@earendil-works/pi-codemode/declarations";
 import type { SelectItem } from "@earendil-works/pi-tui";
 import type { TSchema } from "typebox";
 import { getAgentDir } from "../../config.ts";
@@ -49,7 +51,12 @@ import {
 	updateMcpServerConfig,
 } from "./config.ts";
 import type { McpOAuthCredentialStore, McpSignInPrompt } from "./oauth.ts";
-import { createMcpResourceToolDefinitions } from "./resources.ts";
+import {
+	createMcpResourceToolDefinitions,
+	LIST_MCP_RESOURCE_TEMPLATES_TOOL,
+	LIST_MCP_RESOURCES_TOOL,
+	READ_MCP_RESOURCE_TOOL,
+} from "./resources.ts";
 import { loadMcpRuntime } from "./runtime.lazy.ts";
 import type * as McpRuntime from "./runtime.ts";
 import type { McpServerConnection, McpServerLog, McpTransportFactory } from "./runtime.ts";
@@ -72,14 +79,21 @@ export interface McpExtensionOptions {
 	/** Saves `/mcp` changes to the server's config file. Defaults to editing its `mcp.json`. */
 	updateConfig?: (entry: McpServerEntry, patch: McpServerConfigPatch) => void;
 	/**
-	 * How long the first prompt waits for servers that are still connecting at startup, in
-	 * milliseconds. Their tools become available when they connect. Default: 10000.
+	 * How long the first prompt waits for servers with `direct` tools that are still connecting at
+	 * startup, in milliseconds. Their tools become available when they connect. Other servers are
+	 * waited for when a script or search needs them. Default: 10000.
 	 */
 	startupWaitMs?: number;
 }
 
 const DEFAULT_STARTUP_WAIT_MS = 10_000;
 
+const RESOURCE_TOOL_NAMES: ReadonlySet<string> = new Set([
+	LIST_MCP_RESOURCES_TOOL,
+	LIST_MCP_RESOURCE_TEMPLATES_TOOL,
+	READ_MCP_RESOURCE_TOOL,
+]);
+
 /** A configured server. Disabled servers have no connection. */
 interface McpServer {
 	entry: McpServerEntry;
@@ -88,6 +102,8 @@ interface McpServer {
 	registeredConfig?: string;
 	/** Result of the last `/mcp` action that failed, shown in the manager. */
 	message?: string;
+	/** Settles when the connection started for the server connected or failed. */
+	ready?: Promise<void>;
 }
 
 const EXPOSURE_DESCRIPTIONS: Record<Exclude<McpExposure, "hidden">, string> = {
@@ -104,7 +120,7 @@ function firstLine(text: string): string {
 	return text.split("\n", 1)[0] ?? "";
 }
 
-function isEnabled(server: McpServer): boolean {
+function isEnabled(server: Pick<McpServer, "entry">): boolean {
 	return server.entry.config.enabled !== false;
 }
 
@@ -112,6 +128,101 @@ function exposureOf(entry: McpServerEntry): McpExposure {
 	return entry.config.exposure ?? "codemode";
 }
 
+/** Exposures the server's tools can have, known from its config before it connects. */
+function configuredExposures(entry: McpServerEntry): Set<McpExposure> {
+	return new Set([exposureOf(entry), ...Object.values(entry.config.toolExposure ?? {})]);
+}
+
+/** Whether some of the server's tools are declared to the model, so the first prompt waits for them. */
+function hasDirectTools(entry: McpServerEntry): boolean {
+	return configuredExposures(entry).has("direct");
+}
+
+/** Whether some of the server's tools are reached through codemode or tool_search. */
+function hasIndirectTools(entry: McpServerEntry): boolean {
+	const exposures = configuredExposures(entry);
+	return exposures.has("codemode") || exposures.has("deferred");
+}
+
+function namespaceName(server: string): string {
+	return `mcp__${server}`;
+}
+
+/** Name of the system prompt section that lists the servers whose tools are not declared. */
+export const MCP_SERVERS_SECTION = "mcp_servers";
+/** Characters of a server description in the section, as Codex allows for deferred namespaces. */
+const MAX_SERVER_DESCRIPTION_CHARS = 250;
+/**
+ * Characters of the whole section. Descriptions shrink to fit; when the server lines alone do not
+ * fit, the last servers are left out and counted in a closing line.
+ */
+export const MAX_SERVERS_SECTION_CHARS = 4096;
+
+const SERVERS_SECTION_INTRO =
+	"MCP servers whose tools are not declared to you. Call the tools of `codemode` servers from codemode scripts: find them with `searchTools(query, { namespace })` and read a server's instructions and tool names with `describeNamespace(name)`. Load the tools of `tool_search` servers with `tool_search`.";
+
+function truncate(text: string, max: number): string {
+	if (text.length <= max) return text;
+	return max <= 1 ? "" : `${text.slice(0, max - 1).trimEnd()}…`;
+}
+
+/** What the `mcp_servers` section needs of a server. */
+export interface McpServerListing {
+	entry: McpServerEntry;
+	connection?: { instructions?: string };
+}
+
+/** First line of the configured description, or of the server instructions once connected. */
+function serverSummary(server: McpServerListing): string {
+	const text = server.entry.config.description?.trim() || server.connection?.instructions || "";
+	return (text.split("\n", 1)[0] ?? "").trim();
+}
+
+/**
+ * The `mcp_servers` section: every enabled server with codemode or deferred tools, with how its
+ * tools are reached and a one-line summary. The model learns of the servers from it, since neither
+ * codemode nor tool_search lists them. Undefined when there are no such servers.
+ */
+export function renderServersSection(servers: readonly McpServerListing[]): string | undefined {
+	const listed = servers
+		.filter((server) => isEnabled(server) && hasIndirectTools(server.entry))
+		.sort((a, b) => a.entry.name.localeCompare(b.entry.name));
+	if (listed.length === 0) return undefined;
+	const heads = listed.map((server) => {
+		const exposures = configuredExposures(server.entry);
+		const reach = exposures.has("codemode") ? "codemode" : "tool_search";
+		return `- ${namespaceName(server.entry.name)} (${reach})`;
+	});
+	const omitted = (count: number) =>
+		count > 0 ? [`- … ${count} more server${count === 1 ? "" : "s"}; find their tools with searchTools()`] : [];
+	// Characters of the intro, the first `kept` server lines without descriptions, and the omission line.
+	const size = (kept: number) =>
+		[SERVERS_SECTION_INTRO, ...heads.slice(0, kept), ...omitted(listed.length - kept)].join("\n").length;
+	let kept = listed.length;
+	while (kept > 0 && size(kept) > MAX_SERVERS_SECTION_CHARS) kept--;
+	// Each description also takes a ": " separator.
+	const perServer =
+		kept === 0
+			? 0
+			: Math.min(MAX_SERVER_DESCRIPTION_CHARS, Math.floor((MAX_SERVERS_SECTION_CHARS - size(kept)) / kept) - 2);
+	const lines = listed.slice(0, kept).map((server, index) => {
+		const summary = perServer > 0 ? truncate(serverSummary(server), perServer) : "";
+		return summary ? `${heads[index]}: ${summary}` : heads[index];
+	});
+	return [SERVERS_SECTION_INTRO, ...lines, ...omitted(listed.length - kept)].join("\n");
+}
+
+/**
+ * Whether a codemode script needs the server: it names the server's namespace, as written or as the
+ * script identifier codemode derives from it, or searches, enumerates, or describes tools or
+ * namespaces, which may name the server in other forms.
+ */
+function scriptNeedsServer(code: string, server: string): boolean {
+	if (/\b(searchTools|describeNamespace|describeTool|ALL_TOOLS)\b/.test(code)) return true;
+	const name = namespaceName(server);
+	return code.includes(name) || code.includes(toCodemodeIdentifier(name));
+}
+
 /** Short state for lists and the startup report. `withError` appends the first line of a failure. */
 function describeState(server: McpServer, withError = true): string {
 	if (!isEnabled(server)) return "disabled";
@@ -239,10 +350,9 @@ export function createMcpExtension(options: McpExtensionOptions = {}): Extension
 		const registerTools = (connection: McpServerConnection) => {
 			const server = connection.entry.name;
 			const entry = findServer(server)?.entry ?? connection.entry;
-			const namespaceName = `mcp__${server}`;
 			const description = entry.config.description?.trim();
 			const namespace = {
-				name: namespaceName,
+				name: namespaceName(server),
 				...(description ? { description } : {}),
 				...(connection.instructions ? { instructions: connection.instructions } : {}),
 			};
@@ -327,12 +437,11 @@ export function createMcpExtension(options: McpExtensionOptions = {}): Extension
 		 * tool_search for `deferred`.
 		 */
 		const ensureDiscoveryActive = (ctx: ExtensionContext) => {
+			// From the config, so the tool is active before the servers connect. Resource tools share
+			// their server's exposure.
 			const exposures = new Set<McpExposure>();
-			for (const { connection, entry } of servers) {
-				if (connection?.state !== "connected") continue;
-				// Resource tools share the server's exposure.
-				if (connection.hasResources) exposures.add(exposureOf(entry));
-				for (const tool of connection.tools) exposures.add(getMcpToolExposure(entry.config, tool.name));
+			for (const server of servers) {
+				if (isEnabled(server)) for (const exposure of configuredExposures(server.entry)) exposures.add(exposure);
 			}
 			const needsCodemode = exposures.has("codemode");
 			const needsToolSearch = exposures.has("deferred");
@@ -402,6 +511,42 @@ export function createMcpExtension(options: McpExtensionOptions = {}): Extension
 			return connection;
 		};
 
+		/**
+		 * Connect the server in the background. `server.ready` settles when it connected or failed;
+		 * failures show in its state. It starts after `after`; `isCurrent` stops it when the session ended
+		 * meanwhile. The returned promise rejects when the MCP runtime cannot be loaded.
+		 */
+		const startConnection = (
+			server: McpServer,
+			isCurrent: () => boolean,
+			after?: Promise<unknown>,
+		): Promise<void> => {
+			const ready = (async () => {
+				await after;
+				if (!isCurrent()) return;
+				const connection = await createConnection(server);
+				if (!isCurrent()) return;
+				await connection.getClient().catch(() => undefined);
+			})();
+			server.ready = ready.catch(() => undefined);
+			return ready;
+		};
+
+		/** Wait for servers still connecting, until they settle or `signal` aborts. */
+		const waitForServers = async (waiting: readonly McpServer[], signal: AbortSignal | undefined) => {
+			const ready = waiting.flatMap((server) => (server.ready ? [server.ready] : []));
+			if (ready.length === 0 || signal?.aborted) return;
+			let onAbort: (() => void) | undefined;
+			await Promise.race([
+				Promise.all(ready),
+				new Promise<void>((resolve) => {
+					onAbort = () => resolve();
+					signal?.addEventListener("abort", onAbort, { once: true });
+				}),
+			]);
+			if (onAbort) signal?.removeEventListener("abort", onAbort);
+		};
+
 		/**
 		 * One message for everything that needs the user after startup, or only for `only`, servers
 		 * that connected later.
@@ -495,8 +640,7 @@ export function createMcpExtension(options: McpExtensionOptions = {}): Extension
 				await connection?.close();
 				return undefined;
 			}
-			const connection = await createConnection(server);
-			await connection.getClient().catch(() => undefined);
+			await startConnection(server, () => true);
 			return undefined;
 		};
 
@@ -803,6 +947,9 @@ export function createMcpExtension(options: McpExtensionOptions = {}): Extension
 			overridden = registered.overridden;
 			servers = [...loaded.servers.map((entry) => ({ entry })), ...registered.servers];
 			emitChange();
+			// Codemode or tool_search is activated from the config: the first prompt does not wait for
+			// servers whose tools are not declared to the model, and scripts or searches wait for them.
+			ensureDiscoveryActive(ctx);
 			const enabled = servers.filter(isEnabled);
 			if (enabled.length === 0) {
 				reportProblems(ctx);
@@ -810,16 +957,11 @@ export function createMcpExtension(options: McpExtensionOptions = {}): Extension
 			}
 			// The MCP client loads only now, so sessions without servers never pay for it. Waiting one
 			// event loop turn lets the first render happen before loading and connecting.
-			pending = new Promise((resolve) => setImmediate(resolve))
-				.then(() => loadMcpRuntime())
-				.then(async () => {
-					if (current !== generation) return;
-					const started = await Promise.all(enabled.map((server) => createConnection(server)));
-					if (current !== generation) return;
-					await Promise.allSettled(started.map((connection) => connection.getClient()));
-					if (current !== generation) return;
-					ensureDiscoveryActive(ctx);
-					reportProblems(ctx);
+			const runtime = new Promise((resolve) => setImmediate(resolve)).then(() => loadMcpRuntime());
+			const isCurrent = () => current === generation;
+			pending = Promise.all(enabled.map((server) => startConnection(server, isCurrent, runtime)))
+				.then(() => {
+					if (isCurrent()) reportProblems(ctx);
 				})
 				.catch((error: unknown) => {
 					// The session may have been disposed meanwhile, which makes ctx stale.
@@ -829,15 +971,19 @@ export function createMcpExtension(options: McpExtensionOptions = {}): Extension
 				});
 		});
 
-		// The first prompt waits for startup connections so their tools are available to it, but not
-		// indefinitely: a slow or hanging server must not hold up the prompt.
-		pi.on("before_agent_start", async (_event, ctx) => {
-			const startup = pending;
-			if (!startup || waitedForStartup) return;
+		// The first prompt waits for servers whose tools are declared to the model, so they are declared
+		// in its first request, but not indefinitely: a slow or hanging server must not hold up the
+		// prompt. Other servers are waited for when a script or search needs them (below).
+		const waitForDirectServers = async (ctx: ExtensionContext) => {
+			if (waitedForStartup) return;
 			waitedForStartup = true;
+			const ready = servers.flatMap((server) =>
+				isEnabled(server) && hasDirectTools(server.entry) && server.ready ? [server.ready] : [],
+			);
+			if (ready.length === 0) return;
 			let timer: NodeJS.Timeout | undefined;
 			const finished = await Promise.race([
-				startup.then(() => true),
+				Promise.all(ready).then(() => true),
 				new Promise<boolean>((resolve) => {
 					timer = setTimeout(() => resolve(false), startupWaitMs);
 				}),
@@ -846,6 +992,37 @@ export function createMcpExtension(options: McpExtensionOptions = {}): Extension
 			if (!finished) {
 				ctx.ui.notify("MCP servers are still connecting; their tools become available once connected.", "info");
 			}
+		};
+
+		// Every prompt lists the servers in the `mcp_servers` section as they are when it starts. Pi
+		// appends the section to the conversation when it changed, for example after a server connected.
+		pi.on("before_agent_start", async (event, ctx) => {
+			await waitForDirectServers(ctx);
+			const { sections } = event.systemPromptOptions;
+			const section = renderServersSection(servers);
+			if (section) sections[MCP_SERVERS_SECTION] = section;
+			else delete sections[MCP_SERVERS_SECTION];
+		});
+
+		// A codemode script waits for the servers it names, or for every server when it searches or
+		// enumerates tools, so their tools are registered before the script runs. tool_search and the
+		// resource tools reach every server, so they wait for all of them.
+		pi.on("tool_call", async (event, ctx) => {
+			const tool = pi.getAllTools().find((candidate) => candidate.name === event.toolName);
+			if (!tool) return;
+			const pendingServers = servers.filter(
+				(server) => isEnabled(server) && server.connection?.state !== "connected" && server.ready,
+			);
+			if (pendingServers.length === 0) return;
+			let waiting: McpServer[] = [];
+			if (isCodemodeTool(tool)) {
+				const { code } = event.input as { code?: unknown };
+				const source = typeof code === "string" ? code : "";
+				waiting = pendingServers.filter((server) => scriptNeedsServer(source, server.entry.name));
+			} else if (isToolSearchTool(tool) || RESOURCE_TOOL_NAMES.has(tool.name)) {
+				waiting = pendingServers;
+			}
+			await waitForServers(waiting, ctx.signal);
 		});
 
 		// Pick up sign-ins done outside the session, such as `pi mcp login` run by the agent.
@@ -871,22 +1048,21 @@ export function createMcpExtension(options: McpExtensionOptions = {}): Extension
 			const added = registered.servers.filter((server) => !findServer(server.entry.name));
 			servers.push(...added);
 			emitChange();
+			ensureDiscoveryActive(ctx);
 			await Promise.all(removed.map((server) => server.connection?.close()));
 			const connecting = added.filter(isEnabled);
 			if (current !== generation || connecting.length === 0) return;
 			try {
-				const started = await Promise.all(connecting.map((server) => createConnection(server)));
+				await Promise.all(connecting.map((server) => startConnection(server, () => current === generation)));
 				if (current !== generation) {
-					await Promise.all(started.map((connection) => connection.close()));
+					await Promise.all(connecting.map((server) => server.connection?.close()));
 					return;
 				}
-				await Promise.allSettled(started.map((connection) => connection.getClient()));
 			} catch (error) {
 				ctx.ui.notify(`MCP failed to load: ${errorMessage(error)}`, "error");
 				return;
 			}
 			if (current !== generation) return;
-			ensureDiscoveryActive(ctx);
 			reportProblems(ctx, connecting);
 		});
 
diff --git a/packages/coding-agent/src/extensions/tool-search/tool.ts b/packages/coding-agent/src/extensions/tool-search/tool.ts
index a2cee3986..85b29a4cd 100644
--- a/packages/coding-agent/src/extensions/tool-search/tool.ts
+++ b/packages/coding-agent/src/extensions/tool-search/tool.ts
@@ -214,21 +214,10 @@ function searchAndLoad(
 }
 
 /**
- * The `tool_search` description. `sources` lists the namespaces whose tools can be found, with
- * their descriptions.
+ * The `tool_search` description. It does not list the searchable tools or their namespaces, so it
+ * stays the same while tools are registered, for example when MCP servers connect.
  */
-export function createToolSearchDescription(sources: readonly ToolNamespace[] = []): string {
-	const listed =
-		sources.length === 0
-			? "None currently enabled."
-			: sources
-					.map((source) => {
-						const description = source.description?.trim().split(/\r?\n/)[0];
-						return description ? `- ${source.name}: ${description}` : `- ${source.name}`;
-					})
-					.join("\n");
-	return `# Tool discovery\n\nSearches over deferred tool metadata with BM25 and exposes matching tools for the next model call.\n\nYou have access to tools from the following sources:\n${listed}\n\nSome of the tools may not have been provided to you upfront, and you should use this tool (\`${TOOL_SEARCH_TOOL_NAME}\`) to search for the required tools. For MCP tool discovery, always use \`${TOOL_SEARCH_TOOL_NAME}\`.`;
-}
+export const TOOL_SEARCH_DESCRIPTION = `# Tool discovery\n\nSearches over deferred tool metadata with BM25 and exposes matching tools for the next model call.\n\nSome of the tools, such as tools of MCP servers, may not have been provided to you upfront, and you should use this tool (\`${TOOL_SEARCH_TOOL_NAME}\`) to search for the required tools. For MCP tool discovery, always use \`${TOOL_SEARCH_TOOL_NAME}\`.`;
 
 export function createToolSearchToolDefinition(
 	options: ToolSearchToolOptions = {},
@@ -236,23 +225,11 @@ export function createToolSearchToolDefinition(
 	return {
 		name: TOOL_SEARCH_TOOL_NAME,
 		label: TOOL_SEARCH_TOOL_NAME,
-		// Replaced with the searchable sources when the tool is activated.
-		description: createToolSearchDescription(),
+		description: TOOL_SEARCH_DESCRIPTION,
 		promptSnippet: "Search for tools that are not loaded yet and load the matches",
 		parameters: toolSearchSchema,
 		// Searching is not something scripts need; it changes what the model sees.
 		exposure: "model-only",
-		// List the namespaces of the searchable tools.
-		prepareLoadout: (loadout) => {
-			const sources = new Map<string, ToolNamespace>();
-			for (const tool of loadout.registered) {
-				const namespace = loadout.getNamespace(tool.name);
-				if (isSearchable(loadout.getExposure(tool.name)) && namespace && !sources.has(namespace.name)) {
-					sources.set(namespace.name, namespace);
-				}
-			}
-			return { descriptions: { [TOOL_SEARCH_TOOL_NAME]: createToolSearchDescription([...sources.values()]) } };
-		},
 		async execute(_toolCallId, { query, limit }) {
 			if (query.trim() === "") throw new Error("query must not be empty");
 			const max = limit ?? DEFAULT_TOOL_SEARCH_LIMIT;
diff --git a/packages/coding-agent/test/mcp-extension.test.ts b/packages/coding-agent/test/mcp-extension.test.ts
index 32cbafe2b..dda0a1919 100644
--- a/packages/coding-agent/test/mcp-extension.test.ts
+++ b/packages/coding-agent/test/mcp-extension.test.ts
@@ -13,6 +13,7 @@ import { afterEach, describe, expect, it } from "vitest";
 import { InMemoryAuthStorageBackend } from "../src/core/auth-storage.ts";
 import { truncateMiddle } from "../src/core/tools/truncate.ts";
 import { getMcpToolExposure, loadMcpConfig, type McpServerEntry } from "../src/extensions/mcp/config.ts";
+import { MAX_SERVERS_SECTION_CHARS, renderServersSection } from "../src/extensions/mcp/index.ts";
 import {
 	createDefaultTransport,
 	McpOAuthCredentialStore,
@@ -570,3 +571,46 @@ for await (const line of createInterface({ input: process.stdin })) {
 		await connection.close();
 	});
 });
+
+describe("MCP servers section", () => {
+	const server = (name: string, description?: string, exposure?: "codemode" | "deferred" | "direct") => ({
+		entry: {
+			name,
+			config: { command: "x", ...(description ? { description } : {}), ...(exposure ? { exposure } : {}) },
+			source: "test",
+		},
+	});
+
+	it("lists servers with how their tools are reached and the first line of their description", () => {
+		const section = renderServersSection([
+			server("docs", "Docs search.\nMore."),
+			server("later", undefined, "deferred"),
+			server("direct", "Declared.", "direct"),
+			{ entry: server("plain").entry, connection: { instructions: "From instructions." } },
+		]);
+		expect(section?.split("\n").slice(1)).toEqual([
+			"- mcp__docs (codemode): Docs search.",
+			"- mcp__later (tool_search)",
+			"- mcp__plain (codemode): From instructions.",
+		]);
+		expect(renderServersSection([server("direct", "Declared.", "direct")])).toBeUndefined();
+	});
+
+	it("shortens descriptions to fit the size limit", () => {
+		const servers = Array.from({ length: 40 }, (_, index) => server(`server${index}`, "x".repeat(400)));
+		const section = renderServersSection(servers) ?? "";
+		expect(section.length).toBeLessThanOrEqual(MAX_SERVERS_SECTION_CHARS);
+		expect(section.split("\n")).toHaveLength(41);
+		expect(section).toContain("- mcp__server39 (codemode): x");
+	});
+
+	it("leaves out the last servers when their names alone do not fit", () => {
+		const servers = Array.from({ length: 200 }, (_, index) => server(`server-with-a-long-name-${index}`, "desc"));
+		const section = renderServersSection(servers) ?? "";
+		expect(section.length).toBeLessThanOrEqual(MAX_SERVERS_SECTION_CHARS);
+		const lines = section.split("\n");
+		expect(lines.at(-1)).toMatch(/^- … \d+ more servers; find their tools with searchTools\(\)$/);
+		const omitted = Number(/(\d+) more/.exec(lines.at(-1) ?? "")?.[1]);
+		expect(lines.length - 2 + omitted).toBe(200);
+	});
+});
diff --git a/packages/coding-agent/test/suite/agent-session-mcp.test.ts b/packages/coding-agent/test/suite/agent-session-mcp.test.ts
index b75820882..f127e496e 100644
--- a/packages/coding-agent/test/suite/agent-session-mcp.test.ts
+++ b/packages/coding-agent/test/suite/agent-session-mcp.test.ts
@@ -7,9 +7,10 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import type { ExtensionAPI, ExtensionFactory } from "../../src/core/extensions/types.ts";
 import { createCodemodeExtension } from "../../src/extensions/codemode/index.ts";
 import type { McpExposure, McpServerEntry } from "../../src/extensions/mcp/config.ts";
-import { createMcpExtension } from "../../src/extensions/mcp/index.ts";
+import { createMcpExtension, MCP_SERVERS_SECTION } from "../../src/extensions/mcp/index.ts";
 import { createMcpToolName } from "../../src/extensions/mcp/tools.ts";
 import { createToolSearchExtension } from "../../src/extensions/tool-search/index.ts";
+import { TOOL_SEARCH_DESCRIPTION } from "../../src/extensions/tool-search/tool.ts";
 import {
 	createHarness,
 	createTestUiContext,
@@ -42,13 +43,20 @@ const SERVER_TOOLS = [
 	{ name: "shot", description: "Returns an image.", inputSchema: { type: "object", properties: {} } },
 ];
 
-/** Minimal MCP server over an in-memory transport. Records the tool calls it receives. */
+/**
+ * Minimal MCP server over an in-memory transport. Records the tool calls it receives.
+ * `initializeDelayMs` delays the answer to `initialize`; `Infinity` never answers.
+ */
 function createFakeServer(
 	calls: string[],
-	listTools: () => unknown[] = () => SERVER_TOOLS,
-	resources = false,
-	instructions?: string,
+	options: {
+		listTools?: () => unknown[];
+		resources?: boolean;
+		instructions?: string;
+		initializeDelayMs?: number;
+	} = {},
 ) {
+	const { listTools = () => SERVER_TOOLS, resources = false, instructions, initializeDelayMs = 0 } = options;
 	const pair = createInMemoryTransportPair();
 	const respond = (request: JsonRpcRequest): unknown => {
 		switch (request.method) {
@@ -99,9 +107,9 @@ function createFakeServer(
 	pair.server.onMessage((message) => {
 		if (!("id" in message) || !("method" in message)) return;
 		const request = message as JsonRpcRequest;
-		queueMicrotask(() => {
-			void pair.server.send({ jsonrpc: "2.0", id: request.id, result: respond(request) });
-		});
+		const send = () => void pair.server.send({ jsonrpc: "2.0", id: request.id, result: respond(request) });
+		if (request.method !== "initialize" || initializeDelayMs === 0) queueMicrotask(send);
+		else if (Number.isFinite(initializeDelayMs)) setTimeout(send, initializeDelayMs);
 	});
 	return pair;
 }
@@ -161,7 +169,7 @@ describe("AgentSession MCP integration", () => {
 				createMcpExtension({
 					loadConfig: () => ({ servers: [entry], errors: [], ...configOptions }),
 					createTransport: () => {
-						const pair = createFakeServer(calls, listTools, resources, instructions);
+						const pair = createFakeServer(calls, { listTools, resources, instructions });
 						servers.push(pair.server);
 						void pair.server.start();
 						return pair.client;
@@ -173,6 +181,10 @@ describe("AgentSession MCP integration", () => {
 		await harness.session.bindExtensions({
 			uiContext: createTestUiContext({ notify: (message) => notifications.push(message) }),
 		});
+		// The first prompt waits only for servers with direct tools; wait for the others here.
+		await vi.waitFor(() =>
+			expect(harness.session.getAllTools().some((tool) => tool.name === "mcp__docs__search")).toBe(true),
+		);
 		return { harness, calls, servers, notifications };
 	}
 
@@ -182,6 +194,17 @@ describe("AgentSession MCP integration", () => {
 			.flatMap((message) => (message.toolsAdded ?? []).map((tool) => tool.name));
 	}
 
+	/** The `mcp_servers` prompt section as the model currently has it. */
+	function serversSection(harness: Harness): string | null | undefined {
+		let section: string | null | undefined;
+		for (const message of harness.session.messages) {
+			if (message.role === "system" && message.sections && MCP_SERVERS_SECTION in message.sections) {
+				section = message.sections[MCP_SERVERS_SECTION];
+			}
+		}
+		return section;
+	}
+
 	function nestedToolNames(harness: Harness): string[] {
 		return harness.session.getCallableToolNames();
 	}
@@ -222,11 +245,10 @@ describe("AgentSession MCP integration", () => {
 		expect(harness.session.getActiveToolNames()).toEqual(["codemode"]);
 		expect(declaredToolNames(harness)).toEqual(["codemode"]);
 		expect(nestedToolNames(harness)).toEqual([searchName, "mcp__docs__fail", "mcp__docs__shot"]);
-		// The description lists the server, not its tools.
+		// The description lists neither the server nor its tools; scripts search for them.
 		const codemode = harness.session.agent.state.tools.find((tool) => tool.name === "codemode");
-		expect(codemode?.description).toContain("Shared MCP Types:");
-		expect(codemode?.description).toContain("## mcp__docs (tools not listed)");
-		expect(codemode?.description).not.toContain(searchName);
+		expect(codemode?.description).not.toContain("mcp__docs");
+		expect(codemode?.description).not.toContain("Shared MCP Types:");
 
 		const result = toolResult(harness, "codemode");
 		expect(result.isError).toBe(false);
@@ -259,8 +281,6 @@ describe("AgentSession MCP integration", () => {
 
 		expect(harness.session.getActiveToolNames()).toEqual(["codemode"]);
 		expect(nestedToolNames(harness)).toContain(searchName);
-		const codemode = harness.session.agent.state.tools.find((tool) => tool.name === "codemode");
-		expect(codemode?.description).toContain("## mcp__docs (tools not listed)");
 	});
 
 	it("rejects direct model calls to codemode-only MCP tools", async () => {
@@ -402,10 +422,9 @@ return { uris: listed.resources.map((r) => r.uri), text: read.contents[0].text }
 		await harness.session.prompt("start");
 
 		// `search` is declared, `shot` is only callable from codemode, `fail` keeps the server's `hidden`.
-		expect(declaredToolNames(harness)).toEqual(["mcp__docs__search", "codemode"]);
+		expect(declaredToolNames(harness)).toEqual(["codemode", "mcp__docs__search"]);
 		expect(nestedToolNames(harness)).toEqual(["mcp__docs__search", "mcp__docs__shot"]);
 		const codemode = harness.session.agent.state.tools.find((tool) => tool.name === "codemode");
-		expect(codemode?.description).toContain("## mcp__docs (tools not listed)");
 		expect(codemode?.description).not.toContain("mcp__docs__shot");
 		expect(codemode?.description).not.toContain("mcp__docs__fail");
 	});
@@ -420,7 +439,9 @@ return { uris: listed.resources.map((r) => r.uri), text: read.contents[0].text }
 			fauxAssistantMessage(
 				[
 					fauxToolCall("codemode", {
-						code: `return { docs: await describeNamespace("mcp__docs"), none: await describeNamespace("mcp__nope") };`,
+						code: `const docs = await describeNamespace("mcp__docs");
+const aliases = await Promise.all(["docs", "mcp__docs"].map((name) => describeNamespace(name)));
+return { docs, sameForAliases: aliases.every((alias) => JSON.stringify(alias) === JSON.stringify(docs)), none: await describeNamespace("mcp__nope") };`,
 					}),
 				],
 				{ stopReason: "toolUse" },
@@ -433,8 +454,8 @@ return { uris: listed.resources.map((r) => r.uri), text: read.contents[0].text }
 		// The instructions stay out of every tool description.
 		const description = (name: string) =>
 			harness.session.agent.state.tools.find((tool) => tool.name === name)?.description ?? "";
-		expect(description("codemode")).toContain("## mcp__docs (tools not listed)\nSearch the product docs");
-		expect(description("tool_search")).toContain("- mcp__docs: Search the product docs");
+		expect(description("codemode")).not.toContain("mcp__docs");
+		expect(description("tool_search")).toBe(TOOL_SEARCH_DESCRIPTION);
 		for (const name of ["codemode", "tool_search"]) expect(description(name)).not.toContain("Always search");
 		expect(JSON.parse(getMessageText(toolResult(harness, "codemode")).split("\n").at(-1) ?? "")).toEqual({
 			docs: {
@@ -443,7 +464,21 @@ return { uris: listed.resources.map((r) => r.uri), text: read.contents[0].text }
 				instructions: "Always search before reading.",
 				tools: ["mcp__docs__search", "mcp__docs__fail", "mcp__docs__shot"],
 			},
+			sameForAliases: true,
 		});
+		// The system prompt lists the server with its configured description rather than its instructions.
+		expect(serversSection(harness)).toContain("- mcp__docs (codemode): Search the product docs");
+	});
+
+	it("lists servers by the first line of their instructions without a configured description", async () => {
+		const { harness } = await setup("deferred", undefined, { instructions: "Docs search.\nLong guidance." });
+		harness.setResponses([fauxAssistantMessage("done")]);
+
+		await harness.session.prompt("go");
+
+		const section = serversSection(harness);
+		expect(section).toContain("- mcp__docs (tool_search): Docs search.\n");
+		expect(section).not.toContain("Long guidance");
 	});
 
 	it("does not activate codemode when autoEnableCodemode is false", async () => {
@@ -520,32 +555,196 @@ return { uris: listed.resources.map((r) => r.uri), text: read.contents[0].text }
 		expect(harness.session.getActiveToolNames()).toEqual([]);
 	});
 
-	it("does not hold the first prompt for servers that are still connecting", async () => {
-		const entry: McpServerEntry = { name: "slow", config: { url: "http://unused.invalid" }, source: "test" };
+	/** A server named `slow` whose answer to `initialize` takes `initializeDelayMs`, without waiting for it. */
+	async function setupSlow(
+		config: {
+			exposure?: McpExposure;
+			toolExposure?: Record<string, McpExposure>;
+			name?: string;
+			instructions?: string;
+		},
+		initializeDelayMs: number,
+		startupWaitMs?: number,
+	) {
+		const calls: string[] = [];
+		const notifications: string[] = [];
+		const { name = "slow", instructions, ...serverConfig } = config;
+		const entry: McpServerEntry = { name, config: { url: "http://unused.invalid", ...serverConfig }, source: "test" };
 		const harness = await createHarness({
 			initialActiveToolNames: [],
 			extensionFactories: [
 				createCodemodeExtension(),
+				createToolSearchExtension(),
 				createMcpExtension({
 					loadConfig: () => ({ servers: [entry], errors: [] }),
-					// The server never answers `initialize`.
 					createTransport: () => {
-						const pair = createInMemoryTransportPair();
+						const pair = createFakeServer(calls, { initializeDelayMs, instructions });
 						void pair.server.start();
 						return pair.client;
 					},
-					startupWaitMs: 20,
+					...(startupWaitMs === undefined ? {} : { startupWaitMs }),
 				}),
 			],
 		});
 		harnesses.push(harness);
-		await harness.session.bindExtensions({});
+		await harness.session.bindExtensions({
+			uiContext: createTestUiContext({ notify: (message) => notifications.push(message) }),
+		});
+		return { harness, calls, notifications };
+	}
+
+	it("does not hold the first prompt for codemode servers that are still connecting", async () => {
+		// The server never answers `initialize`.
+		const { harness } = await setupSlow({}, Number.POSITIVE_INFINITY);
+		harness.setResponses([fauxAssistantMessage("ready")]);
+
+		await harness.session.prompt("start");
+
+		expect(getAssistantTexts(harness)).toEqual(["ready"]);
+		// Codemode is activated from the config, before the server connects.
+		expect(declaredToolNames(harness)).toEqual(["codemode"]);
+	});
+
+	it("keeps the codemode description unchanged when the server connects", async () => {
+		const { harness } = await setupSlow({}, 20);
+		const description = () => harness.session.agent.state.tools.find((tool) => tool.name === "codemode")?.description;
+		const before = description();
+		expect(before).toBeDefined();
+		await vi.waitFor(() => expect(harness.session.getCallableToolNames()).toContain("mcp__slow__search"));
+		expect(description()).toBe(before);
+	});
+
+	it("lists a server before it connects and appends its summary with the next prompt", async () => {
+		const { harness } = await setupSlow({ instructions: "Slow docs.\nMore." }, 30);
+		harness.setResponses([fauxAssistantMessage("one"), fauxAssistantMessage("two")]);
+
+		await harness.session.prompt("first");
+		await vi.waitFor(() => expect(harness.session.getCallableToolNames()).toContain("mcp__slow__search"));
+		await harness.session.prompt("second");
+
+		const systemMessages = harness.session.messages.filter(
+			(message): message is SystemMessage => message.role === "system",
+		);
+		// The first request lists the server by name; its summary follows as an appended patch.
+		expect(systemMessages).toHaveLength(2);
+		expect(systemMessages[0].sections?.[MCP_SERVERS_SECTION]).toContain("- mcp__slow (codemode)\n");
+		expect(systemMessages[1].sections).toEqual({
+			[MCP_SERVERS_SECTION]: expect.stringContaining("- mcp__slow (codemode): Slow docs."),
+		});
+		expect(harness.session.messages.indexOf(systemMessages[1])).toBeGreaterThan(
+			harness.session.messages.findIndex((message) => message.role === "assistant"),
+		);
+	});
+
+	it("waits for servers with direct tools before listing the servers", async () => {
+		const { harness } = await setupSlow(
+			{ exposure: "direct", toolExposure: { shot: "codemode" }, instructions: "Slow docs." },
+			30,
+		);
+		harness.setResponses([fauxAssistantMessage("ready")]);
+
+		await harness.session.prompt("start");
+
+		expect(serversSection(harness)).toContain("- mcp__slow (codemode): Slow docs.");
+	});
+
+	it("leaves servers with only direct tools out of the servers section", async () => {
+		const { harness } = await setupSlow({ exposure: "direct" }, 0);
+		harness.setResponses([fauxAssistantMessage("ready")]);
+
+		await harness.session.prompt("start");
+
+		expect(serversSection(harness)).toBeUndefined();
+	});
+
+	it("waits for the servers a codemode script names", async () => {
+		const { harness, calls } = await setupSlow({}, 30);
+		harness.setResponses([
+			fauxAssistantMessage(
+				[
+					fauxToolCall("codemode", {
+						code: `return (await tools.mcp__slow__search({ query: "q" })).structuredContent;`,
+					}),
+				],
+				{ stopReason: "toolUse" },
+			),
+			fauxAssistantMessage("done"),
+		]);
+
+		await harness.session.prompt("go");
+
+		const result = toolResult(harness, "codemode");
+		expect(result.isError).toBe(false);
+		expect(JSON.parse(getMessageText(result).split("\n").at(-1) ?? "")).toEqual({ hits: ["q guide", "q faq"] });
+		expect(calls).toEqual(['search:{"query":"q"}']);
+	});
+
+	it("waits for servers whose script identifiers differ from their names", async () => {
+		const { harness, calls } = await setupSlow({ name: "slow-docs" }, 30);
+		harness.setResponses([
+			fauxAssistantMessage(
+				[
+					fauxToolCall("codemode", {
+						code: `await tools.mcp__slow_docs__search({ query: "q" }); return (await describeNamespace("slow_docs")).name;`,
+					}),
+				],
+				{ stopReason: "toolUse" },
+			),
+			fauxAssistantMessage("done"),
+		]);
+
+		await harness.session.prompt("go");
+
+		expect(toolResult(harness, "codemode").isError).toBe(false);
+		expect(getMessageText(toolResult(harness, "codemode")).split("\n").at(-1)).toBe("mcp__slow-docs");
+		expect(calls).toEqual(['search:{"query":"q"}']);
+	});
+
+	it("does not wait for servers a codemode script does not name", async () => {
+		const { harness } = await setupSlow({}, Number.POSITIVE_INFINITY);
+		harness.setResponses([
+			fauxAssistantMessage([fauxToolCall("codemode", { code: "return 1 + 1;" })], { stopReason: "toolUse" }),
+			fauxAssistantMessage("done"),
+		]);
+
+		await harness.session.prompt("go");
+
+		expect(getMessageText(toolResult(harness, "codemode")).split("\n").at(-1)).toBe("2");
+	});
+
+	it("waits for servers before tool_search searches", async () => {
+		const { harness } = await setupSlow({ exposure: "deferred" }, 30);
+		harness.setResponses([
+			fauxAssistantMessage([fauxToolCall("tool_search", { query: "search the docs", limit: 1 })], {
+				stopReason: "toolUse",
+			}),
+			fauxAssistantMessage([fauxToolCall("mcp__slow__search", { query: "late" })], { stopReason: "toolUse" }),
+			fauxAssistantMessage("done"),
+		]);
+
+		await harness.session.prompt("go");
+
+		expect(getMessageText(toolResult(harness, "mcp__slow__search"))).toBe("late guide\nlate faq");
+	});
+
+	it("holds the first prompt for servers with direct tools", async () => {
+		const { harness } = await setupSlow({ exposure: "direct" }, 30);
+		harness.setResponses([fauxAssistantMessage("ready")]);
+
+		await harness.session.prompt("start");
+
+		expect(declaredToolNames(harness)).toContain("mcp__slow__search");
+	});
+
+	it("holds the first prompt for servers with direct tools only up to startupWaitMs", async () => {
+		const { harness, notifications } = await setupSlow({ exposure: "direct" }, Number.POSITIVE_INFINITY, 20);
 		harness.setResponses([fauxAssistantMessage("ready")]);
 
 		await harness.session.prompt("start");
 
 		expect(getAssistantTexts(harness)).toEqual(["ready"]);
 		expect(harness.session.getActiveToolNames()).toEqual([]);
+		expect(notifications).toEqual(["MCP servers are still connecting; their tools become available once connected."]);
 	});
 
 	it("does not let codemode call itself or inactive direct tools", async () => {
@@ -613,8 +812,9 @@ return { uris: listed.resources.map((r) => r.uri), text: read.contents[0].text }
 		await harness.session.prompt("find a docs tool");
 
 		expect(harness.session.getActiveToolNames()).toEqual(["tool_search", searchName]);
+		// The description does not depend on the connected servers.
 		const toolSearch = harness.session.agent.state.tools.find((tool) => tool.name === "tool_search");
-		expect(toolSearch?.description).toContain("mcp__docs");
+		expect(toolSearch?.description).toBe(TOOL_SEARCH_DESCRIPTION);
 
 		const search = toolResult(harness, "tool_search");
 		expect(getMessageText(search)).toBe(
@@ -715,15 +915,14 @@ describe("AgentSession MCP servers registered by extensions", () => {
 
 	it("prefers the mcp.json server over a registered server of the same name", async () => {
 		const configured: McpServerEntry = { name: "docs", config: { url: "http://config.invalid" }, source: "mcp.json" };
-		const { harness, connected } = await setup(
+		const { connected } = await setup(
 			(pi) => {
 				pi.registerMcpServer("docs", { url: "http://plugin.invalid" });
 			},
 			[configured],
 		);
-		harness.setResponses([fauxAssistantMessage("ready")]);
-		await harness.session.prompt("start");
-
+		await vi.waitFor(() => expect(connected).toEqual([configured]));
+		await new Promise((resolve) => setTimeout(resolve, 10));
 		expect(connected).toEqual([configured]);
 	});
 
diff --git a/packages/coding-agent/test/tool-search.test.ts b/packages/coding-agent/test/tool-search.test.ts
index d5533bb05..421971eb4 100644
--- a/packages/coding-agent/test/tool-search.test.ts
+++ b/packages/coding-agent/test/tool-search.test.ts
@@ -3,12 +3,7 @@ import { Type } from "typebox";
 import { describe, expect, it } from "vitest";
 import type { ToolNamespace } from "../src/core/extensions/types.ts";
 import { createCodemodeDescription } from "../src/extensions/codemode/tool.ts";
-import {
-	Bm25Ranker,
-	createToolSearchDescription,
-	createToolSearchDocument,
-	tokenize,
-} from "../src/extensions/tool-search/tool.ts";
+import { Bm25Ranker, createToolSearchDocument, tokenize } from "../src/extensions/tool-search/tool.ts";
 
 function tool(name: string, description: string, properties: Record<string, unknown> = {}): AgentTool {
 	return {
@@ -69,17 +64,6 @@ describe("Bm25Ranker", () => {
 	});
 });
 
-describe("tool_search description", () => {
-	it("lists the sources", () => {
-		expect(
-			createToolSearchDescription([{ name: "mcp__docs", description: "Docs server\nmore" }, { name: "mcp__x" }]),
-		).toBe(
-			"# Tool discovery\n\nSearches over deferred tool metadata with BM25 and exposes matching tools for the next model call.\n\nYou have access to tools from the following sources:\n- mcp__docs: Docs server\n- mcp__x\n\nSome of the tools may not have been provided to you upfront, and you should use this tool (`tool_search`) to search for the required tools. For MCP tool discovery, always use `tool_search`.",
-		);
-		expect(createToolSearchDescription()).toContain("None currently enabled.");
-	});
-});
-
 describe("codemode description catalog", () => {
 	const plain = tool("read_notes", "Read notes.");
 	const github = ["a", "b", "c"].map((suffix) => tool(`mcp__github__${suffix}`, `GitHub ${suffix}.`));
@@ -92,16 +76,16 @@ describe("codemode description catalog", () => {
 
 	it("lists everything without a budget", () => {
 		const description = createCodemodeDescription(all, { namespaces });
-		expect(description).toContain("Nested tools: COMPLETE list.");
+		expect(description).toContain("Nested tools:");
 		expect(description).toContain("## mcp__github\nGitHub server");
 		expect(description).toContain("## mcp__docs\n\n### `mcp__docs");
-		expect(description).not.toContain("Some deferred nested tools");
+		// The search guidance is always there, so tools that appear later do not change it.
+		expect(description).toContain("To find one, call `await searchTools(query)`");
 	});
 
 	it("fills the budget round-robin, cheapest first, and says what is missing", () => {
 		// Each small section costs about 42 tokens: one tool per group, then one more.
 		const description = createCodemodeDescription(all, { namespaces, inlineBudget: 170 });
-		expect(description).toContain("Nested tools: PARTIAL list.");
 		expect(description).toContain("### `read_notes`");
 		expect(description).toContain("## mcp__docs (some tools not listed)");
 		expect(description).toContain("### `mcp__docs__search`");
@@ -112,22 +96,12 @@ describe("codemode description catalog", () => {
 		expect(createCodemodeDescription(all, { namespaces, inlineBudget: 170 })).toBe(description);
 	});
 
-	it("never lists deferred tools or counts them", () => {
+	it("leaves deferred tools and their namespaces out entirely", () => {
 		const deferred = new Set(github.map((entry) => entry.name));
 		const description = createCodemodeDescription(all, { namespaces, deferred });
-		expect(description).toContain("Nested tools: PARTIAL list.");
-		expect(description).toContain("## mcp__github (tools not listed)\nGitHub server");
-		expect(description).not.toContain("### `mcp__github__a`");
-		expect(description).toContain("Some deferred nested tools may be omitted from this description.");
-		// A server adding a deferred tool does not change the description.
-		const added = tool("mcp__github__d", "GitHub d.");
-		const withAdded = new Map([...namespaces, [added.name, { name: "mcp__github", description: "GitHub server" }]]);
-		expect(
-			createCodemodeDescription([...all, added], {
-				namespaces: withAdded,
-				deferred: new Set([...deferred, added.name]),
-			}),
-		).toBe(description);
+		expect(description).not.toContain("mcp__github");
+		// Deferred tools, such as those of a server that connects later, do not change the description.
+		expect(description).toBe(createCodemodeDescription([plain, ...docs], { namespaces }));
 	});
 
 	it("leaves namespace instructions out", () => {
@@ -142,7 +116,6 @@ describe("codemode description catalog", () => {
 
 	it("lists only namespaces with a zero budget", () => {
 		const description = createCodemodeDescription(all, { namespaces, inlineBudget: 0 });
-		expect(description).toContain("Nested tools: PARTIAL list.");
 		expect(description).toContain("## mcp__docs (tools not listed)");
 		expect(description).not.toContain("codemode tool declaration:");
 	});