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

package/src/modules/mcp/__tests__/tool-schema-guard.test.ts

@@ -0,0 +1,266 @@
+import { describe, expect, it, vi } from 'vitest';
+import { inputSchemaDefect } from '@bevel-software/platform-mcp-core';
+import { MAX_REMEMBERED_CALLERS, ToolSchemaGuard, type ScreenedTool } from '../tool-schema-guard.js';
+
+const tool = (name: string, inputSchema: unknown): ScreenedTool => ({
+  utcpName: `notion.srv.${name}`,
+  mcpName: `notion_srv_${name}`,
+  inputSchema,
+});
+
+const VALID = { type: 'object', properties: { text: { type: 'string' } } };
+/** `required` holding a number, in an `anyOf` branch — the Notion refusal. */
+const INVALID = { type: 'object', properties: { value: { anyOf: [{ type: 'object', required: [7] }] } } };
+
+/** One caller's load: the manuals on their surface, each with the tools it advertised. */
+const load = (groups: Record<string, readonly ScreenedTool[]>) => new Map(Object.entries(groups));
+
+/**
+ * One load, with its own ticket. Every call takes a fresh one, so the order the
+ * tests screen in is the order the guard sees — which is what the two
+ * out-of-order tests below then break on purpose.
+ */
+const screen = (guard: ToolSchemaGuard, userId: string, groups: ReadonlyMap<string, readonly ScreenedTool[]>) =>
+  guard.screen(userId, guard.beginLoad(), groups);
+
+describe('ToolSchemaGuard', () => {
+  it('names the tool, the place and the reason, and leaves its siblings alone', () => {
+    const guard = new ToolSchemaGuard();
+    const hidden = screen(guard, 'u1', load({ notion: [tool('a', VALID), tool('bad', INVALID), tool('b', VALID)] }));
+
+    expect([...hidden.keys()]).toEqual(['notion.srv.bad']);
+    // The UTCP name rides on what the LOAD gets back: the proxy takes the tool
+    // out of its repository by that name and records it in the audit trail by
+    // it, so a multi-segment `<manual>.<server>.<tool>` stays intact.
+    expect(hidden.get('notion.srv.bad')?.utcpName).toBe('notion.srv.bad');
+    // What the owner reads is about the tool by the name an agent calls it.
+    expect(guard.hiddenFor('notion')).toEqual([
+      {
+        manual: 'notion',
+        name: 'notion_srv_bad',
+        path: '/properties/value/anyOf/0/required/0',
+        reason: 'must be a string',
+        marker:
+          'Hidden from agents: its schema is invalid at /properties/value/anyOf/0/required/0 (must be a string).',
+      },
+    ]);
+  });
+
+  it('holds nothing for a server whose tools are all valid, and nothing for one never loaded', () => {
+    const guard = new ToolSchemaGuard();
+    screen(guard, 'u1', load({ notion: [tool('a', VALID)] }));
+    expect(guard.hiddenFor('notion')).toEqual([]);
+    expect(guard.hiddenFor('hubspot')).toEqual([]);
+  });
+
+  it('forgets the finding when the server sends a corrected schema', () => {
+    const guard = new ToolSchemaGuard();
+    screen(guard, 'u1', load({ notion: [tool('bad', INVALID)] }));
+    expect(guard.hiddenFor('notion')).toHaveLength(1);
+
+    screen(guard, 'u1', load({ notion: [tool('bad', VALID)] }));
+    expect(guard.hiddenFor('notion')).toEqual([]);
+  });
+
+  /**
+   * A load with NO tools for a manual is the load that clears it, and there are
+   * two ways to get one: the server removed the offending tool, or the manual
+   * could not be attached at all and its tools were never loaded. Either way
+   * nothing should still be claiming a tool is hidden for a schema this process
+   * can no longer see.
+   */
+  it('forgets the finding when the server advertises nothing at all', () => {
+    const guard = new ToolSchemaGuard();
+    screen(guard, 'u1', load({ notion: [tool('bad', INVALID)] }));
+    screen(guard, 'u1', load({ notion: [] }));
+    expect(guard.hiddenFor('notion')).toEqual([]);
+  });
+
+  it('forgets the finding when the manual leaves the surface entirely', () => {
+    const guard = new ToolSchemaGuard();
+    screen(guard, 'u1', load({ notion: [tool('bad', INVALID)], hubspot: [tool('fine', VALID)] }));
+    expect(guard.hiddenFor('notion')).toHaveLength(1);
+
+    screen(guard, 'u1', load({ hubspot: [tool('fine', VALID)] }));
+    expect(guard.hiddenFor('notion')).toEqual([]);
+  });
+
+  it('keeps each server to itself', () => {
+    const guard = new ToolSchemaGuard();
+    screen(guard, 'u1', load({ notion: [tool('bad', INVALID)], hubspot: [tool('fine', VALID)] }));
+    expect(guard.hiddenFor('notion')).toHaveLength(1);
+    expect(guard.hiddenFor('hubspot')).toEqual([]);
+  });
+
+  /**
+   * Discovery runs on the REQUESTING user's own connection, so two callers can
+   * be shown different tools by one server. A finding is about the server, and
+   * the person who can fix it is not necessarily the person whose connection
+   * saw it — so one caller's load must never erase another's finding, and the
+   * owner-facing surfaces read the union.
+   */
+  describe('with more than one caller', () => {
+    it('does not let one caller\'s load erase another\'s finding', () => {
+      const guard = new ToolSchemaGuard();
+      screen(guard, 'u1', load({ notion: [tool('bad', INVALID)] }));
+      // u2's connection is shown a different, healthy subset of the same server.
+      screen(guard, 'u2', load({ notion: [tool('a', VALID)] }));
+      expect(guard.hiddenFor('notion').map((t) => t.name)).toEqual(['notion_srv_bad']);
+    });
+
+    it('reports a finding once, however many callers were shown it', () => {
+      const guard = new ToolSchemaGuard();
+      screen(guard, 'u1', load({ notion: [tool('bad', INVALID)] }));
+      screen(guard, 'u2', load({ notion: [tool('bad', INVALID)] }));
+      expect(guard.hiddenFor('notion')).toHaveLength(1);
+    });
+
+    it('reports two different defects of one server together', () => {
+      const guard = new ToolSchemaGuard();
+      screen(guard, 'u1', load({ notion: [tool('bad', INVALID)] }));
+      screen(guard, 'u2', load({ notion: [tool('other', { type: 'object', properties: { x: { anyOf: {} } } })] }));
+      expect(guard.hiddenFor('notion').map((t) => t.name).sort()).toEqual([
+        'notion_srv_bad',
+        'notion_srv_other',
+      ]);
+    });
+  });
+
+  /**
+   * Requests overlap — a caller's surface is rebuilt on every one of them, and
+   * two can be dialling the same server at once. So the order loads LAND in is
+   * not the order they READ in, and only the second one is evidence about the
+   * server's current schemas.
+   */
+  describe('with loads that land out of order', () => {
+    it('does not let a load that read the server earlier overwrite a newer one', () => {
+      const guard = new ToolSchemaGuard();
+      const stale = guard.beginLoad(); // request A starts, the schema still broken
+      const fresh = guard.beginLoad(); // request B starts, after the vendor's fix
+      guard.screen('u1', fresh, load({ notion: [tool('bad', VALID)] }));
+
+      // A lands late, with what it saw. Its OWN request still keeps the tool off
+      // its surface — it has judged that schema invalid and must not offer it …
+      const found = guard.screen('u1', stale, load({ notion: [tool('bad', INVALID)] }));
+      expect([...found.keys()]).toEqual(['notion.srv.bad']);
+      // … but the marker everyone else reads is not put back on a tool that is
+      // now fine, to sit there until some later request happened to clear it.
+      expect(guard.hiddenFor('notion')).toEqual([]);
+    });
+
+    it('applies the newer load when the older one landed first', () => {
+      const guard = new ToolSchemaGuard();
+      const first = guard.beginLoad();
+      const second = guard.beginLoad();
+      guard.screen('u1', first, load({ notion: [tool('bad', INVALID)] }));
+      expect(guard.hiddenFor('notion')).toHaveLength(1);
+
+      guard.screen('u1', second, load({ notion: [tool('bad', VALID)] }));
+      expect(guard.hiddenFor('notion')).toEqual([]);
+    });
+
+    it('orders each caller against itself, not against the others', () => {
+      const guard = new ToolSchemaGuard();
+      const early = guard.beginLoad();
+      const late = guard.beginLoad();
+      // u2's NEWER load lands first, and u1's older one after it. Ordering kept
+      // globally rather than per caller would call u1's load stale on the
+      // strength of a ticket belonging to someone else, and drop a finding
+      // nothing else in this process has seen. The order matters: with u1's
+      // load first, both readings pass and the test proves nothing.
+      guard.screen('u2', late, load({ notion: [tool('a', VALID)] }));
+      guard.screen('u1', early, load({ notion: [tool('bad', INVALID)] }));
+      expect(guard.hiddenFor('notion').map((t) => t.name)).toEqual(['notion_srv_bad']);
+    });
+  });
+
+  /**
+   * The point of remembering. The MCP surface is rebuilt per request, so these
+   * same schemas come past on every `tools/list` AND every `tools/call`; the
+   * CHECK happens when a server's tools are loaded and when a refresh brings a
+   * schema this process has not seen, and never again.
+   */
+  it('checks a schema once, however many times it is screened', () => {
+    const check = vi.fn(inputSchemaDefect);
+    const guard = new ToolSchemaGuard(check);
+    const tools = [tool('a', VALID), tool('bad', INVALID)];
+
+    for (let i = 0; i < 10; i += 1) screen(guard, 'u1', load({ notion: tools }));
+    expect(check).toHaveBeenCalledTimes(2);
+
+    // A CHANGED schema is a schema this process has not checked, so it is.
+    screen(guard, 'u1', load({ notion: [tool('a', { type: 'object', properties: { other: { type: 'number' } } })] }));
+    expect(check).toHaveBeenCalledTimes(3);
+  });
+
+  it('checks two tools that share one schema once', () => {
+    const check = vi.fn(inputSchemaDefect);
+    const guard = new ToolSchemaGuard(check);
+    screen(guard, 'u1', load({ notion: [tool('a', VALID), tool('b', { ...VALID })] }));
+    expect(check).toHaveBeenCalledTimes(1);
+  });
+
+  it('checks a schema once across callers, too — the verdict is the schema\'s', () => {
+    const check = vi.fn(inputSchemaDefect);
+    const guard = new ToolSchemaGuard(check);
+    screen(guard, 'u1', load({ notion: [tool('bad', INVALID)] }));
+    screen(guard, 'u2', load({ notion: [tool('bad', INVALID)] }));
+    expect(check).toHaveBeenCalledTimes(1);
+  });
+
+  describe('with more callers than it remembers', () => {
+    const MANY = MAX_REMEMBERED_CALLERS;
+
+    it('evicts the caller longest unseen, and keeps every other caller\'s finding on the owner\'s page', () => {
+      const guard = new ToolSchemaGuard();
+      // The first caller's finding, then a crowd of callers with nothing to
+      // report, then one more than fits.
+      screen(guard, 'first', load({ notion: [tool('bad', INVALID)] }));
+      for (let i = 1; i < MANY; i += 1) screen(guard, `u${i}`, load({ notion: [tool('a', VALID)] }));
+      expect(guard.hiddenFor('notion')).toHaveLength(1);
+      // `first` was seen again since — so it is not the longest unseen, and
+      // its finding stays when the crowd overflows.
+      screen(guard, 'first', load({ notion: [tool('bad', INVALID)] }));
+      screen(guard, 'overflow', load({ notion: [tool('a', VALID)] }));
+      expect(guard.hiddenFor('notion')).toHaveLength(1);
+      // Overflow once more: now `u1` goes, then `u2` — never the whole table.
+      screen(guard, 'overflow-2', load({ notion: [tool('a', VALID)] }));
+      expect(guard.hiddenFor('notion')).toHaveLength(1);
+    });
+
+    it("keeps the order per caller: an evicted caller's next load is their newest, whichever began first", () => {
+      const guard = new ToolSchemaGuard();
+      for (let i = 0; i < MANY; i += 1) screen(guard, `u${i}`, load({ notion: [tool('a', VALID)] }));
+      // `u0` is the longest unseen. Two loads of theirs begin, old then new —
+      // and before either lands, the table overflows and `u0` is evicted,
+      // watermark and all.
+      const older = guard.beginLoad();
+      const newer = guard.beginLoad();
+      screen(guard, 'newcomer', load({ notion: [tool('a', VALID)] }));
+      // Nothing of `u0` is held, so whichever lands first is the newest
+      // picture this process has of them: the old load, with its finding.
+      guard.screen('u0', older, load({ notion: [tool('bad', INVALID)] }));
+      expect(guard.hiddenFor('notion')).toHaveLength(1);
+      // The newer load then lands with the corrected schema and wins —
+      // and the watermark it restores rejects anything older after it.
+      guard.screen('u0', newer, load({ notion: [tool('a', VALID)] }));
+      expect(guard.hiddenFor('notion')).toEqual([]);
+      const own = guard.screen('u0', older, load({ notion: [tool('bad', INVALID)] }));
+      expect([...own.keys()]).toEqual(['notion.srv.bad']);
+      expect(guard.hiddenFor('notion')).toEqual([]);
+    });
+
+    it("does not rank one caller's load against another caller's eviction", () => {
+      const guard = new ToolSchemaGuard();
+      // `x` begins a load; the table then fills and overflows, evicting
+      // callers whose tickets are newer than `x`'s.
+      const x = guard.beginLoad();
+      for (let i = 0; i < MANY; i += 1) screen(guard, `u${i}`, load({ notion: [tool('a', VALID)] }));
+      screen(guard, 'overflow', load({ notion: [tool('a', VALID)] }));
+      // `x`'s load is `x`'s newest, evictions elsewhere notwithstanding: its
+      // finding reaches the owner's page.
+      guard.screen('x', x, load({ notion: [tool('bad', INVALID)] }));
+      expect(guard.hiddenFor('notion')).toHaveLength(1);
+    });
+  });
+});

