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

package/src/modules/agent-instructions/shared-file-rules.ts

@@ -14,24 +14,24 @@
  *
  *  - 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,
   type KbLayout,
@@ -43,9 +43,9 @@ 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';
 
@@ -84,12 +84,11 @@ export interface SharedFileRule {
  * ones that said "this tool" or "this call" name the tools instead.
  */
 export function sharedFileRules(layout: KbLayout): readonly SharedFileRule[] {
-  const agentsFile = agentsFileOf(layout);
   return [
     {
       id: 'agent-guide',
       heading: "This knowledge base's own conventions",
-      body: conventionsRule(agentsFile),
+      body: conventionsRule(),
     },
     {
       id: 'content-kinds',
@@ -204,15 +203,14 @@ export function sharedFileRules(layout: KbLayout): readonly SharedFileRule[] {
 
 /**
  * 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: KbLayout): string {
   const { anyDepth, rootOnly } = platformFilesByDepth(layout);
@@ -221,30 +219,21 @@ function platformFileList(layout: KbLayout): string {
 }
 
 /**
- * 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: string): string {
-  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."
-    );
-  }
+function conventionsRule(): string {
   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.'
+    "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.`
   );
 }
 
@@ -260,55 +249,4 @@ export function sharedFileRulesSection(layout: KbLayout): string {
   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: KbLayout = DEFAULT_KB_LAYOUT): string {
-  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,
-);

package/src/modules/mcp/__tests__/fake-downstream-mcp-server.ts

@@ -8,6 +8,7 @@ import {
   ListToolsRequestSchema,
   isInitializeRequest,
   type CallToolResult,
+  type ListToolsResult,
 } from '@modelcontextprotocol/sdk/types.js';
 
 /**
@@ -44,6 +45,13 @@ export interface FakeDownstreamOptions {
    * revoked or expired token with.
    */
   acceptsToken?: (token: string) => boolean;
+  /**
+   * What `tools/list` answers, in place of the single `echo` tool. A FUNCTION,
+   * read per request, so a test can have the server correct a schema between
+   * two discoveries the way a vendor's fix reaches us — through the next load,
+   * with nothing restarted here.
+   */
+  tools?: () => Array<{ name: string; description?: string; inputSchema: unknown }>;
 }
 
 export async function startFakeDownstreamMcpServer(opts: FakeDownstreamOptions = {}): Promise<FakeDownstreamMcpServer> {
@@ -55,13 +63,16 @@ export async function startFakeDownstreamMcpServer(opts: FakeDownstreamOptions =
   function buildServer(): Server {
     const server = new Server({ name: 'downstream', version: '0.0.0' }, { capabilities: { tools: {} } });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
-      tools: [
+      // Cast because a test may deliberately advertise a schema that is NOT
+      // valid JSON Schema, which is precisely what the SDK's type forbids and
+      // what a real server is free to send.
+      tools: (opts.tools?.() ?? [
         {
           name: 'echo',
           description: 'Return the text it was given.',
-          inputSchema: { type: 'object' as const, properties: { text: { type: 'string' } } },
+          inputSchema: { type: 'object', properties: { text: { type: 'string' } } },
         },
-      ],
+      ]) as unknown as ListToolsResult['tools'],
     }));
     server.setRequestHandler(CallToolRequestSchema, async (request): Promise<CallToolResult> => {
       executions += 1;

package/src/modules/mcp/__tests__/mcp.e2e.test.ts

@@ -1147,3 +1147,253 @@ describe('the first call on a fresh connection, fifty at once', () => {
     expect(report.distinctSessionIds).toBe(50);
   }, 120_000);
 });
+
+
+/**
+ * A connected server's input schemas, end to end: what the server sends is
+ * what a client is offered, and a tool whose schema is genuinely invalid is
+ * kept off every agent surface with a reason its owner can read.
+ *
+ * Over the real transport, because this is the layer where the three
+ * silently-dropped tools would have been caught. The proxy had been corrupting
+ * deeply nested schemas on the way OUT, after every parse in the chain had
+ * approved them, so nothing short of a client's own refusal said so.
+ *
+ * One boundary this suite also pins, because it decides what the check can
+ * ever see: a tool whose schema breaks the shape `@modelcontextprotocol/sdk`
+ * models at the ROOT (`type`, `properties`, `required`) makes the SDK client
+ * reject the WHOLE `tools/list` response, so that server's manual fails to
+ * register and Hexis is handed none of its tools. See the last test.
+ */
+describe('a connected tool whose schema is invalid is not offered to agents', () => {
+  let downstream: FakeDownstreamMcpServer | undefined;
+  afterEach(async () => {
+    await downstream?.stop();
+    downstream = undefined;
+  });
+
+  const manualAt = (server: FakeDownstreamMcpServer) => () => [
+    { name: 'notion', call_template_type: 'mcp', config: { mcpServers: { srv: { transport: 'http', url: server.url } } } },
+  ];
+
+  /** The constructs the dropped tools carried, nested as deep as theirs were. */
+  function richSchema(levels: number): Record<string, unknown> {
+    let node: Record<string, unknown> = {
+      type: 'object',
+      properties: {
+        socialLinks: { type: 'array', items: { anyOf: [{ type: 'string' }, { type: 'null' }] } },
+        value: { anyOf: [{ type: 'object', required: ['id', 'name'] }, { type: 'null' }] },
+        table: { type: 'object', properties: { rows: { type: 'array', items: { type: 'string' } } } },
+      },
+      required: ['value'],
+    };
+    for (let i = levels; i > 0; i -= 1) {
+      node = { type: 'object', properties: { [`level${i}`]: node }, required: [`level${i}`] };
+    }
+    return node;
+  }
+
+  /**
+   * The Notion refusal, as reported: `required` holding a number, in an
+   * `anyOf` branch. `anyOf` is a keyword nothing between the server and Hexis
+   * models, which is why a tool carrying this arrives intact and is ours to
+   * screen — unlike the same mistake at the root (last test).
+   */
+  const INVALID_SCHEMA = {
+    type: 'object',
+    properties: { value: { anyOf: [{ type: 'object', required: [7] }] } },
+  };
+  const INVALID_AT = '/properties/value/anyOf/0/required/0';
+  const INVALID_BECAUSE = 'must be a string';
+
+  const goodTool = (name: string) => ({
+    name,
+    description: `does ${name}`,
+    inputSchema: { type: 'object', properties: { text: { type: 'string' } } },
+  });
+
+  it('offers an `anyOf` list, a `required` list and nested `items` exactly as the server sent them', async () => {
+    // Twelve levels deep: past the point at which the proxy used to replace
+    // whatever node it had reached with `{}`, which is how `anyOf: {}`,
+    // `required: [{}]` and `type: {}` reached clients and cost three real
+    // tools their place in the agent's toolset.
+    const sent = richSchema(12);
+    downstream = await startFakeDownstreamMcpServer({
+      tools: () => [{ name: 'query', description: 'query it', inputSchema: sent }],
+    });
+    const { baseUrl } = await startPlatform({ manualsFor: manualAt(downstream) });
+    const { client } = await connectSdkClient(baseUrl);
+    const offered = (await client.listTools()).tools.find((t) => t.name === 'notion_srv_query');
+    expect(offered).toBeDefined();
+    expect(offered!.inputSchema).toEqual(sent);
+  });
+
+  it('hides the tool whose schema is invalid, keeps its nine siblings, and marks it for the owner', async () => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    downstream = await startFakeDownstreamMcpServer({
+      tools: () => [
+        ...Array.from({ length: 9 }, (_, i) => goodTool(`good${i}`)),
+        { name: 'broken', description: 'broken', inputSchema: INVALID_SCHEMA },
+      ],
+    });
+    const platform = await startPlatform({ manualsFor: manualAt(downstream) });
+    const { client } = await connectSdkClient(platform.baseUrl);
+    const names = (await client.listTools()).tools.map((t) => t.name);
+
+    expect(names).not.toContain('notion_srv_broken');
+    for (let i = 0; i < 9; i += 1) expect(names).toContain(`notion_srv_good${i}`);
+
+    // The owner's side of the same fact, by the manual's catalog name.
+    expect(platform.service.hiddenTools.hiddenFor('notion')).toEqual([
+      {
+        manual: 'notion',
+        name: 'notion_srv_broken',
+        path: INVALID_AT,
+        reason: INVALID_BECAUSE,
+        marker: `Hidden from agents: its schema is invalid at ${INVALID_AT} (${INVALID_BECAUSE}).`,
+      },
+    ]);
+  });
+
+  it('keeps the hidden tool out of `list_tools` and out of the tool chain', async () => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    downstream = await startFakeDownstreamMcpServer({
+      tools: () => [goodTool('fine'), { name: 'broken', description: 'broken', inputSchema: INVALID_SCHEMA }],
+    });
+    const { baseUrl } = await startPlatform({ manualsFor: manualAt(downstream) });
+    const { client } = await connectSdkClient(baseUrl);
+    // `list_tools` and the chain read the SAME tool repository the listing is
+    // built from, which is why taking the tool off it covers all three.
+    const listed = toolText(await client.callTool({ name: 'list_tools', arguments: {} }));
+    expect(listed).toContain('notion.srv_fine');
+    expect(listed).not.toContain('broken');
+
+    // The chain's view of the catalog is the same repository: it can describe
+    // the sibling and knows nothing of the hidden tool.
+    const info = JSON.parse(
+      toolText(
+        await client.callTool({
+          name: 'tools_info',
+          arguments: { tool_names: ['notion.srv_fine', 'notion.srv_broken'] },
+        }),
+      ),
+    ) as { interfaces: string; not_found: string[] };
+    expect(info.interfaces).toContain('fine');
+    expect(info.not_found).toEqual(['notion.srv_broken']);
+
+    // And a chain that calls it dies on a tool that is not there — the
+    // namespace is bound, the member is simply absent, so the isolate's own
+    // reason NAMES it. Asserted on that reason rather than on a prefix: the
+    // chain reports a failure as `isError` with the thrown text, and a test
+    // pinned to the wrapper's wording passes while the tool is still bound.
+    const chain = await client.callTool({
+      name: 'call_tool_chain',
+      arguments: { code: 'return notion.srv_broken({ body: {} });' },
+    });
+    expect(chain.isError).toBe(true);
+    expect(toolText(chain)).toContain('notion.srv_broken is not a function');
+
+    // The same chain, same namespace, on the sibling: bound and callable. This
+    // is what makes the line above a statement about the HIDDEN tool rather
+    // than about a namespace the chain could not reach at all.
+    const sibling = await client.callTool({
+      name: 'call_tool_chain',
+      arguments: { code: 'return notion.srv_fine({ body: {} });' },
+    });
+    expect(sibling.isError).toBeFalsy();
+  });
+
+  it('answers an agent that calls the hidden tool by name, without quoting the schema to it', async () => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    downstream = await startFakeDownstreamMcpServer({
+      tools: () => [{ name: 'broken', description: 'broken', inputSchema: INVALID_SCHEMA }],
+    });
+    const { baseUrl } = await startPlatform({ manualsFor: manualAt(downstream) });
+    const { client } = await connectSdkClient(baseUrl);
+    await client.listTools(); // the load that screens the server's tools
+    const res = await client.callTool({ name: 'notion_srv_broken', arguments: {} });
+    expect(res.isError).toBe(true);
+    const text = toolText(res);
+    expect(text).toContain('hidden from agents because its schema is invalid');
+    expect(text).toContain('list_tool_setup');
+    // The place and the reason are the owner's to read, not the agent's.
+    expect(text).not.toContain(INVALID_AT);
+  });
+
+  it('offers the tool again, with no marker, once the server sends a corrected schema', async () => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    let required: unknown = [7];
+    downstream = await startFakeDownstreamMcpServer({
+      tools: () => [
+        {
+          name: 'query',
+          description: 'query it',
+          inputSchema: { type: 'object', properties: { value: { anyOf: [{ type: 'object', required }] } } },
+        },
+      ],
+    });
+    const platform = await startPlatform({ manualsFor: manualAt(downstream) });
+    const { client } = await connectSdkClient(platform.baseUrl);
+    expect((await client.listTools()).tools.map((t) => t.name)).not.toContain('notion_srv_query');
+
+    required = ['id']; // the vendor fixes it
+    // Dropping the pooled connection is what a refresh IS: the next request
+    // re-dials and re-reads the tools. Nothing is restarted, and no marker has
+    // to be cleared by hand.
+    platform.service.onSecretsChanged(null);
+
+    expect((await client.listTools()).tools.map((t) => t.name)).toContain('notion_srv_query');
+    expect(platform.service.hiddenTools.hiddenFor('notion')).toEqual([]);
+  });
+
+  it('a tool call does not re-run the check, and does not hide a tool it ran on before', async () => {
+    downstream = await startFakeDownstreamMcpServer({ tools: () => [goodTool('echo')] });
+    const { baseUrl } = await startPlatform({ manualsFor: manualAt(downstream) });
+    const { client } = await connectSdkClient(baseUrl);
+    await client.listTools();
+    // The surface is rebuilt per request, so a call sees the same schemas
+    // again; what it must not do is check them again. That the check runs once
+    // per distinct schema is counted in the guard's own unit test — here the
+    // point is that calling costs nothing and changes nothing.
+    for (const text of ['a', 'b', 'c']) {
+      expect((await client.callTool({ name: 'notion_srv_echo', arguments: { text } })).isError).toBeFalsy();
+    }
+    expect((await client.listTools()).tools.map((t) => t.name)).toContain('notion_srv_echo');
+  });
+
+  /**
+   * The boundary, pinned so nobody has to rediscover it: at the ROOT of a
+   * tool's input schema, `type`, `properties` and `required` are the three
+   * fields `@modelcontextprotocol/sdk` models itself
+   * (`ToolSchema.inputSchema`, with `required: z.array(z.string())`), and the
+   * client rejects the ENTIRE `tools/list` response when one tool breaks them.
+   *
+   * So for that class of defect Hexis is handed NOTHING — not the bad tool, not
+   * the good ones — and cannot hide one tool or mark it: the whole manual fails
+   * to register, which is what it did before this change too. The reason is
+   * logged, with the SDK's own message naming the tool's index.
+   */
+  it('cannot single out a root-level defect: the MCP SDK refuses the whole tools/list response', async () => {
+    const warnings: string[] = [];
+    vi.spyOn(console, 'warn').mockImplementation((...args: unknown[]) => {
+      warnings.push(args.map(String).join(' '));
+    });
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    downstream = await startFakeDownstreamMcpServer({
+      tools: () => [
+        goodTool('fine'),
+        { name: 'broken', description: 'broken', inputSchema: { type: 'object', properties: {}, required: [7] } },
+      ],
+    });
+    const platform = await startPlatform({ manualsFor: manualAt(downstream) });
+    const { client } = await connectSdkClient(platform.baseUrl);
+    const names = (await client.listTools()).tools.map((t) => t.name);
+
+    expect(names).not.toContain('notion_srv_broken');
+    // Its sibling goes with it, and the marker cannot name what never arrived.
+    expect(names).not.toContain('notion_srv_fine');
+    expect(platform.service.hiddenTools.hiddenFor('notion')).toEqual([]);
+    expect(warnings.join('\n')).toContain('skipping manual "notion"');
+    expect(warnings.join('\n')).toContain('required');
+  });
+});

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

