stitchkit 0.103.1 → 0.103.2

package/CHANGELOG.md

@@ -15,6 +15,15 @@ additive**; the first breaking change landed in 0.10.0. Grep the file for
 
 ## [Unreleased]
 
+## [0.103.2] — 2026-10-01
+
+### Fixed
+
+- Flattened tool schemas retain distinct field descriptions with their discriminator
+  labels, and advertise both availability and conditional requiredness. Structural
+  deduplication keeps explanations separate from validation constraints; MCP, agent
+  tools and manifests share the same projection. Runtime Zod validation is unchanged.
+
 ## [0.103.1] — 2026-09-30
 
 ### Added

package/dist/entrypoints/agent-runtime/coding-tools.js

@@ -1,5 +1,5 @@
 import"../../index-ct75c3at.js";
-import"../../index-7z9ym7t8.js";
+import"../../index-x87j7csh.js";
 import"../../index-n53mswt3.js";
 import"../../index-b2bz0kdm.js";
 import {
@@ -7,9 +7,9 @@ import {
   AgentCodingToolAuthorizationSchema2,
   AgentCodingToolPathAuthorizationSchema2,
   createAgentCodingTools2
-} from "../../index-djjhhgjk.js";
+} from "../../index-a4ajxwmb.js";
 import"../../index-ahvsksw5.js";
-import"../../index-jzczzcsb.js";
+import"../../index-tgzhq07n.js";
 export {
   AgentCodingToolAuthorizationSchema2 as AgentCodingToolAuthorizationSchema,
   AgentCodingToolLimitsSchema2 as AgentCodingToolLimitsSchema,

package/dist/entrypoints/agent-runtime/harness-tools.js

@@ -4,18 +4,18 @@ import"../../index-b2bz0kdm.js";
 import"../../index-yex7eg1v.js";
 import"../../index-9pw0a51a.js";
 import"../../index-ct75c3at.js";
-import"../../index-7z9ym7t8.js";
-import"../../index-0efgsyav.js";
-import"../../index-kgmh97hf.js";
+import"../../index-x87j7csh.js";
+import"../../index-m2xqkv55.js";
+import"../../index-r956rndn.js";
 import {
   mountAgent2
-} from "../../index-xgc94hy6.js";
+} from "../../index-1khy8y7n.js";
 import {
   composeToolLifecycle2
 } from "../../index-ze1eph1k.js";
-import"../../index-x1dkwx5x.js";
+import"../../index-dnn9z96q.js";
 import"../../index-7n68nmc6.js";
-import"../../index-jzczzcsb.js";
+import"../../index-tgzhq07n.js";
 
 // src/agent-runtime/harness-tools.ts
 function createAgentHarnessTools(resolve) {

package/dist/entrypoints/agent-runtime/harness.js

@@ -5,7 +5,7 @@ import"../../index-8kzct1d6.js";
 import {
   composeAgentPrompt2,
   createAgentRuntime2
-} from "../../index-z3pqcy7r.js";
+} from "../../index-90ppdx3q.js";
 import"../../index-h97tqqp1.js";
 import"../../index-mnkk1ffz.js";
 import"../../index-n53mswt3.js";
@@ -13,8 +13,8 @@ import"../../index-b2bz0kdm.js";
 import"../../index-yex7eg1v.js";
 import"../../index-9pw0a51a.js";
 import"../../index-ct75c3at.js";
-import"../../index-7z9ym7t8.js";
-import"../../index-0efgsyav.js";
+import"../../index-x87j7csh.js";
+import"../../index-m2xqkv55.js";
 import"../../index-5vyd0fkb.js";
 import"../../index-nggfa2yn.js";
 import"../../index-r5hsgkz5.js";
@@ -29,7 +29,7 @@ import {
 import"../../index-7n68nmc6.js";
 import {
   defineRuntimeTool2
-} from "../../index-jzczzcsb.js";
+} from "../../index-tgzhq07n.js";
 
 // src/agent-runtime/harness-contract.ts
 import { z } from "zod";

package/dist/entrypoints/agent-runtime/sandbox.js

