@desplega.ai/agent-swarm 1.123.0 → 1.124.0

package/src/tools/script-connections/tool.ts

@@ -11,7 +11,7 @@ import {
   upsertScriptConnection,
 } from "@/be/script-connections";
 import { can } from "@/rbac";
-import { createToolRegistrar } from "@/tools/utils";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
 import { resolveScopedResourceId, scopedResourceScopeIdSchema } from "@/utils/scoped-resource";
 
 const scriptConnectionsInputSchema = z.object({
@@ -92,11 +92,9 @@ const scriptConnectionsInputSchema = z.object({
   enabled: z.boolean().optional().describe("Whether the connection is enabled."),
 });
 
-const scriptConnectionsOutputSchema = z.object({
+const scriptConnectionsOutputSchema = swarmToolOutputSchema({
   yourAgentId: z.string().optional(),
-  success: z.boolean(),
-  message: z.string(),
-  connections: z.array(z.unknown()),
+  connections: z.array(z.unknown()).optional(),
 });
 
 type ScriptConnectionsArgs = z.infer<typeof scriptConnectionsInputSchema>;
@@ -148,14 +146,7 @@ export const registerScriptConnectionsTool = (server: McpServer) => {
     },
     async (args, requestInfo) => {
       if (!requestInfo.agentId) {
-        return {
-          content: [{ type: "text", text: 'Agent ID not found. Set the "X-Agent-ID" header.' }],
-          structuredContent: {
-            success: false,
-            message: 'Agent ID not found. Set the "X-Agent-ID" header.',
-            connections: [],
-          },
-        };
+        return toolErr('Agent ID not found. Set the "X-Agent-ID" header.');
       }
 
       const agent = getAgentById(requestInfo.agentId);
@@ -170,15 +161,9 @@ export const registerScriptConnectionsTool = (server: McpServer) => {
         source: "mcp",
       });
       if (!decision.allow) {
-        return {
-          content: [{ type: "text", text: "Only the lead can manage script connections." }],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: false,
-            message: "Only the lead can manage script connections.",
-            connections: [],
-          },
-        };
+        return toolErr("Only the lead can manage script connections.", {
+          data: { yourAgentId: requestInfo.agentId },
+        });
       }
 
       if (args.action === "list") {
@@ -186,101 +171,61 @@ export const registerScriptConnectionsTool = (server: McpServer) => {
         const provenanceLines = connections
           .filter((connection) => connection.kind === "openapi" || connection.baseUrl !== null)
           .map(baseUrlProvenanceText);
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Found ${connections.length} script connection(s).${provenanceLines.length ? `\n${provenanceLines.join("\n")}` : ""}`,
-            },
-          ],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: true,
-            message: `Found ${connections.length} script connection(s).`,
-            connections,
-          },
-        };
+        return toolOk(`Found ${connections.length} script connection(s).`, {
+          details: provenanceLines.length > 0 ? provenanceLines.join("\n") : undefined,
+          data: { yourAgentId: requestInfo.agentId, connections },
+        });
       }
 
       if (args.action === "disable") {
         if (!args.id) {
-          return {
-            content: [{ type: "text", text: "id is required for disable." }],
-            structuredContent: {
+          return toolErr("id is required for disable.", {
+            data: {
               yourAgentId: requestInfo.agentId,
-              success: false,
-              message: "id is required for disable.",
               connections: listScriptConnections({ includeDisabled: true, allScopes: true }),
             },
-          };
+          });
         }
         setScriptConnectionEnabled(args.id, false);
         const connections = listScriptConnections({ includeDisabled: true, allScopes: true });
-        return {
-          content: [{ type: "text", text: "Script connection disabled." }],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: true,
-            message: "Script connection disabled.",
-            connections,
-          },
-        };
+        return toolOk("Script connection disabled.", {
+          data: { yourAgentId: requestInfo.agentId, connections },
+        });
       }
 
       if (args.action === "refresh") {
         if (!args.id) {
-          return {
-            content: [{ type: "text", text: "id is required for refresh." }],
-            structuredContent: {
+          return toolErr("id is required for refresh.", {
+            data: {
               yourAgentId: requestInfo.agentId,
-              success: false,
-              message: "id is required for refresh.",
               connections: listScriptConnections({ includeDisabled: true, allScopes: true }),
             },
-          };
+          });
         }
         const refreshed = await refreshScriptConnection(args.id, null, requestInfo.agentId);
         const connections = listScriptConnections({ includeDisabled: true, allScopes: true });
         if (!refreshed) {
-          return {
-            content: [{ type: "text", text: "Script connection not found." }],
-            structuredContent: {
-              yourAgentId: requestInfo.agentId,
-              success: false,
-              message: "Script connection not found.",
-              connections,
-            },
-          };
+          return toolErr("Script connection not found.", {
+            data: { yourAgentId: requestInfo.agentId, connections },
+          });
         }
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Script connection ${refreshed.slug} refreshed (${baseUrlProvenanceText(refreshed)}).`,
-            },
-          ],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: !refreshed.generationError,
-            message: refreshed.generationError
-              ? `Refreshed but generation failed: ${refreshed.generationError}`
-              : `Script connection ${refreshed.slug} refreshed.`,
-            connections,
-          },
+        const extras = {
+          details: baseUrlProvenanceText(refreshed),
+          data: { yourAgentId: requestInfo.agentId, connections },
         };
+        return refreshed.generationError
+          ? toolErr(`Refreshed but generation failed: ${refreshed.generationError}`, extras)
+          : toolOk(`Script connection ${refreshed.slug} refreshed.`, extras);
       }
 
       if (args.action === "upsert-mcp") {
         if (!args.slug || !args.mcpServerId) {
-          return {
-            content: [{ type: "text", text: "slug and mcpServerId are required." }],
-            structuredContent: {
+          return toolErr("slug and mcpServerId are required.", {
+            data: {
               yourAgentId: requestInfo.agentId,
-              success: false,
-              message: "slug and mcpServerId are required.",
               connections: listScriptConnections({ includeDisabled: true, allScopes: true }),
             },
-          };
+          });
         }
 
         const existing = args.id ? getScriptConnectionById(args.id) : null;
@@ -298,30 +243,20 @@ export const registerScriptConnectionsTool = (server: McpServer) => {
         });
 
         const connections = listScriptConnections({ includeDisabled: true, allScopes: true });
-        return {
-          content: [{ type: "text", text: `Script MCP connection ${connection.slug} saved.` }],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: !connection.generationError,
-            message: connection.generationError
-              ? `Saved but generation failed: ${connection.generationError}`
-              : `Script MCP connection ${connection.slug} saved.`,
-            connections,
-          },
-        };
+        const extras = { data: { yourAgentId: requestInfo.agentId, connections } };
+        return connection.generationError
+          ? toolErr(`Saved but generation failed: ${connection.generationError}`, extras)
+          : toolOk(`Script MCP connection ${connection.slug} saved.`, extras);
       }
 
       if (args.action === "upsert-graphql") {
         if (!args.slug || !args.baseUrl || !args.allowedHosts?.length) {
-          return {
-            content: [{ type: "text", text: "slug, baseUrl, and allowedHosts are required." }],
-            structuredContent: {
+          return toolErr("slug, baseUrl, and allowedHosts are required.", {
+            data: {
               yourAgentId: requestInfo.agentId,
-              success: false,
-              message: "slug, baseUrl, and allowedHosts are required.",
               connections: listScriptConnections({ includeDisabled: true, allScopes: true }),
             },
-          };
+          });
         }
 
         const existing = args.id ? getScriptConnectionById(args.id) : null;
@@ -347,51 +282,30 @@ export const registerScriptConnectionsTool = (server: McpServer) => {
         });
 
         const connections = listScriptConnections({ includeDisabled: true, allScopes: true });
-        return {
-          content: [{ type: "text", text: `Script GraphQL connection ${connection.slug} saved.` }],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: !connection.generationError,
-            message: connection.generationError
-              ? `Saved but generation failed: ${connection.generationError}`
-              : `Script GraphQL connection ${connection.slug} saved.`,
-            connections,
-          },
-        };
+        const extras = { data: { yourAgentId: requestInfo.agentId, connections } };
+        return connection.generationError
+          ? toolErr(`Saved but generation failed: ${connection.generationError}`, extras)
+          : toolOk(`Script GraphQL connection ${connection.slug} saved.`, extras);
       }
 
       if (!args.slug || (!args.openapiSpecJson && !args.openapiSpecUrl && !args.specSource)) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: "slug and exactly one OpenAPI spec source (openapiSpecJson, openapiSpecUrl, or specSource) are required.",