package/src/modules/mcp/mcp.service.ts

@@ -53,6 +53,7 @@ import {
 import { EXTERNAL_KB_MANUAL_NAME } from '../tool-manuals/tool-manuals.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 { seedBevelHostedManualVars } from '../../shared/utcp-namespace.js';
 import type { InternalTokenService } from '../tool-auth/internal-token.service.js';
 import type { IAgentEventRecorder } from '../audit/audit.contract.js';
@@ -60,16 +61,17 @@ import { RequestAudit } from '../audit/request-audit.js';
 import { ManualFailureMemo } from './manual-failure-memo.js';
 import { DownstreamPool, POOL_KEY_SEPARATOR, type DownstreamPoolOptions, type Lease } from './downstream-pool.js';
 import { SurfaceLogThrottle } from './surface-log-throttle.js';
+import { ToolSchemaGuard, type ScreenedHiddenTool } 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,
   type AgentPreambleReader,
   type ComposedAgentInstructions,
 } from '../agent-instructions/index.js';
+import { guideFirstDescription } from '../tool-registry/guide-first.js';
 
 /**
  * Configuration for the loopback proxy. `loopbackBaseUrl` is the backend's own
@@ -95,8 +97,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;
@@ -166,6 +168,14 @@ interface RequestSurface {
    * They differ only when the name holds a non-word character (`my-server`).
    */
   catalogNames: ReadonlyMap<string, string>;
