argsbarg 7.1.1 → 7.1.3

package/src/config/validate.ts

@@ -5,6 +5,7 @@ CLI value coercion for configure set remains here (comma-separated arrays, boole
 
 import { format as jsonSchemaFormats, type Schema, type SchemaDraft, Validator } from "@cfworker/json-schema";
 import { parseCommaList, parseDate, parseDateTime, validateCommaList } from "../core/formats.ts";
+import { decodeJsonPointerSegment, resolveJsonPointer } from "../core/json-pointer.ts";
 import { isFrameworkConfigKey } from "./bindings.ts";
 
 type JsonSchema = Record<string, unknown>;
@@ -72,15 +73,360 @@ function formatInstancePath(instanceLocation: string): string {
   return instanceLocation;
 }
 
-function formatValidationErrors(errors: { instanceLocation: string; error: string }[]): string[] {
-  return errors.map(({ instanceLocation, error }) => {
-    const path = formatInstancePath(instanceLocation);
-    return `${path}: ${error}`;
+/** cfworker keywords that only wrap a deeper, more specific failure — dropped when one survives underneath. */
+const WRAPPER_KEYWORDS = new Set([
+  "$ref",
+  "$recursiveRef",
+  "properties",
+  "items",
+  "prefixItems",
+  "additionalItems",
+  "allOf",
+  "anyOf",
+  "oneOf",
+]);
+
+/** Raw cfworker validation error (the subset of `OutputUnit` this module reads). */
+interface RawError {
+  instanceLocation: string;
+  keyword: string;
+  keywordLocation: string;
+  error: string;
+}
+
+/** Walks a `keywordLocation` JSON Pointer against `root`, following `$ref` segments through `resolveJsonPointer`. */
+function schemaAtPointer(root: JsonSchema, keywordLocation: string): JsonSchema | unknown[] | undefined {
+  if (!keywordLocation.startsWith("#")) {
+    return undefined;
+  }
+  const segments = keywordLocation
+    .slice(1)
+    .split("/")
+    .filter((segment) => segment.length > 0)
+    .map(decodeJsonPointerSegment);
+  let current: unknown = root;
+  for (const segment of segments) {
+    if (segment === "$ref") {
+      if (typeof current !== "object" || current === null || Array.isArray(current)) {
+        return undefined;
+      }
+      const ref = (current as JsonSchema).$ref;
+      if (typeof ref !== "string") {
+        return undefined;
+      }
+      current = resolveJsonPointer(root, ref);
+      continue;
+    }
+    if (typeof current !== "object" || current === null) {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return current as JsonSchema | unknown[] | undefined;
+}
+
+/** Walks an `instanceLocation` JSON Pointer against the validated payload. */
+function instanceAtPointer(data: unknown, instanceLocation: string): unknown {
+  if (!instanceLocation.startsWith("#")) {
+    return undefined;
+  }
+  const segments = instanceLocation
+    .slice(1)
+    .split("/")
+    .filter((segment) => segment.length > 0)
+    .map(decodeJsonPointerSegment);
+  let current: unknown = data;
+  for (const segment of segments) {
+    if (typeof current !== "object" || current === null) {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return current;
+}
+
+/** The parent JSON Pointer of `location` (its last `/segment` removed), or `undefined` at the root. */
+function parentPointer(location: string): string | undefined {
+  const idx = location.lastIndexOf("/");
+  if (idx < 0) {
+    return undefined;
+  }
+  return location.slice(0, idx) || "#";
+}
+
+/** A discriminator property common to every branch, with each branch's set of accepted string values. */
+interface UnionDiscriminator {
+  prop: string;
+  valuesByBranch: string[][];
+}
+
+/**
+ * Finds a property present in every branch as a string `const` or all-string `enum`, whose value sets are
+ * pairwise disjoint across branches. Prefers `kind`, then `type`, then the alphabetically first eligible name.
+ * Each branch is resolved through a bare `$ref` first — a schema built with a `definitions`/`$defs` map
+ * (e.g. ts-json-schema-generator output) typically writes `anyOf: [{ $ref: "#/definitions/A" }, …]` rather
+ * than inlining each branch, so without this every branch here would otherwise look property-less.
+ */
+function unionDiscriminator(branches: unknown[], root: JsonSchema): UnionDiscriminator | undefined {
+  const resolvedBranches = branches.map((b) => {
+    if (typeof b !== "object" || b === null || Array.isArray(b)) {
+      return b;
+    }
+    const ref = (b as JsonSchema).$ref;
+    if (typeof ref !== "string") {
+      return b;
+    }
+    return resolveJsonPointer(root, ref) ?? b;
   });
+  const objectBranches = resolvedBranches.filter(
+    (b): b is JsonSchema => typeof b === "object" && b !== null && !Array.isArray(b),
+  );
+  if (objectBranches.length === 0 || objectBranches.length !== resolvedBranches.length) {
+    return undefined;
+  }
+
+  const branchValuesFor = (prop: string): string[][] | undefined => {
+    const perBranch: string[][] = [];
+    for (const branch of objectBranches) {
+      const props = branch.properties;
+      const propSchema =
+        typeof props === "object" && props !== null && !Array.isArray(props)
+          ? (props as Record<string, JsonSchema>)[prop]
+          : undefined;
+      if (!propSchema || typeof propSchema !== "object") {
+        return undefined;
+      }
+      let values: string[] | undefined;
+      if (typeof propSchema.const === "string") {
+        values = [propSchema.const];
+      } else if (Array.isArray(propSchema.enum) && propSchema.enum.every((v) => typeof v === "string")) {
+        values = propSchema.enum as string[];
+      }
+      if (!values || values.length === 0) {
+        return undefined;
+      }
+      perBranch.push(values);
+    }
+    const seen = new Set<string>();
+    for (const values of perBranch) {
+      for (const v of values) {
+        if (seen.has(v)) return undefined;
+        seen.add(v);
+      }
+    }
+    return perBranch;
+  };
+
+  const candidateProps = new Set<string>();
+  for (const branch of objectBranches) {
+    const props = branch.properties;
+    if (typeof props === "object" && props !== null && !Array.isArray(props)) {
+      for (const key of Object.keys(props)) candidateProps.add(key);
+    }
+  }
+
+  const eligible: string[] = [];
+  for (const prop of candidateProps) {
+    if (branchValuesFor(prop)) eligible.push(prop);
+  }
+  if (eligible.length === 0) {
+    return undefined;
+  }
+  const prop = eligible.includes("kind") ? "kind" : eligible.includes("type") ? "type" : [...eligible].sort()[0];
+  const valuesByBranch = prop === undefined ? undefined : branchValuesFor(prop);
+  if (prop === undefined || valuesByBranch === undefined) {
+    return undefined;
+  }
+  return { prop, valuesByBranch };
+}
+
+/** Sorted, comma-joined, unquoted list of values for error messages. */
+function joinSorted(values: Iterable<string>): string {
+  return [...new Set(values)].sort().join(", ");
+}
+
+/** Rewrites a single surviving cfworker error message into a terser, more actionable form. */
+function rewriteErrorMessage(err: RawError, root: JsonSchema): string {
+  const additionalPropsMatch = /^Property "(.+)" does not match additional properties schema\.$/.exec(err.error);
+  if (additionalPropsMatch) {
+    const name = additionalPropsMatch[1] ?? "";
+    const parentLoc = parentPointer(err.keywordLocation);
+    const parentSchema = parentLoc ? schemaAtPointer(root, parentLoc) : undefined;
+    const props =
+      parentSchema && typeof parentSchema === "object" && !Array.isArray(parentSchema)
+        ? (parentSchema as JsonSchema).properties
+        : undefined;
+    const keys = props && typeof props === "object" && !Array.isArray(props) ? Object.keys(props as JsonSchema) : [];
+    const allowed = keys.sort().slice(0, 20).join(", ");
+    return `unknown property "${name}"${allowed ? ` (allowed: ${allowed})` : ""}`;
+  }
+
+  const requiredMatch = /^Instance does not have required property "(.+)"\.$/.exec(err.error);
+  if (requiredMatch) {
+    return `missing required property "${requiredMatch[1]}"`;
+  }
+
+  const enumMatch = /^Instance does not match any of (\[.*\])\.$/.exec(err.error);
+  if (enumMatch) {
+    try {
+      const values = JSON.parse(enumMatch[1] ?? "") as unknown[];
+      return `must be one of: ${values.map((v) => String(v)).join(", ")}`;
+    } catch {
+      // fall through to the raw message
+    }
+  }
+
+  const typeMatch = /^Instance type "(.+)" is invalid\. Expected "(.+)"\.$/.exec(err.error);
+  if (typeMatch) {
+    return `must be ${typeMatch[2]} (got ${typeMatch[1]})`;
+  }
+
+  return err.error;
 }
 
-function decodeJsonPointerSegment(segment: string): string {
-  return segment.replace(/~1/g, "/").replace(/~0/g, "~");
+/** Maximum number of narrowed errors reported before collapsing the remainder into a count. */
+const MAX_NARROWED_ERRORS = 10;
+
+/**
+ * Post-processes raw cfworker errors: for each `anyOf`/`oneOf` failure with a discriminated union, keeps only
+ * the branch matching the instance's discriminator value (or reports one synthetic error naming what a valid
+ * discriminator looks like); drops wrapper keywords once a more specific error survives under them; drops the
+ * `additionalProperties`+`false` pair cfworker emits even for properties that are legitimately declared; then
+ * rewrites the remaining messages into terser, more actionable text.
+ */
+function narrowUnionErrors(errors: RawError[], root: JsonSchema, data: unknown): string[] {
+  const dropped = new Set<RawError>();
+  const synthetic: Array<{ instanceLocation: string; message: string }> = [];
+  // Locations of anyOf/oneOf errors resolved into a synthetic message rather than a kept branch — an ancestor
+  // wrapper (e.g. the `$ref` pointing at that anyOf, for the same instance) counts as "resolved deeper" too.
+  const syntheticReplacedLocations: Array<{ instanceLocation: string; keywordLocation: string }> = [];
+
+  // Stage 1: discriminated-union narrowing.
+  for (const err of errors) {
+    if (err.keyword !== "anyOf" && err.keyword !== "oneOf") continue;
+    const branches = schemaAtPointer(root, err.keywordLocation);
+    if (!Array.isArray(branches)) continue;
+    const discriminator = unionDiscriminator(branches, root);
+    if (!discriminator) continue;
+
+    // Array items reuse one schema, so keywordLocation repeats verbatim across indices — scope by
+    // instanceLocation too, or narrowing one item would wrongly swallow every other item's errors.
+    const under = errors.filter(
+      (e) =>
+        e !== err &&
+        e.keywordLocation.startsWith(`${err.keywordLocation}/`) &&
+        (e.instanceLocation === err.instanceLocation || e.instanceLocation.startsWith(`${err.instanceLocation}/`)),
+    );
+    const validValues = discriminator.valuesByBranch.flat();
+    const instance = instanceAtPointer(data, err.instanceLocation);
+
+    if (typeof instance !== "object" || instance === null || Array.isArray(instance)) {
+      dropped.add(err);
+      for (const e of under) dropped.add(e);
+      syntheticReplacedLocations.push({ instanceLocation: err.instanceLocation, keywordLocation: err.keywordLocation });
+      synthetic.push({
+        instanceLocation: err.instanceLocation,
+        message: `expected an object with "${discriminator.prop}" (one of: ${joinSorted(validValues)})`,
+      });
+      continue;
+    }
+
+    const propValue = (instance as Record<string, unknown>)[discriminator.prop];
+    if (propValue === undefined) {
+      dropped.add(err);
+      for (const e of under) dropped.add(e);
+      syntheticReplacedLocations.push({ instanceLocation: err.instanceLocation, keywordLocation: err.keywordLocation });
+      synthetic.push({
+        instanceLocation: err.instanceLocation,
+        message: `missing "${discriminator.prop}" (expected one of: ${joinSorted(validValues)})`,
+      });
+      continue;
+    }
+
+    const branchIndex = discriminator.valuesByBranch.findIndex(
+      (values) => typeof propValue === "string" && values.includes(propValue),
+    );
+    if (branchIndex < 0) {
+      dropped.add(err);
+      for (const e of under) dropped.add(e);
+      syntheticReplacedLocations.push({ instanceLocation: err.instanceLocation, keywordLocation: err.keywordLocation });
+      synthetic.push({
+        instanceLocation: `${err.instanceLocation}/${discriminator.prop}`,
+        message: `unknown ${discriminator.prop} "${String(propValue)}" (expected one of: ${joinSorted(validValues)})`,
+      });
+      continue;
+    }
+
+    const keepPrefix = `${err.keywordLocation}/${branchIndex}`;
+    dropped.add(err);
+    for (const e of under) {
+      if (e.keywordLocation === keepPrefix || e.keywordLocation.startsWith(`${keepPrefix}/`)) continue;
+      dropped.add(e);
+    }
+  }
+
+  // Stage 2: drop wrapper keywords once a more specific error survives under them, or once a descendant anyOf/oneOf
+  // was resolved into a synthetic message instead (which leaves no raw descendant error to detect otherwise).
+  const survivingAfterStage1 = errors.filter((e) => !dropped.has(e));
+  const nestsUnder = (candidateInstance: string, wrapperInstance: string) =>
+    candidateInstance === wrapperInstance || candidateInstance.startsWith(`${wrapperInstance}/`);
+  for (const err of survivingAfterStage1) {
+    if (!WRAPPER_KEYWORDS.has(err.keyword)) continue;
+    const prefix = `${err.keywordLocation}/`;
+    // Array items reuse one schema, so a wrapper's keywordLocation repeats across indices — scope by
+    // instanceLocation too, or one index's surviving error would mask another index's real problem.
+    const hasDeeper = survivingAfterStage1.some(
+      (other) =>
+        other !== err &&
+        !dropped.has(other) &&
+        other.keywordLocation.startsWith(prefix) &&
+        nestsUnder(other.instanceLocation, err.instanceLocation),
+    );
+    const hasSyntheticDeeper = syntheticReplacedLocations.some(
+      (s) => s.keywordLocation.startsWith(prefix) && nestsUnder(s.instanceLocation, err.instanceLocation),
+    );
+    if (hasDeeper || hasSyntheticDeeper) dropped.add(err);
+  }
+
+  // Stage 3: drop the additionalProperties+false pair cfworker emits for properties actually in `properties`.
+  const additionalPropsInstanceLocations = new Set(
+    errors.filter((e) => e.keyword === "additionalProperties").map((e) => e.instanceLocation),
+  );
+  for (const err of errors) {
+    if (dropped.has(err)) continue;
+    if (err.keyword === "additionalProperties") {
+      const name = /^Property "(.+)" does not match additional properties schema\.$/.exec(err.error)?.[1];
+      const parentLoc = parentPointer(err.keywordLocation);
+      const parentSchema = parentLoc ? schemaAtPointer(root, parentLoc) : undefined;
+      const props =
+        name !== undefined && parentSchema && typeof parentSchema === "object" && !Array.isArray(parentSchema)
+          ? (parentSchema as JsonSchema).properties
+          : undefined;
+      const declared =
+        name !== undefined && props && typeof props === "object" && !Array.isArray(props)
+          ? Object.hasOwn(props as JsonSchema, name)
+          : false;
+      if (declared) dropped.add(err);
+      continue;
+    }
+    if (err.keyword === "false") {
+      const parent = parentPointer(err.instanceLocation);
+      if (parent !== undefined && additionalPropsInstanceLocations.has(parent)) {
+        dropped.add(err);
+      }
+    }
+  }
+
+  // Stage 4: rewrite surviving messages, merge in synthetic ones, cap the total.
+  const kept = errors
+    .filter((e) => !dropped.has(e))
+    .map((e) => `${formatInstancePath(e.instanceLocation)}: ${rewriteErrorMessage(e, root)}`);
+  const syntheticFormatted = synthetic.map((s) => `${formatInstancePath(s.instanceLocation)}: ${s.message}`);
+  const all = [...syntheticFormatted, ...kept];
+  if (all.length <= MAX_NARROWED_ERRORS) {
+    return all;
+  }
+  return [...all.slice(0, MAX_NARROWED_ERRORS), `…and ${all.length - MAX_NARROWED_ERRORS} more errors`];
 }
 
 /** Map a schema `$schema` URI to the @cfworker/json-schema draft (defaults to Draft-07). */
@@ -105,25 +451,6 @@ export function resolveSchemaDraft(schema: JsonSchema): SchemaDraft {
   return "7";
 }
 
-function resolveJsonPointer(root: JsonSchema, ref: string): unknown {
-  if (!ref.startsWith("#/")) {
-    return undefined;
-  }
-  const segments = ref
-    .slice(2)
-    .split("/")
-    .filter((segment) => segment.length > 0)
-    .map(decodeJsonPointerSegment);
-  let current: unknown = root;
-  for (const segment of segments) {
-    if (typeof current !== "object" || current === null || Array.isArray(current)) {
-      return undefined;
-    }
-    current = (current as Record<string, unknown>)[segment];
-  }
-  return current;
-}
-
 function attachRootCompanionSchemas(validator: Validator, root: JsonSchema, active: JsonSchema): void {
   if (active === root) {
     return;
@@ -170,7 +497,7 @@ function validateInstance(
   if (result.valid) {
     return { valid: true, errors: [] };
   }
-  return { valid: false, errors: formatValidationErrors(result.errors) };
+  return { valid: false, errors: narrowUnionErrors(result.errors as RawError[], root, payload) };
 }
 
 function validateAgainstSchema(data: unknown, rootSchema: JsonSchema, partial: boolean): ValidateResult {

package/src/core/document-leaf.test.ts

@@ -180,6 +180,59 @@ describe("kind: document leaf", () => {
     expect(result.kind).toBe("error");
     expect(result.errorMsg).toContain("Document input must be a JSON or YAML object");
   });
+
+  /** Tests that a discriminated-union inputSchema surfaces only the matching branch's narrowed error. */
+  test("invoke surfaces a narrowed discriminated-union error end to end", async () => {
+    const stepSchema = {
+      $schema: "http://json-schema.org/draft-07/schema#",
+      type: "object",
+      properties: { steps: { type: "array", items: { $ref: "#/definitions/Step" } } },
+      required: ["steps"],
+      additionalProperties: false,
+      definitions: {
+        Step: {
+          anyOf: [
+            {
+              type: "object",
+              properties: { kind: { const: "alpha" }, title: { type: "string" } },
+              required: ["kind", "title"],
+              additionalProperties: false,
+            },
+            {
+              type: "object",
+              properties: { kind: { enum: ["beta", "bravo"] }, count: { type: "number" } },
+              required: ["kind"],
+              additionalProperties: false,
+            },
+            {
+              type: "object",
+              properties: { kind: { const: "gamma" }, flag: { type: "boolean" } },
+              required: ["kind"],
+              additionalProperties: false,
+            },
+          ],
+        },
+      },
+    } as const;
+    const program = {
+      key: "steptest",
+      version: "1.0.0",
+      description: "steps test",
+      commands: [
+        {
+          key: "run",
+          description: "run",
+          kind: "document",
+          inputSchema: stepSchema,
+          handler: (ctx) => ctx.inputsAs(),
+        },
+      ],
+    } satisfies CliProgram;
+    const cli = new Cli(program);
+    const result = await cli.invoke(["run", JSON.stringify({ steps: [{ kind: "alfa" }] })], { invocation: "cli" });
+    expect(result.kind).toBe("error");
+    expect(result.errorMsg).toBe('steps.0.kind: unknown kind "alfa" (expected one of: alpha, beta, bravo, gamma)');
+  });
 });
 
 /** Tests for parseDocumentText helper function. */

package/src/core/json-pointer.ts

@@ -0,0 +1,46 @@
+/*
+Same-document JSON Pointer resolution for JSON Schema `$ref` values (`#/definitions/Foo`).
+Shared by schemagen root hoisting, MCP tool schema checks, config validation, and OpenAPI dereferencing.
+*/
+
+/**
+ * Decodes one JSON Pointer segment: URI percent-escapes first (ts-json-schema-generator writes
+ * `#/definitions/Box%3Cstring%3E`), then the `~1` → `/` and `~0` → `~` pointer escapes.
+ */
+export function decodeJsonPointerSegment(
+  /** Raw segment between `/` separators. */
+  segment: string,
+): string {
+  let decoded = segment;
+  try {
+    decoded = decodeURIComponent(segment);
+  } catch {
+    // Malformed percent-escape: fall back to the raw segment.
+  }
+  return decoded.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+/** Resolves a same-document JSON Pointer (`#/definitions/Foo`) against `root`; `undefined` when it does not resolve. */
+export function resolveJsonPointer(
+  /** Document the pointer is resolved against (the schema root). */
+  root: unknown,
+  /** `$ref` value; only `#/…` pointers are resolved. */
+  ref: string,
+): unknown {
+  if (!ref.startsWith("#/")) {
+    return undefined;
+  }
+  const segments = ref
+    .slice(2)
+    .split("/")
+    .filter((segment) => segment.length > 0)
+    .map(decodeJsonPointerSegment);
+  let current: unknown = root;
+  for (const segment of segments) {
+    if (typeof current !== "object" || current === null || Array.isArray(current)) {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return current;
+}

package/src/core/types.ts

@@ -187,6 +187,13 @@ export interface CliMcpBundleConfig {
 export interface CliMcpServerConfig {
   /** When `true`, enables the `mcp` built-in and MCP stdio server. */
   enabled: boolean;
+  /**
+   * Returned as `initialize.result.instructions`. Claude Code adds it to the system prompt of every
+   * session; Cursor writes it to `mcps/<server>/INSTRUCTIONS.md`. Both cases cost context whether or
+   * not the agent ends up using this server, so keep it to a one- or two-line pointer (e.g. when to
+   * reach for this tool, and to read the accompanying skill first) rather than usage documentation.
+   */
+  instructions?: string;
   /** MCP error response defaults. */
   errors?: CliMcpServerErrorsConfig;
   /** Observe-only hooks for JSON-RPC messages. */
@@ -212,6 +219,25 @@ export interface CliMcpServerConfig {
   resources?: CliMcpResource[];
   /** Optional MCP Bundle (`.mcpb`) metadata for `mcp bundle`. */
   bundle?: CliMcpBundleConfig;
+  /** Overrides the default startup size warnings (see {@link CliMcpSizeLimits}). */
+  sizeLimits?: CliMcpSizeLimits;
+}
+
+/**
+ * Size limits for one MCP tool's `description` and pretty-printed definition, and for `instructions`.
+ * Set a field to `false` to disable that check. Defaults come from two client behaviors observed in the
+ * wild, not from the MCP spec itself, so they may need retuning as those clients change:
+ * Claude Code truncates a tool's `description` past `descriptionChars`; Cursor syncs each tool's full
+ * definition (`{name, description, inputSchema, outputSchema}`, pretty-printed) to a file under
+ * `mcps/<server>/tools/<tool>.json` and its agent reads that file in chunks of at most `definitionBytes`
+ * bytes or `definitionLines` lines, whichever comes first — a tool at or beyond either limit is read
+ * incompletely on the first pass.
+ */
+export interface CliMcpSizeLimits {
+  definitionBytes?: number | false;
+  definitionLines?: number | false;
+  descriptionChars?: number | false;
+  instructionsChars?: number | false;
 }
 
 /** JSON Schema for structured error responses (OpenAPI + HTTP/MCP error bodies). */
@@ -334,6 +360,13 @@ export interface CliMcpToolConfig {
    * Default: auto-generated from command path and description.
    */
   description?: string;
+  /**
+   * Overrides the leaf's `notes` in the MCP description only — CLI help always shows `notes` unchanged.
+   * `false` omits notes from the MCP description entirely; a string replaces them. Omit to use `notes` as
+   * given. Useful when a note only makes sense with `--help` in front of it (a CLI-only workflow tip), or
+   * when the full CLI notes would push a definition past a size limit (see {@link CliMcpSizeLimits}).
+   */
+  notes?: string | false;
 }
 
 /**

package/src/core/validate.ts

@@ -5,9 +5,10 @@ This module validates CLI schemas before execution.
 import { reservedDocsTopicResourceUris } from "../docs/mcp-resources.ts";
 import { DOCS_BUILTIN_TOPIC_KEYS, docsEnabled } from "../docs/resolve.ts";
 import { HTTP_RESERVED_TOP_LEVEL_SEGMENTS } from "../http/paths.ts";
-import { resolveMcpSchemaUri } from "../mcp/tools.ts";
+import { collectMcpTools, resolveMcpSchemaUri } from "../mcp/tools.ts";
 import { reservedCommandNames, resolveCapabilities } from "../runtime/capabilities.ts";
 import { validateFormatValue } from "./formats.ts";
+import { resolveJsonPointer } from "./json-pointer.ts";
 import {
   type CliLeaf,
   type CliNode,
@@ -162,6 +163,10 @@ export function cliValidateProgram(program: CliProgram): void {
     throw new CliSchemaValidationError("mcpServer requires enabled: true; omit mcpServer to disable MCP");
   }
 
+  if (program.mcpServer?.instructions !== undefined && program.mcpServer.instructions.trim().length === 0) {
+    throw new CliSchemaValidationError("mcpServer.instructions must not be empty; omit it instead");
+  }
+
   if (program.httpServer !== undefined && program.httpServer.enabled !== true) {
     throw new CliSchemaValidationError("httpServer requires enabled: true; omit httpServer to disable HTTP API");
   }
@@ -192,6 +197,68 @@ export function cliValidateProgram(program: CliProgram): void {
   }
 
   walkNode(program, program, true);
+
+  if (caps.mcp) {
+    validateMcpToolSchemas(program);
+  }
+}
+
+/** Keywords whose values are instance data, not subschemas; a `$ref` string inside them is not a reference. */
+const SCHEMA_DATA_KEYWORDS = new Set(["const", "default", "enum", "examples"]);
+
+/** Collects every `$ref` string in a schema (skipping instance-data keywords). */
+function collectSchemaRefs(
+  /** Schema fragment to walk. */
+  node: unknown,
+  /** Accumulator for found `$ref` values. */
+  out: string[],
+): string[] {
+  if (Array.isArray(node)) {
+    for (const item of node) {
+      collectSchemaRefs(item, out);
+    }
+  } else if (typeof node === "object" && node !== null) {
+    for (const [key, value] of Object.entries(node)) {
+      if (key === "$ref" && typeof value === "string") {
+        out.push(value);
+      } else if (!SCHEMA_DATA_KEYWORDS.has(key)) {
+        collectSchemaRefs(value, out);
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Checks the schemas MCP clients will see (after object-root wrapping in `collectMcpTools`):
+ * every local `$ref` must resolve, and wrapped schemas cannot use `$ref: "#"` (it would point at the wrapper).
+ */
+function validateMcpToolSchemas(
+  /** Program with `mcpServer.enabled`. */
+  program: CliProgram,
+): void {
+  for (const tool of collectMcpTools(program)) {
+    const schemas = [
+      { label: "inputSchema", schema: tool.inputSchema, wrapped: tool.inputWrapped },
+      { label: "outputSchema", schema: tool.outputSchema, wrapped: tool.outputWrapped },
+    ];
+    for (const { label, schema, wrapped } of schemas) {
+      if (schema === undefined) {
+        continue;
+      }
+      for (const ref of collectSchemaRefs(schema, [])) {
+        if (ref === "#" && wrapped) {
+          throw new CliSchemaValidationError(
+            `MCP tool "${tool.name}" ${label} uses $ref "#" but its root is not type "object", so MCP wraps it; ` +
+              "reference a named definition instead",
+          );
+        }
+        if (ref.startsWith("#/") && resolveJsonPointer(schema, ref) === undefined) {
+          throw new CliSchemaValidationError(`MCP tool "${tool.name}" ${label} has an unresolved $ref: ${ref}`);
+        }
+      }
+    }
+  }
 }
 
 const PARAM_ROUTER_KEY = /^:[a-zA-Z][a-zA-Z0-9_]*$/;

package/src/docs/docs.test.ts

@@ -280,6 +280,13 @@ test("generateMcpGuide includes schema URI and .agents install", () => {
   expect(guide).not.toContain("OpenAI Codex");
 });
 
+test("generateMcpGuide includes a Tool sizes table", () => {
+  const guide = generateMcpGuide(docsFixture(true));
+  expect(guide).toContain("## Tool sizes");
+  expect(guide).toContain("| Tool | Description (chars) | Definition (bytes) | Definition (lines) | Status |");
+  expect(guide).toMatch(/\| `run` \| \d+ \| \d+ \| \d+ \| ok \|/);
+});
+
 test("docs --save writes topic file", async () => {
   const result = await new Cli(docsFixture()).invoke(["docs", "readme", "--save"]);
   expect(result.exitCode).toBe(0);