stitchkit 0.34.0 → 0.35.0

package/dist/cli.js

@@ -4,7 +4,7 @@ import {
   emitResult,
   parseCliArgs,
   pollUntilDone
-} from "./index-jr8vf7g8.js";
+} from "./index-bfabej0h.js";
 import"./index-0ed3bx43.js";
 import"./index-x3fcszf8.js";
 import"./index-enc7t99e.js";

package/dist/{index-jr8vf7g8.js → index-bfabej0h.js}

@@ -229,30 +229,97 @@ function stripAnnotations(node) {
       stripAnnotations(value);
   }
 }
-function hasChecks(schema) {
+function hasInvisibleConstraint(schema) {
   if (!(schema instanceof z3.ZodType))
     return false;
   const def = schema.def;
-  if (isRecord(def) && Array.isArray(def.checks) && def.checks.length > 0)
+  if (isRecord(def) && def.type !== "unknown" && def.type !== "any") {
+    if (normalizedJson(schema) === "{}")
+      return true;
+  }
+  if (schema instanceof z3.ZodCatch)
+    return true;
+  if (isRecord(def) && def.coerce === true)
     return true;
+  if (isRecord(def) && Array.isArray(def.checks)) {
+    for (const check of def.checks) {
+      if (isInvisibleCheck(check))
+        return true;
+    }
+  }
   if (schema instanceof z3.ZodOptional || schema instanceof z3.ZodNullable || schema instanceof z3.ZodDefault) {
-    return hasChecks(schema.unwrap());
+    return hasInvisibleConstraint(schema.unwrap());
   }
   if (schema instanceof z3.ZodPipe)
-    return hasChecks(schema.def.in) || hasChecks(schema.def.out);
-  if (schema instanceof z3.ZodObject)
-    return Object.values(schema.shape).some(hasChecks);
+    return true;
+  if (schema instanceof z3.ZodObject) {
+    return Object.values(schema.shape).some(hasInvisibleConstraint);
+  }
   if (schema instanceof z3.ZodArray)
-    return hasChecks(schema.element);
+    return hasInvisibleConstraint(schema.element);
   if (schema instanceof z3.ZodUnion)
-    return schema.def.options.some(hasChecks);
+    return schema.def.options.some(hasInvisibleConstraint);
   if (schema instanceof z3.ZodRecord)
-    return hasChecks(schema.valueType);
+    return hasInvisibleConstraint(schema.valueType);
   if (schema instanceof z3.ZodIntersection) {
-    return hasChecks(schema.def.left) || hasChecks(schema.def.right);
+    return hasInvisibleConstraint(schema.def.left) || hasInvisibleConstraint(schema.def.right);
   }
   return false;
 }
+var INVISIBLE_CHECK_KINDS = new Set(["custom", "overwrite"]);
+function acceptsMoreThanItsType(schema) {
+  if (!(schema instanceof z3.ZodType))
+    return false;
+  if (schema instanceof z3.ZodCatch)
+    return true;
+  if (isRecord(schema.def) && schema.def.coerce === true)
+    return true;
+  if (schema instanceof z3.ZodOptional || schema instanceof z3.ZodNullable || schema instanceof z3.ZodDefault) {
+    return acceptsMoreThanItsType(schema.unwrap());
+  }
+  if (schema instanceof z3.ZodPipe)
+    return acceptsMoreThanItsType(schema.def.in);
+  return false;
+}
+function isInvisibleCheck(check) {
+  if (!isRecord(check))
+    return false;
+  const inner = check._zod;
+  const def = isRecord(inner) ? inner.def : undefined;
+  const kind = isRecord(def) ? def.check : undefined;
+  return typeof kind === "string" && INVISIBLE_CHECK_KINDS.has(kind);
+}
+function projectToBaseType(schema) {
+  if (!(schema instanceof z3.ZodType))
+    return z3.unknown();
+  if (schema instanceof z3.ZodNullable) {
+    return z3.nullable(projectToBaseType(schema.unwrap()));
+  }
+  if (schema instanceof z3.ZodOptional || schema instanceof z3.ZodDefault) {
+    return projectToBaseType(schema.unwrap());
+  }
+  if (schema instanceof z3.ZodPipe)
+    return projectToBaseType(schema.def.in);
+  if (schema instanceof z3.ZodCatch)
+    return z3.unknown();
+  const coerces = isRecord(schema.def) && schema.def.coerce === true;
+  if (schema instanceof z3.ZodNumber)
+    return coerces ? z3.coerce.number() : z3.number();
+  if (schema instanceof z3.ZodString)
+    return coerces ? z3.coerce.string() : z3.string();
+  if (schema instanceof z3.ZodBoolean && coerces)
+    return z3.coerce.boolean();
+  if (schema instanceof z3.ZodEnum || schema instanceof z3.ZodLiteral) {
+    return stringLiteralOrEnumValues(schema) === null ? z3.unknown() : z3.string();
+  }
+  if (schema instanceof z3.ZodBoolean)
+    return z3.boolean();
+  if (schema instanceof z3.ZodArray)
+    return z3.array(z3.unknown());
+  if (schema instanceof z3.ZodObject)
+    return z3.looseObject({});
+  return z3.unknown();
+}
 function normalizedJson(schema) {
   if (!(schema instanceof z3.ZodType))
     return "{}";
@@ -272,7 +339,17 @@ function mergeCollidingFields(schemas) {
   if (values.length <= 1) {
     if (only === undefined)
       return z3.unknown();
-    return schemas.length > 1 && hasChecks(only) ? z3.unknown() : only;
+    if (schemas.length <= 1)
+      return only;
+    const hazards2 = schemas.map(acceptsMoreThanItsType);
+    if (hazards2.some(Boolean) && !hazards2.every(Boolean))
+      return z3.unknown();
+    if (schemas.some(hasInvisibleConstraint)) {
+      if (normalizedJson(only) === "{}")
+        return only;
+      return projectToBaseType(only);
+    }
+    return only;
   }
   const merged = [];
   let allEnum = true;
@@ -286,9 +363,19 @@ function mergeCollidingFields(schemas) {
   }
   if (allEnum) {
     const uniq = [...new Set(merged)];
-    const [first, ...rest] = uniq;
-    if (first !== undefined)
-      return z3.enum([first, ...rest]);
+    const [first2, ...rest] = uniq;
+    if (first2 !== undefined)
+      return z3.enum([first2, ...rest]);
+  }
+  const hazards = schemas.map(acceptsMoreThanItsType);
+  if (hazards.some(Boolean) && !hazards.every(Boolean))
+    return z3.unknown();
+  const projected = values.map(projectToBaseType);
+  const first = projected[0];
+  if (first !== undefined) {
+    const shape = normalizedJson(first);
+    if (shape !== "{}" && projected.every((p) => normalizedJson(p) === shape))
+      return first;
   }
   return z3.unknown();
 }

package/dist/tools/flatten.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flatten.d.ts","sourceRoot":"","sources":["../../src/tools/flatten.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,CAAC,CAAC,qBAAqB,GAC7B,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAiD5B;AAsKD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,OAAO,CAqDpE"}
+{"version":3,"file":"flatten.d.ts","sourceRoot":"","sources":["../../src/tools/flatten.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,CAAC,CAAC,qBAAqB,GAC7B,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAiD5B;AA6TD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,OAAO,CAqDpE"}

package/dist/tools/mcp.d.ts

@@ -48,6 +48,15 @@ export interface McpMountConfig {
 export declare function validateMcpSchemas(services: ServiceDef[], onIncompatibleSchema?: IncompatibleSchemaPolicy, logger?: StitchLogger, options?: {
     extend?: ToolExtend;
     flattenUnionInput?: boolean;
+    /**
+     * Also fail a tool whose advertised schema has a property with no type
+     * information — nothing for a model to obey. Off by default because a
+     * contract may legitimately declare `z.unknown()`; `allowUntyped` lists the
+     * dotted paths that are deliberate, and anything else is a finding. → ADR 0044.
+     */
+    requireTypedProperties?: boolean;
+    /** Dotted paths (`tool.property`) that are deliberately unconstrained. */
+    allowUntyped?: readonly string[];
 }): void;
 export declare function mountMcp(mcpServer: McpServer, services: ServiceDef | ServiceDef[], config?: McpMountConfig): void;
 /**

package/dist/tools/mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/tools/mcp.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/tools/mcp.ts"],"names":[],"mappings":"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"}

package/dist/tools/untyped-properties.d.ts

@@ -0,0 +1,17 @@
+/** One property the model would be shown with no idea what it is. */
+export interface UntypedProperty {
+    /** Dotted path from the tool's argument root, e.g. `operations.partIndex`. */
+    path: string;
+    /** Its `description`, when it has one — usually the only clue present. */
+    description?: string;
+}
+/**
+ * Every property in a JSON Schema that carries no type information, deep.
+ *
+ * Walks `properties`, `items`, `additionalProperties`, `$defs` / `definitions`
+ * and the `allOf` / `anyOf` / `oneOf` branches — an intersection root emits
+ * `allOf` with no root `properties` at all, so reading the top level alone would
+ * inspect nothing and pass.
+ */
+export declare function findUntypedProperties(schema: unknown, prefix?: string): UntypedProperty[];
+//# sourceMappingURL=untyped-properties.d.ts.map

package/dist/tools/untyped-properties.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"untyped-properties.d.ts","sourceRoot":"","sources":["../../src/tools/untyped-properties.ts"],"names":[],"mappings":"AAkBA,qEAAqE;AACrE,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AASD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,SAAK,GAAG,eAAe,EAAE,CA+DrF"}

package/dist/tools.d.ts

@@ -22,5 +22,6 @@ export { type ImplementRemoteOptions, implementRemote } from './tools/remote';
 export { createToolLogger, type ToolCallRecord, type ToolLoggerConfig, } from './tools/tool-logger';
 export { createToolkit, type Toolkit } from './tools/toolkit';
 export { summarizeTransports, type TransportCounts, type TransportSummary, } from './tools/transports';
+export { findUntypedProperties, type UntypedProperty } from './tools/untyped-properties';
 export { type McpAnnotations, type McpMediaContent, mountViewFile, resolveMedia, type ViewFileOptions, } from './tools/view-file';
 //# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,gBAAgB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AACrF,OAAO,EAAE,KAAK,SAAS,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxD,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,YAAY,EACV,WAAW,EACX,eAAe,EACf,aAAa,EACb,aAAa,EACb,UAAU,GACX,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACvE,OAAO,EAAE,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC7E,OAAO,EACL,cAAc,EACd,KAAK,wBAAwB,EAC7B,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,QAAQ,EACR,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,2BAA2B,EAC3B,kBAAkB,EAClB,KAAK,SAAS,EACd,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,KAAK,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACpF,OAAO,EACL,KAAK,kBAAkB,EACvB,YAAY,EACZ,KAAK,aAAa,EAClB,KAAK,UAAU,GAChB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,KAAK,kBAAkB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAChF,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EACL,2BAA2B,EAC3B,uBAAuB,EACvB,KAAK,uBAAuB,EAC5B,4BAA4B,EAC5B,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,kBAAkB,EAClB,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,gBAAgB,GACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,KAAK,sBAAsB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC9E,OAAO,EACL,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,gBAAgB,GACtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,KAAK,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EACL,mBAAmB,EACnB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,aAAa,EACb,YAAY,EACZ,KAAK,eAAe,GACrB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,gBAAgB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AACrF,OAAO,EAAE,KAAK,SAAS,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxD,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,YAAY,EACV,WAAW,EACX,eAAe,EACf,aAAa,EACb,aAAa,EACb,UAAU,GACX,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACvE,OAAO,EAAE,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC7E,OAAO,EACL,cAAc,EACd,KAAK,wBAAwB,EAC7B,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,QAAQ,EACR,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,2BAA2B,EAC3B,kBAAkB,EAClB,KAAK,SAAS,EACd,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,KAAK,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACpF,OAAO,EACL,KAAK,kBAAkB,EACvB,YAAY,EACZ,KAAK,aAAa,EAClB,KAAK,UAAU,GAChB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,KAAK,kBAAkB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAChF,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EACL,2BAA2B,EAC3B,uBAAuB,EACvB,KAAK,uBAAuB,EAC5B,4BAA4B,EAC5B,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,kBAAkB,EAClB,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,gBAAgB,GACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,KAAK,sBAAsB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC9E,OAAO,EACL,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,gBAAgB,GACtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,KAAK,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EACL,mBAAmB,EACnB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,qBAAqB,EAAE,KAAK,eAAe,EAAE,MAAM,4BAA4B,CAAC;AACzF,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,aAAa,EACb,YAAY,EACZ,KAAK,eAAe,GACrB,MAAM,mBAAmB,CAAC"}

package/dist/tools.js

@@ -21,7 +21,7 @@ import {
   readCapped,
   toolResultFromError,
   writeDownload
-} from "./index-jr8vf7g8.js";
+} from "./index-bfabej0h.js";
 import {
   toJsonSchema
 } from "./index-0ed3bx43.js";
@@ -139,6 +139,77 @@ function inlineMcpAppBundle(html) {
   return html.replace(EXT_APPS_BUNDLE_PLACEHOLDER, () => bundle);
 }
 
+// src/tools/untyped-properties.ts
+var TYPE_KEYWORDS = ["type", "enum", "const", "anyOf", "oneOf", "allOf", "$ref", "not"];
+function saysWhatItIs(schema) {
+  return TYPE_KEYWORDS.some((keyword) => schema[keyword] !== undefined);
+}
+function findUntypedProperties(schema, prefix = "") {
+  if (!isRecord(schema))
+    return [];
+  const found = [];
+  const properties = schema.properties;
+  if (isRecord(properties)) {
+    for (const [key, value] of Object.entries(properties)) {
+      const path = prefix ? `${prefix}.${key}` : key;
+      if (isRecord(value)) {
+        if (!saysWhatItIs(value)) {
+          const description = value.description;
+          found.push({
+            path,
+            ...typeof description === "string" && { description }
+          });
+        }
+        found.push(...findUntypedProperties(value, path));
+      }
+    }
+  }
+  for (const key of ["items", "additionalProperties"]) {
+    const child = schema[key];
+    if (isRecord(child))
+      found.push(...findUntypedProperties(child, prefix));
+    if (Array.isArray(child)) {
+      for (const entry of child) {
+        if (isRecord(entry))
+          found.push(...findUntypedProperties(entry, prefix));
+      }
+    }
+  }
+  for (const key of ["prefixItems"]) {
+    const child = schema[key];
+    if (Array.isArray(child)) {
+      for (const entry of child) {
+        if (isRecord(entry))
+          found.push(...findUntypedProperties(entry, prefix));
+      }
+    }
+  }
+  const patterned = schema.patternProperties;
+  if (isRecord(patterned)) {
+    for (const value of Object.values(patterned)) {
+      if (isRecord(value))
+        found.push(...findUntypedProperties(value, prefix));
+    }
+  }
+  for (const key of ["$defs", "definitions"]) {
+    const container = schema[key];
+    if (!isRecord(container))
+      continue;
+    for (const definition of Object.values(container)) {
+      if (isRecord(definition))
+        found.push(...findUntypedProperties(definition, prefix));
+    }
+  }
+  for (const key of ["allOf", "anyOf", "oneOf"]) {
+    const branches = schema[key];
+    if (Array.isArray(branches)) {
+      for (const branch of branches)
+        found.push(...findUntypedProperties(branch, prefix));
+    }
+  }
+  return found;
+}
+
 // src/tools/mcp.ts
 function textBlock(text) {
   return [{ type: "text", text }];
@@ -187,7 +258,7 @@ function reportIncompatible(message, policy, logger, failures) {
 }
 function throwIfFailures(failures) {
   if (failures.length > 0) {
-    throw new Error(`[stitchkit] ${failures.length} MCP tool(s) have an incompatible schema:
+    throw new Error(`[stitchkit] ${failures.length} problem(s) with MCP tool schemas:
  - ${failures.join(`
  - `)}`);
   }
@@ -217,9 +288,19 @@ function prepareMcpTool(mountable, policy, logger, failures, seen) {
 function validateMcpSchemas(services, onIncompatibleSchema = "throw", logger, options) {
   const seen = new Set;
   const failures = [];
+  const allowed = new Set(options?.allowUntyped ?? []);
   for (const service of services) {
     for (const mountable of collectTools(service, "MCP", options)) {
-      prepareMcpTool(mountable, onIncompatibleSchema, logger, failures, seen);
+      const prepared = prepareMcpTool(mountable, onIncompatibleSchema, logger, failures, seen);
+      if (!prepared || !options?.requireTypedProperties)
+        continue;
+      for (const untyped of findUntypedProperties(toJsonSchema(mountable.schema, "input"))) {
+        const path = `${mountable.name}.${untyped.path}`;
+        if (allowed.has(path))
+          continue;
+        const clue = untyped.description ? ` (only a description: "${untyped.description}")` : "";
+        reportIncompatible(`MCP tool "${mountable.name}" — property "${untyped.path}" carries no type, enum or $ref${clue}. ` + "A model is given no way to know what to send. Widen the contract, or list it in `allowUntyped` if it is deliberately free-form.", onIncompatibleSchema === "skip" ? "warn" : onIncompatibleSchema, logger, failures);
+      }
     }
   }
   throwIfFailures(failures);
@@ -1410,6 +1491,7 @@ export {
   implementRemote,
   flattenUnionsDeep,
   flattenDiscriminatedUnion,
+  findUntypedProperties,
   createToolkit,
   createToolLogger,
   createStdioMcpServer,

package/llms-full.txt

@@ -1524,6 +1524,30 @@ cannot become a tool. `onIncompatibleSchema` decides what happens:
 `validateMcpSchemas(services)` runs the same check on its own — useful in a
 startup assertion or a test.
 
+#### Is every property actually usable by a model?
+
+A tool schema is the only instruction a model gets about the shape of its
+arguments. A property that carries a `description` and no `type` / `enum` /
+`anyOf` / `$ref` tells it nothing — and nothing fails: the schema converts, the
+mount succeeds, the tool is advertised, and the model then guesses, retrying the
+same wrong guess because the error does not say what the right one would be.
+
+```ts
+validateMcpSchemas(services, 'throw', logger, {
+  flattenUnionInput: true,          // mirror the live mount
+  requireTypedProperties: true,
+  allowUntyped: ['docs_create.payload'],   // deliberately free-form
+})
+```
+
+Off by default, because a contract may legitimately declare `z.unknown()`.
+`allowUntyped` takes dotted `tool.property` paths — an entry there is a decision,
+anything else is a finding. Pass the **same** `extend` / `flattenUnionInput` the
+mount uses, or the check vets a different document than the one advertised.
+
+`findUntypedProperties(jsonSchema)` is the same walk, exported on its own if you
+want to assert on a schema you built elsewhere.
+
 ### Discriminated unions for weaker models — `flattenUnionInput`
 
 A discriminated union in a tool's input becomes a JSON Schema `oneOf` / `anyOf`.
@@ -1533,6 +1557,15 @@ the field or mangle its strings. Set `flattenUnionInput: true` (on
 union as a **single flat object** instead — the discriminator becomes an enum and
 each variant's fields become optional with a `Required if <disc> = …` hint.
 
+**A field several variants declare keeps its type.** Flattening puts every
+variant's fields side by side, so a key two variants share has to be advertised
+as one thing. Where they agree, that is what you get; where they disagree — a
+`.refine()` only one of them carries, two different bounds on the same number, an
+enum against a free string — the *constraint* is dropped and the **type** is not.
+A field that is a number in every variant is advertised as a number, not as a
+bare description. Only genuinely different kinds (a string in one variant, a
+number in another) fall back to unconstrained. → ADR 0044
+
 It is **deep**: unions are flattened at every depth — top level, object fields,
 array items, and through `optional` / `nullable` / `default` / intersection
 wrappers — so no `oneOf` survives anywhere (e.g. a `content.parts[]` that is an
@@ -3921,6 +3954,8 @@ Server-only. Turns contracts into MCP and AI-agent tools. Needs the
 | `ViewFileOptions` | _type_ | options for `mountViewFile` |
 | `McpAnnotations` | _type_ | MCP annotations on a media result |
 | `CollectToolsConfig` | _type_ | options for `collectTools` |
+| `findUntypedProperties` | function | every property in a JSON Schema with no `type`/`enum`/`$ref` — what a model is shown and cannot obey ([guide](../guide/mcp-and-agents.md)) |
+| `UntypedProperty` | _type_ | one such property — `{ path, description? }` |
 | `ToolNameEntry` | _type_ | one `listToolNames` row — `{ name, service, method, transports }` |
 | `IncompatibleSchemaPolicy` | _type_ | `'throw' \| 'skip' \| 'warn'` |
 | `McpMediaContent` | _type_ | a multimodal MCP content item |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",