+        return toolErr(
+          "slug and exactly one OpenAPI spec source (openapiSpecJson, openapiSpecUrl, or specSource) are required.",
+          {
+            data: {
+              yourAgentId: requestInfo.agentId,
+              connections: listScriptConnections({ includeDisabled: true, allScopes: true }),
             },
-          ],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: false,
-            message:
-              "slug and exactly one OpenAPI spec source (openapiSpecJson, openapiSpecUrl, or specSource) are required.",
-            connections: listScriptConnections({ includeDisabled: true, allScopes: true }),
           },
-        };
+        );
       }
       if ([args.openapiSpecJson, args.openapiSpecUrl, args.specSource].filter(Boolean).length > 1) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: "Provide exactly one OpenAPI spec source.",
-            },
-          ],
-          structuredContent: {
+        return toolErr("Provide exactly one OpenAPI spec source.", {
+          data: {
             yourAgentId: requestInfo.agentId,
-            success: false,
-            message: "Provide exactly one OpenAPI spec source.",
             connections: listScriptConnections({ includeDisabled: true, allScopes: true }),
           },
-        };
+        });
       }
 
       const existing = args.id ? getScriptConnectionById(args.id) : null;
@@ -421,22 +335,13 @@ export const registerScriptConnectionsTool = (server: McpServer) => {
       });
 
       const connections = listScriptConnections({ includeDisabled: true, allScopes: true });
