diff --git a/src/agents/agent-bundle-lsp-runtime.test.ts b/src/agents/agent-bundle-lsp-runtime.test.ts
index 2ff8a99bf41d..2db2f4c72b72 100644
--- a/src/agents/agent-bundle-lsp-runtime.test.ts
+++ b/src/agents/agent-bundle-lsp-runtime.test.ts
@@ -1,3 +1,4 @@
+/** Tests embedded LSP runtime JSON-RPC, tool behavior, and cleanup. */
 import { EventEmitter } from "node:events";
 import { PassThrough, Writable } from "node:stream";
 import { afterEach, describe, expect, it, vi } from "vitest";
diff --git a/src/agents/agent-bundle-lsp-runtime.ts b/src/agents/agent-bundle-lsp-runtime.ts
index e5bae653f619..b95b2491a28c 100644
--- a/src/agents/agent-bundle-lsp-runtime.ts
+++ b/src/agents/agent-bundle-lsp-runtime.ts
@@ -1,3 +1,4 @@
+/** Session-scoped embedded LSP runtime and tool materialization for agent bundles. */
 import { spawn, type ChildProcess } from "node:child_process";
 import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
@@ -46,6 +47,7 @@ type LspServerCapabilities = {
   [key: string]: unknown;
 };
 
+/** Materialized LSP tools plus session capabilities and cleanup handle. */
 export type BundleLspToolRuntime = {
   tools: AnyAgentTool[];
   sessions: Array<{ serverName: string; capabilities: LspServerCapabilities }>;
@@ -69,6 +71,7 @@ function delay(ms: number): Promise<void> {
   });
 }
 
