@sema-agent/core 5.53.0 → 5.55.0

package/dist/core/mcp.js

@@ -7,6 +7,7 @@ import { lstat, mkdir, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { CallToolResultSchema, ElicitRequestSchema, ErrorCode, ListResourcesResultSchema, McpError } from "@modelcontextprotocol/sdk/types.js";
+import { DEFAULT_REQUEST_TIMEOUT_MSEC } from "@modelcontextprotocol/sdk/shared/protocol.js";
 import { MCP_IMAGE_MAX_BASE64, sharpImageResizer } from "./image-downsample.js";
 import { sliceHeadSafe, sliceTailSafe } from "./surrogate-safe-slice.js";
 import { truncateError } from "./tool-errors.js";
@@ -536,6 +537,82 @@ export async function mapContent(content, serverName, imageResizer) {
     }
     return out;
 }
+export const MCP_INVISIBLE_TEXT_RE = /[\p{Cf}\p{Co}\p{Cn}]/gu;
+const MCP_SANITIZE_MAX_ROUNDS = 10;
+function sanitizeMcpModelFacingText(text) {
+    let out = text;
+    for (let round = 0; round < MCP_SANITIZE_MAX_ROUNDS; round++) {
+        const next = out.normalize("NFKC").replace(MCP_INVISIBLE_TEXT_RE, "");
+        if (next === out)
+            return out;
+        out = next;
+    }
+    return out.replace(MCP_INVISIBLE_TEXT_RE, "");
+}
+const MCP_SCHEMA_PROSE_KEYS = new Set(["description", "title", "$comment"]);
+const MCP_SCHEMA_CHILD_SEAT = new Map([
+    ...["properties", "definitions", "$defs", "dependentSchemas"].map((k) => [k, "properties"]),
+    ...["patternProperties"].map((k) => [k, "schemaMap"]),
+    ...["items", "prefixItems", "additionalItems", "additionalProperties", "unevaluatedItems", "unevaluatedProperties", "contains", "propertyNames", "contentSchema", "not", "if", "then", "else", "allOf", "anyOf", "oneOf"].map((k) => [k, "schema"]),
+    ...["required", "dependentRequired", "dependencies", "$ref", "$dynamicRef", "$id", "$anchor", "$dynamicAnchor"].map((k) => [k, "nameRefs"]),
+]);
+class McpPayloadKeyCollision extends Error {
+}
+function sanitizeMcpSchemaNameRefs(value) {
+    if (typeof value === "string")
+        return sanitizeMcpModelFacingText(value);
+    if (Array.isArray(value))
+        return value.map(sanitizeMcpSchemaNameRefs);
+    if (value !== null && typeof value === "object") {
+        const out = Object.create(null);
+        for (const [key, v] of Object.entries(value)) {
+            const neutralized = sanitizeMcpModelFacingText(key);
+            if (Object.hasOwn(out, neutralized))
+                throw new McpPayloadKeyCollision(neutralized);
+            out[neutralized] = Array.isArray(v) ? sanitizeMcpSchemaNameRefs(v) : sanitizeMcpModelFacingValue(v, "schema");
+        }
+        return out;
+    }
+    return value;
+}
+function sanitizeMcpModelFacingValue(value, seat = "schema") {
+    if (seat === "data")
+        return value;
+    if (seat === "nameRefs")
+        return sanitizeMcpSchemaNameRefs(value);
+    if (Array.isArray(value))
+        return value.map((v) => sanitizeMcpModelFacingValue(v, seat === "schema" ? "schema" : "data"));
+    if (value !== null && typeof value === "object") {
+        const out = Object.create(null);
+        for (const [key, v] of Object.entries(value)) {
+            if (seat === "schemaMap") {
+                out[key] = sanitizeMcpModelFacingValue(v, "schema");
+                continue;
+            }
+            const neutralized = sanitizeMcpModelFacingText(key);
+            if (Object.hasOwn(out, neutralized))
+                throw new McpPayloadKeyCollision(neutralized);
+            if (seat === "properties") {
+                out[neutralized] = sanitizeMcpModelFacingValue(v, "schema");
+                continue;
+            }
+            if (MCP_SCHEMA_PROSE_KEYS.has(neutralized)) {
+                out[neutralized] = typeof v === "string" ? sanitizeMcpModelFacingText(v) : v;
+                continue;
+            }
+            out[neutralized] = sanitizeMcpModelFacingValue(v, MCP_SCHEMA_CHILD_SEAT.get(neutralized) ?? "data");
+        }
+        return out;
+    }
+    return value;
+}
+const MCP_TOOL_DESCRIPTION_MAX_CHARS = 2048;
+const MCP_TOOL_DESCRIPTION_TRUNCATION_MARK = "… [truncated]";
+function capMcpToolDescription(description) {
+    if (description.length <= MCP_TOOL_DESCRIPTION_MAX_CHARS)
+        return description;
+    return sliceHeadSafe(description, MCP_TOOL_DESCRIPTION_MAX_CHARS) + MCP_TOOL_DESCRIPTION_TRUNCATION_MARK;
+}
 const MCP_SCHEMA_COMBINATOR_KEYS = ["anyOf", "oneOf", "allOf"];
 const MCP_SCHEMA_PROP_NAME_RE = /^[a-zA-Z0-9_.-]{1,64}$/;
 const MCP_SCHEMA_CARRY_KEYS = ["$defs", "definitions", "$schema", "additionalProperties", "description", "title"];
