@desplega.ai/agent-swarm 1.123.0 → 1.124.0

package/src/tools/utils.ts

@@ -12,9 +12,10 @@ import type {
   ServerRequest,
   ToolAnnotations,
 } from "@modelcontextprotocol/sdk/types.js";
+import * as z from "zod";
 import { withSpan } from "../otel";
 import type { PermissionVerb } from "../rbac/permissions";
-import { scrubSecrets } from "../utils/secret-scrubber";
+import { scrubObject, scrubSecrets } from "../utils/secret-scrubber";
 
 type Meta = RequestHandlerExtra<ServerRequest, ServerNotification>;
 
@@ -91,6 +92,183 @@ function toolResultAttributes(result: CallToolResult) {
   };
 }
 
+/**
+ * Canonical result every swarm MCP tool returns. The registrar — not the tool —
+ * composes the wire-level CallToolResult from it, so the text channel and
+ * structuredContent can never diverge (see runbooks/mcp-tool-results.md for the
+ * per-harness evidence behind this contract).
+ */
+export type SwarmToolData = Record<string, unknown>;
+
+export type SwarmToolResult<TData extends SwarmToolData = SwarmToolData> = {
+  /** Truthful outcome. Becomes `isError = !ok` and `structuredContent.success`. */
+  ok: boolean;
+  /** One-line summary. Required, non-empty — the first thing every harness shows the model. */
+  message: string;
+  /** Model-needed payload rendering (tables, lists, error detail). Appended to the text channel. */
+  details?: string;
+  /** Structured payload, spread into structuredContent alongside the envelope keys. */
+  data?: TData;
+  /** Single-sentence conditional steer, appended to BOTH channels. */
+  nudge?: string;
+  /**
+   * Skip the finalize pipeline's secret scrubbing for this result. ONLY for
+   * deliberate credential-reveal branches (oauth-access-token, script-apis
+   * create/rotate, get-config includeSecrets) whose entire purpose is handing
+   * the agent a secret — the central scrubber would otherwise redact the
+   * reveal. Everything else stays scrubbed.
+   */
+  allowSecretEgress?: boolean;
+};
+
+export const toolOk = <TData extends SwarmToolData = SwarmToolData>(
+  message: string,
+  extras: Omit<SwarmToolResult<TData>, "ok" | "message"> = {},
+): SwarmToolResult<TData> => ({ ok: true, message, ...extras });
+
+export const toolErr = <TData extends SwarmToolData = SwarmToolData>(
+  message: string,
+  extras: Omit<SwarmToolResult<TData>, "ok" | "message"> = {},
+): SwarmToolResult<TData> => ({ ok: false, message, ...extras });
+
+/**
+ * Envelope keys the registrar writes into structuredContent for every tool.
+ * Output schemas must include these and must be LOOSE (`z.looseObject`):
+ * plain `z.object` emits `additionalProperties: false`, which makes
+ * client-side validators (opencode's official-SDK client) reject the spread
+ * `data` keys after the write already landed.
+ */
+export const swarmToolEnvelopeShape = {
+  success: z.boolean(),
+  message: z.string(),
+  details: z.string().optional(),
+  nudge: z.string().optional(),
+};
+
+/** Build a permissive output schema: envelope + optional tool-specific data shape. */
+export const swarmToolOutputSchema = <S extends z.ZodRawShape>(dataShape?: S) =>
+  z.looseObject({ ...swarmToolEnvelopeShape, ...(dataShape ?? ({} as S)) });
+
+export const SCRIPT_AUTHORING_NUDGE =
+  "Scripts must `export default async function (args, ctx)` — args FIRST, ctx second; run script-query-types (no name) for the full ctx/SDK type surface, and see the `swarm-scripts` skill for authoring patterns.";
+
+// Only steer on failures plausibly caused by the script itself (typecheck or
+// runtime) — on lookup/transport/authorization errors the authoring advice
+// distracts from the reported problem.
+const scriptAuthoringNudge = (r: SwarmToolResult): string | undefined =>
+  !r.ok && /Typecheck failed:|Script run .*failed/.test(r.message)
+    ? SCRIPT_AUTHORING_NUDGE
+    : undefined;
+
+/**
+ * Central conditional nudges, keyed by tool name. Applied by the finalize
+ * pipeline when the tool did not set an explicit nudge. Keep entries to a
+ * single sentence; derive only from already-scrubbed result fields.
+ */
+export const NUDGES: Record<string, (result: SwarmToolResult) => string | undefined> = {
+  "script-run": scriptAuthoringNudge,
+  "script-upsert": scriptAuthoringNudge,
+  "launch-script-run": scriptAuthoringNudge,
+  "get-script-run": scriptAuthoringNudge,
+  "script-search": (r) => {
+    if (!r.ok) return undefined;
+    // proxyScriptsApi wraps the parsed HTTP body as data = { status, data },
+    // so the results array lives one level down.
+    const body = (r.data as { data?: { results?: unknown[] } } | undefined)?.data;
+    const results = body?.results;
+    return Array.isArray(results) && results.length === 0
+      ? "No scripts matched — the catalog ships seeded example scripts; re-run script-search with an empty query to list them."
+      : undefined;
+  },
+  "memory-search": (r) => {
+    if (!r.ok) return undefined;
+    const results = (r.data as { results?: Array<{ rateHint?: unknown }> } | undefined)?.results;
+    return Array.isArray(results) && results.some((entry) => Boolean(entry?.rateHint))
+      ? "Rate memories that help or mislead you with memory_rate."
+      : undefined;
+  },
+};
+
+// Cap for any rendered details string — Codex's ~10KB middle-out truncation is
+// the tightest harness budget. Structured data remains intact; only the
+// human/model-facing rendering is bounded.
+const DETAILS_CAP = 8_000;
+
+function truncateForText(text: string): string {
+  if (text.length <= DETAILS_CAP) return text;
+  return `${text.slice(0, DETAILS_CAP)}\n… [truncated ${text.length - DETAILS_CAP} chars]`;
+}
+
+type FinalizeContext = { toolName: string };
+type FinalizeMiddleware = (result: SwarmToolResult, ctx: FinalizeContext) => SwarmToolResult;
+
+const scrubMiddleware: FinalizeMiddleware = (result) =>
+  result.allowSecretEgress ? result : scrubObject(result);
+
+const nudgeMiddleware: FinalizeMiddleware = (result, ctx) => {
+  if (result.nudge) return result;
+  const nudge = NUDGES[ctx.toolName]?.(result);
+  return nudge ? { ...result, nudge } : result;
+};
+
+// Ordered: scrub first so nudges (and any future middleware) only ever see
+// scrubbed data. Future ctx-control middleware (response pruning, auto-KV
+// overflow) slots in between nudge and the final transform.
+const FINALIZE_PIPELINE: FinalizeMiddleware[] = [scrubMiddleware, nudgeMiddleware];
+
+/**
+ * Transform a SwarmToolResult into the wire CallToolResult. Both channels are
+ * composed identically and are independently self-sufficient: Codex reads only
+ * structuredContent, pi/opencode/claude-managed read only content.text.
+ * structuredContent is ALWAYS present (opencode's SDK client throws when a
+ * declared outputSchema has no structuredContent).
+ */
+export function finalizeSwarmToolResult(toolName: string, result: SwarmToolResult): CallToolResult {
+  let r = result;
+  if (!r.message?.trim()) {
+    console.warn(`[mcp] tool ${toolName} returned an empty message — every tool must summarize`);
+    r = {
+      ...r,
+      message: r.ok
+        ? "Tool call succeeded (no message provided)."
+        : "Tool call failed (no message provided).",
+    };
+  }
+  for (const middleware of FINALIZE_PIPELINE) r = middleware(r, { toolName });
+
+  // Normalize and cap explicit details only after the scrub middleware has
+  // removed secrets. The same bounded value feeds both wire channels.
+  // Whitespace-only details count as absent so data fallback remains visible.
+  const explicitDetails = r.details?.trim() ? truncateForText(r.details.trim()) : undefined;
+
+  // Text-channel completeness guarantee: when a tool sets data but no details,
+  // render the data as JSON into the text channel. Most harnesses only ever
+  // show the model content.text — without this fallback, a data-only payload
+  // would be invisible there. Not copied into structuredContent.details (the
+  // structured channel already carries data verbatim).
+  const dataFallback =
+    !explicitDetails && r.data && Object.keys(r.data).length > 0
+      ? truncateForText(JSON.stringify(r.data, null, 2))
+      : undefined;
+
+  const text = [r.message, explicitDetails ?? dataFallback, r.nudge]
+    .filter((part): part is string => Boolean(part?.trim()))
+    .join("\n\n");
+  const structuredContent: Record<string, unknown> = {
+    ...(r.data ?? {}),
+    success: r.ok,
+    message: r.message,
+  };
+  if (explicitDetails) structuredContent.details = explicitDetails;
+  if (r.nudge) structuredContent.nudge = r.nudge;
+
+  return {
+    content: [{ type: "text", text }],
+    structuredContent,
+    isError: !r.ok,
+  };
+}
+
 // Infer the input type from the schema
 type InferInput<Args extends undefined | ZodRawShapeCompat | AnySchema> =
   Args extends ZodRawShapeCompat