-      return {
-        content: [
-          {
-            type: "text",
-            text: `Script connection ${connection.slug} saved (${baseUrlProvenanceText(connection)}).`,
-          },
-        ],
-        structuredContent: {
-          yourAgentId: requestInfo.agentId,
-          success: !connection.generationError,
-          message: connection.generationError
-            ? `Saved but generation failed: ${connection.generationError}`
-            : `Script connection ${connection.slug} saved.`,
-          connections,
-        },
+      const extras = {
+        details: baseUrlProvenanceText(connection),
+        data: { yourAgentId: requestInfo.agentId, connections },
       };
+      return connection.generationError
+        ? toolErr(`Saved but generation failed: ${connection.generationError}`, extras)
+        : toolOk(`Script connection ${connection.slug} saved.`, extras);
     },
   );
 };

package/src/tools/script-query-types.ts

@@ -9,7 +9,31 @@ import {
 } from "./script-common";
 
 export const SCRIPT_QUERY_TYPES_DESCRIPTION =
-  "Fetch the signature + the auto-generated `swarm-sdk.d.ts` (derived from the live MCP tool registry) + the `stdlib.d.ts` blobs — for IDE-style introspection before authoring or running a script. The same types are used by `script-upsert`'s typecheck pass, so they are authoritative.";
+  "Fetch the auto-generated `swarm-sdk.d.ts` (derived from the live MCP tool registry) + the `stdlib.d.ts` blobs — for IDE-style introspection before authoring or running a script. Pass `name` to also get that script's signature; omit it for the swarm-wide type surface. The same types are used by `script-upsert`'s typecheck pass, so they are authoritative.";
+
+function renderTypeBlobs(data: unknown): string | undefined {
+  if (typeof data !== "object" || data === null) return undefined;
+  const body = data as {
+    signature?: unknown;
+    argsJsonSchema?: unknown;
+    sdkTypes?: unknown;
+    stdlibTypes?: unknown;
+  };
+  const parts: string[] = [];
+  if (body.signature !== undefined && body.signature !== null) {
+    parts.push(`signature:\n${JSON.stringify(body.signature, null, 2)}`);
+  }
+  if (body.argsJsonSchema !== undefined && body.argsJsonSchema !== null) {
+    parts.push(`argsJsonSchema:\n${JSON.stringify(body.argsJsonSchema, null, 2)}`);
+  }
+  if (typeof body.sdkTypes === "string" && body.sdkTypes) {
+    parts.push(`swarm-sdk.d.ts:\n${body.sdkTypes}`);
+  }
+  if (typeof body.stdlibTypes === "string" && body.stdlibTypes) {
+    parts.push(`stdlib.d.ts:\n${body.stdlibTypes}`);
+  }
+  return parts.length > 0 ? parts.join("\n\n") : undefined;
+}
 
 export const registerScriptQueryTypesTool = (server: McpServer) => {
   createToolRegistrar(server)(
@@ -19,18 +43,34 @@ export const registerScriptQueryTypesTool = (server: McpServer) => {
       description: SCRIPT_QUERY_TYPES_DESCRIPTION,
       annotations: { readOnlyHint: true, openWorldHint: false },
       inputSchema: z.object({
-        name: scriptNameSchema.describe("Script name whose signature should be fetched."),
+        name: scriptNameSchema
+          .optional()
+          .describe(
+            "Optional script name whose signature should be fetched. Omit to get the swarm-wide sdk/stdlib type surface.",
+          ),
         scope: scriptScopeSchema.optional().describe("Optional scope for script resolution."),
       }),
       outputSchema: scriptToolOutputSchema,
     },
     async ({ name, scope }, requestInfo) => {
+      if (!name) {
+        return proxyScriptsApi({
+          method: "GET",
+          path: "/api/scripts/type-defs",
+          requestInfo,
+          successMessage: () => "Swarm script SDK + stdlib type definitions fetched.",
+          successDetails: renderTypeBlobs,
+          uncappedDetails: true,
+        });
+      }
       const query = scope ? `?scope=${encodeURIComponent(scope)}` : "";
       return proxyScriptsApi({
         method: "GET",
         path: `/api/scripts/${encodeURIComponent(name)}/types${query}`,
         requestInfo,
-        successMessage: () => "Script type query completed.",
+        successMessage: () => `Type definitions for script \`${name}\` fetched.`,
+        successDetails: renderTypeBlobs,
+        uncappedDetails: true,
       });
     },
   );

package/src/tools/script-run.ts

@@ -10,7 +10,39 @@ import {
 } from "./script-common";
 
 export const SCRIPT_RUN_DESCRIPTION =
-  "Run a named swarm-shared script (callable across agents and from workflow `swarm-script` nodes), OR inline source (auto-saved as scratch to the catalog). Use for swarm-visible, durable scripts. For local-only throwaway TS, use code-mode `run`.";
+  "Run a named swarm-shared script (callable across agents and from workflow `swarm-script` nodes), OR inline source (auto-saved as scratch to the catalog). Inline source executes without the `script-upsert` compile-time typecheck. Use for swarm-visible, durable scripts. For local-only throwaway TS, use code-mode `run`.";
+
+function renderRunOutput(data: unknown): string | undefined {
+  if (typeof data !== "object" || data === null) return undefined;
+  const body = data as {
+    result?: unknown;
+    stdout?: string;
+    durationMs?: number;
+    truncated?: { stdout?: boolean; stderr?: boolean };
+    autoSaved?: { slug?: string };
+    kvSaved?: { namespace?: string; key?: string };
+  };
+  const parts: string[] = [];
+  if (body.result !== undefined) {
+    parts.push(
+      `result:\n${typeof body.result === "string" ? body.result : JSON.stringify(body.result, null, 2)}`,
+    );
+  }
+  if (typeof body.stdout === "string" && body.stdout.trim()) {
+    parts.push(`stdout:\n${body.stdout.trim()}`);
+  }
+  const notes: string[] = [];
+  if (typeof body.durationMs === "number") notes.push(`${body.durationMs}ms`);
+  if (body.truncated?.stdout || body.truncated?.stderr) {
+    notes.push("output truncated by the runtime");
+  }
+  if (body.autoSaved?.slug) notes.push(`auto-saved as scratch script \`${body.autoSaved.slug}\``);
+  if (body.kvSaved?.key) {
+    notes.push(`output persisted to kv ${body.kvSaved.namespace}/${body.kvSaved.key}`);
+  }
+  if (notes.length > 0) parts.push(`(${notes.join("; ")})`);
+  return parts.length > 0 ? parts.join("\n\n") : undefined;
+}
 
 export const registerScriptRunTool = (server: McpServer) => {
   createToolRegistrar(server)(
@@ -21,7 +53,13 @@ export const registerScriptRunTool = (server: McpServer) => {
       annotations: { openWorldHint: true },
       inputSchema: z.object({
         name: scriptNameSchema.optional().describe("Name of a reusable script to run."),
-        source: z.string().min(1).optional().describe("Inline TypeScript source to run."),
+        source: z
+          .string()
+          .min(1)
+          .optional()
+          .describe(
+            'Inline TypeScript source to run without a compile-time typecheck. Must `export default async function (args, ctx)` — args FIRST, ctx second. Import `ScriptContext` from "swarm-sdk" for promotion-safe typing.',
+          ),
         args: z.unknown().optional().describe("JSON-serializable script arguments."),
         intent: z.string().default("").describe("Why this script is being run."),
         scope: scriptScopeSchema.optional().describe("Optional scope for named script resolution."),
@@ -45,6 +83,7 @@ export const registerScriptRunTool = (server: McpServer) => {
         body: args,
         requestInfo,
         successMessage: () => "Script run completed.",
+        successDetails: renderRunOutput,
       }),
   );
 };

package/src/tools/script-runs.ts

@@ -13,6 +13,66 @@ export const GET_SCRIPT_RUN_DESCRIPTION =
 export const LIST_SCRIPT_RUNS_DESCRIPTION =
   "List durable script workflow runs, optionally filtered by status or agent ID.";
 
+const JOURNAL_RENDER_LIMIT = 20;
+const JOURNAL_VALUE_CAP = 400;
+
+function journalValuePreview(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 > JOURNAL_VALUE_CAP
+    ? `${serialized.slice(0, JOURNAL_VALUE_CAP)}…`
+    : serialized;
+}
+
+function renderRunDetail(data: unknown): string | undefined {
+  if (typeof data !== "object" || data === null) return undefined;
+  const run = (data as { run?: Record<string, unknown> }).run;
+  if (!run) return undefined;
+  const lines: string[] = [];
+  if (typeof run.status === "string") lines.push(`status: ${run.status}`);
+  if (typeof run.error === "string" && run.error) lines.push(`error: ${run.error}`);
+  if (run.output !== undefined && run.output !== null) {
+    lines.push(`output: ${JSON.stringify(run.output)}`);
+  }
+  // Journal entries must reach the text channel — most harnesses never show
+  // the model structuredContent, and a bare count hides step outcomes.
+  const journal = (data as { journal?: unknown[] }).journal;
+  if (Array.isArray(journal) && journal.length > 0) {
+    lines.push(`journal (${journal.length} entr${journal.length === 1 ? "y" : "ies"}):`);
+    for (const raw of journal.slice(0, JOURNAL_RENDER_LIMIT)) {
+      const entry = (raw ?? {}) as Record<string, unknown>;
+      const key = String(entry.stepKey ?? entry.label ?? entry.id ?? "?");
+      const kind = typeof entry.stepType === "string" ? ` [${entry.stepType}]` : "";
+      const status = typeof entry.status === "string" ? ` ${entry.status}` : "";
+      const error =
+        typeof entry.error === "string" && entry.error ? ` — error: ${entry.error}` : "";
+      const output = error ? undefined : journalValuePreview(entry.output ?? entry.result);
+      lines.push(`- ${key}${kind}:${status}${error}${output ? ` — ${output}` : ""}`);
+    }
+    if (journal.length > JOURNAL_RENDER_LIMIT) {
+      lines.push(
+        `… +${journal.length - JOURNAL_RENDER_LIMIT} more entries (see structuredContent.data.journal)`,
+      );
+    }
+  }
+  return lines.length > 0 ? lines.join("\n") : undefined;
+}
+
+function renderRunsList(data: unknown): string | undefined {
+  if (typeof data !== "object" || data === null) return undefined;
+  const runs = (data as { runs?: unknown[] }).runs;
+  if (!Array.isArray(runs) || runs.length === 0) return undefined;
+  return runs
+    .map((entry) => {
+      const run = entry as Record<string, unknown>;
+      const name = typeof run.scriptName === "string" && run.scriptName ? ` ${run.scriptName}` : "";
+      const error = typeof run.error === "string" && run.error ? ` — ${run.error}` : "";
+      return `- ${String(run.id ?? "?")}${name}: ${String(run.status ?? "unknown")}${error}`;
+    })
+    .join("\n");
+}
+
 export const registerScriptRunsTools = (server: McpServer) => {
   const register = createToolRegistrar(server);
 
@@ -23,7 +83,12 @@ export const registerScriptRunsTools = (server: McpServer) => {
       description: LAUNCH_SCRIPT_RUN_DESCRIPTION,
       annotations: { openWorldHint: true },
       inputSchema: z.object({
-        source: z.string().min(1).describe("TypeScript script workflow source."),
+        source: z
+          .string()
+          .min(1)
+          .describe(
+            "TypeScript script workflow source. Must `export default async function (args, ctx)` — args FIRST, ctx second.",
+          ),
         args: z.unknown().optional().describe("JSON-serializable workflow arguments."),
         idempotencyKey: z
           .string()
@@ -83,6 +148,8 @@ export const registerScriptRunsTools = (server: McpServer) => {
               : "unknown";
           return `Script run ${id} status: ${status}.`;
         },
+        successDetails: renderRunDetail,
+        failureDetails: renderRunDetail,
       }),
   );
 
@@ -117,6 +184,7 @@ export const registerScriptRunsTools = (server: McpServer) => {
               : 0;
           return `Found ${Number.isFinite(total) ? total : 0} script run(s).`;
         },
+        successDetails: renderRunsList,
       });
     },
   );