+/** Spawns one LSP server process using sanitized host env and Windows shim handling. */
 export function spawnLspServerProcess(config: StdioMcpServerLaunchConfig): ChildProcess {
   const mergedEnv = sanitizeHostExecEnv({ baseEnv: process.env, overrides: config.env ?? null });
   const program = resolveWindowsSpawnProgram({
diff --git a/src/agents/agent-bundle-lsp-runtime.windows-spawn.test.ts b/src/agents/agent-bundle-lsp-runtime.windows-spawn.test.ts
index afe7a65fd2fa..bc2651ff54b1 100644
--- a/src/agents/agent-bundle-lsp-runtime.windows-spawn.test.ts
+++ b/src/agents/agent-bundle-lsp-runtime.windows-spawn.test.ts
@@ -1,3 +1,4 @@
+/** Tests LSP server spawning with Windows shim and sanitized env handling. */
 import { describe, expect, it, vi, beforeEach } from "vitest";
 import { spawnLspServerProcess } from "./agent-bundle-lsp-runtime.js";
 
diff --git a/src/agents/agent-bundle-mcp-materialize.ts b/src/agents/agent-bundle-mcp-materialize.ts
index 083b6e022f43..2860c911ba50 100644
--- a/src/agents/agent-bundle-mcp-materialize.ts
+++ b/src/agents/agent-bundle-mcp-materialize.ts
@@ -1,3 +1,4 @@
+/** Materializes configured MCP catalog entries into agent tools and runtime helpers. */
 import crypto from "node:crypto";
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
diff --git a/src/agents/agent-bundle-mcp-names.test.ts b/src/agents/agent-bundle-mcp-names.test.ts
index 1463789843db..4f4ad7709f28 100644
--- a/src/agents/agent-bundle-mcp-names.test.ts
+++ b/src/agents/agent-bundle-mcp-names.test.ts
@@ -1,3 +1,4 @@
+/** Tests MCP server/tool name sanitization, truncation, and collision handling. */
 import { describe, expect, it } from "vitest";
 import {
   buildSafeToolName,
diff --git a/src/agents/agent-bundle-mcp-names.ts b/src/agents/agent-bundle-mcp-names.ts
index 33e9969b9c1b..6604f8994dcc 100644
--- a/src/agents/agent-bundle-mcp-names.ts
+++ b/src/agents/agent-bundle-mcp-names.ts
@@ -1,3 +1,4 @@
+/** Sanitizes MCP server/tool names into stable model-facing tool ids. */
 import {
   normalizeLowercaseStringOrEmpty,
   normalizeOptionalLowercaseString,
@@ -38,6 +39,7 @@ function sanitizeToolName(raw: string): string {
   return sanitizeToolFragment(raw, "tool");
 }
 
+/** Normalizes reserved tool names for collision checks. */
 export function normalizeReservedToolNames(names?: Iterable<string>): Set<string> {
   return new Set(
     Array.from(names ?? [], (name) => normalizeOptionalLowercaseString(name)).filter(
diff --git a/src/agents/agent-bundle-mcp-runtime.test.ts b/src/agents/agent-bundle-mcp-runtime.test.ts
index 028ec14c819d..02134b67637d 100644
--- a/src/agents/agent-bundle-mcp-runtime.test.ts
+++ b/src/agents/agent-bundle-mcp-runtime.test.ts
@@ -1,3 +1,4 @@
+/** Tests session-scoped MCP runtime catalog, transport, validation, and lifecycle behavior. */
 import fs from "node:fs/promises";
 import http from "node:http";
 import os from "node:os";
diff --git a/src/agents/agent-bundle-mcp-runtime.ts b/src/agents/agent-bundle-mcp-runtime.ts
index 54f96536ea98..350264cbe65f 100644
--- a/src/agents/agent-bundle-mcp-runtime.ts
+++ b/src/agents/agent-bundle-mcp-runtime.ts
@@ -1,3 +1,4 @@
+/** Session-scoped MCP runtime manager, catalog loader, and transport lifecycle. */
 import crypto from "node:crypto";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
diff --git a/src/agents/agent-bundle-mcp-test-harness.ts b/src/agents/agent-bundle-mcp-test-harness.ts
index 8fcc40e0a0cf..6f2a84294ca1 100644
--- a/src/agents/agent-bundle-mcp-test-harness.ts
+++ b/src/agents/agent-bundle-mcp-test-harness.ts
@@ -1,4 +1,4 @@
-// Test helper for resetting bundle MCP runtime state between harness tests.
+/** Test helper for resetting bundle MCP runtime state between harness tests. */
 /** Reset session-scoped bundle MCP runtime manager state. */
 export async function cleanupBundleMcpHarness(): Promise<void> {
   const { testing } = await import("./agent-bundle-mcp-tools.js");
diff --git a/src/agents/agent-bundle-mcp-tools.materialize.test.ts b/src/agents/agent-bundle-mcp-tools.materialize.test.ts
index c4c9f2cd544e..8558dc7712ba 100644
--- a/src/agents/agent-bundle-mcp-tools.materialize.test.ts
+++ b/src/agents/agent-bundle-mcp-tools.materialize.test.ts
@@ -1,3 +1,4 @@
+/** Tests materializing MCP catalog tools into agent tool definitions and results. */
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { validateToolArguments } from "openclaw/plugin-sdk/llm";
 import { describe, expect, it } from "vitest";
diff --git a/src/agents/agent-bundle-mcp-tools.request-boundary.test.ts b/src/agents/agent-bundle-mcp-tools.request-boundary.test.ts
index 60d21027331f..e9d07a648275 100644
--- a/src/agents/agent-bundle-mcp-tools.request-boundary.test.ts
+++ b/src/agents/agent-bundle-mcp-tools.request-boundary.test.ts
@@ -1,3 +1,4 @@
+/** Tests configured MCP tools survive policy/splitting to the outbound request boundary. */
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import {
diff --git a/src/agents/agent-bundle-mcp-tools.ts b/src/agents/agent-bundle-mcp-tools.ts
index 6d43ba952c08..46c0b25e1e16 100644
--- a/src/agents/agent-bundle-mcp-tools.ts
+++ b/src/agents/agent-bundle-mcp-tools.ts
@@ -1,5 +1,4 @@
-// Public barrel for bundle MCP tool materialization and session-scoped runtime
-// management. Keep callers on this facade instead of importing runtime internals.
+/** Public facade for bundle MCP tool materialization and session-scoped runtime management. */
 export type {
   BundleMcpToolRuntime,
   McpCatalogTool,
diff --git a/src/agents/agent-bundle-mcp-types.ts b/src/agents/agent-bundle-mcp-types.ts
index 787fb13c6e27..d669e99e7b9a 100644
--- a/src/agents/agent-bundle-mcp-types.ts
+++ b/src/agents/agent-bundle-mcp-types.ts
@@ -1,14 +1,17 @@
+/** Shared bundle MCP catalog, runtime, and manager types. */
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import type { TSchema } from "typebox";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { AnyAgentTool } from "./tools/common.js";
 
+/** Materialized MCP tools plus diagnostics and cleanup handle for one run. */
 export type BundleMcpToolRuntime = {
   tools: AnyAgentTool[];
   diagnostics?: readonly McpToolCatalogDiagnostic[];
   dispose: () => Promise<void>;
 };
 
+/** Catalog metadata for one configured MCP server. */
 export type McpServerCatalog = {
   serverName: string;
   safeServerName?: string;
@@ -32,6 +35,7 @@ export type McpServerCatalog = {
   };
 };
 
+/** MCP tool entry after server-name sanitization and schema normalization. */
 export type McpCatalogTool = {
   serverName: string;
   safeServerName: string;
@@ -42,6 +46,7 @@ export type McpCatalogTool = {
   fallbackDescription: string;
 };
 
+/** Complete tool catalog for a session-scoped MCP runtime. */
 export type McpToolCatalog = {
   version: number;
   generatedAt: number;
@@ -57,6 +62,7 @@ export type McpToolCatalogDiagnostic = {
   message: string;
 };
 
+/** Live MCP runtime bound to one session/workspace. */
 export type SessionMcpRuntime = {
   sessionId: string;
   sessionKey?: string;
@@ -79,6 +85,7 @@ export type SessionMcpRuntime = {
   dispose: () => Promise<void>;
 };
 
+/** Manager for session-scoped MCP runtimes and their idle lifecycle. */
 export type SessionMcpRuntimeManager = {
   getOrCreate: (params: {
     sessionId: string;