@@ -5,12 +5,12 @@ import {
 } from "../../index-ahvsksw5.js";
 import"../../index-n53mswt3.js";
 import"../../index-ct75c3at.js";
-import"../../index-7z9ym7t8.js";
+import"../../index-x87j7csh.js";
 import"../../index-b2bz0kdm.js";
 import {
   createAgentCodingTools2
-} from "../../index-djjhhgjk.js";
-import"../../index-jzczzcsb.js";
+} from "../../index-a4ajxwmb.js";
+import"../../index-tgzhq07n.js";
 
 // src/agent-runtime/sandbox-bubblewrap.ts
 import { mkdir as mkdir2, mkdtemp, realpath, rm as rm2 } from "node:fs/promises";

package/dist/entrypoints/agent-runtime.js

@@ -110,7 +110,7 @@ import {
   agentGoalStateSlot2,
   agentTodoStateSlot2,
   createAgentRuntime2
-} from "../index-z3pqcy7r.js";
+} from "../index-90ppdx3q.js";
 import {
   AgentConversationSummarySchema2,
   AgentConversationPageSchema2,
@@ -125,12 +125,12 @@ import {
 } from "../index-yex7eg1v.js";
 import"../index-9pw0a51a.js";
 import"../index-ct75c3at.js";
-import"../index-7z9ym7t8.js";
-import"../index-0efgsyav.js";
-import"../index-kgmh97hf.js";
+import"../index-x87j7csh.js";
+import"../index-m2xqkv55.js";
+import"../index-r956rndn.js";
 import {
   mountAgent2
-} from "../index-xgc94hy6.js";
+} from "../index-1khy8y7n.js";
 import {
   createBoundedSinkManager
 } from "../index-h97tqqp1.js";
@@ -192,13 +192,13 @@ import {
 } from "../index-vgkbcnkc.js";
 import {
   buildToolManifest2
-} from "../index-860vjkgm.js";
-import"../index-x1dkwx5x.js";
+} from "../index-kmpzj1cq.js";
+import"../index-dnn9z96q.js";
 import"../index-7n68nmc6.js";
 import {
   defineRuntimeTool2,
   executableAgentRuntimeTools
-} from "../index-jzczzcsb.js";
+} from "../index-tgzhq07n.js";
 
 // src/agent-runtime/child-tools.ts
 import { z as z2 } from "zod";

package/dist/entrypoints/cli.js

@@ -18,25 +18,25 @@ import {
   renderCliView2,
   pollUntilDone2,
   createCli2
-} from "../index-kkk1wzsq.js";
+} from "../index-1br6gwhf.js";
 import {
   AppError2
 } from "../index-n53mswt3.js";
 import"../index-b2bz0kdm.js";
-import"../index-0efgsyav.js";
+import"../index-m2xqkv55.js";
 import"../index-ct75c3at.js";
-import"../index-7z9ym7t8.js";
+import"../index-x87j7csh.js";
 import"../index-yex7eg1v.js";
-import"../index-kgmh97hf.js";
+import"../index-r956rndn.js";
 import {
   writeFileAtomicSync2
 } from "../index-aan6hqb9.js";
-import"../index-x1dkwx5x.js";
+import"../index-dnn9z96q.js";
 import {
   argumentsDigest
 } from "../index-r7a7r7ha.js";
 import"../index-7n68nmc6.js";
-import"../index-jzczzcsb.js";
+import"../index-tgzhq07n.js";
 import {
   serializeCanonicalJson
 } from "../index-zsvzhjtk.js";

package/dist/entrypoints/testing.js

@@ -36,7 +36,7 @@ import {
   projectToolSurface,
   mcpProjectionCandidate,
   prepareProjectedMcpTools
-} from "../index-7z9ym7t8.js";
+} from "../index-x87j7csh.js";
 import"../index-b2bz0kdm.js";
 import {
   compareCodeUnits,

package/dist/entrypoints/tools/connections.js

@@ -2,14 +2,14 @@ import"../../index-ct75c3at.js";
 import {
   declaresDraft07,
   withDefsDialect
-} from "../../index-7z9ym7t8.js";
+} from "../../index-x87j7csh.js";
 import {
   AppError2
 } from "../../index-n53mswt3.js";
 import"../../index-b2bz0kdm.js";
 import {
   defineRuntimeTool2
-} from "../../index-jzczzcsb.js";
+} from "../../index-tgzhq07n.js";
 import {
   safeJsonParse
 } from "../../index-zsarb5xp.js";