@@ -12,7 +12,9 @@ import { createManualRoutes } from '../../tool-registry/manual.routes.js';
 import { ToolRegistry } from '../../tool-registry/tool-registry.js';
 import { toolDef } from '../../tool-helpers/tool-def.js';
 import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
-import { TOOL_PREFIX_LINE, platformInstructions, sharedRulesPointer } from '../../agent-instructions/index.js';
+import { TOOL_PREFIX_LINE, platformInstructions } from '../../agent-instructions/index.js';
+import { GUIDE_FIRST_SENTENCE } from '../../tool-registry/guide-first.js';
+import { GUIDE_FIRST_SENTENCE } from '../../tool-registry/guide-first.js';
 import type { AgentEventInput, IAgentEventRecorder } from '../../audit/audit.contract.js';
 
 /** The platform-owned part of the handshake text: the header plus the shared file rules. */
@@ -266,23 +268,23 @@ describe('McpService (UTCP→MCP proxy)', () => {
     expect(askSchema.properties.body?.properties?.prompt).toBeDefined();
   });
 
-  it('ends the served call_tool_chain description with the shared-rules pointer', async () => {
-    // What a chained read does to an IMAGE is one of the rules the file tools
-    // share, so it is stated once — in the handshake instructions and in the
-    // managed guide — and the chain, like every file tool, ends with the one
-    // sentence saying where. The clients that drop `instructions` have only
-    // descriptions to go on, so that sentence is their way to the rule.
+  it('opens every served meta-tool with the guide-first sentence, and states the chain rules nowhere on the chain', async () => {
+    // What a chained read does to an IMAGE, a failure or a large result is one
+    // of the rules the file tools share, so it is stated once — in the
+    // handshake instructions and in the guide — and each meta-tool, like every
+    // tool of the platform's own, opens with the one sentence saying where.
+    // The clients that drop `instructions` have only descriptions to go on, so
+    // that sentence is their way to the rules.
     const client = await setup();
     const { tools } = await client.listTools();
-    const chain = tools.find((t) => t.name === 'call_tool_chain')!;
-    const pointer = sharedRulesPointer(DEFAULT_KB_LAYOUT);
-    expect(chain.description!.endsWith(pointer)).toBe(true);
-    // Once, and not on the two meta-tools that describe the registry rather
-    // than a file.
-    expect(chain.description!.split(pointer)).toHaveLength(2);
-    for (const name of ['list_tools', 'tools_info']) {
-      expect(tools.find((t) => t.name === name)!.description, name).not.toContain(pointer);
+    for (const name of ['call_tool_chain', 'list_tools', 'tools_info']) {
+      const served = tools.find((t) => t.name === name)!;
+      expect(served.description!.startsWith(`${GUIDE_FIRST_SENTENCE} `), name).toBe(true);
+      expect(served.description!.split(GUIDE_FIRST_SENTENCE), name).toHaveLength(2);
     }
+    const chain = tools.find((t) => t.name === 'call_tool_chain')!;
+    expect(chain.description).not.toContain('image_omitted');
+    expect(chain.description).not.toContain('Shared rules for all file tools');
   });
 
   it('a $defs/$ref tool schema survives tools/list and a real MCP client accepts it', async () => {
@@ -612,27 +614,33 @@ describe('McpService — agent instructions', () => {
       expect.stringContaining('mcp-description.md'),
       expect.objectContaining({ message: 'disk' }),
     );
-    // And the four tools carry the fixed line alone.
+    // And the four tools carry the fixed line alone, ahead of the guide-first
+    // opening every listed tool has.
     const { tools } = await client.listTools();
     for (const name of KB_TOOLS) {
-      expect(tools.find((t) => t.name === name)?.description).toBe(`${TOOL_PREFIX_LINE}\n\noriginal ${name} description`);
+      expect(tools.find((t) => t.name === name)?.description).toBe(
+        `${TOOL_PREFIX_LINE}\n\n${GUIDE_FIRST_SENTENCE} original ${name} description`,
+      );
     }
   });
 
-  it('prefixes exactly the four knowledge-base tools; every other description is byte-for-byte unchanged', async () => {
+  it('prefixes exactly the four knowledge-base tools; every other description is as the catalog lists it', async () => {
     const client = await setup({ readAgentPreamble: async () => 'Acme builds solar farms.', extraTools: KB_TOOLS });
     const { tools } = await client.listTools();
     const byName = Object.fromEntries(tools.map((t) => [t.name, t.description]));
     const prefix = `${TOOL_PREFIX_LINE} Acme builds solar farms.`;
     for (const name of KB_TOOLS) {
-      expect(byName[name], name).toBe(`${prefix}\n\noriginal ${name} description`);
+      expect(byName[name], name).toBe(`${prefix}\n\n${GUIDE_FIRST_SENTENCE} original ${name} description`);
     }
-    // Regression: the rest, meta-tools included, is untouched.
-    expect(byName.ask).toBe('echo the prompt');
-    expect(byName.boom).toBe('always errors');
-    expect(byName.refy).toBe('has $defs/$ref in its schema');
+    // Regression: the rest carries only what the catalog gives every tool —
+    // the guide-first opening — and never the purpose prefix; the meta-tools
+    // open with that sentence too.
+    expect(byName.ask).toBe(`${GUIDE_FIRST_SENTENCE} echo the prompt`);
+    expect(byName.boom).toBe(`${GUIDE_FIRST_SENTENCE} always errors`);
+    expect(byName.refy).toBe(`${GUIDE_FIRST_SENTENCE} has $defs/$ref in its schema`);
     for (const meta of ['call_tool_chain', 'list_tools', 'tools_info']) {
       expect(byName[meta], meta).not.toContain(TOOL_PREFIX_LINE);
+      expect(byName[meta]!.startsWith(`${GUIDE_FIRST_SENTENCE} `), meta).toBe(true);
     }
   });