simt-dev 0.2.0 → 0.2.2

package/src/mcp/server.mjs

@@ -22,7 +22,24 @@
 import { createInterface } from 'node:readline';
 import { CLI } from '../name.mjs';
 
-export const PROTOCOL_VERSION = '2025-06-18';
+/**
+ * Every protocol revision this server speaks, newest first.
+ *
+ * The list is a claim about revisions that were read, not about ones that exist: each
+ * entry names a published revision and the behaviour this file implements for it, and
+ * ADR-068 records what changed. A revision not in this list is answered with
+ * `UnsupportedProtocolVersionError` rather than an optimistic guess, because the failure
+ * mode of guessing is a client that believes a feature is on and watches it misbehave.
+ */
+export const SUPPORTED_VERSIONS = ['2026-07-28', '2025-11-25', '2025-06-18'];
+
+/**
+ * The revision this server answers with when the client has not asked for one.
+ *
+ * Named the way every caller has always named it, and it is the newest supported
+ * revision rather than the only one: a client that asks for an older one gets it.
+ */
+export const PROTOCOL_VERSION = SUPPORTED_VERSIONS[0];
 
 /** JSON-RPC codes. -32700/-32600/-32601 are the spec's parse/request/method set. */
 export const RPC = {
@@ -30,16 +47,60 @@ export const RPC = {
   REQUEST: -32600,
   METHOD: -32601,
   INTERNAL: -32603,
+  /**
+   * `UnsupportedProtocolVersionError`, renumbered to -32022 in 2026-07-28. The spec
+   * reserves -32000..-32019 for implementations and -32020..-32099 for itself, so the
+   * older -32004 would now be an implementation-defined code in the wrong range.
+   */
+  UNSUPPORTED_VERSION: -32022,
+  /** Resource not found: -32002 in every revision up to 2025-11-25, -32602 after. */
+  RESOURCE_NOT_FOUND_LEGACY: -32002,
+  RESOURCE_NOT_FOUND: -32602,
+};
+
+/** The `_meta` keys 2026-07-28 puts on a request and in a result. */
+export const META = {
+  PROTOCOL_VERSION: 'io.modelcontextprotocol/protocolVersion',
+  CLIENT_INFO: 'io.modelcontextprotocol/clientInfo',
+  CLIENT_CAPABILITIES: 'io.modelcontextprotocol/clientCapabilities',
+  SERVER_INFO: 'io.modelcontextprotocol/serverInfo',
 };
 
+/** Revisions that removed `ping`, per the 2026-07-28 changelog (SEP-2575). */
+const PING_REMOVED_IN = '2026-07-28';
+
 const SERVER_INFO = { name: 'simt-dev', title: 'SIMT developer and agent tooling' };
 
+/**
+ * One hour, and the reason it is a number rather than an omission.
+ *
+ * `ttlMs` and `cacheScope` are required on list results from 2026-07-28, and the value
+ * is a fact about this server rather than a courtesy: the tool list changes when the
+ * release changes and not otherwise, so an hour is long enough to spare a client the
+ * round trip and short enough that a client started from a stale one re-reads it within
+ * a working day. `private`, because the list names the reader's own repository and no
+ * intermediary may hold it.
+ */
+const LIST_CACHE = { ttlMs: 3600000, cacheScope: 'private' };
+
 /**
  * Handle one parsed request. Pure with respect to the process: returns the response
  * object or null (for a notification), and never writes anywhere. Testable without a
  * pipe, which is the only way to test a line protocol honestly.
+ *
+ * `state` is the negotiated revision, and it is the only thing this function mutates.
+ * 2026-07-28 removed the handshake and made every request carry its own version, so a
+ * session is not part of the protocol any more - but a client on an older revision
+ * negotiates once and then sends bare requests, and answering those at the newest
+ * revision would hand it fields it did not ask for. So the version is read from the
+ * request when there is one and remembered only for the clients that need it.
+ *
+ * @param {object|null} request a parsed JSON-RPC message
+ * @param {object[]} tools
+ * @param {{packageVersion?: string, state?: {version: string|null}}} options
+ * @returns {Promise<object|null>}
  */
-export async function handle(request, tools, { version } = {}) {
+export async function handle(request, tools, { packageVersion, state } = {}) {
   if (request === null || typeof request !== 'object' || Array.isArray(request)) {
     return error(null, RPC.REQUEST, 'request must be a JSON object');
   }
@@ -54,25 +115,68 @@ export async function handle(request, tools, { version } = {}) {
   }
   if (isNotification) return null;
 
+  const asked = params?._meta?.[META.PROTOCOL_VERSION];
+  if (typeof asked === 'string' && !SUPPORTED_VERSIONS.includes(asked)) {
+    // The one place a client checks whether it got what it asked for, so this is where
+    // an unsupported version has to fail. The message names the revisions that do work,
+    // because "unsupported" alone leaves the client to guess between the two answers a
+    // server can give.
+    return error(
+      id,
+      RPC.UNSUPPORTED_VERSION,
+      `protocol version ${asked} is not supported; this server speaks ${SUPPORTED_VERSIONS.join(', ')}`,
+    );
+  }
+  const negotiated =
+    typeof asked === 'string' ? asked : method === 'initialize' ? negotiate(params?.protocolVersion) : state?.version;
+  // A caller that passes no `state` gets one request with no memory: `serve` threads one
+  // through the stream, and a test that calls this directly usually wants exactly that.
+  const session = state ?? { version: null };
+  if (method === 'initialize') session.version = negotiated;
+  const v = negotiated ?? PROTOCOL_VERSION;
+
+  const reply = (value) => result(id, decorate(value, v, { packageVersion, tools }));
+
   switch (method) {
     case 'initialize':
-      return result(id, {
-        protocolVersion: negotiate(params?.protocolVersion),
-        capabilities: { tools: { listChanged: false } },
-        serverInfo: { ...SERVER_INFO, version: version ?? '0.0.0' },
-        instructions:
-          `Read-only. Every answer is JSON. \`${CLI} skills brief\` is the one to call first: it returns the pre-assembled set for a task, plus what it deliberately left out and why.`,
+      return reply({
+        protocolVersion: v,
+        capabilities: capabilities(tools),
+        // `serverInfo` stays in the body here even on 2026-07-28: a client that has just
+        // called a method the newest revision removed is by definition an older client,
+        // and the field is where it looks.
+        serverInfo: serverInfo(packageVersion),
+        instructions: INSTRUCTIONS,
       });
 
     case 'notifications/initialized':
     case 'initialized':
       return null;
 
+    // MUST, from 2026-07-28 on. Cheap, stateless, and the stdio way for a client that
+    // supports both shapes to find out which one it is talking to before it commits.
+    case 'server/discover':
+      return reply({
+        supportedVersions: [...SUPPORTED_VERSIONS],
+        capabilities: capabilities(tools),
+        instructions: INSTRUCTIONS,
+        ...(cacheable(v) ? LIST_CACHE : {}),
+      });
+
     case 'ping':
-      return result(id, {});
+      // Removed in 2026-07-28, and kept before it: a client that speaks an older
+      // revision and probes liveness gets an answer, and one that speaks the newest
+      // gets told the method is gone rather than a success it would read as support.
+      if (atLeast(v, PING_REMOVED_IN)) {
+        return error(id, RPC.METHOD, `ping was removed in ${PING_REMOVED_IN}; this session negotiated ${v}`);
+      }
+      return reply({});
 
     case 'tools/list':
-      return result(id, { tools: tools.map(describe) });
+      return reply({
+        tools: tools.map((t) => describe(t, v)),
+        ...(cacheable(v) ? LIST_CACHE : {}),
+      });
 
     case 'tools/call': {
       const name = params?.name;
@@ -85,12 +189,21 @@ export async function handle(request, tools, { version } = {}) {
       const args = params?.arguments ?? {};
       try {
         const payload = await tool.run(args);
-        return result(id, { content: [contentOf(payload)], isError: false });
-      } catch (failure) {
-        return result(id, {
-          content: [contentOf({ error: failure.message, remedy: failure.remedy ?? null })],
-          isError: true,
+        // Both blocks, always. `structuredContent` is what a client validates against
+        // `outputSchema` and what it can index; the text block is what a client that
+        // predates structured output reads. Emitting one without the other leaves half
+        // the clients guessing, which is the state this release was filed for.
+        return reply({
+          content: [contentOf(payload)],
+          structuredContent: payload,
+          isError: false,
         });
+      } catch (failure) {
+        // An error is a result too, and it carries the same two shapes: the remedy is
+        // the part a model needs to act on, and it has to survive in whichever block the
+        // client reads.
+        const payload = { error: failure.message, remedy: failure.remedy ?? null };
+        return reply({ content: [contentOf(payload)], structuredContent: payload, isError: true });
       }
     }
 
@@ -99,6 +212,22 @@ export async function handle(request, tools, { version } = {}) {
   }
 }
 
+const INSTRUCTIONS =
+  `Read-only. Every answer is JSON. \`${CLI} skills brief\` is the one to call first: it returns the pre-assembled set for a task, plus what it deliberately left out and why.`;
+
+function serverInfo(packageVersion) {
+  return { ...SERVER_INFO, version: packageVersion ?? '0.0.0' };
+}
+
+function capabilities(tools) {
+  return {
+    tools: { listChanged: false },
+    // Declared only when there is something to read. A capability with no method behind
+    // it is a promise a client will keep waiting on.
+    ...(tools.resources ? { resources: { listChanged: false, subscribe: false } } : {}),
+  };
+}
+
 /**
  * Echo the client's protocol version when it is one this server implements.
  *
@@ -107,16 +236,58 @@ export async function handle(request, tools, { version } = {}) {
  * fails loudly at the one place the client checks.
  */
 function negotiate(requested) {
-  const SUPPORTED = new Set([PROTOCOL_VERSION]);
-  return typeof requested === 'string' && SUPPORTED.has(requested) ? requested : PROTOCOL_VERSION;
+  return typeof requested === 'string' && SUPPORTED_VERSIONS.includes(requested)
+    ? requested
+    : PROTOCOL_VERSION;
 }
 
-function describe(tool) {
+/** Revision ordering. These are dates, so lexicographic is chronological - stated here
+ *  because "sort a version string" is the kind of helper that gets rewritten by someone
+ *  who thinks it is a number, and this one is right. */
+function atLeast(version, floor) {
+  return version >= floor;
+}
+
+/** 2026-07-28 requires `ttlMs` and `cacheScope` on list results; earlier ones ignore them. */
+function cacheable(version) {
+  return atLeast(version, '2026-07-28');
+}
+
+/**
+ * What the newest revision adds to every result.
+ *
+ * `resultType` is required from 2026-07-28 and is absent before it — clients on older
+ * revisions treat it as an unknown field, and clients MUST read a missing one as
+ * `complete`, so emitting it unconditionally is the compatible half and omitting it on
+ * the new revision is not. `_meta.serverInfo` is a SHOULD, and it is how a stateless
+ * client learns who it is talking to now that `initialize` is gone.
+ */
+function decorate(value, version, { packageVersion }) {
+  if (!atLeast(version, '2026-07-28')) return value;
   return {
+    resultType: 'complete',
+    ...value,
+    _meta: { [META.SERVER_INFO]: serverInfo(packageVersion) },
+  };
+}
+
+function describe(tool, version) {
+  const entry = {
     name: tool.name,
     description: tool.description,
     inputSchema: tool.inputSchema,
+    // Every tool here is a reader: none writes, and none writes twice. Saying so lets a
+    // client cache the answer and, where it offers, let the model call without a
+    // confirmation step. The declaration is per tool rather than global because the next
+    // tool this file gains may not be one.
+    annotations: { readOnlyHint: true, idempotentHint: true, ...(tool.annotations ?? {}) },
   };
+  // `outputSchema` exists in all three revisions, and a tool that declares its input
+  // shape but not its output shape leaves the client guessing what a successful answer
+  // looks like - which is the same defect as a returned value nothing can be checked
+  // against.
+  if (tool.outputSchema) entry.outputSchema = tool.outputSchema;
+  return entry;
 }
 
 /** Content is one text block. Bounded, and truncation is announced in the text itself -
@@ -146,15 +317,21 @@ function error(id, code, message) {
  * Lines are processed strictly in order. A server that interleaves responses would let a
  * client match the wrong answer to the wrong question, and the tools here are already
  * sequential and cheap - parallelising them would buy nothing and cost correctness.
+ *
+ * One `state` for the whole stream, holding the revision a client negotiated through
+ * `initialize`. That is the residue of a handshake the 2026-07-28 revision removed, kept
+ * only because a client on an older revision sends bare requests afterwards and expects
+ * the answers it agreed to.
  */
-export async function serve(tools, { input = process.stdin, output = process.stdout, version, onError } = {}) {
+export async function serve(tools, { input = process.stdin, output = process.stdout, packageVersion, onError } = {}) {
   const rl = createInterface({ input, crlfDelay: Infinity });
+  const state = { version: null };
   for await (const line of rl) {
     if (line.trim() === '') continue;
 
     let response;
     try {
-      response = await handle(JSON.parse(line), tools, { version });
+      response = await handle(JSON.parse(line), tools, { packageVersion, state });
     } catch (parseFailure) {
       response = error(null, RPC.PARSE, `invalid JSON: ${parseFailure.message}`);
     }

package/src/mcp/tools.mjs

@@ -19,7 +19,7 @@
 // cause by accident because the caller cannot see the size until it has paid for it.
 
 import { fingerprint } from '../resolve/fingerprint.mjs';
-import { loadRegistry, REGISTRY_PATH } from '../graph/load.mjs';
+import { loadRegistry } from '../graph/load.mjs';
 import { tokenize, rankSkills, closure, selectWithinBudget, scoreSkill, selectionVerdict, stackCompatible } from '../resolve/resolve.mjs';
 import { loadRules, select, checkTargets, provenanceDigest } from '../projection/project.mjs';
 import { loadDecisions, byId, citations } from '../decisions/index.mjs';
@@ -35,6 +35,283 @@ const GATE_KINDS = new Map(Object.entries(GATES).map(([name, g]) => [name, g.kin
 
 /** A schema with no required fields still needs the object declared. */
 const noArgs = { type: 'object', properties: {}, required: [] };
+
+/**
+ * Output schemas, one per tool, describing what a SUCCESSFUL call returns.
+ *
+ * Every one of these tools is a reader: none writes, and none writes twice. The
+ * annotations say so, and the schemas say what comes back — because a client that can
+ * validate an answer against a declared shape catches a wrong answer at the boundary,
+ * while one handed a bag of JSON has to trust that the tool meant it.
+ *
+ * Properties are required unless the payload can legitimately omit them: `error` is
+ * absent when there is none, `body` is null when there is none, and a schema that
+ * required the exception would describe a shape that never occurs. `additionalProperties`
+ * is left open, which is what the 2026-07-28 revision permits and what a reader wants:
+ * these payloads are data, and a new field from a future release should not make an
+ * older client's validation fail.
+ */
+/**
+ * The shape of a failure, exported because a client validating an answer needs it and
+ * because the test that checks every tool's answer needs it for the failures. Two
+ * copies of this schema would drift, and the copy that drifted would be the one nobody
+ * validates against - which is exactly how a remedy quietly stops being a string.
+ */
+export const ERROR_SHAPE = {
+  type: 'object',
+  properties: { error: { type: 'string' }, remedy: { type: ['string', 'null'] } },
+  required: ['error'],
+};
+
+const output = {
+  doctor: {
+    type: 'object',
+    properties: {
+      root: { type: 'string' },
+      workspace: {
+        type: 'object',
+        properties: {
+          // Null is the honest value for a repository that is not inside a workspace:
+          // there is no root to name, and naming the repository as one would be a claim
+          // about the reader's directory layout that nothing established.
+          root: { type: ['string', 'null'] },
+          source: { type: ['string', 'null'] },
+          detail: { type: ['string', 'null'] },
+        },
+        required: ['root', 'source'],
+      },
+      stack: { type: 'array', items: { type: 'string' } },
+      facts: { type: 'object', additionalProperties: { type: ['string', 'null'] } },
+      signals: { type: 'array', items: { type: 'string' } },
+      // One entry per signal, naming the file that proved it. The payload is a list of
+      // paths, not of records - `fingerprint` returns evidence as the paths themselves.
+      evidence: { type: 'array', items: { type: 'string' } },
+      manifest: { type: ['object', 'null'] },
+      error: { type: ['string', 'null'] },
+    },
+    required: ['root', 'workspace', 'stack', 'facts', 'signals', 'evidence'],
+  },
+  skills_index: {
+    type: 'object',
+    properties: {
+      skills: { type: 'number' },
+      totalBytes: { type: 'number' },
+      deferred: { type: 'array', items: { type: 'string' } },
+      workspace: { type: 'object' },
+      verified: { type: 'boolean' },
+      entries: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+            summary: { type: 'string' },
+            bytes: { type: 'number' },
+            stack: { type: 'array', items: { type: 'string' } },
+            deferred: { type: 'boolean' },
+          },
+          required: ['name', 'bytes'],
+        },
+      },
+    },
+    required: ['skills', 'totalBytes', 'entries'],
+  },
+  skills_brief: {
+    type: 'object',
+    properties: {
+      repo: {
+        type: 'object',
+        properties: {
+          root: { type: 'string' },
+          stack: { type: 'array', items: { type: 'string' } },
+          facts: { type: 'array', items: { type: 'string' } },
+        },
+        required: ['root', 'stack', 'facts'],
+      },
+      task: { type: ['string', 'null'] },
+      budget: { type: 'number' },
+      inlineBytes: { type: 'number' },
+      selected: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+            bytes: { type: 'number' },
+            summary: { type: 'string' },
+            why: { type: 'array', items: { type: 'string' } },
+          },
+          required: ['name', 'bytes', 'why'],
+        },
+      },
+      deferred: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: { name: { type: 'string' }, bytes: { type: 'number' }, reason: { type: 'string' } },
+          required: ['name', 'reason'],
+        },
+      },
+      notSelected: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: { name: { type: 'string' }, reason: { type: 'string' } },
+          required: ['name', 'reason'],
+        },
+      },
+    },
+    required: ['repo', 'budget', 'inlineBytes', 'selected', 'deferred', 'notSelected'],
+  },
+  skills_show: {
+    type: 'object',
+    properties: {
+      name: { type: 'string' },
+      summary: { type: 'string' },
+      bytes: { type: 'number' },
+      capabilities: { type: 'array', items: { type: 'string' } },
+      stack: { type: 'array', items: { type: 'string' } },
+      deferred: { type: 'boolean' },
+      source: { type: ['string', 'null'] },
+      readFrom: { type: 'string', enum: ['ok', 'empty', 'unavailable'] },
+      requires: { type: 'array', items: { type: 'string' } },
+      variants: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: { id: { type: 'string' }, stack: { type: 'array', items: { type: 'string' } }, bytes: { type: 'number' } },
+          required: ['id'],
+        },
+      },
+      maxBytes: { type: 'number' },
+      body: { type: ['string', 'null'] },
+    },
+    required: ['name', 'bytes', 'readFrom', 'requires', 'variants'],
+  },
+  skills_find: {
+    type: 'object',
+    properties: {
+      query: { type: 'string' },
+      results: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+            score: { type: 'number' },
+            summary: { type: 'string' },
+            why: { type: 'array', items: { type: 'string' } },
+          },
+          required: ['name', 'score', 'why'],
+        },
+      },
+    },
+    required: ['query', 'results'],
+  },
+  skills_why: {
+    type: 'object',
+    properties: {
+      name: { type: 'string' },
+      score: { type: 'number' },
+      compatible: { type: 'boolean' },
+      reasons: { type: 'array', items: { type: 'string' } },
+      repo: {
+        type: 'object',
+        properties: { root: { type: 'string' }, signals: { type: 'array', items: { type: 'string' } } },
+      },
+      task: { type: ['string', 'null'] },
+      pathsSeen: { type: 'array', items: { type: 'string' } },
+    },
+    required: ['name', 'score', 'compatible', 'reasons'],
+  },
+  rules_list: {
+    type: 'object',
+    properties: {
+      sha: { type: 'string' },
+      notes: { type: 'array', items: { type: 'string' } },
+      rules: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            id: { type: ['string', 'null'] },
+            title: { type: ['string', 'null'] },
+            // A profile may name one signal or several, and the frontmatter keeps both
+            // spellings. Describing only the list would make a conforming rule look
+            // broken.
+            applies: { anyOf: [{ type: 'array', items: { type: 'string' } }, { type: 'string' }] },
+            origin: { type: 'string' },
+            source: { type: 'string' },
+            bytes: { type: 'number' },
+            adrs: { type: 'array', items: { type: 'string' } },
+            error: { type: ['string', 'null'] },
+            selected: { type: 'boolean' },
+          },
+          required: ['source', 'bytes', 'selected'],
+        },
+      },
+    },
+    required: ['sha', 'rules'],
+  },
+  rules_why: {
+    type: 'object',
+    properties: {
+      direction: { type: 'string', enum: ['rule', 'decision'] },
+      id: { type: 'string' },
+      title: { type: ['string', 'null'] },
+      status: { type: 'string' },
+      source: { type: 'string' },
+      origin: { type: 'string' },
+      uncited: { type: 'boolean' },
+      readWith: { type: 'string' },
+      supersededBy: { type: ['string', 'null'] },
+      supersedes: { type: 'array', items: { type: 'string' } },
+      // A decision record may be partially superseded; the record carries the list of
+      // what it replaced, so this is a list and not a flag.
+      partial: { type: ['boolean', 'array'] },
+      decisions: { type: 'array', items: { type: 'object' } },
+      rules: { type: 'array', items: { type: 'string' } },
+    },
+    required: ['direction', 'id'],
+  },
+  check: {
+    type: 'object',
+    properties: {
+      root: { type: 'string' },
+      ok: { type: 'boolean' },
+      findings: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            file: { type: 'string' },
+            status: { type: 'string' },
+            detail: { type: ['string', 'null'] },
+            remedy: { type: ['string', 'null'] },
+          },
+          required: ['file', 'status'],
+        },
+      },
+    },
+    required: ['root', 'ok', 'findings'],
+  },
+  compare: {
+    type: 'object',
+    properties: {
+      root: { type: 'string' },
+      shape: { type: 'string', enum: ['repo', 'workspace'] },
+      expectedSha: { type: 'string' },
+      summary: { type: 'object' },
+      repos: { type: 'array', items: { type: 'object' } },
+      worktrees: { type: 'array', items: { type: 'object' } },
+      directories: { type: 'array', items: { type: 'string' } },
+    },
+    required: ['root', 'shape', 'expectedSha', 'summary', 'repos'],
+  },
+  /** The shape of every tool failure, which is a result and not a protocol error. */
+  error: ERROR_SHAPE,
+};
+
 const rootArg = {
   type: 'object',
   properties: { root: { type: 'string', description: 'repository root; defaults to the editor cwd' } },
@@ -46,7 +323,7 @@ function rootOf(args) {
 }
 
 async function registry(args) {
-  const { registry, errors, ok, verified, workspace } = await loadRegistry(REGISTRY_PATH, args ?? {});
+  const { registry, errors, ok, verified, workspace } = await loadRegistry(null, args ?? {});
   if (!ok) {
     throw Object.assign(new Error(errors[0]), {
       remedy: `run: ${CLI} graph lint`,
@@ -57,6 +334,7 @@ async function registry(args) {
 
 export const TOOLS = [
   {
+    outputSchema: output.doctor,
     name: 'doctor',
     description:
       'Classify a repository: its stack tags, the emitted facts with the file that proved each, and whether a simt-dev manifest is present. Call this first when you do not yet know what a repo is.',
@@ -79,6 +357,7 @@ export const TOOLS = [
   },
 
   {
+    outputSchema: output.skills_index,
     name: 'skills_index',
     description:
       'The full skill catalogue: every skill with its summary, size, stack tags and whether it is deferred. Cheap enough to always afford, and the fallback when brief returns nothing useful.',
@@ -99,6 +378,7 @@ export const TOOLS = [
   },
 
   {
+    outputSchema: output.skills_brief,
     name: 'skills_brief',
     description:
       'THE entry point. Resolve the skill set for a task in a repository. Returns what was selected, why each was selected, what was deferred, and what was NOT selected with the reason - the last part matters, because it is what lets you override the resolver instead of guessing at it.',
@@ -165,6 +445,7 @@ export const TOOLS = [
   },
 
   {
+    outputSchema: output.skills_show,
     name: 'skills_show',
     description: 'One skill body, with the metadata needed to decide whether to trust it: source path, which of the two locations it was read from, and its cited decisions.',
     inputSchema: {
@@ -206,6 +487,7 @@ export const TOOLS = [
   },
 
   {
+    outputSchema: output.skills_find,
     name: 'skills_find',
     description: 'Raw search across capability, keyword and summary. Use when skills_brief has nothing and you suspect a skill exists.',
     inputSchema: {
@@ -230,6 +512,7 @@ export const TOOLS = [
   },
 
   {
+    outputSchema: output.skills_why,
     name: 'skills_why',
     description:
       'The signal chain for one skill in one repository: its score, the reasons behind it, whether the stack gate admits it at all, and what it would take to make it selected.',
@@ -263,6 +546,7 @@ export const TOOLS = [
   },
 
   {
+    outputSchema: output.rules_list,
     name: 'rules_list',
     description:
       'The rule catalogue, and which rules a given repository actually receives. Pass `root` to get the selection rather than just the catalogue.',
@@ -300,9 +584,10 @@ export const TOOLS = [
   },
 
   {
+    outputSchema: output.rules_why,
     name: 'rules_why',
     description:
-      'Why a rule exists. Give a rule id for the decisions that settled it and whether each is still in force, or an ADR id for the rules that decision restsates. A rule citing no decision reports that - it is a finding, not an empty answer.',
+      'Why a rule exists. Give a rule id for the decisions that settled it and whether each is still in force, or an ADR id for the rules that decision repeats. A rule citing no decision reports that - it is a finding, not an empty answer.',
     inputSchema: {
       type: 'object',
       properties: { what: { type: 'string', description: 'a rule id or ADR-NNN' } },
@@ -355,6 +640,7 @@ export const TOOLS = [
   },
 
   {
+    outputSchema: output.check,
     name: 'check',
     description:
       'The gate for one repository: is its generated region current, unmanaged, drifted or malformed, and does any rule file lack an id. Read-only - it never repairs.',
@@ -371,6 +657,7 @@ export const TOOLS = [
   },
 
   {
+    outputSchema: output.compare,
     name: 'compare',
     description:
       'The organisation-wide matrix: every repository under the root, its adoption, region state, pinned simt-dev SHA, hook routing and declared gates, plus the problems found. This is the command that replaces reconstructing the estate by hand.',