package/dist/entrypoints/tools/invoker.js

@@ -1,14 +1,14 @@
 import"../../index-n53mswt3.js";
 import"../../index-b2bz0kdm.js";
-import"../../index-0efgsyav.js";
+import"../../index-m2xqkv55.js";
 import"../../index-yex7eg1v.js";
 import"../../index-9pw0a51a.js";
 import"../../index-ct75c3at.js";
-import"../../index-7z9ym7t8.js";
-import"../../index-kgmh97hf.js";
+import"../../index-x87j7csh.js";
+import"../../index-r956rndn.js";
 import {
   createToolInvoker2
-} from "../../index-ds7jdhep.js";
+} from "../../index-n2gre124.js";
 import"../../index-7n68nmc6.js";
 export {
   createToolInvoker2 as createToolInvoker

package/dist/entrypoints/tools.js

@@ -35,21 +35,21 @@ import {
   presentationMetadata,
   findUntypedProperties2,
   prepareProjectedMcpTools
-} from "../index-7z9ym7t8.js";
+} from "../index-x87j7csh.js";
 import {
   parseToolCallArguments,
   toolResultFromError,
   ToolExecutionControlError2,
   isToolExecutionControlError2
-} from "../index-0efgsyav.js";
+} from "../index-m2xqkv55.js";
 import {
   collectTools2,
   createToolRunner,
   formatToolError
-} from "../index-kgmh97hf.js";
+} from "../index-r956rndn.js";
 import {
   mountAgent2
-} from "../index-xgc94hy6.js";
+} from "../index-1khy8y7n.js";
 import"../index-m38ej7e5.js";
 import {
   ALL_TRANSPORTS2,
@@ -77,7 +77,7 @@ import {
   WaitTimeoutError,
   runWaitOperation,
   createCli2
-} from "../index-kkk1wzsq.js";
+} from "../index-1br6gwhf.js";
 import {
   ManagedFilePathSchema2,
   ManagedFileRefSchema2
@@ -104,16 +104,16 @@ import {
 import {
   describeToolCatalog2,
   buildToolManifest2
-} from "../index-860vjkgm.js";
+} from "../index-kmpzj1cq.js";
 import {
   collectToolSurface
-} from "../index-x1dkwx5x.js";
+} from "../index-dnn9z96q.js";
 import {
   argumentsDigest
 } from "../index-r7a7r7ha.js";
 import {
   createToolInvoker2
-} from "../index-ds7jdhep.js";
+} from "../index-n2gre124.js";
 import {
   runWithRequestContext2,
   getRequestContext2,
@@ -122,7 +122,7 @@ import {
 import {
   defineRuntimeTool2,
   createRuntimeToolFactory2
-} from "../index-jzczzcsb.js";
+} from "../index-tgzhq07n.js";
 import {
   compareCodeUnits,
   serializeCanonicalJson

package/dist/{index-kkk1wzsq.js → index-1br6gwhf.js}

@@ -4,7 +4,7 @@ import {
 import {
   toolResultFromError,
   toolErrorFromResult
-} from "./index-0efgsyav.js";
+} from "./index-m2xqkv55.js";
 import {
   coerceJsonArgs2
 } from "./index-9pw0a51a.js";
@@ -15,17 +15,17 @@ import {
   objectShapeKeys,
   assertUniqueToolName,
   buildToolPresentationSchema
-} from "./index-7z9ym7t8.js";
+} from "./index-x87j7csh.js";
 import {
   createToolRunner,
   formatToolError
-} from "./index-kgmh97hf.js";
+} from "./index-r956rndn.js";
 import {
   isWithinDir2
 } from "./index-5cc6r990.js";
 import {
   collectToolSurface
-} from "./index-x1dkwx5x.js";
+} from "./index-dnn9z96q.js";
 import {
   formatZodError2
 } from "./index-1eeqpadm.js";

