From 182b27b7d9b27d5c4deb4ee249707470dd6a3004 Mon Sep 17 00:00:00 2001
From: Etan Joseph Heyman <etan@heyman.net>
Date: Sat, 31 Oct 2026 14:48:40 +0200
Subject: [PATCH] fix(server): delegate_task and create_threads say where a
 target's providerInstanceId comes from

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../mcp/toolkits/orchestrator/tools.test.ts   | 20 +++++++++++++++++++
 .../src/provider/agentContextBudget.json      |  2 +-
 packages/contracts/src/orchestratorMcp.ts     |  7 ++++---
 3 files changed, 25 insertions(+), 4 deletions(-)

diff --git a/apps/server/src/mcp/toolkits/orchestrator/tools.test.ts b/apps/server/src/mcp/toolkits/orchestrator/tools.test.ts
index ea0caa4ce166a..39f104b638ce1 100644
--- a/apps/server/src/mcp/toolkits/orchestrator/tools.test.ts
+++ b/apps/server/src/mcp/toolkits/orchestrator/tools.test.ts
@@ -3,6 +3,7 @@ import * as Exit from "effect/Exit";
 import * as Schema from "effect/Schema";
 import { Tool } from "effect/ai";
 
+import { advertisedJsonSchema } from "../../advertisedJsonSchema.ts";
 import { OrchestratorToolkit } from "./tools.ts";
 
 // Oversized page sizes clamp on decode, so the schema has no `maximum`; Codex also drops
@@ -27,3 +28,22 @@ it("refuses a t3_thread_update whose fields do not fit its action", () => {
     true,
   );
 });
+
+it("tells agents where a target's providerInstanceId comes from", () => {
+  type Schema = {
+    readonly properties?: Record<string, Schema>;
+    readonly items?: Schema;
+    readonly description?: string;
+  };
+  const { delegate_task, create_threads } = OrchestratorToolkit.tools;
+  const delegate = advertisedJsonSchema(delegate_task) as Schema;
+  const threads = advertisedJsonSchema(create_threads) as Schema;
+  for (const target of [
+    delegate.properties?.target,
+    threads.properties?.threads?.items?.properties?.target,
+  ]) {
+    expect(target?.properties?.providerInstanceId?.description).toBe(
+      "From orchestrator_capabilities.",
+    );
+  }
+});
diff --git a/apps/server/src/provider/agentContextBudget.json b/apps/server/src/provider/agentContextBudget.json
index 07830f90d0567..f31468a25658e 100644
--- a/apps/server/src/provider/agentContextBudget.json
+++ b/apps/server/src/provider/agentContextBudget.json
@@ -1,5 +1,5 @@
 {
   "claudeSystemAppendBytes": 5129,
   "codexAdditionalContextBytes": 6859,
-  "mcpToolListJsonBytes": 46109
+  "mcpToolListJsonBytes": 46205
 }
diff --git a/packages/contracts/src/orchestratorMcp.ts b/packages/contracts/src/orchestratorMcp.ts
index 1474a5d6e87b6..7bffdd1f26ed4 100644
--- a/packages/contracts/src/orchestratorMcp.ts
+++ b/packages/contracts/src/orchestratorMcp.ts
@@ -95,9 +95,10 @@ export type OrchestratorMcpTargetOptions = typeof OrchestratorMcpTargetOptions.T
 
 export const OrchestratorMcpTarget = Schema.Struct({
   providerInstanceId: Schema.optional(
-    ProviderInstanceId.annotate({
-      description: "Provider instance id from `orchestrator_capabilities`.",
-    }),
+    // JSON Schema shows a transform's encoded side, so `.annotate` would never reach tools/list.
+    ProviderInstanceId.pipe(
+      Schema.annotateEncoded({ description: "From orchestrator_capabilities." }),
+    ),
   ),
   driverKind: Schema.optional(
     ProviderDriverKind.annotate({