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

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

@@ -65,32 +65,24 @@ 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.
     description:
-      'Configuration status of every `.tool` the current user can access: what each tool needs set up and ' +
-      'what is already configured. Results are scoped to the caller — a `.tool` the caller cannot READ is ' +
-      'absent entirely, and all status flags reflect the caller\'s own state. Per tool: `setup` describes ' +
-      'an MCP server\'s sign-in requirement (`open` = none; `oauth-auto` = sign-in was configured ' +
-      'automatically; `oauth-manual` = the sign-in needs an OAuth app the owner registers with the provider: ' +
-      'a writer declares its client id on a `user`-scoped variable with an `oauth` block — in the plugin.json ' +
-      'extensions entry for an mcp.json server (endpoints are discovered from the server; PKCE is on by ' +
-      'default), or in the `.tool` file with explicit URLs — and pastes the client secret on the tool\'s page. ' +
-      '`setup.reason` is present only while something still blocks the sign-in and says what). ' +
-      'Per variable: whether the shared (admin) value is set, whether the CURRENT user has ' +
-      'set/authorized their own, and whether it is an OAuth sign-in (users authorize those on the /connect ' +
-      'page, never by typing a value). `canWrite` = the caller may write THAT `.tool` FILE (per-file access ' +
-      'from its frontmatter `write:`/`owner:` verbs and the access.md chain — NOT a platform role), which ' +
-      'is exactly what gates setting its shared secrets: the people who manage the file configure the tool. ' +
-      '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. ' +
-      '`invalid` names any `.tool` file the scan REFUSED, with the reason and its location: those files ' +
-      'are the only ones missing — every other tool is listed and callable, and a refused file is listed ' +
-      'again as a normal tool on the next call once it is fixed (or removed), with nothing to restart or ' +
-      'reconnect. ' +
-      '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.',
+      '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. ' +
+      '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.',
     path: '/api/agent/tools/list_tool_setup',
     inputs: {
       type: 'object',
@@ -119,12 +111,32 @@ export function registerToolManualsTools(
               type: { type: 'string' },
               setup: {
                 type: ['object', 'null'],
-                description: 'MCP auto-discovery setup requirement; null for non-mcp tools.',
-                properties: { kind: { type: 'string' }, reason: { type: 'string' } },
+                description: "An MCP server's sign-in requirement; null for non-mcp tools.",
+                properties: {
+                  kind: {
+                    type: 'string',
+                    description:
+                      '`open` = no sign-in; `oauth-auto` = sign-in was configured automatically; `oauth-manual` = the ' +
+                      'sign-in needs an OAuth app the owner registers with the provider: a writer declares its client ' +
+                      'id on a `user`-scoped variable with an `oauth` block — in the plugin.json extensions entry for ' +
+                      'an mcp.json server (endpoints are discovered from the server; PKCE is on by default), or in the ' +
+                      '`.tool` file with explicit URLs — and pastes the client secret on the tool\'s page.',
+                  },
+                  reason: {
+                    type: 'string',
+                    description: 'Present only while something still blocks the sign-in, and says what.',
+                  },
+                },
+              },
+              canWrite: {
+                type: 'boolean',
+                description: 'You may write this `.tool` FILE, which is what gates setting its shared secrets.',
               },
-              canWrite: { type: 'boolean' },
               variables: {
                 type: 'array',
+                description:
+                  'What this tool needs configured, and by whom: per variable, whether the shared (admin) value is ' +
+                  'set and whether the CURRENT user has set or authorized their own.',
                 items: {
                   type: 'object',
                   properties: {
@@ -150,9 +162,10 @@ export function registerToolManualsTools(
         invalid: {
           type: 'array',
           description:
-            '`.tool` files the scan refused — the ONLY tools missing from `tools`. Each names the file and ' +
-            'why it was refused, with the line/column or field where the validation failed. Fix the file (or ' +
-            'delete it) and the next call lists it as a normal tool. Never contains a secret value.',
+            '`.tool` files the scan refused — the ONLY tools missing from `tools`; every other tool is listed and ' +
+            'callable. Each names the file and why it was refused, with the line/column or field where the validation ' +
+            'failed. Fix the file (or delete it) and the next call lists it as a normal tool, with nothing to restart ' +
+            'or reconnect. Never contains a secret value.',
           items: {
             type: 'object',
             properties: {

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

@@ -0,0 +1,378 @@
+import express from 'express';
+import { describe, expect, it } from 'vitest';
+import {
+  CALL_TOOL_CHAIN_NAME,
+  CHAIN_FAILURES_RULE,
+  CHAIN_LARGE_RESULTS_RULE,
+  codeModeMetaTools,
+} from '@bevel-software/platform-mcp-core';
+import { testKbContext } from '../../../__tests__/kb-context.js';
+import { EXTERNAL_KB_MANUAL_NAME } from '../../tool-manuals/tool-manuals.contract.js';
+import { ToolRegistry } from '../tool-registry.js';
+import type { UtcpTool } from '../tool.contract.js';
+import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
+import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
+import { registerWorkspaceTools } from '../../workspace/workspace.tools.js';
+import { registerWorkflowTools } from '../../workflow/agent-tools/workflow.tools.js';
+import { registerPluginsTools } from '../../plugins/plugins.tools.js';
+import { registerSkillsTools } from '../../skills/skills.tools.js';
+import { registerToolManualsTools } from '../../tool-manuals/tool-manuals.tools.js';
+import { ToolDescriptionNotes } from '../../workspace/agent-access.gate.js';
+import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
+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';
+
+/**
+ * The cap exists because clients cut a long tool description, and they cut it
+ * from the END — where the text specific to the tool sits. Agents reported
+ * `file_stat`, `read_file`, `write_file` and `write_files` arriving as
+ * "[truncated]". So this measures what a client is actually handed, and fails
+ * NAMING the tool: the next paragraph someone appends to a description has to
+ * answer to this test rather than to an agent's truncated catalog.
+ *
+ * Every registrar Hexis owns is mounted here, on stand-ins, because the
+ * descriptions are the only thing under test: a stand-in that is never called
+ * is honest about that. Tools PROXIED from connected MCP servers are not
+ * measured — their text is the other server's.
+ */
+
+/** Dependencies the registrars take but never touch while they are only building defs. */
+const unused = <T,>(): T => ({}) as T;
+
+/** A `.tool` catalog with nothing in it: the shortest honest answer for a listing. */
+const emptyManuals = {
+  listLocalOnly: async () => [],
+  listAll: async () => [],
+  list: async () => [],
+  listInvalid: async () => [],
+} as unknown as Parameters<typeof registerToolManualsTools>[4];
+
+/** A skill catalog with nothing in it — the per-user skill line is then one fixed sentence. */
+const emptySkills = { listSkills: async () => [] } as unknown as Parameters<typeof registerSkillsTools>[4];
+
+/**
+ * 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.
+ */
+function servedMetaTools(external: readonly UtcpTool[], pointer = sharedRulesPointer(testKbContext().layout)) {
+  return codeModeMetaTools(
+    EXTERNAL_KB_MANUAL_NAME,
+    external.map((t) => ({ utcpName: `${EXTERNAL_KB_MANUAL_NAME}.${t.name}`, inputSchema: t.inputs })),
+    { sharedRulesPointer: pointer },
+  );
+}
+
+/** Every tool Hexis itself registers, on both surfaces, deduplicated by name. */
+async function hexisTools(): Promise<UtcpTool[]> {
+  const registry = new ToolRegistry();
+  const router = express.Router();
+  const toolAuth = ((_req, _res, next) => next()) as unknown as ToolAuth;
+  const toolHandler = createToolHandlerFactory(unused());
+  const kb = testKbContext();
+  const gate = { recoveryBotEmail: 'bot@x', hooks: new WorkflowHooks(), notes: new ToolDescriptionNotes() };
+
+  registerWorkspaceTools(
+    registry,
+    router,
+    toolAuth,
+    toolHandler,
+    unused(),
+    unused(),
+    unused(),
+    kb,
+    gate,
+    new RoutineWritePolicyService(),
+    new UuidSessionSink(),
+    undefined,
+    undefined,
+    // The two upload tools are mounted only when a store is supplied, and
+    // every real composition supplies one: without it they would be the two
+    // descriptions this suite never measured.
+    unused(),
+  );
+  registerWorkflowTools(registry, router, toolAuth, toolHandler, kb);
+  registerPluginsTools(registry);
+  registerSkillsTools(registry, router, toolAuth, toolHandler, emptySkills);
+  registerToolManualsTools(registry, router, toolAuth, toolHandler, emptyManuals, {
+    accessControl: unused(),
+    variableStatus: unused(),
+    kb,
+  });
+
+  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.
+  const external = (await registry.listExternal()) as UtcpTool[];
+  const metaTools = servedMetaTools(external);
+  for (const tool of [...(await registry.listInternal()), ...external, ...metaTools]) {
+    byName.set(tool.name, tool as UtcpTool);
+  }
+  return [...byName.values()];
+}
+
+describe('no Hexis tool description is long enough to be cut', () => {
+  it(`keeps every description a client is handed within ${TOOL_DESCRIPTION_CAP} characters`, async () => {
+    const over = (await hexisTools())
+      .map((t) => ({ tool: t.name, chars: clientVisibleLength(t) }))
+      .filter((m) => m.chars > TOOL_DESCRIPTION_CAP)
+      .sort((a, b) => b.chars - a.chars);
+    // The message names the tool and its length, because "a description is too
+    // long" sends the next reader back to measuring them by hand.
+    expect(
+      over,
+      over.map((m) => `${m.tool}: ${m.chars} characters (cap ${TOOL_DESCRIPTION_CAP})`).join('\n'),
+    ).toEqual([]);
+  });
+
+  it(`leaves the tool's own first sentence inside the shorter ${CLIENT_SHORT_CUT}-character cut`, async () => {
+    // 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.
+    const late = (await hexisTools())
+      .map((t) => ({ tool: t.name, endsAt: firstSentenceEnd(t) }))
+      .filter((m) => m.endsAt > CLIENT_SHORT_CUT)
+      .sort((a, b) => b.endsAt - a.endsAt);
+    expect(
+      late,
+      late
+        .map((m) => `${m.tool}: first sentence ends at ${m.endsAt} (cut ${CLIENT_SHORT_CUT}) — lead with what it does`)
+        .join('\n'),
+    ).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.
+    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);
+    }
+  });
+
+  it('measures a prefixed tool with the prefix a client sees, not without it', async () => {
+    // The four knowledge-base tools carry the deployment's tool prefix ahead of
+    // their description on the MCP surface — up to `TOOL_PREFIX_CAP` characters
+    // the admin writes. A cap applied to the bare description would pass while
+    // 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);
+  });
+
+  it('fails, naming the tool, when a paragraph takes a description over the cap', () => {
+    const padded = { name: 'write_file', description: 'x'.repeat(TOOL_DESCRIPTION_CAP + 1) } as UtcpTool;
+    expect(clientVisibleLength(padded)).toBeGreaterThan(TOOL_DESCRIPTION_CAP);
+    // A tool with no description at all is not over the cap.
+    expect(clientVisibleLength({ name: 'nothing' } as UtcpTool)).toBe(0);
+    // Unless it is a PREFIXED one: the prefix is sent on its own then (no
+    // description, so no blank line either), and that text is what the client
+    // was handed. Measuring it as nothing would hide the only thing it got.
+    expect(clientVisibleLength({ name: 'read_file' } as UtcpTool)).toBe(TOOL_PREFIX_CAP);
+  });
+
+  it('measures the catalog, which is what a client lists — and says what is outside it', async () => {
+    // The cap is about `tools/list`: a client cuts what it was sent. The ONE
+    // long description this repository still writes is the in-process Mastra
+    // `call_tool_chain`, which no client lists — the in-process agent is handed
+    // it directly — and which OPENS with `@utcp/code-mode`'s own 2,500-character
+    // usage guide, text this repository does not own. It is left as it is, on
+    // purpose, and this assertion is what keeps that a stated fact rather than
+    // an oversight: if it ever reaches the catalog, the cap test above measures
+    // it like everything else.
+    const { createCallToolChainTool } = await import('../../code-mode/code-mode.tool.js');
+    const mastraTool = createCallToolChainTool(unused(), unused(), EXTERNAL_KB_MANUAL_NAME) as unknown as {
+      description: string;
+    };
+    expect(mastraTool.description).toContain('UTCP CodeMode Tool Usage Guide');
+    expect(mastraTool.description.length).toBeGreaterThan(TOOL_DESCRIPTION_CAP);
+    expect((await hexisTools()).some((t) => t.description === mastraTool.description)).toBe(false);
+  });
+});
+
+describe('every file tool ends with the pointer and carries no shared paragraph', () => {
+  /** The tools that used to carry the shared paragraphs — every `mount`ed one. */
+  const FILE_TOOLS = [
+    'read_file',
+    'list_files',
+    'file_stat',
+    'grep',
+    'write_file',
+    'write_files',
+    'edit_file',
+    'delete_file',
+    'delete_folder',
+    'mkdir',
+    'move_file',
+    'copy_file',
+    'unzip',
+    'execute_command',
+    'apply_file_upload',
+  ];
+
+  it('ends each description with the one sentence naming the shared rules', 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);
+      // Ends with a full sentence, so nothing reads as cut off mid-thought.
+      expect(def!.description!.trimEnd().endsWith('.'), name).toBe(true);
+    }
+  });
+
+  it('no longer repeats a shared paragraph inside a description', async () => {
+    const tools = await hexisTools();
+    // One recognisable fragment per rule that moved out. Searched across EVERY
+    // Hexis description, not only the file tools: a rule that came back by
+    // being pasted into a neighbouring tool is the same regression.
+    const moved = [
+      'Content rule (the same on every file tool)',
+      'they refuse documents, images, archives and other binary files',
+      '`mode` decides what may happen at a path and DEFAULTS TO',
+      'Images: keep them in an `assets/` folder',
+      'Escape sequences: some clients decode them in arguments',
+      'If this is refused for permissions',
+      'Before your first read or change in a workspace',
+      'Do NOT set `confirm: true` on your first call',
+    ];
+    for (const fragment of moved) {
+      const carriers = tools.filter((t) => (t.description ?? '').includes(fragment)).map((t) => t.name);
+      expect(carriers, `"${fragment}" is a shared rule and belongs in the shared places only`).toEqual([]);
+    }
+  });
+});
+
+describe('the shared rules describe the tools they name', () => {
+  it('ends the chain description with the pointer 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);
+    const served = (await hexisTools()).find((t) => t.name === CALL_TOOL_CHAIN_NAME)!;
+    expect(served.description!.endsWith(pointer)).toBe(true);
+    expect(clientVisibleLength(served)).toBeLessThanOrEqual(TOOL_DESCRIPTION_CAP);
+    // The other two describe the registry, not what a call does: no pointer.
+    for (const tool of servedMetaTools([]).filter((t) => t.name !== CALL_TOOL_CHAIN_NAME)) {
+      expect(tool.description).not.toContain(pointer);
+    }
+  });
+
+  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
+    // 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')!;
+    expect(rule.body).toContain(CHAIN_FAILURES_RULE);
+    expect(rule.body).toContain(CHAIN_LARGE_RESULTS_RULE);
+    const served = (await hexisTools()).find((t) => t.name === CALL_TOOL_CHAIN_NAME)!;
+    expect(served.description).not.toContain(CHAIN_FAILURES_RULE);
+    expect(served.description).not.toContain(CHAIN_LARGE_RESULTS_RULE);
+    // What a chained read does to an image was already one of the shared rules.
+    const content = sharedFileRules(testKbContext().layout).find((r) => r.id === 'content-kinds')!;
+    expect(content.body).toContain('image_omitted');
+  });
+
+  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
+    // 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);
+    expect(chain.description).toContain(CHAIN_LARGE_RESULTS_RULE);
+    expect(chain.description).toContain('image_omitted');
+  });
+
+  it('names a dry run only on the tools that take one', async () => {
+    // A rule is worse than no rule when it promises an argument the tool
+    // rejects: `delete_file` has no `dryRun`, so an agent told to preflight a
+    // single-file delete gets a validation error on the safe call and learns to
+    // skip it. Read off the schemas rather than asserted by hand.
+    const rule = sharedFileRules(testKbContext().layout).find((r) => r.id === 'dry-run-confirm')!;
+    const tools = await hexisTools();
+    // `toolDef` wraps a tool's own inputs under `body`, which is the schema a
+    // client validates against — so that is where the argument either is or is not.
+    const takesDryRun = (name: string): boolean => {
+      const inputs = tools.find((t) => t.name === name)?.inputs as
+        | { properties?: { body?: { properties?: Record<string, unknown> } } }
+        | undefined;
+      return inputs?.properties?.body?.properties?.dryRun !== undefined;
+    };
+    expect(takesDryRun('move_file')).toBe(true);
+    expect(takesDryRun('delete_folder')).toBe(true);
+    expect(takesDryRun('delete_file')).toBe(false);
+    // Every tool that takes one, read off the catalog rather than listed here —
+    // a hand-written list is what let `copy_file` gain a `dryRun` on dev while
+    // the rule still named two tools, so an agent reading the guide was told
+    // the copy had no preflight it could run.
+    const withDryRun = tools.filter((t) => takesDryRun(t.name)).map((t) => t.name);
+    expect(withDryRun.length, 'no tool takes a dryRun — the rule would be vacuous').toBeGreaterThan(1);
+    for (const name of withDryRun) {
+      expect(rule.body, name).toContain(name);
+    }
+    // Named, but as the tool that has none — never as one that takes one.
+    expect(rule.body).toContain('delete_file takes neither');
+    expect(rule.body).not.toContain('move_file, delete_file and delete_folder take');
+  });
+
+  it('gives each platform file the depth it actually counts at', () => {
+    const rule = sharedFileRules(testKbContext().layout).find((r) => r.id === 'managed-items')!;
+    const { anyDepth, rootOnly } = platformFilesByDepth(testKbContext().layout);
+    // The split is the half of the rule a list of names leaves out, and
+    // `isPlatformFile` is the predicate the prose has to match.
+    expect(rule.body).toContain(`${anyDepth.map((n) => `\`${n}\``).join(' or ')} in any folder`);
+    expect(rule.body).toContain(`${rootOnly.map((n) => `\`${n}\``).join(' or ')} at the repository root`);
+    for (const name of anyDepth) expect(isPlatformFile(`Deep/Folder/${name}`, testKbContext().layout), name).toBe(true);
+    for (const name of rootOnly) expect(isPlatformFile(`Deep/Folder/${name}`, testKbContext().layout), name).toBe(false);
+  });
+
+  it('says what unzip extracts, rather than that it takes any bytes', () => {
+    const rule = sharedFileRules(testKbContext().layout).find((r) => r.id === 'content-kinds')!;
+    // `unzip` refuses anything but a `.zip` (`workspace.service.ts`: "Only .zip
+    // files can be extracted"), so the byte-tool clause must not sweep it in.
+    expect(rule.body).toContain('unzip extracts the entries of a `.zip`');
+    expect(rule.body).not.toContain('and unzip act on bytes of any kind');
+  });
+});

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

@@ -0,0 +1,111 @@
+/**
+ * How long a tool description may be, and how to measure one.
+ *
+ * Clients cut a long description, and they cut it from the END — which is
+ * 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.
+ */
+
+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 type { UtcpTool } from './tool.contract.js';
+
+/**
+ * The ceiling on what a client is handed for one tool, enforced by
+ * `__tests__/tool-description-length.test.ts`.
+ *
+ * DERIVED, not published: the clients that cut descriptions do not say where.
+ * Two cuts were observed, and they are different problems. claude.ai cuts
+ * around 500 characters — NOT what this cap answers, and not something a cap
+ * 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
+ * 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.
+ *
+ * So the cap is a ceiling on growth rather than a guarantee of survival, and it
+ * is a number the reviewer may move: the point of pinning it is that moving it
+ * is a decision someone takes, rather than a paragraph someone appends.
+ */
+export const TOOL_DESCRIPTION_CAP = 1_200;
+
+/**
+ * The OTHER cut — the ~500 characters claude.ai allows — as a number the tests
+ * can hold something to.
+ *
+ * It is deliberately not the value of {@link TOOL_DESCRIPTION_CAP}, and the
+ * difference is the whole point: lowering the cap to 500 would not make these
+ * descriptions survive that client, it would only move the loss from the client
+ * to the source, because no useful description of `move_file` or `file_stat`
+ * fits in 500 characters and shortening them to fit means dropping facts an
+ * agent needs.
+ *
+ * What survives a cut here is decided by ORDER instead, and order is testable:
+ * the purpose prefix goes first, the tool's own opening sentence next, the
+ * pointer to the shared rules last. So a cut at 500 takes the pointer — which
+ * costs the agent the name of a file the handshake instructions and the guide
+ * both state anyway — and leaves the sentence saying what the tool does.
+ * {@link firstSentenceEnd} measures where that sentence ends, and the suite
+ * pins it under this number for every tool, so the claim above is a check
+ * rather than a comment.
+ */
+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.
+ *
+ * A description with no sentence-ending punctuation counts whole — the honest
+ * answer for text that never finishes a sentence.
+ */
+export function firstSentenceEnd(tool: Pick<UtcpTool, 'name' | 'description'>): number {
+  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;
+  const firstSentence = own.match(/^[\s\S]*?[.!?](?=\s|$)/)?.[0] ?? own;
+  return prefix + firstSentence.length;
+}
+
+/**
+ * The length of the description as a CLIENT receives it — which for the four
+ * knowledge-base tools includes the deployment's purpose prefix, since the MCP
+ * surface prepends it (`prefixToolDescription`) and the client cuts the result.
+ * Measured at the prefix's CAP rather than at whatever the current admin wrote:
+ * 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.
+ */
+export function clientVisibleLength(tool: Pick<UtcpTool, 'name' | 'description'>): number {
+  const own = tool.description?.length ?? 0;
+  // A prefixed tool with no description of its own is still handed the prefix,
+  // and nothing else — `prefixToolDescription` sends the prefix alone, with no
+  // 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;
+}