@@ -99,15 +277,16 @@ type InferInput<Args extends undefined | ZodRawShapeCompat | AnySchema> =
       ? SchemaOutput<Args>
       : undefined;
 
-// Callback type with requestInfo injected as second parameter
+// Callback type with requestInfo injected as second parameter.
+// Tools return SwarmToolResult (ours) — never a raw MCP CallToolResult.
 type ToolCallbackWithInfo<Args extends undefined | ZodRawShapeCompat | AnySchema = undefined> =
   Args extends undefined
-    ? (requestInfo: RequestInfo, meta: Meta) => CallToolResult | Promise<CallToolResult>
+    ? (requestInfo: RequestInfo, meta: Meta) => SwarmToolResult | Promise<SwarmToolResult>
     : (
         args: InferInput<Args>,
         requestInfo: RequestInfo,
         meta: Meta,
-      ) => CallToolResult | Promise<CallToolResult>;
+      ) => SwarmToolResult | Promise<SwarmToolResult>;
 
 type ToolConfig<
   InputArgs extends undefined | ZodRawShapeCompat | AnySchema,
@@ -155,12 +334,13 @@ export const createToolRegistrar = (server: McpServer) => {
         return withSpan(
           "mcp.tool",
           async (span) => {
-            const result = await (
+            const outcome = await (
               cb as (
                 requestInfo: RequestInfo,
                 meta: Meta,
-              ) => CallToolResult | Promise<CallToolResult>
+              ) => SwarmToolResult | Promise<SwarmToolResult>
             )(requestInfo, meta);
+            const result = finalizeSwarmToolResult(name, outcome);
             span.setAttributes(toolResultAttributes(result));
             return result;
           },
@@ -176,13 +356,14 @@ export const createToolRegistrar = (server: McpServer) => {
         // trace tree. Cardinality is bounded — tool names are a fixed enum.
         `mcp.tool ${name}`,
         async (span) => {
-          const result = await (
+          const outcome = await (
             cb as (
               args: InferInput<InputArgs>,
               requestInfo: RequestInfo,
               meta: Meta,
-            ) => CallToolResult | Promise<CallToolResult>
+            ) => SwarmToolResult | Promise<SwarmToolResult>
           )(args, requestInfo, meta);
+          const result = finalizeSwarmToolResult(name, outcome);
           span.setAttributes(toolResultAttributes(result));
           return result;
         },

package/src/tools/whatsapp-message.ts

@@ -2,16 +2,20 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
 import { sendKapsoText } from "@/integrations/kapso/client";
 import { getKapsoConfig } from "@/integrations/kapso/config";
-import { createToolRegistrar } from "@/tools/utils";
+import {
+  createToolRegistrar,
+  type SwarmToolResult,
+  swarmToolOutputSchema,
+  toolErr,
+  toolOk,
+} from "@/tools/utils";
 
 /** Shared structured-error message for the 24h session-window case. */
 const SESSION_WINDOW_HINT =
   'Outside the 24h WhatsApp session window — free-form text is rejected. Use a pre-approved template message (see the `kapso-whatsapp` skill, "Send a template").';
 
-const outputSchema = z.object({
+const outputSchema = swarmToolOutputSchema({
   yourAgentId: z.string().optional(),
-  success: z.boolean(),
-  message: z.string(),
   messageId: z.string().optional(),
   sessionWindowExpired: z.boolean().optional(),
 });
@@ -79,15 +83,13 @@ async function sendAndFormat(
   params: { phoneNumberId: string; to: string; body: string; previewUrl?: boolean },
   agentId: string | undefined,
   contextMessageId: string | undefined,
-) {
+): Promise<SwarmToolResult> {
   try {
     const config = getKapsoConfig();
     if (!config.apiKey) {
-      const msg = "KAPSO_API_KEY is not configured in swarm config.";
-      return {
-        content: [{ type: "text" as const, text: msg }],
-        structuredContent: { yourAgentId: agentId, success: false, message: msg },
-      };
+      return toolErr("KAPSO_API_KEY is not configured in swarm config.", {
+        data: { yourAgentId: agentId },
+      });
     }
 
     const result = await sendKapsoText({
@@ -102,34 +104,19 @@ async function sendAndFormat(
 
     if (result.ok) {
       const text = `Sent WhatsApp message to ${params.to} (wamid ${result.messageId ?? "unknown"})`;
-      return {
-        content: [{ type: "text" as const, text }],
-        structuredContent: {
-          yourAgentId: agentId,
-          success: true,
-          message: text,
-          messageId: result.messageId,
-        },
-      };
+      return toolOk(text, {
+        data: { yourAgentId: agentId, messageId: result.messageId },
+      });
     }
 
     const text = result.sessionWindowExpired
       ? `${SESSION_WINDOW_HINT} (Kapso: ${result.errorMessage})`
       : `Kapso send failed: ${result.errorMessage}`;
-    return {
-      content: [{ type: "text" as const, text }],
-      structuredContent: {
-        yourAgentId: agentId,
-        success: false,
-        message: text,
-        sessionWindowExpired: result.sessionWindowExpired,
-      },
-    };
+    return toolErr(text, {
+      data: { yourAgentId: agentId, sessionWindowExpired: result.sessionWindowExpired },
+    });
   } catch (err) {
     const errorMessage = err instanceof Error ? err.message : String(err);
-    return {
-      content: [{ type: "text" as const, text: `Error: ${errorMessage}` }],
-      structuredContent: { yourAgentId: agentId, success: false, message: errorMessage },
-    };
+    return toolErr(errorMessage, { data: { yourAgentId: agentId } });
   }
 }

package/src/tools/workflows/cancel-workflow-run.ts

@@ -1,6 +1,6 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { createToolRegistrar } from "@/tools/utils";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
 import { cancelWorkflowRun } from "@/workflows";
 
 export const registerCancelWorkflowRunTool = (server: McpServer) => {
@@ -15,26 +15,14 @@ export const registerCancelWorkflowRunTool = (server: McpServer) => {
         runId: z.string().uuid().describe("Workflow run ID to cancel"),
         reason: z.string().optional().describe("Optional reason for cancellation"),
       }),
-      outputSchema: z.object({
-        success: z.boolean(),
-        message: z.string(),
-      }),
+      outputSchema: swarmToolOutputSchema(),
     },
     async ({ runId, reason }) => {
       try {
         cancelWorkflowRun(runId, reason);
-        return {
-          content: [{ type: "text" as const, text: `Cancelled workflow run ${runId}.` }],
-          structuredContent: {
-            success: true,
-            message: `Cancelled workflow run ${runId}.`,
-          },
-        };
+        return toolOk(`Cancelled workflow run ${runId}.`);
       } catch (err) {
-        return {
-          content: [{ type: "text" as const, text: `Failed: ${err}` }],
-          structuredContent: { success: false, message: String(err) },
-        };
+        return toolErr(String(err));
       }
     },
   );

package/src/tools/workflows/create-workflow.ts

@@ -3,7 +3,7 @@ import { z } from "zod";
 import { authorizeAssetKeyWrite } from "@/be/asset-key-auth";
 import { resolveTaskAuditUserId } from "@/be/audit-user";
 import { createWorkflow } from "@/be/db";
-import { createToolRegistrar } from "@/tools/utils";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
 import {
   AssetKeySchema,
   CooldownConfigSchema,
@@ -84,10 +84,8 @@ export const registerCreateWorkflowTool = (server: McpServer) => {
               "Other JSON-Schema keywords are silently ignored.",
           ),
       }),
-      outputSchema: z.object({
+      outputSchema: swarmToolOutputSchema({
         yourAgentId: z.string().optional(),
-        success: z.boolean(),
-        message: z.string(),
         workflow: z.unknown().optional(),
       }),
     },
@@ -107,27 +105,13 @@ export const registerCreateWorkflowTool = (server: McpServer) => {
       requestInfo,
     ) => {
       if (!requestInfo.agentId) {
-        return {
-          content: [{ type: "text" as const, text: "Agent ID required." }],
-          structuredContent: { success: false, message: "Agent ID required." },
-        };
+        return toolErr("Agent ID required.");
       }
       try {
         // Validate definition structure
         const validation = validateDefinition(definition);
         if (!validation.valid) {
-          return {
-            content: [
-              {
-                type: "text" as const,
-                text: `Invalid definition: ${validation.errors.join("; ")}`,
-              },
-            ],
-            structuredContent: {
-              success: false,
-              message: `Invalid definition: ${validation.errors.join("; ")}`,
-            },
-          };
+          return toolErr(`Invalid definition: ${validation.errors.join("; ")}`);
         }
 
         const createdBy =
@@ -148,25 +132,12 @@ export const registerCreateWorkflowTool = (server: McpServer) => {
           createdByAgentId: requestInfo.agentId,
           createdBy,
         });
-        return {
-          content: [
-            {
-              type: "text" as const,
-              text: `Created workflow "${workflow.name}" (${workflow.id}).`,
-            },
-          ],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: true,
-            message: `Created workflow "${workflow.name}".`,
-            workflow,
-          },
-        };
+        return toolOk(`Created workflow "${workflow.name}".`, {
+          details: `Created workflow "${workflow.name}" (${workflow.id}).`,
+          data: { yourAgentId: requestInfo.agentId, workflow },
+        });
       } catch (err) {
-        return {
-          content: [{ type: "text" as const, text: `Failed: ${err}` }],
-          structuredContent: { success: false, message: String(err) },
-        };
+        return toolErr(String(err));
       }
     },
   );

package/src/tools/workflows/delete-workflow.ts

@@ -1,7 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { deleteWorkflow } from "@/be/db";
-import { createToolRegistrar } from "@/tools/utils";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
 
 export const registerDeleteWorkflowTool = (server: McpServer) => {
   createToolRegistrar(server)(
@@ -13,29 +13,17 @@ export const registerDeleteWorkflowTool = (server: McpServer) => {
       inputSchema: z.object({
         id: z.string().uuid().describe("Workflow ID to delete"),
       }),
-      outputSchema: z.object({
-        success: z.boolean(),
-        message: z.string(),
-      }),
+      outputSchema: swarmToolOutputSchema(),
     },
     async ({ id }) => {
       try {
         const deleted = deleteWorkflow(id);
         if (!deleted) {
-          return {
-            content: [{ type: "text" as const, text: `Workflow not found: ${id}` }],
-            structuredContent: { success: false, message: `Workflow not found: ${id}` },
-          };
+          return toolErr(`Workflow not found: ${id}`);
         }
-        return {
-          content: [{ type: "text" as const, text: `Deleted workflow ${id}.` }],
-          structuredContent: { success: true, message: `Deleted workflow ${id}.` },
-        };
+        return toolOk(`Deleted workflow ${id}.`);
       } catch (err) {
-        return {
-          content: [{ type: "text" as const, text: `Failed: ${err}` }],
-          structuredContent: { success: false, message: String(err) },
-        };
+        return toolErr(String(err));
       }
     },
   );

package/src/tools/workflows/get-workflow-run.ts

@@ -1,7 +1,39 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { getWorkflowRun, getWorkflowRunStepsByRunId } from "@/be/db";
-import { createToolRegistrar } from "@/tools/utils";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
+
+const STEP_VALUE_CAP = 400;
+
+function stepValuePreview(value: unknown): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  const serialized = typeof value === "string" ? value : JSON.stringify(value);
+  if (!serialized) return undefined;
+  return serialized.length > STEP_VALUE_CAP
+    ? `${serialized.slice(0, STEP_VALUE_CAP)}…`
+    : serialized;
+}
+
+function renderSteps(steps: ReturnType<typeof getWorkflowRunStepsByRunId>): string | undefined {
+  if (steps.length === 0) return undefined;
+  return steps
+    .map((step) => {
+      const nodeId = (step as { nodeId?: unknown }).nodeId ?? "?";
+      const status = (step as { status?: unknown }).status ?? "?";
+      const error = (step as { error?: unknown }).error;
+      const errorSuffix = typeof error === "string" && error ? ` — error: ${error}` : "";
+      // Step results must reach the text channel — details suppresses the
+      // JSON fallback, and text-only harnesses never see structured data.
+      const output = errorSuffix
+        ? undefined
+        : stepValuePreview((step as { output?: unknown }).output);
+      const outputSuffix = output ? ` — output: ${output}` : "";
+      const diagnostics = stepValuePreview((step as { diagnostics?: unknown }).diagnostics);
+      const diagnosticsSuffix = diagnostics ? ` — diagnostics: ${diagnostics}` : "";
+      return `- ${String(nodeId)}: ${String(status)}${errorSuffix}${outputSuffix}${diagnosticsSuffix}`;
+    })
+    .join("\n");
+}
 
 export const registerGetWorkflowRunTool = (server: McpServer) => {
   createToolRegistrar(server)(
@@ -13,46 +45,24 @@ export const registerGetWorkflowRunTool = (server: McpServer) => {
       inputSchema: z.object({
         id: z.string().uuid().describe("Workflow run ID"),
       }),
-      outputSchema: z.object({
-        success: z.boolean(),
-        message: z.string(),
+      outputSchema: swarmToolOutputSchema({
         run: z.unknown().optional(),
-        steps: z.array(z.unknown()),
+        steps: z.array(z.unknown()).optional(),
       }),
     },
     async ({ id }) => {
       try {
         const run = getWorkflowRun(id);
         if (!run) {
-          return {
-            content: [{ type: "text" as const, text: `Workflow run not found: ${id}` }],
-            structuredContent: {
-              success: false,
-              message: `Workflow run not found: ${id}`,
-              steps: [],
-            },
-          };
+          return toolErr(`Workflow run not found: ${id}`, { data: { steps: [] } });
         }
         const steps = getWorkflowRunStepsByRunId(id);
-        return {
-          content: [
-            {
-              type: "text" as const,
-              text: `Run ${id} — status: ${run.status}, steps: ${steps.length}.`,
-            },
-          ],
-          structuredContent: {
-            success: true,
-            message: `Run ${id} status: ${run.status}.`,
-            run,
-            steps,
-          },
-        };
+        return toolOk(`Run ${id} status: ${run.status}.`, {
+          details: renderSteps(steps),
+          data: { run, steps },
+        });
       } catch (err) {
-        return {
-          content: [{ type: "text" as const, text: `Failed: ${err}` }],
-          structuredContent: { success: false, message: String(err), steps: [] },
-        };
+        return toolErr(String(err), { data: { steps: [] } });
       }
     },
   );

package/src/tools/workflows/get-workflow.ts

@@ -1,7 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { getWorkflow } from "@/be/db";
-import { createToolRegistrar } from "@/tools/utils";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
 import { generateEdges } from "@/workflows/definition";
 
 export const registerGetWorkflowTool = (server: McpServer) => {
@@ -15,9 +15,7 @@ export const registerGetWorkflowTool = (server: McpServer) => {
       inputSchema: z.object({
         id: z.string().uuid().describe("Workflow ID"),
       }),
-      outputSchema: z.object({
-        success: z.boolean(),
-        message: z.string(),
+      outputSchema: swarmToolOutputSchema({
         workflow: z.unknown().optional(),
         edges: z.array(z.unknown()).optional(),
       }),
@@ -26,27 +24,18 @@ export const registerGetWorkflowTool = (server: McpServer) => {
       try {
         const workflow = getWorkflow(id);
         if (!workflow) {
-          return {
-            content: [{ type: "text" as const, text: `Workflow not found: ${id}` }],
-            structuredContent: { success: false, message: `Workflow not found: ${id}` },
-          };
+          return toolErr(`Workflow not found: ${id}`);
         }
         // Auto-generate edges for UI rendering
         const edges = generateEdges(workflow.definition);
-        return {
-          content: [{ type: "text" as const, text: `Workflow "${workflow.name}" (${id}).` }],
-          structuredContent: {
-            success: true,
-            message: `Workflow "${workflow.name}".`,
-            workflow,
-            edges,
-          },
-        };
+        return toolOk(`Workflow "${workflow.name}" (${id}).`, {
+          // The definition must reach the text channel — most harnesses never
+          // show the model structuredContent.
+          details: JSON.stringify(workflow, null, 2),
+          data: { workflow, edges },
+        });
       } catch (err) {
-        return {
-          content: [{ type: "text" as const, text: `Failed: ${err}` }],
-          structuredContent: { success: false, message: String(err) },
-        };
+        return toolErr(String(err));
       }
     },
   );