@@ -642,6 +719,19 @@ export function normalizeMcpToolSchema(schema) {
         return { outcome: "drop", reason: `input schema uses top-level ${combinatorsPresent.join("/")} and could not be normalized` };
     }
 }
+export function mcpToolSchemaAdvisory(schema) {
+    if (schema === undefined || !isPlainSchemaObject(schema))
+        return undefined;
+    const properties = schema.properties;
+    if (!isPlainSchemaObject(properties))
+        return undefined;
+    for (const key of Object.keys(properties)) {
+        if (!MCP_SCHEMA_PROP_NAME_RE.test(key)) {
+            return `its parameter name ${inlineUntrusted(JSON.stringify(key), 80)} is outside the character set some providers accept for tool parameters (${MCP_SCHEMA_PROP_NAME_RE.source}); requests carrying this tool may be rejected by such a provider`;
+        }
+    }
+    return undefined;
+}
 export function mcpToolSchemaProblem(schema) {
     if (schema === undefined)
         return undefined;
@@ -719,7 +809,7 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
             if (r.status === "fulfilled") {
                 const s = r.value;
                 clients.push(s.client);
-                serverHandles.push({ name: spec.name, spec, client: s.client, health: s.health, toolNames: s.tools.map((t) => t.name) });
+                serverHandles.push({ name: spec.name, spec, client: s.client, health: s.health, tools: s.tools, listedRaw: s.listedTools });
                 tools.push(...s.tools);
                 toolAxes.push(...s.axes);
                 if (s.instructions) {
@@ -740,6 +830,13 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
                     resourceServers.push(s.resourceServer);
                 for (const d of s.dropped)
                     droppedTools.push({ server: inlineUntrusted(spec.name, 160), ...d });
+                for (const a of s.schemaAdvisories)
+                    warnings.push(schemaAdvisoryWarning(spec.name, a.tool, a.reason));
+                if (s.toolsCapabilityAbsent === true && spec.allowTools !== undefined && spec.allowTools.length > 0) {
+                    warnings.push(toolsCapabilityAbsentWarning(spec.name));
+                }
+                if (s.listingIncomplete)
+                    warnings.push(listingIncompleteWarning(spec.name, s.listingIncomplete));
                 statuses.push(s.status);
             }
             else {
@@ -781,12 +878,17 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
                 }
                 try {
                     const listed = await listToolsLenient(h.client);
-                    cacheMcpToolMetadata(h.client, listed.tools);
-                    const { serverTools, serverAxes, dropped } = intakeListedTools(listed, h.spec, h.client, h.health, imageResizer, mcpDisclosure, isServerRevoked);
+                    const advertised = new Set(listed.tools.map((t) => t.name));
+                    const retainedRaw = listed.incomplete !== undefined ? h.listedRaw.filter((t) => !advertised.has(t.name)) : [];
+                    const mergedRaw = retainedRaw.length > 0 ? [...listed.tools, ...retainedRaw] : listed.tools;
+                    cacheMcpToolMetadata(h.client, retainedRaw.length > 0 ? [...retainedRaw, ...listed.tools] : listed.tools);
+                    const { serverTools, serverAxes, dropped } = intakeListedTools({ tools: mergedRaw }, h.spec, h.client, h.health, imageResizer, mcpDisclosure, isServerRevoked);
+                    const priorNames = h.tools.map((t) => t.name);
                     const newNames = serverTools.map((t) => t.name);
-                    const added = newNames.filter((n) => !h.toolNames.includes(n));
-                    const removed = h.toolNames.filter((n) => !newNames.includes(n));
-                    h.toolNames = newNames;
+                    const added = newNames.filter((n) => !priorNames.includes(n));
+                    const removed = priorNames.filter((n) => !newNames.includes(n));
+                    h.tools = serverTools;
+                    h.listedRaw = mergedRaw;
                     results.push({
                         server: h.name,
                         prefix: prefixOf(h.name),
@@ -797,6 +899,9 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
                         tools: serverTools,
                         axes: serverAxes,
                         dropped: dropped.map((d) => ({ server: inlineUntrusted(h.name, 160), ...d })),
+                        ...(listed.incomplete !== undefined
+                            ? { listingIncomplete: listed.incomplete, error: `tool listing incomplete — ${listingIncompleteNote(listed.incomplete)}` }
+                            : {}),
                     });
                 }
                 catch (err) {
@@ -804,7 +909,7 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
                         server: h.name,
                         prefix: prefixOf(h.name),
                         status: "failed",
-                        toolCount: h.toolNames.length,
+                        toolCount: h.tools.length,
                         added: [],
                         removed: [],
                         error: inlineUntrusted(namedMcpFailureText(err), 240),
@@ -875,6 +980,110 @@ function resourceLine(r) {
 function serverNames(servers) {
     return servers.map((r) => r.server).join(", ") || "(none)";
 }
+const MAX_MCP_LIST_PAGES = 20;
+const MIN_MCP_PAGE_BUDGET_MS = 250;
+function continuationPageFloorMs(budgetMs) {
+    return Math.max(1, Math.min(MIN_MCP_PAGE_BUDGET_MS, Math.floor(budgetMs / 10)));
+}
+export function listEntryFingerprint(entry) {
+    try {
+        const json = JSON.stringify(entry);
+        return typeof json === "string" ? json : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+const LIST_ENTRY_FINGERPRINT_MAX_CHARS = 8 * 1024;
+const LOOP_REWIND_FINGERPRINT_MAX_CHARS = 1024 * 1024;
+export async function walkMcpListPages(fetchPage, opts) {
+    const items = [];
+    const used = new Set();
+    const deadline = Date.now() + opts.budgetMs;
+    let cursor;
+    let pages = 0;
+    for (;;) {
+        const remainingMs = pages === 0 ? opts.budgetMs : deadline - Date.now();
+        if (pages > 0 && remainingMs < continuationPageFloorMs(opts.budgetMs)) {
+            return { items, incomplete: { reason: "budget_exhausted", pages, budgetMs: opts.budgetMs } };
+        }
+        let page;
+        try {
+            page = await fetchPage(cursor, remainingMs);
+        }
+        catch (err) {
+            if (pages === 0 || opts.signal?.aborted)
+                throw err;
+            return { items, incomplete: { reason: "page_error", pages, error: err instanceof Error ? err.message : String(err) } };
+        }
+        opts.onPage?.();
+        const pageStart = items.length;
+        items.push(...page.items);
+        pages++;
+        if (page.cursorInvalid === true)
+            return { items, incomplete: { reason: "cursor_invalid", pages } };
+        const next = page.nextCursor;
+        if (next === undefined)
+            return { items };
+        if (used.has(next)) {
+            const fresh = [];
+            const fingerprintOf = opts.fingerprintOf;
+            if (fingerprintOf !== undefined) {
+                const before = new Set();
+                let keying = LOOP_REWIND_FINGERPRINT_MAX_CHARS;
+                const keyOf = (item) => {
+                    if (keying <= 0)
+                        return undefined;
+                    const fp = fingerprintOf(item);
+                    if (fp === undefined) {
+                        keying -= LIST_ENTRY_FINGERPRINT_MAX_CHARS;
+                        return undefined;
+                    }
+                    keying -= fp.length;
+                    return fp.length <= LIST_ENTRY_FINGERPRINT_MAX_CHARS ? fp : undefined;
+                };
+                for (let i = 0; i < pageStart; i++) {
+                    const fp = keyOf(items[i]);
+                    if (fp !== undefined)
+                        before.add(fp);
+                }
+                for (const item of page.items) {
+                    const fp = keyOf(item);
+                    if (fp !== undefined && before.has(fp))
+                        continue;
+                    fresh.push(item);
+                }
+            }
+            items.length = pageStart;
+            items.push(...fresh);
+            return { items, incomplete: { reason: "cursor_loop", pages } };
+        }
+        if (pages >= MAX_MCP_LIST_PAGES)
+            return { items, incomplete: { reason: "page_cap", pages } };
+        used.add(next);
+        cursor = next;
+    }
+}
+function idleWatchdogTripText(idleMs) {
+    return `received no response for ${idleMs}ms (idle watchdog; set MCP_IDLE_TIMEOUT_STDIO / MCP_IDLE_TIMEOUT_HTTP to change this bound)`;
+}
+function listingIncompleteNote(flag) {
+    const pages = `${flag.pages} page${flag.pages === 1 ? "" : "s"}`;
+    if (flag.reason === "page_cap") {
+        return `[listing truncated: the ${MAX_MCP_LIST_PAGES}-page pagination limit was reached — more entries may exist beyond this listing]`;
+    }
+    if (flag.reason === "cursor_loop") {
+        return `[listing truncated: after ${pages} the server handed back a pagination cursor it had already used, so the walk stopped — more entries may exist beyond this listing]`;
+    }
+    if (flag.reason === "cursor_invalid") {
+        return `[listing truncated: after ${pages} the server sent a pagination cursor that is not a string, so the walk could not continue — more entries may exist beyond this listing]`;
+    }
+    if (flag.reason === "budget_exhausted") {
+        const budget = flag.budgetMs !== undefined ? `${flag.budgetMs}ms ` : "";
+        return `[listing truncated: after ${pages} the ${budget}time budget for this listing was too low to give the next page a usable request, so the client stopped without sending one — this is a client-side bound, not a server failure; more entries may exist beyond this listing]`;
+    }
+    return `[listing incomplete: the server failed mid-pagination after ${pages} (${inlineUntrusted(flag.error ?? "unknown error", 240)}) — only the pages retrieved before the failure are shown]`;
+}
 async function readDirViaExtension(rs, uri, signal, timeoutMs, watchdog) {
     const resources = [];
     let cursor;
@@ -918,10 +1127,13 @@ function renderDirChildren(server, uri, children, flags) {
     if (flags?.cursorInvalid) {
         notes.push(`[listing incomplete: the server rejected the pagination cursor (invalid or expired) — only the pages retrieved before the rejection are shown; more entries may exist beyond this listing]`);
     }
+    if (flags?.listing)
+        notes.push(listingIncompleteNote(flags.listing));
     const detailFlags = {
         ...(flags?.truncated ? { truncated: true } : {}),
         ...(flags?.incomplete !== undefined ? { incomplete: true, error: flags.incomplete } : {}),
         ...(flags?.cursorInvalid ? { incomplete: true, cursorInvalid: true } : {}),
+        ...(flags?.listing ? { incomplete: true, listing: flags.listing } : {}),
     };
     const listing = children.length === 0
         ? `(Empty directory: ${inlineUntrusted(uri)})`
@@ -959,6 +1171,7 @@ function buildResourceTools(resourceServers, isServerRevoked = () => false) {
                 const sections = [];
                 const all = [];
                 const errors = [];
+                const incomplete = [];
                 for (const rs of targets) {
                     if (isServerRevoked(rs.server)) {
                         errors.push({ server: rs.server, error: "server revoked by the operator mid-session (request not sent)" });
@@ -973,16 +1186,30 @@ function buildResourceTools(resourceServers, isServerRevoked = () => false) {
                     const idleMs = mcpIdleTimeoutMs(rs.transportKind);
                     const watchdog = armMcpIdleWatchdog(rs.health, idleMs, signal);
                     try {
-                        const res = await rs.client.listResources(undefined, { signal: watchdog.combinedSignal, timeout: mcpToolTimeoutMs() });
-                        all.push(...res.resources.map((r) => ({ server: rs.server, ...r })));
-                        const lines = res.resources.map((r) => resourceLine(r));
-                        sections.push(`[${rs.server}]\n${lines.length ? lines.join("\n") : "(no resources)"}`);
+                        const walk = await walkMcpListPages(async (cursor, remainingMs) => {
+                            const page = await rs.client
+                                .listResources(cursor === undefined ? undefined : { cursor }, { signal: watchdog.combinedSignal, timeout: remainingMs })
+                                .catch((err) => {
+                                throw watchdog.idleSignal.reason === IDLE_WATCHDOG_ABORT_REASON ? new Error(idleWatchdogTripText(idleMs)) : err;
+                            });
+                            return { items: page.resources, ...(page.nextCursor !== undefined ? { nextCursor: page.nextCursor } : {}) };
+                        }, { budgetMs: mcpToolTimeoutMs(), onPage: () => watchdog.rearm(), fingerprintOf: listEntryFingerprint, ...(signal !== undefined ? { signal } : {}) });
+                        all.push(...walk.items.map((r) => ({ server: rs.server, ...r })));
+                        const lines = walk.items.map((r) => resourceLine(r));
+                        const body = lines.length ? lines.join("\n") : "(no resources)";
+                        if (walk.incomplete) {
+                            incomplete.push({ server: rs.server, ...walk.incomplete });
+                            sections.push(`[${rs.server}]\n${body}\n${listingIncompleteNote(walk.incomplete)}`);
+                        }
+                        else {
+                            sections.push(`[${rs.server}]\n${body}`);
+                        }
                     }
                     catch (err) {
                         if (signal?.aborted)
                             throw err;
                         const msg = watchdog.idleSignal.reason === IDLE_WATCHDOG_ABORT_REASON
-                            ? `received no response for ${idleMs}ms (idle watchdog; set MCP_IDLE_TIMEOUT_STDIO / MCP_IDLE_TIMEOUT_HTTP to change this bound)`
+                            ? idleWatchdogTripText(idleMs)
                             : err instanceof Error
                                 ? err.message
                                 : String(err);
@@ -996,7 +1223,7 @@ function buildResourceTools(resourceServers, isServerRevoked = () => false) {
                 const body = sections.join("\n\n");
                 return {
                     content: [{ type: "text", text: sections.length ? delimitUntrusted("mcp resources", body) : "(no MCP resources)" }],
-                    details: { resources: all, ...(errors.length ? { errors } : {}) },
+                    details: { resources: all, ...(errors.length ? { errors } : {}), ...(incomplete.length ? { incomplete } : {}) },
                     terminate: false,
                 };
             },
@@ -1125,12 +1352,15 @@ function buildResourceTools(resourceServers, isServerRevoked = () => false) {
                             return renderDirChildren(server, uri, r.resources, { truncated: r.truncated, incomplete: r.incomplete, cursorInvalid: r.cursorInvalid });
                         watchdog.rearm();
                     }
-                    const res = await rs.client
-                        .listResources(undefined, { signal: watchdog.combinedSignal, timeout: timeoutMs })
-                        .catch((err) => rethrowHonestMcpError(err, { server, what, timeoutMs, writeEffect: false, signal, attributeServer: true, idle: { signal: watchdog.idleSignal, idleMs } }));
+                    const walk = await walkMcpListPages(async (cursor, remainingMs) => {
+                        const page = await rs.client
+                            .listResources(cursor === undefined ? undefined : { cursor }, { signal: watchdog.combinedSignal, timeout: remainingMs })
+                            .catch((err) => rethrowHonestMcpError(err, { server, what, timeoutMs: remainingMs, writeEffect: false, signal, attributeServer: true, idle: { signal: watchdog.idleSignal, idleMs } }));
+                        return { items: page.resources, ...(page.nextCursor !== undefined ? { nextCursor: page.nextCursor } : {}) };
+                    }, { budgetMs: timeoutMs, onPage: () => watchdog.rearm(), fingerprintOf: listEntryFingerprint, ...(signal !== undefined ? { signal } : {}) });
                     const dirPrefix = uri.endsWith("/") ? uri : `${uri}/`;
-                    const children = res.resources.filter((r) => typeof r.uri === "string" && r.uri !== uri && r.uri.startsWith(dirPrefix));
-                    return renderDirChildren(server, uri, children);
+                    const children = walk.items.filter((r) => typeof r.uri === "string" && r.uri !== uri && r.uri.startsWith(dirPrefix));
+                    return renderDirChildren(server, uri, children, walk.incomplete ? { listing: walk.incomplete } : undefined);
                 }
                 finally {
                     watchdog.dispose();
@@ -1177,7 +1407,8 @@ const LenientListToolsResultSchema = {
             });
         }
         const nextCursor = data.nextCursor;
-        return { success: true, data: { tools, ...(typeof nextCursor === "string" ? { nextCursor } : {}) } };
+        const cursorInvalid = nextCursor !== undefined && nextCursor !== null && typeof nextCursor !== "string";
+        return { success: true, data: { tools, ...(typeof nextCursor === "string" ? { nextCursor } : {}), ...(cursorInvalid ? { cursorInvalid: true } : {}) } };
     },
 };
 export function parseCallToolResultLenient(data) {
@@ -1192,7 +1423,21 @@ export function parseCallToolResultLenient(data) {
 }
 const LENIENT_CALL_TOOL_RESULT_SCHEMA = { safeParse: parseCallToolResultLenient };
 async function listToolsLenient(client, options) {
-    return client.request({ method: "tools/list", params: {} }, LenientListToolsResultSchema, options);
+    if (!client.getServerCapabilities()?.tools)
+        return { tools: [], toolsCapabilityAbsent: true };
+    const walk = await walkMcpListPages(async (cursor, remainingMs) => {
+        const page = await client.request({ method: "tools/list", params: cursor === undefined ? {} : { cursor } }, LenientListToolsResultSchema, { ...options, timeout: remainingMs });
+        return {
+            items: page.tools,
+            ...(page.nextCursor !== undefined ? { nextCursor: page.nextCursor } : {}),
+            ...(page.cursorInvalid === true ? { cursorInvalid: true } : {}),
+        };
+    }, {
+        budgetMs: options?.timeout ?? DEFAULT_REQUEST_TIMEOUT_MSEC,
+        fingerprintOf: listEntryFingerprint,
+        ...(options?.signal !== undefined ? { signal: options.signal } : {}),
+    });
+    return { tools: walk.items, ...(walk.incomplete !== undefined ? { incomplete: walk.incomplete } : {}) };
 }
 async function connectServer(spec, principal, onElicit, imageResizer, reminderDisclosure, isServerRevoked) {
     const elicitOn = spec.elicitation === true && onElicit !== undefined;
@@ -1230,7 +1475,7 @@ async function connectServer(spec, principal, onElicit, imageResizer, reminderDi
         };
         const listed = await listToolsLenient(client, startupOpts);
         cacheMcpToolMetadata(client, listed.tools);
-        const { serverTools, serverAxes, dropped } = intakeListedTools(listed, spec, client, health, imageResizer, reminderDisclosure, isServerRevoked);
+        const { serverTools, serverAxes, dropped, advisories } = intakeListedTools(listed, spec, client, health, imageResizer, reminderDisclosure, isServerRevoked);
         const caps = client.getServerCapabilities();
         const resourceInfo = caps?.resources
             ? {
@@ -1254,7 +1499,11 @@ async function connectServer(spec, principal, onElicit, imageResizer, reminderDi
             tools: serverTools,
             axes: serverAxes,
             dropped,
+            schemaAdvisories: advisories,
+            ...(listed.toolsCapabilityAbsent === true ? { toolsCapabilityAbsent: true } : {}),
+            listedTools: listed.tools,
             ...(instructions ? { instructions } : {}),
+            ...(listed.incomplete !== undefined ? { listingIncomplete: listed.incomplete } : {}),
             ...(resourceInfo && (resourceInfo.listAllowed || resourceInfo.readAllowed) ? { resourceServer: { server: spec.name, client, health, transportKind: idleKindOf(spec), ...resourceInfo } } : {}),
         };
     }
@@ -1267,14 +1516,28 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
     const serverTools = [];
     const serverAxes = [];
     const dropped = [];
-    const mintedNames = new Set();
+    const advisories = [];
+    const mintedNames = new Map();
     for (const t of listed.tools) {
         if (spec.allowTools && !spec.allowTools.includes(t.name)) {
             continue;
         }
-        const normalized = normalizeMcpToolSchema(t.inputSchema);
-        let effectiveInputSchema = t.inputSchema;
-        let effectiveDescription = t.description !== undefined ? sanitizeUntrustedText(t.description) : undefined;
+        let modelFacingSchema;
+        let sanitizedDescription;
+        try {
+            modelFacingSchema = sanitizeMcpModelFacingValue(t.inputSchema);
+            sanitizedDescription = t.description !== undefined ? sanitizeMcpModelFacingText(t.description) : undefined;
+        }
+        catch (err) {
+            const reason = err instanceof McpPayloadKeyCollision
+                ? `two of its advertised names neutralize to the same model-facing spelling ${inlineUntrusted(JSON.stringify(err.message), 80)}; one parameter would have vanished from the schema the model is given while the server still expects it`
+                : "advertised tool payload could not be neutralized for model-facing display (pathological nesting)";
+            dropped.push({ tool: inlineUntrusted(t.name), reason: inlineUntrusted(reason, 240) });
+            continue;
+        }
+        const normalized = normalizeMcpToolSchema(modelFacingSchema);
+        let effectiveInputSchema = modelFacingSchema;
+        let effectiveDescription = sanitizedDescription !== undefined ? sanitizeUntrustedText(sanitizedDescription) : undefined;
         if (normalized.outcome === "drop") {
             dropped.push({ tool: inlineUntrusted(t.name), reason: inlineUntrusted(normalized.reason, 240) });
             continue;
@@ -1288,16 +1551,23 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
             dropped.push({ tool: inlineUntrusted(t.name), reason: inlineUntrusted(schemaProblem, 240) });
             continue;
         }
+        const schemaAdvisory = mcpToolSchemaAdvisory(effectiveInputSchema);
+        if (schemaAdvisory !== undefined) {
+            advisories.push({ tool: inlineUntrusted(t.name), reason: inlineUntrusted(schemaAdvisory, 240) });
+        }
         const remoteName = t.name;
         const namespacedName = mintNamespacedToolName(MCP_NAMESPACE, spec.name, remoteName);
-        if (mintedNames.has(namespacedName)) {
+        const mintedBy = mintedNames.get(namespacedName);
+        if (mintedBy !== undefined) {
             dropped.push({
                 tool: inlineUntrusted(t.name),
-                reason: `name collides with an earlier tool of this server: both mount as "${namespacedName}" after namespacing (only [a-zA-Z0-9_-] survives), and one name cannot denote two tools`,
+                reason: mintedBy === t.name
+                    ? `this server listed this tool name more than once in one listing; the first entry is mounted as "${namespacedName}" and the repeat is dropped (one name cannot denote two tools)`
+                    : `name collides with an earlier tool of this server: both mount as "${namespacedName}" after namespacing (only [a-zA-Z0-9_-] survives), and one name cannot denote two tools`,
             });
             continue;
         }
-        mintedNames.add(namespacedName);
+        mintedNames.set(namespacedName, t.name);
         const hintAxis = mcpAxisFor(namespacedName, t.annotations);
         const axis = applyCallerAxisOverride(namespacedName, hintAxis, spec.toolAxes?.[remoteName]);
         if (axis)
@@ -1308,7 +1578,7 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
         const mcpAlwaysLoad = mcpToolMeta?.["anthropic/alwaysLoad"] === true;
         serverTools.push({
             name: namespacedName,
-            description: effectiveDescription ?? `MCP tool ${remoteName} from ${spec.name}`,
+            description: capMcpToolDescription(effectiveDescription ?? `MCP tool ${inlineUntrusted(sanitizeMcpModelFacingText(remoteName))} from ${spec.name}`),
             label: `${spec.name}:${remoteName}`,
             parameters: (effectiveInputSchema ?? { type: "object" }),
             ...(mcpMaxResultSizeChars !== undefined ? { mcpMaxResultSizeChars } : {}),
@@ -1410,10 +1680,25 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
             },
         });
     }
-    return { serverTools, serverAxes, dropped };
+    return { serverTools, serverAxes, dropped, advisories };
 }
 function asServerWarning(spec, err) {
     const warning = new Error(`mcp: server "${spec.name}" failed to connect — skipped (${namedMcpFailureText(err)})`, { cause: err });
     warning.code = "mcp.server_unavailable";
     return warning;
 }
+function schemaAdvisoryWarning(server, tool, reason) {
+    const warning = new Error(`mcp: server "${inlineUntrusted(server, 160)}" tool "${tool}" is mounted, but ${reason}.`);
+    warning.code = "mcp.tool_schema_advisory";
+    return warning;
+}
+function toolsCapabilityAbsentWarning(server) {
+    const warning = new Error(`mcp: server "${inlineUntrusted(server, 160)}" declared no "tools" capability, so no tool listing was requested and none of the tools named in this server's allowTools can be mounted. If the server does serve tools, it must declare the capability at initialize.`);
+    warning.code = "mcp.tools_capability_absent";
+    return warning;
+}
+function listingIncompleteWarning(server, flag) {
+    const warning = new Error(`mcp: server "${inlineUntrusted(server, 160)}" listed its tools INCOMPLETELY — ${listingIncompleteNote(flag)}. The tools beyond the ${flag.pages} page${flag.pages === 1 ? "" : "s"} retrieved are NOT mounted for this task.`);
+    warning.code = "mcp.listing_incomplete";
+    return warning;
+}