package/dist/{index-xgc94hy6.js → index-1khy8y7n.js}

@@ -6,14 +6,14 @@ import {
   toolResultFromError,
   toolCauseFromResult,
   isToolExecutionControlError2
-} from "./index-0efgsyav.js";
+} from "./index-m2xqkv55.js";
 import {
   createToolRunner,
   formatToolError
-} from "./index-kgmh97hf.js";
+} from "./index-r956rndn.js";
 import {
   collectToolSurface
-} from "./index-x1dkwx5x.js";
+} from "./index-dnn9z96q.js";
 import {
   isRecord
 } from "./index-9jfdm5tg.js";

package/dist/{index-z3pqcy7r.js → index-90ppdx3q.js}

@@ -14,7 +14,7 @@ import {
 import {
   ToolExecutionControlError2,
   isToolExecutionControlError2
-} from "./index-0efgsyav.js";
+} from "./index-m2xqkv55.js";
 import {
   agentDurableEventId2
 } from "./index-mnkk1ffz.js";

package/dist/{index-djjhhgjk.js → index-a4ajxwmb.js}

@@ -28,7 +28,7 @@ import {
 } from "./index-d4pa2bgs.js";
 import {
   defineRuntimeTool2
-} from "./index-jzczzcsb.js";
+} from "./index-tgzhq07n.js";
 
 // src/agent-runtime/coding-tool-contract.ts
 import { z } from "zod";

package/dist/{index-x1dkwx5x.js → index-dnn9z96q.js}

@@ -1,12 +1,12 @@
 import {
   projectToolSurface
-} from "./index-7z9ym7t8.js";
+} from "./index-x87j7csh.js";
 import {
   contractToolMountable
-} from "./index-kgmh97hf.js";
+} from "./index-r956rndn.js";
 import {
   runtimeToolMountable
-} from "./index-jzczzcsb.js";
+} from "./index-tgzhq07n.js";
 
 // src/tools/surface.ts
 function collectToolSurface({

package/dist/{index-860vjkgm.js → index-kmpzj1cq.js}

@@ -1,6 +1,6 @@
 import {
   collectToolSurface
-} from "./index-x1dkwx5x.js";
+} from "./index-dnn9z96q.js";
 
 // src/tools/manifest.ts
 function utf8Length(value) {

package/dist/{index-0efgsyav.js → index-m2xqkv55.js}

@@ -15,7 +15,7 @@ import {
   applyToolViewDefaults,
   projectToolView,
   objectShapeKeys
-} from "./index-7z9ym7t8.js";
+} from "./index-x87j7csh.js";
 import {
   runWithRequestContext2,
   getRequestContext2

package/dist/{index-ds7jdhep.js → index-n2gre124.js}

@@ -3,14 +3,14 @@ import {
 } from "./index-n53mswt3.js";
 import {
   toolErrorFromResult
-} from "./index-0efgsyav.js";
+} from "./index-m2xqkv55.js";
 import {
   assertUniqueToolName
-} from "./index-7z9ym7t8.js";
+} from "./index-x87j7csh.js";
 import {
   collectTools2,
   createToolRunner
-} from "./index-kgmh97hf.js";
+} from "./index-r956rndn.js";
 
 // src/tools/invoker.ts
 function createToolInvoker2(services, config) {

package/dist/{index-kgmh97hf.js → index-r956rndn.js}

@@ -6,11 +6,11 @@ import {
   mergeSchemas,
   assertToolExtensionCompatible,
   projectToolSurface
-} from "./index-7z9ym7t8.js";
+} from "./index-x87j7csh.js";
 import {
   toolErrorFromResult,
   executeToolMethod
-} from "./index-0efgsyav.js";
+} from "./index-m2xqkv55.js";
 
 // src/tools/mount.ts
 import { z } from "zod";

package/dist/{index-jzczzcsb.js → index-tgzhq07n.js}

