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

package/src/modules/tool-manuals/tool-manuals.tools.ts

@@ -7,6 +7,7 @@ import type { ToolHandlerFactory } from '../tool-helpers/tool-handler.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
 import { utcpNamespacedKey } from '../../shared/utcp-namespace.js';
 import type { IToolManualService } from './tool-manuals.contract.js';
+import type { HiddenToolSource } from '../../shared/hidden-tools.js';
 
 /**
  * What `list_tool_setup` needs from the secrets vault (structurally satisfied
@@ -43,6 +44,12 @@ export function registerToolManualsTools(
     variableStatus: VariableStatusPort;
     /** Which branch tools are served from, and its clone. */
     kb: Pick<KbContext, 'defaultBranch' | 'defaultWorkspaceId'>;
+    /**
+     * Where a hidden tool's schema finding comes from (the MCP proxy).
+     * Optional: a deployment with no MCP surface has nothing to report, and
+     * `hiddenTools` is then empty everywhere.
+     */
+    hiddenTools?: HiddenToolSource;
   },
 ): void {
   registry.registerExternalTool((ctx) => buildListLocalToolsDef(toolManualService, ctx.userEmail));
@@ -66,23 +73,30 @@ export function registerToolManualsTools(
   const listSetupDef = toolDef({
     name: 'list_tool_setup',
     // What each FIELD means is documented on the field, in `outputs` below:
-    // `setup.kind`, `variables` and `invalid` each carried a paragraph here,
-    // which made this description two thousand characters and so the first
-    // thing a client cut. The description says what the tool answers and the
-    // three things an agent cannot read off a field.
+    // `setup.kind`, `variables`, `invalid` and `hiddenTools` each carried a
+    // paragraph here, which made this description two thousand characters and
+    // so the first thing a client cut. The description says what the tool
+    // answers and the four things an agent cannot read off a field.
+    //
+    // It sits a few characters under `TOOL_DESCRIPTION_CAP` WITH the guide-first
+    // sentence the registry puts in front of it (`tool-registry/guide-first.ts`),
+    // which is why every sentence here is the short form: the `hiddenTools`
+    // clause and that opener both came out of the same budget, and what a
+    // hidden tool's entry CONTAINS is on the field below rather than here.
     description:
       'Configuration status of every `.tool` the current user can access: what each tool needs set up and what is ' +
-      'already configured, as `{ tools, invalid, onBranchOnly, note? }`. Scoped to the CALLER — a `.tool` it cannot ' +
-      'READ is absent entirely, and every flag is the caller\'s own state. ' +
-      'Secret VALUES are never returned and can never be set through a tool: an admin enters them in the tool editor, ' +
-      'and users sign in on /connect rather than typing a value. ' +
-      'What gates setting a tool\'s shared secrets is `canWrite` on the `.tool` FILE — per-file access from its ' +
-      'frontmatter `write:`/`owner:` verbs and the access.md chain, NOT a platform role: the people who manage the ' +
-      'file configure the tool. ' +
+      'already configured, as `{ tools, invalid, onBranchOnly, note? }`. Scoped to the CALLER: a `.tool` it cannot ' +
+      'READ is absent, and every flag is the caller\'s own. ' +
+      'Secret VALUES are never returned and can never be set through a tool: an admin enters them in the tool ' +
+      'editor; users sign in on /connect. ' +
+      'Setting a tool\'s shared secrets is gated by `canWrite` on the `.tool` FILE (its frontmatter ' +
+      '`write:`/`owner:` verbs and the access.md chain), NOT by a platform role: who manages the file configures ' +
+      'the tool. ' +
+      '`hiddenTools` names the tools Hexis hides from agents for an invalid schema. ' +
       'The listing is the RELEASED catalog, built from the default branch only: a server or `.tool` you declared on a ' +
-      'draft is not listed, not callable and not signed-in-able until that draft is merged. Pass `branch` (the draft ' +
-      'you wrote the declaration on) and `onBranchOnly` names every tool declared there that the default branch does ' +
-      'not serve yet — open a change request, then ask the user to review and merge it in the app to activate it.',
+      'draft is not listed, callable or signed-in-able until it is merged. Pass `branch` (the draft you wrote the ' +
+      'declaration on) and `onBranchOnly` names every tool declared there that the default branch does not serve ' +
+      'yet — open a change request and ask the user to merge it in the app to activate it.',
     path: '/api/agent/tools/list_tool_setup',
     inputs: {
       type: 'object',
@@ -132,6 +146,22 @@ export function registerToolManualsTools(
                 type: 'boolean',
                 description: 'You may write this `.tool` FILE, which is what gates setting its shared secrets.',
               },
+              hiddenTools: {
+                type: 'array',
+                description:
+                  'Tools of this server kept off every agent surface for an invalid input schema. Empty ' +
+                  'unless the caller may write this tool.',
+                items: {
+                  type: 'object',
+                  properties: {
+                    name: { type: 'string', description: 'The name the tool would have been offered under.' },
+                    path: { type: 'string', description: 'JSON Pointer to the place in the schema that is not valid.' },
+                    reason: { type: 'string', description: 'Why that place is not valid, in the validator\'s words.' },
+                    marker: { type: 'string', description: 'The one sentence the tool page shows for this tool.' },
+                  },
+                  required: ['name', 'path', 'reason', 'marker'],
+                },
+              },
               variables: {
                 type: 'array',
                 description:
@@ -156,7 +186,7 @@ export function registerToolManualsTools(
                 },
               },
             },
-            required: ['slug', 'name', 'path', 'type', 'canWrite', 'variables'],
+            required: ['slug', 'name', 'path', 'type', 'canWrite', 'hiddenTools', 'variables'],
           },
         },
         invalid: {
@@ -219,27 +249,35 @@ export function registerToolManualsTools(
       const status = await deps.variableStatus.statusFor(ctx.user.id, allKeys);
       const statusByKey = new Map(status.map((s) => [s.key, s]));
       const tools = await Promise.all(
-        manuals.map(async (m) => ({
-          slug: m.slug,
-          name: m.name,
-          path: m.path,
-          type: m.type,
-          setup: m.setup ?? null,
-          canWrite: await deps.accessControl.canWrite(defaultWs(), ctx.user.email, m.path),
-          variables: (m.variables ?? []).map((v) => {
-            const st = statusByKey.get(varKey(m.name, v.name));
-            const isOAuth = v.oauth != null;
-            return {
-              name: v.name,
-              scope: v.scope,
-              label: v.label ?? null,
-              oauth: isOAuth,
-              adminConfigured: st?.adminConfigured ?? false,
-              userConfigured: st?.userConfigured ?? false,
-              authorized: isOAuth ? (st?.userAuthorized ?? false) : null,
-            };
-          }),
-        })),
+        manuals.map(async (m) => {
+          const canWrite = await deps.accessControl.canWrite(defaultWs(), ctx.user.email, m.path);
+          return {
+            slug: m.slug,
+            name: m.name,
+            path: m.path,
+            type: m.type,
+            setup: m.setup ?? null,
+            canWrite,
+            // The marker goes only to the people who manage the server — the
+            // same verdict that gates setting its shared secrets. A caller who
+            // may only READ the tool is told nothing about it: they cannot fix
+            // the schema, and the tool is simply not among the ones they can call.
+            hiddenTools: canWrite ? (deps.hiddenTools?.hiddenFor(m.name) ?? []) : [],
+            variables: (m.variables ?? []).map((v) => {
+              const st = statusByKey.get(varKey(m.name, v.name));
+              const isOAuth = v.oauth != null;
+              return {
+                name: v.name,
+                scope: v.scope,
+                label: v.label ?? null,
+                oauth: isOAuth,
+                adminConfigured: st?.adminConfigured ?? false,
+                userConfigured: st?.userConfigured ?? false,
+                authorized: isOAuth ? (st?.userAuthorized ?? false) : null,
+              };
+            }),
+          };
+        }),
       );
       const onBranchOnly = pending.map((p) => ({ ...p, branch: branch! }));
       if (onBranchOnly.length === 0) return { tools, invalid, onBranchOnly };

package/src/modules/tool-registry/__tests__/own-tool-schemas.test.ts

@@ -0,0 +1,160 @@
+import { readFileSync } from 'node:fs';
+import express from 'express';
+import { describe, expect, it } from 'vitest';
+import { inputSchemaDefect } from '@bevel-software/platform-mcp-core';
+import { ToolRegistry } from '../tool-registry.js';
+import { registerWorkflowTools } from '../../workflow/agent-tools/workflow.tools.js';
+import { registerChangeRequestReadTools } from '../../workflow/agent-tools/change-request-read.tools.js';
+import { registerWorkspaceTools } from '../../workspace/workspace.tools.js';
+import { registerSkillsTools } from '../../skills/skills.tools.js';
+import { registerPluginsTools } from '../../plugins/plugins.tools.js';
+import { registerToolManualsTools } from '../../tool-manuals/tool-manuals.tools.js';
+import { registerAgentGuideTool } from '../../agent-guide/agent-guide.tools.js';
+import { ToolDescriptionNotes } from '../../workspace/agent-access.gate.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
+
+/**
+ * Every tool Hexis declares itself, checked against the same JSON Schema rules
+ * a connected server's tool is checked against.
+ *
+ * Hexis hides a connected tool whose input schema is invalid, because an AI
+ * client would otherwise drop it in silence. The platform's own tools go to
+ * those same clients through those same surfaces, so a mistake in one of these
+ * schemas costs the tool just as quietly — and it would be Hexis's mistake.
+ * This test is the thing that makes shipping one impossible.
+ *
+ * It registers the DEFS as `create-core-server` does, with stubs for the
+ * services (no def-building path touches one: the lazy providers are resolved
+ * with no caller context, which is their static form).
+ *
+ * Add a tool module to the server and this test FAILS until it is added here:
+ * `covers every tool module the server registers` reads the server's own source
+ * and compares the `register…Tools` calls in it with `MODULES` below. A test
+ * that silently skipped a whole module's schemas would be worse than no test,
+ * because it would read as if it had checked them.
+ */
+
+/**
+ * A stub service: every method answers with an empty list. The def-building
+ * paths that do reach a service only ask it what exists (which skills, which
+ * local-only tools) to name them in a description, and "none" is a valid
+ * answer that keeps the SCHEMAS — what this test is about — untouched.
+ * `then` is excluded so the stub is never mistaken for a promise.
+ */
+const nothing = new Proxy(
+  {},
+  {
+    get: (_target, key) => (key === 'then' ? undefined : async () => []),
+  },
+) as never;
+
+const pass: express.RequestHandler = (_req, _res, next) => next();
+const handler = (() => pass) as never;
+
+/** Where the server registers its tool modules — read, not imported, see below. */
+const CORE_SERVER_SOURCE = new URL('../../../core/create-core-server.ts', import.meta.url);
+
+/** Every tool-registering module, by the name the server calls it under. */
+const MODULES: ReadonlyArray<{ name: string; register: (registry: ToolRegistry) => void }> = [
+  {
+    name: 'registerWorkflowTools',
+    register: (registry) => registerWorkflowTools(registry, express.Router(), pass, handler, testKbContext()),
+  },
+  {
+    name: 'registerChangeRequestReadTools',
+    register: (registry) =>
+      registerChangeRequestReadTools(registry, express.Router(), pass, handler, nothing, testKbContext()),
+  },
+  {
+    name: 'registerWorkspaceTools',
+    register: (registry) =>
+      registerWorkspaceTools(
+        registry,
+        express.Router(),
+        pass,
+        handler,
+        nothing,
+        nothing,
+        nothing,
+        testKbContext(),
+        { recoveryBotEmail: 'recovery@bevel.software', hooks: nothing, notes: new ToolDescriptionNotes() },
+        nothing,
+        nothing,
+        undefined,
+        undefined,
+        // The upload store: the two upload tools are mounted only when one is
+        // supplied, and the server supplies one — so this harness does too,
+        // or their schemas would be the two it silently never checked.
+        nothing,
+      ),
+  },
+  {
+    name: 'registerSkillsTools',
+    register: (registry) => registerSkillsTools(registry, express.Router(), pass, handler, nothing),
+  },
+  { name: 'registerPluginsTools', register: (registry) => registerPluginsTools(registry, testKbContext()) },
+  {
+    name: 'registerToolManualsTools',
+    register: (registry) =>
+      registerToolManualsTools(registry, express.Router(), pass, handler, nothing, {
+        accessControl: nothing,
+        variableStatus: nothing,
+        kb: testKbContext(),
+      }),
+  },
+  {
+    // The one module registering a single tool: a provider on both surfaces,
+    // built from the sections the reader answers — none here, which still
+    // builds the def.
+    name: 'registerAgentGuideTool',
+    register: (registry) => registerAgentGuideTool(registry, express.Router(), pass, handler, async () => []),
+  },
+];
+
+async function toolsOf(modules: ReadonlyArray<(typeof MODULES)[number]>) {
+  const registry = new ToolRegistry();
+  for (const module of modules) module.register(registry);
+  // Both surfaces: the external one is what reaches a connected AI client, the
+  // internal one is what the in-app agent calls. Either can carry a bad schema.
+  return [...(await registry.listExternal()), ...(await registry.listInternal())];
+}
+
+const allOwnTools = () => toolsOf(MODULES);
+
+describe("Hexis's own tool schemas", () => {
+  /**
+   * The harness's own guard, and the reason it reads a source file: nothing in
+   * the registry can tell this test about a module nobody registered. A count
+   * cannot either — a new module leaves it larger either way. The server's call
+   * list can, and it is the only place that knows the whole set.
+   */
+  it('covers every tool module the server registers', () => {
+    const source = readFileSync(CORE_SERVER_SOURCE, 'utf8');
+    // `register…Tools` and `register…Tool` alike: a module registering one
+    // tool is a module whose schema this harness must check too.
+    const registered = [...source.matchAll(/\b(register\w+Tools?)\s*\(/g)].map((m) => m[1]);
+    expect([...new Set(registered)].sort()).toEqual(MODULES.map((m) => m.name).sort());
+  });
+
+  it.each(MODULES.map((m) => [m.name, m] as const))('%s contributes tools to check', async (_name, module) => {
+    // A module that registers nothing — a renamed registry method, a provider
+    // that threw away its defs — would otherwise pass every assertion below
+    // while exercising nothing.
+    expect(await toolsOf([module])).not.toEqual([]);
+  });
+
+  it('declares valid JSON Schema for every tool, on both surfaces', async () => {
+    const defects = (await allOwnTools())
+      .map((tool) => ({ tool: tool.name, defect: inputSchemaDefect(tool.inputs) }))
+      .filter((entry) => entry.defect !== null);
+    // Named, not counted: a failure has to say WHICH tool and WHERE.
+    expect(defects).toEqual([]);
+  });
+
+  it('declares an object schema for every tool, as MCP requires of an input schema', async () => {
+    const notObjects = (await allOwnTools())
+      .filter((tool) => (tool.inputs as { type?: unknown }).type !== 'object')
+      .map((tool) => tool.name);
+    expect(notObjects).toEqual([]);
+  });
+});

package/src/modules/tool-registry/__tests__/tool-description-length.test.ts

@@ -23,13 +23,13 @@ import { UuidSessionSink } from '../../workspace/session-sink.js';
 import { RoutineWritePolicyService } from '../../workspace/routine-write-policy.js';
 import { CLIENT_SHORT_CUT, TOOL_DESCRIPTION_CAP, clientVisibleLength, firstSentenceEnd } from '../description-length.js';
 import {
-  POINTER_GUIDE_NAME_BUDGET,
-  SHARED_RULES_POINTER_MAX,
   TOOL_PREFIX_CAP,
   sharedFileRules,
-  sharedRulesPointer,
 } from '../../agent-instructions/index.js';
 import { isPlatformFile, platformFilesByDepth } from '@bevel-software/platform-shared';
+import { GET_AGENT_GUIDE_TOOL, GUIDE_FIRST_SENTENCE, guideFirstDescription } from '../guide-first.js';
+import { registerAgentGuideTool } from '../../agent-guide/agent-guide.tools.js';
+import { agentGuideSections } from '../../agent-guide/agent-guide.js';
 
 /**
  * The cap exists because clients cut a long tool description, and they cut it
@@ -62,16 +62,18 @@ const emptySkills = { listSkills: async () => [] } as unknown as Parameters<type
 /**
  * The meta-tools as the hosted endpoint builds them (`mcp.service.ts`):
  * examples written against the namespace it registers the knowledge-base tools
- * under and against the catalog it serves, and the chain ending in the pointer.
- * So the chain description measured here carries the worked call a client is
- * really sent, which is its longest form.
+ * under and against the catalog it serves, and the chain without the rules it
+ * states only in the shared places. So the chain description measured here
+ * carries the worked call a client is really sent, which is its longest form.
  */
-function servedMetaTools(external: readonly UtcpTool[], pointer = sharedRulesPointer(testKbContext().layout)) {
+function servedMetaTools(external: readonly UtcpTool[]) {
   return codeModeMetaTools(
     EXTERNAL_KB_MANUAL_NAME,
     external.map((t) => ({ utcpName: `${EXTERNAL_KB_MANUAL_NAME}.${t.name}`, inputSchema: t.inputs })),
-    { sharedRulesPointer: pointer },
-  );
+    { sharedRulesPointer: '' },
+    // As the hosted endpoint serves them: opening with the guide-first
+    // sentence, through the one helper the endpoint itself uses.
+  ).map((t) => ({ ...t, description: guideFirstDescription(t.description) }));
 }
 
 /** Every tool Hexis itself registers, on both surfaces, deduplicated by name. */
@@ -103,18 +105,21 @@ async function hexisTools(): Promise<UtcpTool[]> {
     unused(),
   );
   registerWorkflowTools(registry, router, toolAuth, toolHandler, kb);
-  registerPluginsTools(registry);
+  registerPluginsTools(registry, kb);
   registerSkillsTools(registry, router, toolAuth, toolHandler, emptySkills);
   registerToolManualsTools(registry, router, toolAuth, toolHandler, emptyManuals, {
     accessControl: unused(),
     variableStatus: unused(),
     kb,
   });
+  // The guide's own tool, with the platform's sections: the one description
+  // that lists the sections is measured with the list it really carries.
+  registerAgentGuideTool(registry, router, toolAuth, toolHandler, () => agentGuideSections(kb.layout));
 
   const byName = new Map<string, UtcpTool>();
-  // The meta-tools as a client is served them: the chain carries its pointer
-  // (`mcp.service.ts` appends it at the mount), so the catalog measured here is
-  // the catalog that goes out rather than the unpointed constant.
+  // The meta-tools as a client is served them (`mcp.service.ts` opens each
+  // with the guide-first sentence at the mount), so the catalog measured here
+  // is the catalog that goes out rather than the bare constant.
   const external = (await registry.listExternal()) as UtcpTool[];
   const metaTools = servedMetaTools(external);
   for (const tool of [...(await registry.listInternal()), ...external, ...metaTools]) {
@@ -141,9 +146,11 @@ describe('no Hexis tool description is long enough to be cut', () => {
     // The cap does not answer the ~500-character cut; the ORDER of the text
     // does, and this is where that claim is checked rather than asserted in a
     // comment. A client that stops at 500 must still have the sentence saying
-    // what the tool does — what it loses is the pointer tail, and the file the
-    // pointer names is stated in the handshake instructions and in the guide
-    // anyway. Lowering the cap to 500 would not buy this; only order does.
+    // what the tool does — what it loses is the tail. The shared rules are
+    // stated in the guide (which the opener sends every client to, including
+    // the description-only ones this cut is about) and, for the clients that
+    // honour it, in the handshake instructions as well. Lowering
+    // the cap to 500 would not buy this; only order does.
     const late = (await hexisTools())
       .map((t) => ({ tool: t.name, endsAt: firstSentenceEnd(t) }))
       .filter((m) => m.endsAt > CLIENT_SHORT_CUT)
@@ -156,30 +163,26 @@ describe('no Hexis tool description is long enough to be cut', () => {
     ).toEqual([]);
   });
 
-  it('holds the cap on a deployment that renamed its guide, not only under the default', async () => {
-    // The pointer ends every file tool's description and its length moves with
-    // a deployment setting, so a cap checked only against the nine characters
-    // of `AGENTS.md` guarantees nothing about the catalog a renamed deployment
-    // serves. Two things make it hold: the pointer is bounded by construction
-    // (past `POINTER_GUIDE_NAME_BUDGET` the guide is named by its role), and
-    // `clientVisibleLength` charges the worst case rather than this layout's.
+  it('opens every tool but the guide\'s own with the guide-first sentence, and fits with it', async () => {
+    // The sentence is in the description the registry lists, so the catalog
+    // measured here is the catalog a client gets, sentence included.
     const tools = await hexisTools();
-    const atWorst = tools
-      .map((t) => ({ tool: t.name, chars: clientVisibleLength(t) }))
-      .filter((m) => m.chars > TOOL_DESCRIPTION_CAP);
-    expect(atWorst, atWorst.map((m) => `${m.tool}: ${m.chars}`).join('\n')).toEqual([]);
-
-    // And measured literally, under the longest guide name a deployment can
-    // actually configure: every description still fits.
-    const longest = `${'x'.repeat(252)}.md`;
-    const pointerHere = sharedRulesPointer(testKbContext().layout);
-    const pointerThere = sharedRulesPointer({ ...testKbContext().layout, agentsFile: longest });
-    expect(pointerThere.length).toBeLessThanOrEqual(SHARED_RULES_POINTER_MAX);
-    for (const tool of tools) {
-      if (!tool.description?.endsWith(pointerHere)) continue;
-      const asRenamed = tool.description.slice(0, -pointerHere.length) + pointerThere;
-      const chars = clientVisibleLength({ name: tool.name, description: asRenamed });
-      expect(chars, `${tool.name} on a renamed deployment`).toBeLessThanOrEqual(TOOL_DESCRIPTION_CAP);
+    // ONE predicate for both halves, so no description falls between them: a
+    // tool whose own description is empty is served the sentence alone, and
+    // one with text after it has whitespace between — not `here.Read`.
+    const opensWithGuide = (t: UtcpTool): boolean => {
+      const description = t.description ?? '';
+      if (description === GUIDE_FIRST_SENTENCE) return true;
+      return description.startsWith(GUIDE_FIRST_SENTENCE) && /^\s/.test(description.slice(GUIDE_FIRST_SENTENCE.length));
+    };
+    const opened = tools.filter(opensWithGuide);
+    expect(opened.length).toBeGreaterThan(0);
+    // The guide's own tool is the one exception: it is what the sentence
+    // points at, and it is in the catalog measured here so the cap holds on
+    // it too (see the first test).
+    expect(tools.filter((t) => !opensWithGuide(t)).map((t) => t.name)).toEqual([GET_AGENT_GUIDE_TOOL]);
+    for (const tool of opened) {
+      expect(clientVisibleLength(tool), tool.name).toBeLessThanOrEqual(TOOL_DESCRIPTION_CAP);
     }
   });
 
@@ -190,12 +193,10 @@ describe('no Hexis tool description is long enough to be cut', () => {
     // the catalog the agent reads was over it by 300.
     const read = (await hexisTools()).find((t) => t.name === 'read_file');
     expect(read).toBeDefined();
-    // Its own text, with the pointer charged at its worst case rather than at
-    // this layout's, plus the prefix at ITS cap and the blank line between.
-    const pointer = sharedRulesPointer();
-    const ownAtWorstPointer = read!.description!.length - pointer.length + SHARED_RULES_POINTER_MAX;
-    expect(clientVisibleLength(read!)).toBe(ownAtWorstPointer + TOOL_PREFIX_CAP + 2);
-    expect(ownAtWorstPointer + TOOL_PREFIX_CAP + 2).toBeLessThanOrEqual(TOOL_DESCRIPTION_CAP);
+    // Its own text (the guide-first sentence included), plus the prefix at
+    // ITS cap and the blank line between, must fit — measured as the client
+    // sees it.
+    expect(clientVisibleLength(read!)).toBeLessThanOrEqual(TOOL_DESCRIPTION_CAP);
   });
 
   it('fails, naming the tool, when a paragraph takes a description over the cap', () => {
@@ -228,7 +229,7 @@ describe('no Hexis tool description is long enough to be cut', () => {
   });
 });
 
-describe('every file tool ends with the pointer and carries no shared paragraph', () => {
+describe('every file tool opens with the guide-first sentence and carries no shared paragraph', () => {
   /** The tools that used to carry the shared paragraphs — every `mount`ed one. */
   const FILE_TOOLS = [
     'read_file',
@@ -248,13 +249,12 @@ describe('every file tool ends with the pointer and carries no shared paragraph'
     'apply_file_upload',
   ];
 
-  it('ends each description with the one sentence naming the shared rules', async () => {
+  it('opens each description with the sentence sending the agent to the guide, and ends it as a sentence', async () => {
     const tools = await hexisTools();
-    const pointer = sharedRulesPointer(testKbContext().layout);
     for (const name of FILE_TOOLS) {
       const def = tools.find((t) => t.name === name);
       expect(def, name).toBeDefined();
-      expect(def!.description!.endsWith(pointer), `${name} must end with: ${pointer}`).toBe(true);
+      expect(def!.description!.startsWith(`${GUIDE_FIRST_SENTENCE} `), `${name} must open with: ${GUIDE_FIRST_SENTENCE}`).toBe(true);
       // Ends with a full sentence, so nothing reads as cut off mid-thought.
       expect(def!.description!.trimEnd().endsWith('.'), name).toBe(true);
     }
@@ -283,25 +283,27 @@ describe('every file tool ends with the pointer and carries no shared paragraph'
 });
 
 describe('the shared rules describe the tools they name', () => {
-  it('ends the chain description with the pointer too, under the cap', async () => {
+  it('opens the chain description with the guide-first sentence too, under the cap', async () => {
     // What a chain does with a failure, a large result or an image is true of
     // every call, so it is stated in the shared rules — and the clients that
     // drop the handshake `instructions` see only descriptions, so the chain
-    // gets the same pointer every file tool ends with. Composed at the mount,
-    // because `mcp-core` may not spell a guide name that is a deployment
-    // setting.
-    const pointer = sharedRulesPointer(testKbContext().layout);
+    // opens with the same sentence every tool of the platform's own opens
+    // with, and ends with no second pointer: the one at the front is the way
+    // to the rules. Composed at the mount, because `mcp-core` builds the
+    // constant without knowing where this deployment states them.
     const served = (await hexisTools()).find((t) => t.name === CALL_TOOL_CHAIN_NAME)!;
-    expect(served.description!.endsWith(pointer)).toBe(true);
+    expect(served.description!.startsWith(`${GUIDE_FIRST_SENTENCE} `)).toBe(true);
+    expect(served.description!.split(GUIDE_FIRST_SENTENCE)).toHaveLength(2);
+    expect(served.description!.trimEnd().endsWith('.')).toBe(true);
     expect(clientVisibleLength(served)).toBeLessThanOrEqual(TOOL_DESCRIPTION_CAP);
-    // The other two describe the registry, not what a call does: no pointer.
+    // The other two open the same way: the guide comes before the registry too.
     for (const tool of servedMetaTools([]).filter((t) => t.name !== CALL_TOOL_CHAIN_NAME)) {
-      expect(tool.description).not.toContain(pointer);
+      expect(tool.description!.startsWith(`${GUIDE_FIRST_SENTENCE} `), tool.name).toBe(true);
     }
   });
 
   it('states what a chain does in the shared rules, and not a second time on the chain', async () => {
-    // The pointer is only honest if the rules it points at are THERE. These
+    // The opener is only honest if the rules it points at are THERE. These
     // two were paragraphs of the chain's description; they moved, whole, and a
     // description that kept them as well would be the long one a client cuts.
     const rule = sharedFileRules(testKbContext().layout).find((r) => r.id === 'tool-chain')!;
@@ -317,7 +319,7 @@ describe('the shared rules describe the tools they name', () => {
 
   it('keeps the rules on the chain itself where no shared rules are served', () => {
     // The standalone bridge proxies a deployment whose guide it cannot name, so
-    // it passes no pointer — and an agent there must still be told what a chain
+    // it passes no pointer at all — and an agent there must still be told what a chain
     // that timed out, or answered too much, or read an image, does.
     const [chain] = codeModeMetaTools('hexis', []).filter((t) => t.name === CALL_TOOL_CHAIN_NAME);
     expect(chain.description).toContain(CHAIN_FAILURES_RULE);

package/src/modules/tool-registry/description-length.ts

@@ -5,14 +5,15 @@
  * where the text specific to the tool sits, after whatever shared preamble it
  * carried. Agents reported `file_stat`, `read_file`, `write_file` and
  * `write_files` arriving ending in "[truncated]". The rules those descriptions
- * shared now live in one place (see `agent-instructions/shared-file-rules.ts`)
- * and each description ends with one sentence pointing there, which is what
- * makes the cap below reachable rather than aspirational.
+ * shared now live in one place (see `agent-instructions/shared-file-rules.ts`,
+ * served in the guide `get_agent_guide` returns) and each description OPENS
+ * with the one sentence sending the agent there (`guide-first.ts`), which is
+ * what makes the cap below reachable rather than aspirational.
  */
 
 import { TOOL_PREFIX_CAP } from '@bevel-software/platform-shared';
 import { PREFIXED_TOOLS } from '../agent-instructions/compose.js';
-import { SHARED_RULES_POINTER_MAX, sharedRulesPointer } from '../agent-instructions/shared-file-rules.js';
+import { GUIDE_FIRST_SENTENCE } from './guide-first.js';
 import type { UtcpTool } from './tool.contract.js';
 
 /**
@@ -25,8 +26,10 @@ import type { UtcpTool } from './tool.contract.js';
  * could answer: no useful description of `move_file` fits in 500. What answers
  * that one is the ORDER of the text, which is why the deployment's purpose line
  * is prepended rather than appended (see `prefixToolDescription`) and why every
- * description now leads with what the tool does and ends with the pointer: a
- * cut at 500 then takes the pointer and leaves the tool. The other cut is the
+ * description now opens with the guide-first sentence and then what the tool
+ * does, with the tool's own detail last: a cut at 500 keeps the sentence and
+ * the tool's first sentence (see `firstSentenceEnd`) and takes the detail,
+ * which the guide states in full anyway. The other cut is the
  * four-figure one agents reported on `file_stat`, `read_file`, `write_file` and
  * `write_files`, and 1,200 sits below it with room to spare.
  *
@@ -60,9 +63,10 @@ export const CLIENT_SHORT_CUT = 500;
 
 /**
  * Where the tool's OWN opening sentence ends in the text a client is handed:
- * the purpose prefix counted at its cap, as in {@link clientVisibleLength}, and
- * the pointer not counted at all, since it is the part a short cut is meant to
- * take.
+ * the purpose prefix counted at its cap, as in {@link clientVisibleLength},
+ * and the guide-first sentence every listed tool opens with counted as the
+ * text it is — a client that cuts at 500 must still reach the sentence saying
+ * what the tool does, past that one.
  *
  * A description with no sentence-ending punctuation counts whole — the honest
  * answer for text that never finishes a sentence.
@@ -71,10 +75,15 @@ export function firstSentenceEnd(tool: Pick<UtcpTool, 'name' | 'description'>):
   const prefix = PREFIXED_TOOLS.has(tool.name) ? TOOL_PREFIX_CAP + 2 : 0;
   const description = tool.description ?? '';
   if (description === '') return prefix;
-  const pointer = sharedRulesPointer();
-  const own = description.endsWith(pointer) ? description.slice(0, -pointer.length) : description;
+  // The opener and whatever whitespace follows it: `guideFirstDescription`
+  // joins with one space, and leaves a description that already opens with
+  // the sentence as it came — a newline after it is still the opener's.
+  const opener = description.startsWith(GUIDE_FIRST_SENTENCE)
+    ? GUIDE_FIRST_SENTENCE.length + (description.slice(GUIDE_FIRST_SENTENCE.length).match(/^\s*/)?.[0].length ?? 0)
+    : 0;
+  const own = description.slice(opener);
   const firstSentence = own.match(/^[\s\S]*?[.!?](?=\s|$)/)?.[0] ?? own;
-  return prefix + firstSentence.length;
+  return prefix + opener + firstSentence.length;
 }
 
 /**
@@ -85,12 +94,8 @@ export function firstSentenceEnd(tool: Pick<UtcpTool, 'name' | 'description'>):
  * the cap is what an admin may grow their text to without being told, so a
  * description that only fits beside a short prefix does not really fit.
  *
- * The pointer sentence is measured the same way, for the same reason. It ends
- * every file tool's description and its length moves with a DEPLOYMENT SETTING
- * — the guide's file name — so a description measured beside the nine
- * characters of `AGENTS.md` would pass here and arrive cut on a deployment
- * that renamed its guide. Whatever pointer a description actually carries is
- * discounted and charged at {@link SHARED_RULES_POINTER_MAX} instead.
+ * The guide-first sentence every listed tool opens with is already in the
+ * description the registry lists, so it is measured as the text it is.
  */
 export function clientVisibleLength(tool: Pick<UtcpTool, 'name' | 'description'>): number {
   const own = tool.description?.length ?? 0;
@@ -99,13 +104,6 @@ export function clientVisibleLength(tool: Pick<UtcpTool, 'name' | 'description'>
   // blank line after it. Measuring that as zero would under-report the only
   // text the client got.
   if (own === 0) return PREFIXED_TOOLS.has(tool.name) ? TOOL_PREFIX_CAP : 0;
-  // The pointer at its worst case rather than at this layout's: swap the one
-  // it carries for the longest it could be. A description that does not end
-  // with it (`start_session`, the proxied tools) is charged nothing.
-  const pointer = sharedRulesPointer();
-  const atWorstPointer = tool.description!.endsWith(pointer)
-    ? own - pointer.length + SHARED_RULES_POINTER_MAX
-    : own;
   // `+ 2` for the blank line `prefixToolDescription` puts between the two.
-  return PREFIXED_TOOLS.has(tool.name) ? atWorstPointer + TOOL_PREFIX_CAP + 2 : atWorstPointer;
+  return PREFIXED_TOOLS.has(tool.name) ? own + TOOL_PREFIX_CAP + 2 : own;
 }