package/src/tools/script-search.ts

@@ -6,6 +6,20 @@ import { proxyScriptsApi, scriptScopeSchema, scriptToolOutputSchema } from "./sc
 export const SCRIPT_SEARCH_DESCRIPTION =
   "Semantic search over swarm-shared TypeScript scripts (catalog persisted in the agent-swarm DB; callable from agents and workflows). For ephemeral throwaway TS on your local machine, use code-mode instead.";
 
+function renderSearchResults(data: unknown): string | undefined {
+  if (typeof data !== "object" || data === null) return undefined;
+  const results = (data as { results?: unknown[] }).results;
+  if (!Array.isArray(results) || results.length === 0) return undefined;
+  return results
+    .map((entry) => {
+      const item = entry as { name?: unknown; description?: unknown; score?: unknown };
+      const description =
+        typeof item.description === "string" && item.description ? ` — ${item.description}` : "";
+      return `- ${String(item.name ?? "?")}${description}`;
+    })
+    .join("\n");
+}
+
 export const registerScriptSearchTool = (server: McpServer) => {
   createToolRegistrar(server)(
     "script-search",
@@ -26,7 +40,16 @@ export const registerScriptSearchTool = (server: McpServer) => {
         path: "/api/scripts/search",
         body: args,
         requestInfo,
-        successMessage: () => "Script search completed.",
+        successMessage: (data) => {
+          const results =
+            typeof data === "object" &&
+            data !== null &&
+            Array.isArray((data as { results?: unknown[] }).results)
+              ? (data as { results: unknown[] }).results
+              : [];
+          return `Found ${results.length} script(s).`;
+        },
+        successDetails: renderSearchResults,
       }),
   );
 };