@@ -1,6 +1,6 @@
 import {
   projectRuntimeTool
-} from "./index-7z9ym7t8.js";
+} from "./index-x87j7csh.js";
 
 // src/tools/runtime-tool.ts
 function defineRuntimeTool2(definition) {

package/dist/{index-7z9ym7t8.js → index-x87j7csh.js}

@@ -308,7 +308,26 @@ function commonBaseType(schemas) {
   const types = normalizeTypes(nullable ? [...bases, "null"] : bases);
   return types.length > 0 ? { type: types } : {};
 }
-function mergePropertySchemas(properties) {
+function describeVariants(properties, discriminator) {
+  const groups = new Map;
+  for (const { schema, labels } of properties) {
+    if (typeof schema.description !== "string")
+      continue;
+    const group = groups.get(schema.description) ?? [];
+    group.push(...labels);
+    groups.set(schema.description, group);
+  }
+  if (groups.size === 0)
+    return;
+  if (groups.size === 1 && properties.every(({ schema }) => typeof schema.description === "string")) {
+    return groups.keys().next().value;
+  }
+  return [...groups].map(([description, labels]) => ({
+    description,
+    labels: [...new Set(labels)].sort().join(" | ")
+  })).sort((left, right) => left.labels < right.labels ? -1 : left.labels > right.labels ? 1 : 0).map(({ description, labels }) => `When ${discriminator} = ${labels}: ${description}`).join(" ");
+}
+function mergePropertySchemas(properties, discriminator) {
   const schemas = properties.map((property) => nullableProjection(property.schema));
   const structural = schemas.map(withoutAnnotations);
   const [first] = structural;
@@ -318,13 +337,14 @@ function mergePropertySchemas(properties) {
   } else {
     const values = schemas.map(stringValues);
     const allStrings = values.every((value) => value !== null);
-    merged = allStrings ? { type: "string", enum: [...new Set(values.flatMap((value) => value ?? []))] } : commonBaseType(structural);
-  }
-  const descriptions = [
-    ...new Set(schemas.map((schema) => schema.description).filter((value) => typeof value === "string"))
-  ];
-  if (descriptions.length === 1)
-    merged.description = descriptions[0];
+    merged = allStrings ? { type: "string", enum: [...new Set(values.flatMap((value) => value ?? []))].sort() } : commonBaseType(structural);
+  }
+  const description = describeVariants(properties.map((property, index) => ({
+    ...property,
+    schema: typeof property.schema.description === "string" ? property.schema : schemas[index] ?? property.schema
+  })), discriminator);
+  if (description !== undefined)
+    merged.description = description;
   return merged;
 }
 
@@ -434,20 +454,21 @@ function flattenNode(node) {
     });
   }
   const properties = {
-    [discriminator.key]: mergePropertySchemas(discriminatorProperties)
+    [discriminator.key]: mergePropertySchemas(discriminatorProperties, discriminator.key)
   };
   const required = [discriminator.key];
-  for (const [key, entries] of perKey) {
-    let merged = mergePropertySchemas(entries);
+  for (const [key, entries] of [...perKey].sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)) {
+    let merged = mergePropertySchemas(entries, discriminator.key);
     const requiredEverywhere = entries.length === variants.length && entries.every((entry) => entry.required);
     if (requiredEverywhere) {
       required.push(key);
     } else {
       const requiredLabels = entries.filter((entry) => entry.required).flatMap((entry) => entry.labels);
       const presentLabels = entries.flatMap((entry) => entry.labels);
-      const labels = requiredLabels.length > 0 ? requiredLabels : presentLabels;
-      const verb = requiredLabels.length > 0 ? "Required" : "Available";
-      merged = appendHint(merged, `${verb} if ${discriminator.key} = ${[...new Set(labels)].join(" | ")}`);
+      merged = appendHint(merged, `Available if ${discriminator.key} = ${[...new Set(presentLabels)].sort().join(" | ")}.`);
+      if (requiredLabels.length > 0) {
+        merged = appendHint(merged, `Required if ${discriminator.key} = ${[...new Set(requiredLabels)].sort().join(" | ")}`);
+      }
     }
     properties[key] = merged;
   }

package/dist/tools/schema/flatten-join.d.ts

