@bevel-software/platform-core-backend 0.25.0 → 0.26.0

package/dist/modules/agent-instructions/shared-file-rules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shared-file-rules.d.ts","sourceRoot":"","sources":["../../../src/modules/agent-instructions/shared-file-rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAKL,KAAK,QAAQ,EACd,MAAM,iCAAiC,CAAC;AAGzC,oFAAoF;AACpF,eAAO,MAAM,oBAAoB,uBAAuB,CAAC;AAUzD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,OAAQ,CAAC;AAE3C,oEAAoE;AACpE,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,EAAE,EAAE,MAAM,CAAC;IACX,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,oFAAoF;IACpF,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,cAAc,EAAE,CAqH3E;AAgDD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,CAK/D;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,GAAE,QAA4B,GAAG,MAAM,CAK/E;AAED;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,QAGpC,CAAC"}
+{"version":3,"file":"shared-file-rules.d.ts","sourceRoot":"","sources":["../../../src/modules/agent-instructions/shared-file-rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAGL,KAAK,QAAQ,EACd,MAAM,iCAAiC,CAAC;AAGzC,oFAAoF;AACpF,eAAO,MAAM,oBAAoB,uBAAuB,CAAC;AAUzD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,OAAQ,CAAC;AAE3C,oEAAoE;AACpE,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,EAAE,EAAE,MAAM,CAAC;IACX,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,oFAAoF;IACpF,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,cAAc,EAAE,CAoH3E;AAsCD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,CAK/D"}

package/dist/modules/agent-instructions/shared-file-rules.js

@@ -14,29 +14,31 @@
  *
  *  - the MCP `instructions` of the initialize handshake (see `compose.ts`),
  *    which Claude Code, Claude Desktop and Cursor put in the system prompt;
- *  - the platform-managed agent guide at the repository root (`AGENTS.md` by
- *    default), rendered from `{{sharedFileRules}}` in the template — claude.ai
- *    on the web, the Agent SDK and Cline drop `instructions`, and a guide the
- *    agent is told to read before its first action is always available.
+ *  - the platform's agent guide, which `get_agent_guide` returns and a
+ *    `read_file` of the guide's name serves (see `modules/agent-guide`) —
+ *    claude.ai on the web, the Agent SDK and Cline drop `instructions`, and a
+ *    guide the agent is told to read before its first action is always
+ *    available.
  *
  * Both places get the SAME string, from {@link sharedFileRulesSection} — not
  * two hand-mirrored copies. A rule written twice is a rule that drifts, and a
  * drifted rule is worse than a repeated one, because the agent cannot tell
- * which copy is current. Each description ends instead with
- * {@link sharedRulesPointer}, one sentence naming the section and the file.
+ * which copy is current. Each description opens instead with the one
+ * sentence sending the agent to the guide (`tool-registry/guide-first.ts`).
  *
- * Pure text, a function of the layout only: the guide's file name is a
- * deployment setting, so nothing here may snapshot `AGENTS.md`.
+ * Pure text, a function of the layout only: the guide's name is a deployment
+ * setting (an alias a deployment chose before the guide left the disk), so
+ * nothing here may snapshot `AGENTS.md`.
  */
-import { DEFAULT_KB_LAYOUT, agentsFileOf, LEGACY_AGENTS_FILE, platformFilesByDepth, } from '@bevel-software/platform-shared';
+import { LEGACY_AGENTS_FILE, platformFilesByDepth, } from '@bevel-software/platform-shared';
 import { CHAIN_FAILURES_RULE, CHAIN_LARGE_RESULTS_RULE } from '@bevel-software/platform-mcp-core';
 /** The heading the rules live under, in both places and in the pointer sentence. */
 export const SHARED_RULES_SECTION = 'Working with files';
 /**
  * The guide's name on a knowledge base seeded before it was renamed to
- * {@link LEGACY_AGENTS_FILE}. Named in the conventions rule because the seeder
- * never deletes a file it did not expect, so such a knowledge base still
- * carries one.
+ * {@link LEGACY_AGENTS_FILE}, back when the guide was a file. The platform's
+ * own copy is taken out at startup now (see template-files.step.ts); one that
+ * stays is a file the organisation edited, so it is theirs and still named.
  */
 const PRE_RENAME_AGENTS_FILE = 'CLAUDE.md';
 /**
@@ -63,12 +65,11 @@ export const SHARED_FILE_RULES_CAP = 7_000;
  * ones that said "this tool" or "this call" name the tools instead.
  */
 export function sharedFileRules(layout) {
-    const agentsFile = agentsFileOf(layout);
     return [
         {
             id: 'agent-guide',
             heading: "This knowledge base's own conventions",
-            body: conventionsRule(agentsFile),
+            body: conventionsRule(),
         },
         {
             id: 'content-kinds',
@@ -174,15 +175,14 @@ export function sharedFileRules(layout) {
 }
 /**
  * The platform files as the rules list them — from the one function that knows
- * which they are, so the list cannot drift from what actually refuses a move,
- * and the guide appears under this deployment's name for it.
+ * which they are, so the list cannot drift from what actually refuses a move.
  *
  * WITH THE DEPTH each name counts at, because the name alone is half the rule:
  * `access.md` governs the folder it sits in and `.bevelignore` layers, so both
- * are platform files wherever they are; `roles.yaml` and the guide are read
- * from the repository root only, so a nested copy of either is ordinary
- * content that moves and deletes like any page. An agent told only the names
- * refuses a rename it may make, and trusts a nested `access.md` it may not.
+ * are platform files wherever they are; `roles.yaml` is read from the
+ * repository root only, so a nested copy is ordinary content that moves and
+ * deletes like any page. An agent told only the names refuses a rename it may
+ * make, and trusts a nested `access.md` it may not.
  */
 function platformFileList(layout) {
     const { anyDepth, rootOnly } = platformFilesByDepth(layout);
@@ -190,27 +190,20 @@ function platformFileList(layout) {
     return `${quoted(anyDepth)} in any folder, ${quoted(rootOnly)} at the repository root`;
 }
 /**
- * The conventions reminder — which file holds the author's own rules for this
- * knowledge base, and to read it first.
+ * The conventions reminder — where the platform's guide is, that the
+ * organisation's own conventions file comes with it, and to read both first.
  *
- * `CLAUDE.md` is named as a fallback because knowledge bases seeded before the
- * rename still carry one. WHEN THE GUIDE HAS BEEN RENAMED the sentence names
- * two files, ours first: the second is the organisation's OWN `AGENTS.md`,
- * which on such a deployment is ordinary content the platform never touches —
- * and which no harness reads for a remote agent, because a remote agent has no
- * checkout. Under the default name the wording collapses to the one file it
- * has always named.
+ * The guide is read by name at the repository root, where coding agents look
+ * for an `AGENTS.md` by convention, and `get_agent_guide` returns it alone.
+ * One name on every deployment, so the rule takes no layout. `CLAUDE.md` is
+ * named as a fallback because a knowledge base seeded before the rename may
+ * still carry one its people edited.
  */
-function conventionsRule(agentsFile) {
-    if (agentsFile === LEGACY_AGENTS_FILE) {
-        return (`Before your first read or change in a workspace, read \`${LEGACY_AGENTS_FILE}\` at the KB root — or ` +
-            `\`${PRE_RENAME_AGENTS_FILE}\` on a knowledge base seeded before it was renamed — if either exists: it holds ` +
-            "the author's conventions for this knowledge base, and you should follow them.");
-    }
-    return (`Before your first read or change in a workspace, read \`${agentsFile}\` at the KB root, then ` +
-        `\`${LEGACY_AGENTS_FILE}\` if it also exists (the organisation's own conventions) — or ` +
-        `\`${PRE_RENAME_AGENTS_FILE}\` on a knowledge base seeded before it was renamed: together they hold the ` +
-        'conventions for this knowledge base, and you should follow them.');
+function conventionsRule() {
+    return ("Before your first read or change in a workspace, call `get_agent_guide` and read the platform's guide " +
+        `(whole, or one section). read_file on \`${LEGACY_AGENTS_FILE}\` at the KB root answers with the same ` +
+        "guide, after the organisation's own conventions file of that name when it has one: follow both. A " +
+        `\`${PRE_RENAME_AGENTS_FILE}\` at the KB root is the organisation's own too; read it if it exists.`);
 }
 /**
  * The shared rules as ONE markdown section — the string both channels carry,
@@ -223,50 +216,4 @@ export function sharedFileRulesSection(layout) {
         .join('\n\n');
     return `## ${SHARED_RULES_SECTION}\n\n${body}`;
 }
-/**
- * The longest guide file name the pointer sentence spells out. Beyond this it
- * names the guide by its ROLE instead (see {@link sharedRulesPointer}).
- *
- * There has to be a bound somewhere, because the pointer rides on every file
- * tool and a file name is not a fixed cost: `validateFilename` allows a name
- * of up to 255 bytes, so an unbounded pointer could reach 318 characters and
- * push `file_stat` to 1,428 — over the description cap, recreating on a
- * renamed deployment exactly the truncation this module exists to prevent, and
- * invisibly, because every measurement is taken under the default layout.
- *
- * 40 is well past any name a deployment plausibly picks
- * (`ENGINEERING-AGENT-CONVENTIONS.md` is 32) and the fallback below is only
- * reachable past it.
- */
-export const POINTER_GUIDE_NAME_BUDGET = 40;
-/**
- * The one sentence a tool description ends with, in place of the paragraphs it
- * used to carry. Short on purpose: it costs every description the same ~100
- * characters at worst, and its whole job is to name the section and the file
- * to read.
- *
- * BOUNDED BY CONSTRUCTION, which is what lets the description cap mean
- * something on a deployment that renamed its guide: a name within
- * {@link POINTER_GUIDE_NAME_BUDGET} is spelled out, and a longer one gets the
- * generic wording. Naming the file is the better sentence and wins whenever it
- * fits; a name past the budget is pathological, and there the choice is between
- * a sentence that says where to look and a catalog entry the client cuts. The
- * guide's own name is still in the section's first rule either way.
- *
- * An absent layout means the default one, as it does in
- * `composeAgentInstructions`: a caller reading the layout from configuration
- * gets `undefined` when none is set, and the pointer must still name a file.
- */
-export function sharedRulesPointer(layout = DEFAULT_KB_LAYOUT) {
-    const agentsFile = agentsFileOf(layout);
-    const where = agentsFile.length <= POINTER_GUIDE_NAME_BUDGET ? agentsFile : 'the agent guide at the KB root';
-    return ` Shared rules for all file tools: see "${SHARED_RULES_SECTION}" in ${where}.`;
-}
-/**
- * The most the pointer can ever cost a description, over every layout. What the
- * description cap is measured against, the way the tool prefix is measured at
- * ITS cap rather than at whatever the current admin wrote: a description that
- * only fits beside the short default guide name does not really fit.
- */
-export const SHARED_RULES_POINTER_MAX = Math.max(sharedRulesPointer({ ...DEFAULT_KB_LAYOUT, agentsFile: `${'x'.repeat(POINTER_GUIDE_NAME_BUDGET - 3)}.md` }).length, sharedRulesPointer({ ...DEFAULT_KB_LAYOUT, agentsFile: `${'x'.repeat(POINTER_GUIDE_NAME_BUDGET + 10)}.md` }).length);
 //# sourceMappingURL=shared-file-rules.js.map

package/dist/modules/agent-instructions/shared-file-rules.js.map

@@ -1 +1 @@
-{"version":3,"file":"shared-file-rules.js","sourceRoot":"","sources":["../../../src/modules/agent-instructions/shared-file-rules.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"shared-file-rules.js","sourceRoot":"","sources":["../../../src/modules/agent-instructions/shared-file-rules.ts"],"names":[],"mappings":"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"}

package/dist/modules/mcp/mcp.service.d.ts

@@ -5,6 +5,7 @@ import type { KbLayout } from '@bevel-software/platform-shared';
 import { type ISecretsVaultService } from '../secrets-vault/secrets-vault.contract.js';
 import type { IToolManualService } from '../tool-manuals/tool-manuals.contract.js';
 import type { SpillStore } from '../workspace/spill-store.js';
+import type { HiddenToolSource } from '../../shared/hidden-tools.js';
 import type { InternalTokenService } from '../tool-auth/internal-token.service.js';
 import type { IAgentEventRecorder } from '../audit/audit.contract.js';
 import { type DownstreamPoolOptions } from './downstream-pool.js';
@@ -33,8 +34,8 @@ export interface McpProxyOptions {
     readAgentPreamble?: AgentPreambleReader;
     /**
      * The layout in effect, read per request: the shared file rules name the
-     * managed guide, and a deployment may rename it after boot (the setup save
-     * applies a name without a restart). A GETTER, so nothing snapshots the
+     * guide by the name a deployment saved for it, and the setup save applies
+     * a layout without a restart. A GETTER, so nothing snapshots the
      * pre-setup default. Absent, the rules name `AGENTS.md`.
      */
     kbLayout?: () => KbLayout;
@@ -136,6 +137,14 @@ export declare class McpService {
      * server's tools.
      */
     private readonly knownDownstreamTools;
+    /**
+     * The JSON Schema check on connected tools, and the memory of what it found.
+     * Process-wide rather than per request, because a schema's validity is a
+     * property of the server and not of the caller — and because the point of
+     * remembering is that the check runs when a server's tools are loaded, not
+     * once per request and never on a tool call. See {@link ToolSchemaGuard}.
+     */
+    private readonly toolSchemas;
     private readonly downstream;
     constructor(opts: McpProxyOptions, secretsVault?: ISecretsVaultService | undefined, toolManuals?: IToolManualService | undefined, internalTokens?: InternalTokenService | undefined, revokeOAuthAccess?: ((bearer: string) => Promise<void>) | undefined, auditRecorder?: IAgentEventRecorder | undefined);
     /**
@@ -248,6 +257,24 @@ export declare class McpService {
      * corrected `mcp.json` URL) is tried on the very next request.
      */
     private discoverTools;
+    /**
+     * Check the input schema of every tool the servers just advertised, and take
+     * the invalid ones OFF the client's tool repository.
+     *
+     * The repository is the single place `tools/list`, `list_tools`/`tools_info`
+     * and the TypeScript interfaces `call_tool_chain` generates are all built
+     * from, so removing a tool here removes it from all three — which is what
+     * "not offered to agents" has to mean. Its siblings are untouched: the check
+     * is per tool, so one bad schema costs that tool and nothing else of the
+     * server.
+     *
+     * A client would otherwise drop such a tool itself, silently, and the agent
+     * would be left without it and without a reason. Hidden here, the reason
+     * reaches the people who manage the server (see {@link ToolSchemaGuard}).
+     */
+    private hideInvalidSchemas;
+    /** The schema findings the owner-facing surfaces report — see {@link ToolSchemaGuard}. */
+    get hiddenTools(): HiddenToolSource;
     /**
      * Make one `mcp` manual's tools part of this request's client, backed by the
      * pooled connection for (user, manual).

package/dist/modules/mcp/mcp.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.service.d.ts","sourceRoot":"","sources":["../../../src/modules/mcp/mcp.service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mcp.service.d.ts","sourceRoot":"","sources":["../../../src/modules/mcp/mcp.service.ts"],"names":[],"mappings":"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"}

package/dist/modules/mcp/mcp.service.js

@@ -16,9 +16,11 @@ import { RequestAudit } from '../audit/request-audit.js';
 import { ManualFailureMemo } from './manual-failure-memo.js';
 import { DownstreamPool, POOL_KEY_SEPARATOR } from './downstream-pool.js';
 import { SurfaceLogThrottle } from './surface-log-throttle.js';
+import { ToolSchemaGuard } from './tool-schema-guard.js';
 import { DownstreamRefreshGuard, isDownstreamTokenRejection } from './downstream-token-refresh.js';
 import { printable } from '../../shared/printable.js';
-import { composeAgentInstructions, prefixToolDescription, PREFIXED_TOOLS, sharedRulesPointer, } from '../agent-instructions/index.js';
+import { composeAgentInstructions, prefixToolDescription, PREFIXED_TOOLS, } from '../agent-instructions/index.js';
+import { guideFirstDescription } from '../tool-registry/guide-first.js';
 /**
  * Upper bound on one `loopbackJson` round-trip (manual list, skill fetch) so a
  * hung loopback can't stall a request. Generous: these endpoints answer in
@@ -105,6 +107,14 @@ export class McpService {
      * server's tools.
      */
     knownDownstreamTools = new Map();
+    /**
+     * The JSON Schema check on connected tools, and the memory of what it found.
+     * Process-wide rather than per request, because a schema's validity is a
+     * property of the server and not of the caller — and because the point of
+     * remembering is that the check runs when a server's tools are loaded, not
+     * once per request and never on a tool call. See {@link ToolSchemaGuard}.
+     */
+    toolSchemas = new ToolSchemaGuard();
     // The downstream connection pool for `mcp` manuals — see the class doc.
     downstream;
     constructor(opts, 
@@ -295,14 +305,17 @@ export class McpService {
             // different name, and one fixed example is necessarily wrong on one of the
             // two surfaces.
             //
-            // The chain's description ends with the same pointer every file tool ends
-            // with: what a chain does with a failure, a large result or an image is
-            // stated once, in the shared rules, and the clients that drop
-            // `instructions` have the description and the guide to go on. Composed
-            // here because the guide's name is this deployment's setting.
+            // What a chain does with a failure, a large result or an image is
+            // stated once, in the shared rules — in the guide and in the handshake
+            // instructions — and not on the chain itself (an EMPTY pointer is how
+            // `mcp-core` is told the rules are served elsewhere). Like every tool of
+            // the platform's own, each meta-tool opens with the one sentence saying
+            // what to do before any of them, which is where those rules are. The
+            // registry puts the sentence on the tools it lists; the meta-tools are
+            // built here, so here it is.
             const metaTools = codeModeMetaTools(EXTERNAL_KB_MANUAL_NAME, examplePool, {
-                sharedRulesPointer: sharedRulesPointer(this.opts.kbLayout?.()),
-            });
+                sharedRulesPointer: '',
+            }).map((tool) => ({ ...tool, description: guideFirstDescription(tool.description) }));
             // Log only when a tool was dropped (name/schema/duplicate) — that's the
             // anomaly worth surfacing, since a downstream client would otherwise hide
             // it by rejecting the whole response.
@@ -316,7 +329,7 @@ export class McpService {
             };
         });
         server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
-            const { client, tools, unavailable, catalogNames } = await requestSurface();
+            const { client, tools, unavailable, catalogNames, hidden: hiddenTools } = await requestSurface();
             const toolName = request.params.name;
             const args = request.params.arguments ?? {};
             if (META_TOOL_NAMES.has(toolName)) {
@@ -359,6 +372,23 @@ export class McpService {
             };
             const proxied = tools.find((t) => t.mcpName === toolName);
             if (!proxied) {
+                // A tool this process hid for an invalid schema: say that, rather than
+                // "Unknown tool" about a tool the agent has every reason to think
+                // exists. The place and the reason are deliberately NOT here — they are
+                // for the people who manage the server, who are the only ones who can
+                // act on them.
+                const hidden = hiddenTools.get(toolName);
+                if (hidden) {
+                    // The UTCP name, as every other audit path records a tool: the
+                    // flattened agent name loses the server segment of a multi-segment
+                    // `<manual>.<server>.<tool>`, and an audit trail that names a
+                    // different tool than the rest of the trail is worse than none.
+                    if (audit)
+                        await audit.denied(hidden.utcpName, args);
+                    return toolError(`The "${toolName}" tool is hidden from agents because its schema is invalid, so it cannot be ` +
+                        `called. The people who manage its server can see the place in the schema and the reason, on ` +
+                        `the tool's page in Hexis and through \`list_tool_setup\`.`);
+                }
                 // Not on the surface — but if the name belongs to a manual that is off
                 // it only because this caller's sign-in is gone (and nothing in this
                 // process has seen its tools yet), the honest answer is the sign-in
@@ -427,7 +457,7 @@ export class McpService {
         const manuals = await this.fetchManualTemplates(loopbackBearer);
         const catalogMs = performance.now() - started;
         const client = await this.buildClient(loopbackBearer, userId, manuals);
-        const { tools, unavailable, catalogNames } = await this.discoverTools(client, manuals, userId);
+        const { tools, unavailable, catalogNames, hidden } = await this.discoverTools(client, manuals, userId);
         const totalMs = performance.now() - started;
         // Per user: on a shape change or once per interval, never per request —
         // see SurfaceLogThrottle for why both halves matter.
@@ -441,7 +471,7 @@ export class McpService {
                 `(catalog ${catalogMs.toFixed(0)}ms, registration ${(totalMs - catalogMs).toFixed(0)}ms)` +
                 (decision.suppressed > 0 ? ` [+${decision.suppressed} identical rebuild(s) since last line]` : ''));
         }
-        return { client, tools, unavailable, catalogNames };
+        return { client, tools, unavailable, catalogNames, hidden };
     }
     /**
      * The instructions and tool prefix. A reader failure (a disk fault; ENOENT
@@ -591,11 +621,31 @@ export class McpService {
     async discoverTools(client, manuals, userId) {
         const routes = new Map();
         const unavailable = [];
+        // Taken BEFORE a single manual is registered, so it ranks this load by the
+        // freshness of what it is about to read — see ToolSchemaGuard.beginLoad.
+        const loadId = this.toolSchemas.beginLoad();
         const catalogNames = new Map();
         for (const m of manuals) {
             if (m.call_template_type === 'mcp')
                 catalogNames.set(utcpManualName(m), String(m.name));
         }
+        // Every manual's catalog name, which is how the owner-facing surfaces know
+        // it. `catalogNames` above is the credential catalog's map and covers `mcp`
+        // manuals only; the schema check is about the tools of every connected
+        // server, so it needs the whole list. Taken HERE, before registration:
+        // registering a manual renames the template in place, so `m.name` read
+        // afterwards is the rewritten identifier and `my-server` would be recorded
+        // as `my_server` — a name no tool page ever looks up.
+        // Keyed by the rewritten name, which two manuals can share (the collision
+        // handled below): the KB manual's entry is the one that stays, since it is
+        // the one that is registered when a `.tool` collides with it.
+        const manualCatalogNames = new Map();
+        for (const m of manuals) {
+            const rewritten = utcpManualName(m);
+            if (manualCatalogNames.get(rewritten) === EXTERNAL_KB_MANUAL_NAME)
+                continue;
+            manualCatalogNames.set(rewritten, String(m.name));
+        }
         // The shared layer rewrites every manual name (`[^\w]` → `_`) and tools
         // route by the rewritten prefix, so two manuals whose names rewrite to one
         // identifier would silently share it. Sequential registration used to
@@ -677,11 +727,58 @@ export class McpService {
         if (routes.size > 0)
             routeToDownstream(client, routes);
         const utcpTools = await client.getTools();
-        return {
-            tools: utcpTools.map((tool) => flattenManualTool(tool, EXTERNAL_KB_MANUAL_NAME)),
-            unavailable,
-            catalogNames,
-        };
+        const flattened = utcpTools.map((tool) => flattenManualTool(tool, EXTERNAL_KB_MANUAL_NAME));
+        const { tools, hidden } = await this.hideInvalidSchemas(client, flattened, manualCatalogNames, userId, loadId);
+        return { tools, unavailable, catalogNames, hidden };
+    }
+    /**
+     * Check the input schema of every tool the servers just advertised, and take
+     * the invalid ones OFF the client's tool repository.
+     *
+     * The repository is the single place `tools/list`, `list_tools`/`tools_info`
+     * and the TypeScript interfaces `call_tool_chain` generates are all built
+     * from, so removing a tool here removes it from all three — which is what
+     * "not offered to agents" has to mean. Its siblings are untouched: the check
+     * is per tool, so one bad schema costs that tool and nothing else of the
+     * server.
+     *
+     * A client would otherwise drop such a tool itself, silently, and the agent
+     * would be left without it and without a reason. Hidden here, the reason
+     * reaches the people who manage the server (see {@link ToolSchemaGuard}).
+     */
+    async hideInvalidSchemas(client, tools, catalogNames, userId, loadId) {
+        const byManual = new Map();
+        // EVERY manual of this surface is screened, including the ones that
+        // advertised nothing. A server that removed its last invalid tool, and one
+        // whose tools never loaded at all (a sign-in that has gone), both come
+        // through here with an empty group — and an empty group is what clears the
+        // marker. Screening only the groups that have tools would leave the tool
+        // page, `list_tool_setup` and the hidden-tool answer on a call all
+        // reporting a defect this process can no longer see.
+        for (const manual of catalogNames.values())
+            byManual.set(manual, []);
+        for (const tool of tools) {
+            const manual = catalogNames.get(tool.manualName) ?? tool.manualName;
+            byManual.set(manual, [...(byManual.get(manual) ?? []), tool]);
+        }
+        const found = this.toolSchemas.screen(userId, loadId, byManual);
+        const hidden = new Map();
+        for (const tool of found.values())
+            hidden.set(tool.name, tool);
+        if (found.size === 0)
+            return { tools, hidden };
+        for (const utcpName of found.keys()) {
+            await client.config.tool_repository.removeTool(utcpName);
+        }
+        // Logged every time rather than throttled: a hidden tool is the one thing
+        // about this surface that a person has to act on, and it is rare.
+        log.warn(`hiding ${found.size} connected tool(s) whose input schema is not valid JSON Schema: ` +
+            `${[...found.values()].map((t) => `${t.name} (${t.path}: ${t.reason})`).join(', ')}`);
+        return { tools: tools.filter((tool) => !found.has(tool.utcpName)), hidden };
+    }
+    /** The schema findings the owner-facing surfaces report — see {@link ToolSchemaGuard}. */
+    get hiddenTools() {
+        return this.toolSchemas;
     }
     /**
      * Make one `mcp` manual's tools part of this request's client, backed by the