+  /**
+   * The tools this request's load took OFF the surface for an invalid schema,
+   * by the name an agent would have called them by. Carried on the surface
+   * rather than read back out of the guard: it is this caller's own load, so a
+   * call answered from it cannot answer about a schema some other caller's
+   * connection was shown.
+   */
+  hidden: ReadonlyMap<string, ScreenedHiddenTool>;
 }
 
 /** A manual off the surface for want of a sign-in — see {@link RequestSurface.unavailable}. */
@@ -273,6 +283,15 @@ export class McpService {
    */
   private readonly knownDownstreamTools = new Map<string, { definition: string; tools: UtcpTool[] }>();
 
+  /**
+   * 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 = new ToolSchemaGuard();
+
   // The downstream connection pool for `mcp` manuals — see the class doc.
   private readonly downstream: DownstreamPool<PooledDownstream>;
 
@@ -486,14 +505,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.
@@ -510,7 +532,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)) {
@@ -551,6 +573,24 @@ 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
@@ -626,7 +666,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.
@@ -641,7 +681,7 @@ export class McpService {
           (decision.suppressed > 0 ? ` [+${decision.suppressed} identical rebuild(s) since last line]` : ''),
       );
     }
-    return { client, tools, unavailable, catalogNames };
+    return { client, tools, unavailable, catalogNames, hidden };
   }
 
   /**
@@ -798,13 +838,37 @@ export class McpService {
     client: CodeModeUtcpClient,
     manuals: CallTemplate[],
     userId: string,
-  ): Promise<{ tools: ProxiedTool[]; unavailable: UnavailableManual[]; catalogNames: Map<string, string> }> {
+  ): Promise<{
+    tools: ProxiedTool[];
+    unavailable: UnavailableManual[];
+    catalogNames: Map<string, string>;
+    hidden: Map<string, ScreenedHiddenTool>;
+  }> {
     const routes = new Map<string, DownstreamRoute>();
     const unavailable: UnavailableManual[] = [];
+    // 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<string, string>();
     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<string, string>();
+    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
@@ -884,11 +948,65 @@ export class McpService {
     if (kbFailure && !kbFailure.ok) throw new Error(`Bevel tool discovery failed: ${kbFailure.error}`);
     if (routes.size > 0) routeToDownstream(client, routes);
     const utcpTools = await client.getTools();
-    return {
-      tools: utcpTools.map((tool: UtcpTool) => flattenManualTool(tool, EXTERNAL_KB_MANUAL_NAME)),
-      unavailable,
-      catalogNames,
-    };
+    const flattened = utcpTools.map((tool: UtcpTool) => 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}).
+   */
+  private async hideInvalidSchemas(
+    client: CodeModeUtcpClient,
+    tools: ProxiedTool[],
+    catalogNames: ReadonlyMap<string, string>,
+    userId: string,
+    loadId: number,
+  ): Promise<{ tools: ProxiedTool[]; hidden: Map<string, ScreenedHiddenTool> }> {
+    const byManual = new Map<string, ProxiedTool[]>();
+    // 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<string, ScreenedHiddenTool>();
+    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(): HiddenToolSource {
+    return this.toolSchemas;
   }
 
   /**