@@ -6,5 +6,5 @@ export interface VariantProperty {
 }
 /** The string members of a `const`/`enum`, or `null` when any member is not one. */
 export declare function stringValues(schema: ToolPresentationSchema): string[] | null;
-export declare function mergePropertySchemas(properties: VariantProperty[]): ToolPresentationSchema;
+export declare function mergePropertySchemas(properties: VariantProperty[], discriminator: string): ToolPresentationSchema;
 //# sourceMappingURL=flatten-join.d.ts.map

package/dist/tools/schema/flatten-join.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flatten-join.d.ts","sourceRoot":"","sources":["../../../src/tools/schema/flatten-join.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAExD,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,sBAAsB,CAAC;IAC/B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAsED,oFAAoF;AACpF,wBAAgB,YAAY,CAAC,MAAM,EAAE,sBAAsB,GAAG,MAAM,EAAE,GAAG,IAAI,CAK5E;AAuID,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,sBAAsB,CA4B1F"}
+{"version":3,"file":"flatten-join.d.ts","sourceRoot":"","sources":["../../../src/tools/schema/flatten-join.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAExD,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,sBAAsB,CAAC;IAC/B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAsED,oFAAoF;AACpF,wBAAgB,YAAY,CAAC,MAAM,EAAE,sBAAsB,GAAG,MAAM,EAAE,GAAG,IAAI,CAK5E;AAsKD,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,eAAe,EAAE,EAC7B,aAAa,EAAE,MAAM,GACpB,sBAAsB,CAiCxB"}

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

@@ -1 +1 @@
-{"version":3,"file":"flatten.d.ts","sourceRoot":"","sources":["../../../src/tools/schema/flatten.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,sBAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAsJ7D;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,sBAAsB,GAAG,sBAAsB,CAG5F;AAED,0EAA0E;AAC1E,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,sBAAsB,GAAG,sBAAsB,CAG3F"}
+{"version":3,"file":"flatten.d.ts","sourceRoot":"","sources":["../../../src/tools/schema/flatten.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,sBAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AA4J7D;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,sBAAsB,GAAG,sBAAsB,CAG5F;AAED,0EAA0E;AAC1E,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,sBAAsB,GAAG,sBAAsB,CAG3F"}

package/llms/tools.3.txt

@@ -280,7 +280,7 @@ Advanced building blocks — the shared machinery the mounts are built on.
 | `ToolSurfaceDefinition` | _type_ | shared object-shaped `{ services?, runtimeTools? }` introspection surface |
 | `ToolManifestConfig` | _type_ | mixed surface plus required model-facing `transport` and presentation options |
 | `coerceJsonArgs` | function | coerce JSON-stringified array/object tool arguments |
-| `flattenToolJsonSchema` | function | project structurally identifiable discriminated unions into conservative object joins; divergent fields retain every provable base kind in a deterministic `type` array, and the projection never executes validation |
+| `flattenToolJsonSchema` | function | project structurally identifiable discriminated unions into conservative object joins; scalar collisions retain provable types, object/array collisions retain structural alternatives, and field descriptions retain discriminator labels plus availability/requiredness hints; the projection never executes validation |
 | `ToolPresentationSchema` | _type_ | immutable model-facing JSON Schema document shared by tool transports |
 | `MountableTool` | _type_ | one operation with separate executable CLI argument schema and model-facing presentation schema |
 | `ToolManifestEntry` | _type_ | one `buildToolManifest` row |

package/llms/tools.txt

@@ -714,7 +714,25 @@ Capable models (Claude, Gemini, GPT) handle that; weaker / cheaper ones can drop
 the field or mangle its strings. Set `flattenUnionInput: true` (on
 `createMcpHandler` / `mountMcp` / `mountAgent`) to advertise each discriminated
 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.
+each field required by every variant stays required. Other fields become optional
+with `Available if <disc> = …` and, where applicable, `Required if <disc> = …` hints.
+
+**Branch explanations keep their meaning.** A shared description appears once;
+different descriptions are grouped by text and qualified with `When <disc> = …:`.
+A branch without a description does not inherit another branch's explanation.
+For example, an optional object `value` in `single` and a required array `value`
+in `group` advertise:
+
+```text
+When kind = group: Two to ten references.
+When kind = single: One reference.
+Available if kind = group | single. Required if kind = group
+```
+
+A third branch without `value` is absent from those labels. The object and array
+retain their separate shapes; the array's minimum length does not apply to the object.
+Discriminator values, branch explanation labels and joined property order are
+deterministic under branch reordering. → ADR [0221](../decisions/0221-flat-field-explanations-retain-branch-meaning.md).
 
 **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

package/llms-full.txt

@@ -4177,7 +4177,25 @@ Capable models (Claude, Gemini, GPT) handle that; weaker / cheaper ones can drop
 the field or mangle its strings. Set `flattenUnionInput: true` (on
 `createMcpHandler` / `mountMcp` / `mountAgent`) to advertise each discriminated
 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.
+each field required by every variant stays required. Other fields become optional
+with `Available if <disc> = …` and, where applicable, `Required if <disc> = …` hints.
+
+**Branch explanations keep their meaning.** A shared description appears once;
+different descriptions are grouped by text and qualified with `When <disc> = …:`.
+A branch without a description does not inherit another branch's explanation.
+For example, an optional object `value` in `single` and a required array `value`
+in `group` advertise:
+
+```text
+When kind = group: Two to ten references.
+When kind = single: One reference.
+Available if kind = group | single. Required if kind = group
+```
+
+A third branch without `value` is absent from those labels. The object and array
+retain their separate shapes; the array's minimum length does not apply to the object.
+Discriminator values, branch explanation labels and joined property order are
+deterministic under branch reordering. → ADR [0221](../decisions/0221-flat-field-explanations-retain-branch-meaning.md).
 
 **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
@@ -20216,7 +20234,7 @@ Advanced building blocks — the shared machinery the mounts are built on.
 | `ToolSurfaceDefinition` | _type_ | shared object-shaped `{ services?, runtimeTools? }` introspection surface |
 | `ToolManifestConfig` | _type_ | mixed surface plus required model-facing `transport` and presentation options |
 | `coerceJsonArgs` | function | coerce JSON-stringified array/object tool arguments |
-| `flattenToolJsonSchema` | function | project structurally identifiable discriminated unions into conservative object joins; divergent fields retain every provable base kind in a deterministic `type` array, and the projection never executes validation |
+| `flattenToolJsonSchema` | function | project structurally identifiable discriminated unions into conservative object joins; scalar collisions retain provable types, object/array collisions retain structural alternatives, and field descriptions retain discriminator labels plus availability/requiredness hints; the projection never executes validation |
 | `ToolPresentationSchema` | _type_ | immutable model-facing JSON Schema document shared by tool transports |
 | `MountableTool` | _type_ | one operation with separate executable CLI argument schema and model-facing presentation schema |
 | `ToolManifestEntry` | _type_ | one `buildToolManifest` row |

package/llms.txt

@@ -13,7 +13,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/live**: [llms/live.txt](llms/live.txt) 21.6 KB
 - **stitchkit/react**: [llms/react.txt](llms/react.txt) 9.0 KB
 - **stitchkit/react/keyboard**: [llms/react-keyboard.txt](llms/react-keyboard.txt) 9.4 KB
-- **stitchkit/tools**: [llms/tools.txt](llms/tools.txt) 45.0 KB → [llms/tools.2.txt](llms/tools.2.txt) 26.9 KB → [llms/tools.3.txt](llms/tools.3.txt) 25.4 KB
+- **stitchkit/tools**: [llms/tools.txt](llms/tools.txt) 45.9 KB → [llms/tools.2.txt](llms/tools.2.txt) 26.9 KB → [llms/tools.3.txt](llms/tools.3.txt) 25.5 KB
 - **stitchkit/tools/contract**: [llms/tools-contract.txt](llms/tools-contract.txt) 0.2 KB
 - **stitchkit/tools/invoker**: [llms/tools-invoker.txt](llms/tools-invoker.txt) 0.2 KB
 - **stitchkit/tools/connections**: [llms/tools-connections.txt](llms/tools-connections.txt) 3.1 KB

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.103.1",
+  "version": "0.103.2",
   "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",