@easysociable/cli 0.1.16 → 0.1.17

package/dist/easysociable.js

@@ -14621,9 +14621,9 @@ function convertBaseSchema(schema, ctx) {
           zodSchema = z.record(keySchema, valueSchema);
           break;
         }
-        const objectSchema3 = z.object(shape).passthrough();
+        const objectSchema2 = z.object(shape).passthrough();
         const recordSchema = z.looseRecord(keySchema, valueSchema);
-        zodSchema = z.intersection(objectSchema3, recordSchema);
+        zodSchema = z.intersection(objectSchema2, recordSchema);
         break;
       }
       if (schema.patternProperties) {
@@ -14653,13 +14653,13 @@ function convertBaseSchema(schema, ctx) {
         }
         break;
       }
-      const objectSchema2 = z.object(shape);
+      const objectSchema = z.object(shape);
       if (schema.additionalProperties === false) {
-        zodSchema = objectSchema2.strict();
+        zodSchema = objectSchema.strict();
       } else if (typeof schema.additionalProperties === "object") {
-        zodSchema = objectSchema2.catchall(convertSchema(schema.additionalProperties, ctx));
+        zodSchema = objectSchema.catchall(convertSchema(schema.additionalProperties, ctx));
       } else {
-        zodSchema = objectSchema2.passthrough();
+        zodSchema = objectSchema.passthrough();
       }
       break;
     }
@@ -31439,6 +31439,19 @@ var init_validate_tool_input = __esm({
 });
 
 // ../../packages/mcp-common/src/server.ts