package/src/tools/script-upsert.ts

@@ -10,7 +10,7 @@ import {
 } from "./script-common";
 
 export const SCRIPT_UPSERT_DESCRIPTION =
-  "Persist a TypeScript script to the swarm catalog under your agent scope (or global if you're a lead). Other agents and workflow nodes will be able to find and run it. For local-only scripts, use code-mode `save`.";
+  'Typecheck and persist a TypeScript script to the swarm catalog under your agent scope (or global if you\'re a lead). Import `ScriptContext` from "swarm-sdk" for a real context type. Other agents and workflow nodes will be able to find and run it. For local-only scripts, use code-mode `save`.';
 
 export const registerScriptUpsertTool = (server: McpServer) => {
   createToolRegistrar(server)(
@@ -21,7 +21,12 @@ export const registerScriptUpsertTool = (server: McpServer) => {
       annotations: { openWorldHint: false },
       inputSchema: z.object({
         name: scriptNameSchema.describe("Stable script name within the selected scope."),
-        source: z.string().min(1).describe("TypeScript source with a default export function."),
+        source: z
+          .string()
+          .min(1)
+          .describe(
+            'TypeScript source, typechecked before saving. Must `export default async function (args, ctx)` — args FIRST, ctx second. Import `ScriptContext` from "swarm-sdk" to type `ctx`.',
+          ),
         description: z.string().default("").describe("Human-readable script description."),
         intent: z.string().default("").describe("Why this script exists."),
         scope: scriptScopeSchema.default("agent").describe("Persist under agent or global scope."),
@@ -37,7 +42,17 @@ export const registerScriptUpsertTool = (server: McpServer) => {
         path: "/api/scripts/upsert",
         body: args,
         requestInfo,
-        successMessage: () => "Script upsert completed.",
+        successMessage: (data) => {
+          const body = (data ?? {}) as {
+            name?: unknown;
+            version?: unknown;
+            contentDeduped?: unknown;
+          };
+          const name = typeof body.name === "string" ? body.name : args.name;
+          const version = typeof body.version === "number" ? ` v${body.version}` : "";
+          const deduped = body.contentDeduped ? " (content unchanged — deduped)" : "";
+          return `Script \`${name}\`${version} saved.${deduped}`;
+        },
       }),
   );
 };