+function mapAnnotations(tool) {
+  const isReadOnly = tool.effect === "read-only" || tool.effect === "explicit-owned-account-read";
+  const isDestructive = tool.effect === "explicit-approval" || tool.name.startsWith("delete_") || tool.name.startsWith("trash_");
+  const isIdempotent = isReadOnly || tool.name.startsWith("archive_") || tool.name.startsWith("restore_") || tool.name.startsWith("attest_");
+  return {
+    title: tool.title,
+    readOnlyHint: isReadOnly,
+    destructiveHint: isDestructive,
+    idempotentHint: isIdempotent,
+    openWorldHint: false,
+    effect: tool.effect
+  };
+}
 function createMcpServer(options) {
   const server = new Server(
     { name: options.name, version: options.version },
@@ -31450,7 +31463,8 @@ function createMcpServer(options) {
       title: tool.title,
       description: tool.description,
       inputSchema: tool.inputSchema,
-      annotations: { effect: tool.effect }
+      outputSchema: tool.outputSchema,
+      annotations: mapAnnotations(tool)
     }))
   }));
   server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({
@@ -31758,67 +31772,67 @@ var init_src4 = __esm({
       {
         name: "list_templates",
         title: "List templates",
-        description: "List public template catalog summaries from Gateway (filterable; no AST). Paged: follow nextCursor, or pass all=true with platforms to get the whole platform catalog before choosing. For Slideshow page choice prefer recommend_slideshow_templates.",
+        description: "List public template catalog summaries from Gateway (filterable by platform, role, density, canvasPreset). For Slideshow page template selection, prefer recommend_slideshow_templates. Alternatives: Use get_template to inspect specific slot requirements. Read-only catalog query.",
         effect: "read-only",
         inputSchema: {
           type: "object",
           properties: {
-            platforms: { type: "array", items: { type: "string" } },
-            roles: { type: "array", items: { type: "string" } },
-            contentFamily: { type: "string" },
-            contentArchetypes: { type: "array", items: { type: "string" } },
-            density: { type: "string" },
-            canvasPreset: { type: "string" },
-            requiresImage: { type: "boolean" },
-            locale: { type: "string" },
-            q: { type: "string" },
-            limit: { type: "number" },
-            cursor: { type: "string" },
-            all: { type: "boolean" }
+            platforms: { type: "array", items: { type: "string" }, description: "Platform filter: tiktok | linkedin | instagram | threads | xiaohongshu" },
+            roles: { type: "array", items: { type: "string" }, description: "Narrative role filter: hook | value | rehook | cta" },
+            contentFamily: { type: "string", description: "Content family filter." },
+            contentArchetypes: { type: "array", items: { type: "string" }, description: "Content archetypes list." },
+            density: { type: "string", description: "Density filter: sparse | normal | dense" },
+            canvasPreset: { type: "string", description: "Aspect ratio preset (e.g. 9:16, 4:5, 1:1, 3:4)." },
+            requiresImage: { type: "boolean", description: "Filter templates that require an image slot." },
+            locale: { type: "string", description: "Language/locale code (e.g. en, zh-CN)." },
+            q: { type: "string", description: "Search term matching template name or description." },
+            limit: { type: "number", description: "Max items per page." },
+            cursor: { type: "string", description: "Pagination cursor from previous nextCursor." },
+            all: { type: "boolean", description: "Fetch all matching templates across pages." }
           },
           additionalProperties: false
         },
-        outputSchema: { type: "object", properties: { templates: { type: "array" }, nextCursor: { type: ["string", "null"] } } }
+        outputSchema: { type: "object", properties: { templates: { type: "array", description: "Template summaries." }, nextCursor: { type: ["string", "null"], description: "Cursor for next page." } } }
       },
       {
         name: "get_template",
         title: "Get template",
-        description: "Get one published template detail including the public slots[] table (key/type/required/constraints). Use slots to fill create_render_job. Never returns AST or bindingMap.",
+        description: "Get one published template detail including the public slots[] table (key, type, required, constraints). Use slots to bind slide copy in create_slideshow_run or inspect template constraints. Alternatives: Use list_templates to browse catalog. Read-only catalog query.",
         effect: "read-only",
         inputSchema: {
           type: "object",
-          properties: { templateId: { type: "string" } },
+          properties: { templateId: { type: "string", description: "The unique published template identifier to retrieve." } },
           required: ["templateId"],
           additionalProperties: false
         },
         outputSchema: {
           type: "object",
           properties: {
-            id: { type: "string" },
-            slots: { type: "array" }
+            id: { type: "string", description: "Published template ID." },
+            slots: { type: "array", description: "Public slots table." }
           }
         }
       },
       {
         name: "list_gradients",
         title: "List gradients",
-        description: "List or search platform gradient recipe summaries by keyword query or tag (Gateway catalog only). Prefer small limit for Agent token budget.",
+        description: "List or search platform gradient recipe summaries by keyword query or tag. Call to discover gradient presets before styling cards. Alternatives: Use get_gradient to retrieve full CSS declaration for a specific gradientId. Read-only platform catalog query.",
         effect: "read-only",
         inputSchema: {
           type: "object",
           properties: {
-            tag: { type: "string" },
-            q: { type: "string" },
-            limit: { type: "number" }
+            tag: { type: "string", description: "Style tag filter (e.g. vibrant, subtle, dark, pastel)." },
+            q: { type: "string", description: "Search term matching gradient name or tone." },
+            limit: { type: "number", description: "Max items to return (prefer small limit for token budget)." }
           },
           additionalProperties: false
         },
-        outputSchema: { type: "object", properties: { gradients: { type: "array" } } }
+        outputSchema: { type: "object", properties: { gradients: { type: "array", description: "Array of gradient summaries." } } }
       },
       {
         name: "get_gradient",
         title: "Get gradient",
-        description: "Retrieve the full gradient CSS recipe (color stops, linear angle, and semantic tokens) for a specific gradient by gradientId. Use this after selecting a gradient from list_gradients to apply background styling or surface decoration to cards.",
+        description: "Retrieve the full gradient CSS recipe (linear angle, color stops, and semantic token values) for a specific gradient by gradientId. Call after list_gradients to materialize background styles or decorative surfaces on cards. Alternatives: Use list_gradients to search available recipes. Read-only platform catalog lookup. Returns full gradient recipe object.",
         effect: "read-only",
         inputSchema: {
           type: "object",
@@ -31828,12 +31842,12 @@ var init_src4 = __esm({
           required: ["gradientId"],
           additionalProperties: false
         },
-        outputSchema: { type: "object", properties: {} }
+        outputSchema: { type: "object", properties: { id: { type: "string", description: "Gradient preset identifier." }, css: { type: "string", description: "Full CSS linear-gradient declaration." } } }
       },
       {
         name: "search_icons",
         title: "Search icons",
-        description: "Search the internal Template Icon Catalog (Gateway-only; allowlisted Iconify collections). Read-only \u2014 does not materialize assets. Prefer \u22648 candidates and wait for user confirmation before get_icon.",
+        description: "Search the internal safe Template Icon Catalog (curated Iconify collections) by keyword, collection, or visual style. Use when designing templates or adding icon decorations. Select \u22648 candidates and confirm choice before materializing. Alternatives: Call get_icon once an iconId is selected to generate the immutable asset. Read-only catalog search; does not consume quota.",
         effect: "read-only",
         inputSchema: {
           type: "object",
@@ -31846,12 +31860,12 @@ var init_src4 = __esm({
           required: ["query"],
           additionalProperties: false
         },
-        outputSchema: { type: "object", properties: { icons: { type: "array" } } }
+        outputSchema: { type: "object", properties: { icons: { type: "array", description: "Candidate icons array with id, name, and previewSvg." } } }
       },
       {
         name: "get_icon",
         title: "Get / materialize icon",
-        description: "After the user confirms one search_icons candidate, materialize an immutable TemplateIconAsset via Gateway. Requires idempotencyKey. Returns canonicalSvg + iconAssetId. Never call Iconify or Better Icons from the client.",
+        description: "Materialize an immutable TemplateIconAsset via Gateway from a confirmed iconId. Call after confirming a candidate from search_icons. Requires idempotencyKey to prevent duplicate creation. Idempotent: repeated calls with identical keys return the existing asset without consuming extra quota. Returns canonical SVG string, iconAssetId, and contentHash.",
         effect: "local-write-job",
         inputSchema: {
           type: "object",
@@ -31865,28 +31879,28 @@ var init_src4 = __esm({
         outputSchema: {
           type: "object",
           properties: {
-            iconAssetId: { type: "string" },
-            canonicalSvg: { type: "string" },
-            contentHash: { type: "string" }
+            iconAssetId: { type: "string", description: "Permanent immutable icon asset ID." },
+            canonicalSvg: { type: "string", description: "Optimized sanitized SVG code." },
+            contentHash: { type: "string", description: "SHA-256 hash of the SVG content." }
           }
         }
       },
       {
         name: "list_drafts",
         title: "List authoring drafts",
-        description: "List all template authoring drafts for the current account owner. Returns draft summaries with validation status, name, and timestamps. Use to resume an authoring session or find draft IDs before updating or publishing.",
+        description: "List all template authoring drafts for the current account owner. Returns draft summaries with validation status, name, and timestamps. Use to resume an authoring session or discover draft IDs before updating or publishing. Alternatives: Use get_template_draft when you have a draftId to inspect full layer AST. Read-only query scoped to account owner.",
         effect: "read-only",
         inputSchema: {
           type: "object",
           properties: {},
           additionalProperties: false
         },
-        outputSchema: { type: "object", properties: { drafts: { type: "array" } } }
+        outputSchema: { type: "object", properties: { drafts: { type: "array", description: "Array of draft summary objects." } } }
       },
       {
         name: "create_draft",
         title: "Create authoring draft",
-        description: "Initialize a new Page Template draft for authoring. Returns draftId and an interactive authoringStudioUrl for real-time visual canvas editing before publishing. Call this to create custom template layouts.",
+        description: "Initialize a new Page Template draft for authoring with custom layout, layers, and slot contracts. Use when authoring a new slide template from scratch. Do NOT use to edit an existing draft (use update_template_draft) or browse public templates (use list_templates). Requires workspace owner authorization. Returns created TemplateDraft record with draftId and interactive authoringStudioUrl for real-time visual canvas editing.",
         effect: "local-write-job",
         inputSchema: {
           type: "object",
@@ -31900,12 +31914,12 @@ var init_src4 = __esm({
           required: ["name"],
           additionalProperties: false
         },
-        outputSchema: { type: "object", properties: { id: { type: "string" }, authoringStudioUrl: { type: "string" } } }
+        outputSchema: { type: "object", properties: { id: { type: "string", description: "Unique draft ID." }, authoringStudioUrl: { type: "string", description: "Direct browser link to Studio visual canvas editor." } } }
       },
       {
         name: "get_draft",
         title: "Get authoring draft",
-        description: "Fetch full authoring draft detail by draftId including layer canvas tree, slot contracts, theme bindings, and validation errors. Call this to inspect or validate a draft prior to updating or publishing.",
+        description: "Fetch complete authoring draft details by draftId, including full layer AST, slot contract definitions, theme bindings, and validation error logs. Call before update_template_draft or publish_template_draft to inspect draft structure and check validation status. Alternatives: Use list_template_drafts to discover draftIds. Read-only query scoped to draft owner. Returns full TemplateDraft AST entity.",
         effect: "read-only",
         inputSchema: {
           type: "object",
@@ -31915,31 +31929,31 @@ var init_src4 = __esm({
           required: ["draftId"],
           additionalProperties: false
         },
-        outputSchema: { type: "object", properties: { id: { type: "string" } } }
+        outputSchema: { type: "object", properties: { id: { type: "string", description: "Draft ID." }, name: { type: "string", description: "Draft name." }, authoringSource: { type: "object", description: "Layer AST and slots." } } }
       },
       {
         name: "update_draft",
         title: "Update authoring draft",
-        description: "Update properties of an existing authoring draft. Modifies layer nodes, slot definitions, selection metadata, or theme tokens. Re-validates layout rules upon save. Call this to iteratively refine draft designs.",
+        description: "Update layer AST, slot definitions, selection metadata, or theme tokens of an existing template authoring draft by draftId. Call iteratively to refine draft layout and slot contracts during authoring. Do NOT use to create new drafts (use create_template_draft), view draft AST (use get_template_draft), or release to public catalog (use publish_template_draft). Requires draft owner authorization. Performs safe partial patch: unmentioned properties remain untouched. Automatically triggers layout rule validation on save; returns validation warnings if constraints are breached. Returns updated TemplateDraft record with latest validation status and AST snapshot.",
         effect: "local-write-job",
         inputSchema: {
           type: "object",
           properties: {
             draftId: { type: "string", description: "The unique draft identifier to update." },
             name: { type: "string", description: "Updated template title." },
-            authoringSource: { type: "object", additionalProperties: true, description: "Updated template AST layout structure." },
+            authoringSource: { type: "object", additionalProperties: true, description: "Updated template AST layout structure and slot bindings." },
             selectionMetadata: { type: "object", additionalProperties: true, description: "Updated platform and family metadata." },
             theme: { type: "object", additionalProperties: true, description: "Updated theme tokens." }
           },
           required: ["draftId"],
           additionalProperties: false
         },
-        outputSchema: { type: "object", properties: { id: { type: "string" } } }
+        outputSchema: { type: "object", properties: { id: { type: "string", description: "Draft ID." }, validationStatus: { type: "string", description: "Validation status: valid | warnings | errors" } } }
       },
       {
         name: "delete_draft",
         title: "Delete authoring draft",
-        description: "Permanently discard and delete a template authoring draft. Destructive operation requiring confirmation: draft canvas data and unpublished changes cannot be recovered.",
+        description: "Permanently delete a template authoring draft by draftId. Call only when abandoning a draft that should be permanently destroyed. If the draft is complete and ready for production, call publish_template_draft instead. Destructive operation requiring explicit user confirmation: draft canvas data, layer AST, and unpublished revisions cannot be recovered. Returns deletion confirmation record.",
         effect: "explicit-approval",
         inputSchema: {
           type: "object",
@@ -31949,12 +31963,12 @@ var init_src4 = __esm({
           required: ["draftId"],
           additionalProperties: false
         },
-        outputSchema: { type: "object", properties: {} }
+        outputSchema: { type: "object", properties: { draftId: { type: "string", description: "Deleted draft ID." }, deleted: { type: "boolean", description: "True if deletion confirmed." } } }
       },
       {
         name: "publish_draft",
         title: "Publish authoring draft",
-        description: "Validate and publish an authoring draft into the immutable public or workspace template catalog. Once published, the template becomes immutable and can be instantiated into multi-page slideshow runs.",
+        description: "Validate and publish an authoring draft into the public or workspace template catalog. Call when draft design and slot contracts are finalized and ready for instantiation in slideshow runs. If still editing or fixing layout rules, use update_template_draft. To inspect validation before publishing, use get_template_draft. Promotes draft to an immutable published template. Validates AST against layout rules; fails if required slots or constraints are violated. Returns published Template entity with public templateId, slots table, and catalog status.",
         effect: "local-write-job",
         inputSchema: {
           type: "object",
@@ -31964,7 +31978,7 @@ var init_src4 = __esm({
           required: ["draftId"],
           additionalProperties: false
         },
-        outputSchema: { type: "object", properties: { id: { type: "string" }, status: { type: "string" } } }
+        outputSchema: { type: "object", properties: { id: { type: "string", description: "Published template ID." }, status: { type: "string", description: "Catalog status (published)." }, slots: { type: "array", description: "Public slots table." } } }
       },
       {
         name: "create_preview_job",
@@ -31984,29 +31998,29 @@ var init_src4 = __esm({
       {
         name: "import_template_image",
         title: "Import template image",
-        description: "Upload an image asset specifically attached to a template draft canvas (for general brand/media library assets, use import_image).",
+        description: "Upload and attach a transient image asset specifically to a template draft canvas. Call while authoring a template draft in canvas studio to place background or sample imagery. Do NOT use for general workspace media library assets, logos, and photos (use import_image instead). Requires draft owner authorization and idempotencyKey. Idempotent: duplicate uploads with identical idempotencyKey return the existing asset. Returns created template image asset with imageId, dimensions, and public CDN preview URL.",
         effect: "local-write-job",
         inputSchema: {
           type: "object",
           properties: {
-            draftId: { type: "string" },
-            fileName: { type: "string" },
-            mimeType: { type: "string", description: "image/jpeg | image/png | image/webp" },
-            dataBase64: { type: "string" },
-            provider: { type: "string", description: "pinterest | unsplash | pexels | user_upload | generated" },
-            rightsStatus: { type: "string", description: "rights_unknown | licensed_for_publish | user_owned | generated" },
-            idempotencyKey: { type: "string" },
-            sourceUrl: { type: "string" },
-            externalId: { type: "string" },
-            creator: { type: "string" },
-            license: { type: "string" },
-            attribution: { type: "string" },
-            searchQuery: { type: "string" }
+            draftId: { type: "string", description: "The unique template draft ID this image is attached to." },
+            fileName: { type: "string", description: "Original image filename (e.g. background.jpg)." },
+            mimeType: { type: "string", description: "MIME type: image/jpeg | image/png | image/webp" },
+            dataBase64: { type: "string", description: "Base64-encoded image binary string." },
+            provider: { type: "string", description: "Asset origin provider: pinterest | unsplash | pexels | user_upload | generated" },
+            rightsStatus: { type: "string", description: "Rights ownership status: rights_unknown | licensed_for_publish | user_owned | generated" },
+            idempotencyKey: { type: "string", description: "Unique idempotency key to prevent duplicate image creation." },
+            sourceUrl: { type: "string", description: "Optional source URL if fetched from web." },
+            externalId: { type: "string", description: "Optional external asset ID from provider." },
+            creator: { type: "string", description: "Optional author or photographer attribution name." },
+            license: { type: "string", description: "Optional license type identifier." },
+            attribution: { type: "string", description: "Optional human-readable attribution string." },
+            searchQuery: { type: "string", description: "Optional search keyword that discovered this image." }
           },
           required: ["draftId", "fileName", "mimeType", "dataBase64", "provider", "rightsStatus", "idempotencyKey"],
           additionalProperties: false
         },
-        outputSchema: { type: "object", properties: { imageId: { type: "string" }, url: { type: "string" } } }
+        outputSchema: { type: "object", properties: { imageId: { type: "string", description: "Created template image ID." }, url: { type: "string", description: "Public delivery URL." } } }
       }
     ];
     TemplateGatewayMcpBackend = class {
@@ -32173,18 +32187,17 @@ var init_src4 = __esm({
 function meta3() {
   return { requestId: `mcp_${Date.now().toString(36)}`, runtimeVersion: "0.0.0", schemaVersion: 1, toolContractVersion: "2026-08-12" };
 }
-var objectSchema, slideshowToolRegistry, slideshowResourceTemplates, SlideshowMcpBackend;
+var slideshowToolRegistry, slideshowResourceTemplates, SlideshowMcpBackend;
 var init_src5 = __esm({
   "../../packages/slideshow-mcp-adapter/src/index.ts"() {
     "use strict";
     init_src3();
     init_src2();
-    objectSchema = { type: "object", properties: {}, additionalProperties: true };
     slideshowToolRegistry = [
       {
         name: "list_runs",
         title: "List slideshow runs",
-        description: "List owner-scoped Slideshow Runs with optional platform, status, or search query filters. Returns run metadata, platform, page counts, and timestamps. Follow pagination to inspect existing carousel projects and draft runs.",
+        description: "List owner-scoped Slideshow Runs with optional platform, lifecycle status, or search query filters. Returns run metadata, platform target, page counts, revision numbers, and timestamps. Call to browse existing carousels or find a runId before inspection, updating, or archiving. Alternatives: Use get_slideshow_run when you already have a specific runId to fetch full slide content. Behavior: Read-only query scoped to current authenticated workspace owner.",
         effect: "read-only",
         inputSchema: {
           type: "object",
@@ -32199,12 +32212,12 @@ var init_src5 = __esm({
           },
           additionalProperties: true
         },
-        outputSchema: objectSchema
+        outputSchema: { type: "object", properties: { runs: { type: "array", description: "Array of slideshow run summary items." }, total: { type: "number", description: "Total count of matching runs." } } }
       },
       {
         name: "recommend_templates",
         title: "Recommend slideshow page templates",
-        description: "Before create_run: send the Page Contracts (role, density, slotSummary per page) and get a shortlist per page with reasons. Recently used Layout Families are demoted and one unused family is always kept. Pick one templateId per page yourself; gaps list pages needing more templates.",
+        description: "Recommend curated template options for each slide in a slideshow before run creation based on narrative page contracts (role, density, image requirement). Demotes recently used layout families to prevent visual monotony and guarantees diversity across slides. Call immediately before create_slideshow_run to select templateId per slide. Alternatives: Use list_templates to browse raw catalog. Behavior: Read-only stateless layout intelligence query.",
         effect: "read-only",
         inputSchema: {
           type: "object",
@@ -32231,12 +32244,12 @@ var init_src5 = __esm({
           required: ["platform", "pages"],
           additionalProperties: true
         },
-        outputSchema: objectSchema
+        outputSchema: { type: "object", properties: { recommendations: { type: "array", description: "Ranked template recommendations per page." }, gaps: { type: "array", description: "Pages requiring more templates." } } }
       },
       {
         name: "create_run",
         title: "Create slideshow run",
-        description: "Create a durable multi-page Slideshow Run from a structured content-pack.v1 (pages with role, templateId, and filled slot copy). Returns runId and interactive Studio review URL for browser preview and PNG pack download.",
+        description: "Create a durable multi-page Slideshow Run from a structured ContentPack (specifying platform, pages array with bound templateId and slot text values). Call recommend_slideshow_templates first to select templates. Do NOT use to edit an existing run (use update_slideshow_run instead). Requires workspace owner write authorization. Returns created SlideshowRun record with generated runId, initial revision (1), and authoringStudioUrl for interactive browser review and PNG download.",
         effect: "local-write-job",
         inputSchema: {
           type: "object",
@@ -32249,12 +32262,12 @@ var init_src5 = __esm({
           required: ["pack"],
           additionalProperties: true
         },
-        outputSchema: objectSchema
+        outputSchema: { type: "object", properties: { runId: { type: "string", description: "Unique identifier of the created run." }, revision: { type: "number", description: "Initial revision number (1)." }, studioUrl: { type: "string", description: "Studio preview and download URL." } } }
       },
       {
         name: "get_run",
         title: "Get slideshow run",
-        description: "Retrieve full details of a Slideshow Run by runId, including page list, bound template IDs, filled slot content, theme snapshot, and studio edit URL.",
+        description: "Retrieve full details of an existing Slideshow Run by runId, including complete slide pages, bound template IDs, slot contents, brand theme snapshot, current revision number, and studio review URL. Call before update_slideshow_run to inspect current slide contents and capture baseRevision for concurrency locking. Alternatives: Use list_slideshow_runs to discover runIds. Read-only query scoped to authenticated workspace owner.",
         effect: "read-only",
         inputSchema: {
           type: "object",
@@ -32264,24 +32277,24 @@ var init_src5 = __esm({
           required: ["runId"],
           additionalProperties: true
         },
-        outputSchema: objectSchema
+        outputSchema: { type: "object", properties: { runId: { type: "string", description: "Unique run identifier." }, revision: { type: "number", description: "Current revision number." }, pages: { type: "array", description: "Slide pages array." }, studioUrl: { type: "string", description: "Studio review URL." } } }
       },
       {
         name: "update_run",
         title: "Update slideshow run",
-        description: "Update slide copy, slot bindings, theme overrides, or presentation preferences of an existing Slideshow Run. Uses optimistic concurrency revision lock to prevent overwrite conflicts.",
+        description: "Partially update slide copy, slot bindings, layout, styling, or brand settings of an existing Slideshow Run by runId. Call get_slideshow_run first to obtain current revision and slide data. Do NOT use to create new runs (use create_slideshow_run) or delete runs (use delete_slideshow_run). Safe partial patch: unspecified fields are preserved. Requires baseRevision for optimistic concurrency locking; on revision mismatch returns 409 Conflict (no auto-merge), requiring a fresh get_slideshow_run. To patch a single slide, provide pageIndex (0-indexed) with slots, layout, or style. To update entire deck, provide pack. Returns updated SlideshowRun with incremented revision number.",
         effect: "local-write-job",
         inputSchema: {
           type: "object",
           properties: {
             runId: { type: "string", description: "The unique Slideshow Run identifier to update." },
-            baseRevision: { type: "integer", minimum: 1, description: "Current revision number for optimistic concurrency locking to prevent overwrite races." },
-            pack: { type: "object", description: "Updated complete content-pack.v1 structure." },
-            brandId: { type: "string", description: "Updated Brand ID styling reference." },
+            baseRevision: { type: "integer", minimum: 1, description: "Current revision number for optimistic concurrency locking to prevent overwrite races. Must match latest revision from get_slideshow_run." },
+            pack: { type: "object", description: "Updated complete content-pack.v1 structure. Overrides entire slide deck when provided." },
+            brandId: { type: "string", description: "Updated Brand ID styling reference applied across slides." },
             brandProfileId: { type: "string", description: "Optional legacy brand profile ID." },
             contentSlug: { type: "string", description: "Updated content topic slug." },
-            pageIndex: { type: "integer", minimum: 0, description: "Index of a single slide page to patch (0-indexed)." },
-            slots: { type: "object", description: "Key-value map of slot overrides for the specified pageIndex." },
+            pageIndex: { type: "integer", minimum: 0, description: "Index of a single slide page to patch (0-indexed). Must be paired with slots, layout, style, or decorations." },
+            slots: { type: "object", description: "Key-value map of slot text/image overrides for the specified pageIndex." },
             layout: { type: "object", description: "Layout adjustments for the specified pageIndex." },
             style: { type: "object", description: "Style token adjustments for the specified pageIndex." },
             decorations: { type: "array", description: "Visual decorations list for the specified pageIndex." }
@@ -32289,12 +32302,12 @@ var init_src5 = __esm({
           required: ["runId"],
           additionalProperties: true
         },
-        outputSchema: objectSchema
+        outputSchema: { type: "object", properties: { runId: { type: "string", description: "Run identifier." }, revision: { type: "number", description: "Incremented revision number." }, studioUrl: { type: "string", description: "Studio review URL." } } }
       },
       {
         name: "archive_run",
         title: "Archive slideshow run",
-        description: "Archive a Slideshow Run to declutter the workspace and hide it from default project lists while keeping all generated slides and review URLs intact. Reversible via restore_slideshow_run.",
+        description: "Soft-hide an active Slideshow Run from default workspace lists and pickers without deleting slide data or review URLs. Use to declutter the workspace after campaign completion. Do NOT use for permanent destruction; use delete_slideshow_run instead. Idempotent state change, fully reversible via restore_slideshow_run. Preserves all slide records, rendered assets, and external links. Returns updated SlideshowRun with status set to archived.",
         effect: "local-write-job",
         inputSchema: {
           type: "object",
@@ -32304,12 +32317,12 @@ var init_src5 = __esm({
           required: ["runId"],
           additionalProperties: true
         },
-        outputSchema: objectSchema
+        outputSchema: { type: "object", properties: { runId: { type: "string", description: "Run identifier." }, status: { type: "string", description: "Updated status (archived)." } } }
       },
       {
         name: "restore_run",
         title: "Restore slideshow run",
-        description: "Restore a previously archived or trashed Slideshow Run back to active workspace status, restoring it to the default projects view.",
+        description: "Restore a previously archived or trashed Slideshow Run back to active workspace status, restoring it to the default projects view. Use to reactivate an archived or trashed carousel project. Alternatives: Use get_slideshow_run to inspect run contents before restoring. Idempotent state change. Returns restored SlideshowRun record visible in default workspace listings.",
         effect: "local-write-job",
         inputSchema: {
           type: "object",
@@ -32319,12 +32332,12 @@ var init_src5 = __esm({
           required: ["runId"],
           additionalProperties: true
         },
-        outputSchema: objectSchema
+        outputSchema: { type: "object", properties: { runId: { type: "string", description: "Run identifier." }, status: { type: "string", description: "Restored status (active)." } } }
       },
       {
         name: "delete_run",
         title: "Delete slideshow run",
-        description: "Permanently delete a Slideshow Run and its associated slide page records. Destructive operation requiring explicit user confirmation; studio review link will become invalid.",
+        description: "Move a Slideshow Run to trash or permanently remove it from the workspace along with its slide page records. Use only when a run is obsolete and permanently discarded. Alternatives: If you only want to hide the run from active lists while preserving review links and data, use archive_slideshow_run instead. Destructive operation requiring explicit user confirmation. Invalidates studio review URLs. Returns deletion confirmation record.",
         effect: "explicit-approval",
         inputSchema: {
           type: "object",
@@ -32334,7 +32347,7 @@ var init_src5 = __esm({
           required: ["runId"],
           additionalProperties: true
         },
-        outputSchema: objectSchema
+        outputSchema: { type: "object", properties: { runId: { type: "string", description: "Deleted run identifier." }, deleted: { type: "boolean", description: "True if deletion confirmed." } } }
       }
     ];
     slideshowResourceTemplates = [
@@ -32441,15 +32454,15 @@ var init_src6 = __esm({
       {
         name: "list_brands",
         title: "List brands",
-        description: "List owner-scoped Brands with typography tokens, color palettes, and logos. Use to discover available brand identities before creating or styling slideshow runs.",
+        description: "List owner-scoped Brands with typography tokens, color palettes, and logos. Call to discover available brand identities before creating or styling slideshow runs. Alternatives: Use get_brand when you have a specific brandId to inspect full tokens. Read-only query scoped to current workspace owner. Returns array of Brand summaries.",
         effect: "read-only",
         inputSchema: { type: "object", properties: {}, additionalProperties: false },
-        outputSchema: { type: "object", properties: {} }
+        outputSchema: { type: "object", properties: { brands: { type: "array", description: "Array of brand kit summaries." } } }
       },
       {
         name: "get_brand",
         title: "Get brand",
-        description: "Fetch a complete Brand profile by brandId, including typography tokens, 4-color palette (primary, secondary, accent, surface), logoAssetId, and baseRevision. Call this before generating branded slides to inject brand styles.",
+        description: "Fetch a complete Brand profile by brandId, including typography tokens, 4-color palette (primary, secondary, accent, surface), logoAssetId, and baseRevision. Call before generating or updating branded slides to inject brand styles and capture baseRevision. Alternatives: Use list_brands to discover brandIds. Read-only query scoped to workspace owner. Returns full Brand entity.",
         effect: "read-only",
         inputSchema: {
           type: "object",
@@ -32459,12 +32472,12 @@ var init_src6 = __esm({
           required: ["brandId"],
           additionalProperties: false
         },
-        outputSchema: { type: "object", properties: {} }
+        outputSchema: { type: "object", properties: { brandId: { type: "string", description: "Brand ID." }, revision: { type: "number", description: "Current revision number." }, typography: { type: "object", description: "Typography settings." }, colors: { type: "object", description: "Color palette." } } }
       },
       {
         name: "create_brand",
         title: "Create brand",
-        description: "Create a new owner-scoped Brand kit defining typography, color palette, handle, and optional logo asset. Returns the created Brand entity with revision 1. Best invoked before creating slideshow runs to establish consistent visual identity.",
+        description: "Create a new owner-scoped Brand kit defining typography, color palette, handle, and optional logo asset. Call before creating slideshow runs to establish consistent visual identity. Do NOT use to edit an existing brand; use update_brand instead. Requires workspace owner authorization. Persists initial brand record with revision 1. Returns created Brand entity with brandId and initial revision.",
         effect: "local-write-job",
         inputSchema: {
           type: "object",
@@ -32479,18 +32492,18 @@ var init_src6 = __esm({
           required: ["name"],
           additionalProperties: false
         },
-        outputSchema: { type: "object", properties: {} }
+        outputSchema: { type: "object", properties: { brandId: { type: "string", description: "Created brand ID." }, revision: { type: "number", description: "Initial revision (1)." } } }
       },
       {
         name: "update_brand",
         title: "Update brand",
-        description: "Patch visual styles or metadata of an existing Brand. Requires baseRevision for optimistic concurrency locking to prevent overwrite races. Returns updated Brand with incremented revision.",
+        description: "Patch visual styles, typography, or metadata of an existing Brand by brandId. Call after get_brand to modify palette or fonts. Do NOT use to create new brands (use create_brand) or to delete (use delete_brand). Requires baseRevision for optimistic concurrency locking to prevent overwrite races; on revision mismatch returns 409 Conflict. Safe partial patch: unspecified styling tokens are preserved. Returns updated Brand with incremented revision.",
         effect: "local-write-job",
         inputSchema: {
           type: "object",
           properties: {
             brandId: { type: "string", description: "The unique identifier of the brand to update." },
-            baseRevision: { type: "integer", minimum: 1, description: "Current revision number for optimistic concurrency lock." },
+            baseRevision: { type: "integer", minimum: 1, description: "Current revision number for optimistic concurrency lock. Must match latest revision from get_brand." },
             name: { type: "string", description: "Updated brand name." },
             displayName: { type: "string", description: "Updated display name." },
             handle: { type: "string", description: "Updated social handle." },
@@ -32501,12 +32514,12 @@ var init_src6 = __esm({
           required: ["brandId", "baseRevision"],
           additionalProperties: false
         },
-        outputSchema: { type: "object", properties: {} }
+        outputSchema: { type: "object", properties: { brandId: { type: "string", description: "Brand ID." }, revision: { type: "number", description: "Incremented revision number." } } }
       },
       {
         name: "archive_brand",
         title: "Archive brand",
-        description: "Archive an active Brand to soft-hide it from default pickers and list queries without losing styling tokens. Reversible via restore_brand. Existing slideshow runs referencing this brand continue to display correctly.",
+        description: "Archive an active Brand to soft-hide it from default pickers and list queries without losing styling tokens. Call to declutter workspace brands. Do NOT use for permanent deletion; use delete_brand instead. Idempotent state transition, fully reversible via restore_brand. Existing slideshow runs referencing this brand continue to display correctly. Returns updated Brand with status set to archived.",
         effect: "local-write-job",
         inputSchema: {
           type: "object",
@@ -32516,12 +32529,12 @@ var init_src6 = __esm({
           required: ["brandId"],
           additionalProperties: false
         },
-        outputSchema: { type: "object", properties: {} }
+        outputSchema: { type: "object", properties: { brandId: { type: "string", description: "Brand ID." }, status: { type: "string", description: "Updated status (archived)." } } }
       },
       {
         name: "restore_brand",
         title: "Restore brand",
-        description: "Restore a previously archived or trashed Brand back to active status, making it immediately selectable in brand selectors and default list queries.",
+        description: "Restore a previously archived or trashed Brand back to active status. Call to unhide a brand and make it immediately selectable in brand selectors and default list queries. Alternatives: Use get_brand to inspect tokens before restoring. Idempotent state transition. Returns restored Brand with status set to active.",
         effect: "local-write-job",
         inputSchema: {
           type: "object",
@@ -32531,12 +32544,12 @@ var init_src6 = __esm({
           required: ["brandId"],
           additionalProperties: false
         },
-        outputSchema: { type: "object", properties: {} }
+        outputSchema: { type: "object", properties: { brandId: { type: "string", description: "Brand ID." }, status: { type: "string", description: "Restored status (active)." } } }
       },
       {
         name: "delete_brand",
         title: "Delete brand",
-        description: "Move a Brand to trash/pending deletion. Requires confirmation because dependent design workflows may lose default brand styling. Can be recovered with restore_brand.",
+        description: "Move a Brand to trash for deletion. Call only when a brand kit is obsolete and permanently discarded. Alternatives: If existing runs still use this brand theme, prefer archive_brand to preserve styling safely. Destructive operation requiring explicit confirmation. Dependent design workflows may lose default brand styling. Returns deletion confirmation record.",
         effect: "explicit-approval",
         inputSchema: {
           type: "object",
@@ -32546,7 +32559,7 @@ var init_src6 = __esm({
           required: ["brandId"],
           additionalProperties: false
         },
-        outputSchema: { type: "object", properties: {} }
+        outputSchema: { type: "object", properties: { brandId: { type: "string", description: "Deleted brand ID." }, deleted: { type: "boolean", description: "True if deletion confirmed." } } }
       }
     ];
     rename = (tool, names) => ({ ...tool, name: names[tool.name] ?? tool.name });
@@ -32556,7 +32569,7 @@ var init_src6 = __esm({
       {
         name: "list_images",
         title: "List images",
-        description: "List owner-scoped image assets in the media library with optional search query q. Returns image IDs, CDN URLs, mime types, and rights status for slot assignment.",
+        description: "List owner-scoped image assets in the media library with optional search query q. Returns image IDs, CDN URLs, dimensions, and rights status for slot assignment. Call to browse media assets or discover imageId before slot binding. Alternatives: Use get_image to fetch full metadata for a specific imageId. Read-only query scoped to workspace owner.",
         effect: "read-only",
         inputSchema: {
           type: "object",
@@ -32565,12 +32578,12 @@ var init_src6 = __esm({
           },
           additionalProperties: false
         },
-        outputSchema: { type: "object", properties: {} }
+        outputSchema: { type: "object", properties: { images: { type: "array", description: "Array of image asset records." } } }
       },
       {
         name: "get_image",
         title: "Get image",
-        description: "Fetch metadata and public R2/CDN delivery URL for a specific image asset by imageId. Use to inspect dimensions and rightsStatus before binding to slide slots.",
+        description: "Fetch metadata and public R2/CDN delivery URL for a specific image asset by imageId. Call to inspect dimensions, content hash, and rightsStatus before binding to slide slots. Alternatives: Use list_images to search assets across media library. Read-only query scoped to workspace owner. Returns full Image entity.",
         effect: "read-only",
         inputSchema: {
           type: "object",
@@ -32580,12 +32593,12 @@ var init_src6 = __esm({
           required: ["imageId"],
           additionalProperties: false
         },
-        outputSchema: { type: "object", properties: {} }
+        outputSchema: { type: "object", properties: { imageId: { type: "string", description: "Image asset ID." }, url: { type: "string", description: "Public delivery URL." }, rightsStatus: { type: "string", description: "Rights status." } } }
       },
       {
         name: "import_image",
         title: "Import image",
-        description: "Upload and register an image into the permanent account media library (persisted to R2 + Directus metadata). For transient draft canvas images only, use import_template_image instead.",
+        description: "Upload a new image file into the permanent workspace media library, storing the binary asset on Cloudflare R2 and registering metadata in Directus. Call to add reusable media assets (logos, photos, graphics) for use across slideshow runs and brands. Do NOT use for transient template draft canvas images (use import_template_image instead). Requires workspace write permissions. Returns created Image record with generated imageId and public delivery URL.",
         effect: "local-write-job",
         inputSchema: {
           type: "object",
@@ -32598,12 +32611,12 @@ var init_src6 = __esm({
           },
           additionalProperties: false
         },
-        outputSchema: { type: "object", properties: {} }
+        outputSchema: { type: "object", properties: { imageId: { type: "string", description: "Created image ID." }, url: { type: "string", description: "Public delivery URL." } } }
       },
       {
         name: "update_image",
         title: "Update image",
-        description: "Update metadata for an existing media library asset by imageId (e.g. rename asset or update rightsStatus). Does not re-upload binary content.",
+        description: "Update metadata fields (such as human-readable name or rightsStatus) for an existing image asset by imageId. Call to rename images or change categorization tags. Do NOT use to record legal commercial compliance attestations (use attest_image instead) or to replace image binary pixels (use import_image to upload a new asset). Requires workspace owner authorization. Safe partial update: only provided fields are modified. Returns updated Image asset record.",
         effect: "local-write-job",
         inputSchema: {
           type: "object",
@@ -32615,28 +32628,28 @@ var init_src6 = __esm({
           required: ["imageId"],
           additionalProperties: false
         },
-        outputSchema: { type: "object", properties: {} }
+        outputSchema: { type: "object", properties: { imageId: { type: "string", description: "Image asset ID." }, name: { type: "string", description: "Updated title." }, rightsStatus: { type: "string", description: "Updated rights status." } } }
       },
       {
         name: "attest_image",
         title: "Attest image rights",
-        description: "Record legal ownership or commercial rights attestation for an image asset (statementVersion). Recommended before multi-platform export to ensure commercial compliance.",
+        description: "Record an immutable legal copyright or commercial rights ownership attestation for an image asset. Call before multi-platform export to satisfy commercial compliance requirements. Do NOT use to edit metadata like title or tags (use update_image instead) or upload images (use import_image). Not required for personal or draft-only runs. Requires workspace owner authorization. Writes a permanent audit log record bound to imageId. Re-attesting with a new statementVersion creates a new timestamped attestation record without revoking prior history. Returns attestation confirmation object.",
         effect: "local-write-job",
         inputSchema: {
           type: "object",
           properties: {
             imageId: { type: "string", description: "The unique image asset identifier to attest." },
-            statementVersion: { type: "string", description: "Legal attestation terms version accepted (e.g. v1)." }
+            statementVersion: { type: "string", description: "Legal attestation terms version accepted (e.g. v1). Returns 400 if invalid or empty." }
           },
           required: ["imageId"],
           additionalProperties: false
         },
-        outputSchema: { type: "object", properties: {} }
+        outputSchema: { type: "object", properties: { imageId: { type: "string", description: "Image asset ID." }, statementVersion: { type: "string", description: "Recorded statement version." }, attestedAt: { type: "string", description: "ISO timestamp of attestation." } } }
       },
       {
         name: "archive_image",
         title: "Archive image",
-        description: "Archive an image asset to soft-hide it from active media pickers without deleting binary storage. Reversible via restore_image. Slides referencing this image remain intact.",
+        description: "Archive an image asset to soft-hide it from active media pickers without deleting binary files from storage. Call to declutter media library when an image is retired from active use. For permanent deletion, use delete_image instead. Idempotent state transition, fully reversible via restore_image. Slides and carousels currently referencing this image continue to display and render without disruption. Returns updated Image record with status set to archived.",
         effect: "local-write-job",
         inputSchema: {
           type: "object",
@@ -32646,12 +32659,12 @@ var init_src6 = __esm({
           required: ["imageId"],
           additionalProperties: false
         },
-        outputSchema: { type: "object", properties: {} }
+        outputSchema: { type: "object", properties: { imageId: { type: "string", description: "Image asset ID." }, status: { type: "string", description: "Updated status (archived)." } } }
       },
       {
         name: "restore_image",
         title: "Restore image",
-        description: "Restore an archived image asset back to active status in the media library, making it selectable in slot editors and list queries.",
+        description: "Restore a previously archived or trashed image asset back to active status in the workspace media library. Call to unhide a retired asset and make it selectable again in slide slot editors. Alternatives: Use get_image to inspect asset details before restoring. Idempotent state transition. Returns restored Image record visible in default media queries.",
         effect: "local-write-job",
         inputSchema: {
           type: "object",
@@ -32661,12 +32674,12 @@ var init_src6 = __esm({
           required: ["imageId"],
           additionalProperties: false
         },
-        outputSchema: { type: "object", properties: {} }
+        outputSchema: { type: "object", properties: { imageId: { type: "string", description: "Image asset ID." }, status: { type: "string", description: "Restored status (active)." } } }
       },
       {
         name: "delete_image",
         title: "Delete image",
-        description: "Move an image asset to trash for deletion. Requires confirmation because slides referencing this image asset may fail to render properly.",
+        description: "Move an image asset to trash for permanent removal. Call only when an image is obsolete, copyrighted without license, or marked for permanent deletion. If existing slides still use this image, prefer archive_image to hide it safely without breaking slide renders. Destructive operation requiring explicit user confirmation. May cause slide render failures if imageId is bound to active slides. Returns deletion confirmation record.",
         effect: "explicit-approval",
         inputSchema: {
           type: "object",
@@ -32676,7 +32689,7 @@ var init_src6 = __esm({
           required: ["imageId"],
           additionalProperties: false
         },
-        outputSchema: { type: "object", properties: {} }
+        outputSchema: { type: "object", properties: { imageId: { type: "string", description: "Deleted image asset ID." }, deleted: { type: "boolean", description: "True if deletion confirmed." } } }
       }
     ];
     unifiedToolRegistry = [...templateTools, ...slideshowTools, ...brandTools, ...imageTools];