@socialneuron/mcp-server 1.5.0 → 1.5.2

package/dist/http.js

@@ -853,6 +853,41 @@ function checkRateLimit(category, key) {
 
 // src/tools/ideation.ts
 init_supabase();
+
+// src/lib/tool-errors.ts
+function formatToolError(rawMessage) {
+  const msg = rawMessage.toLowerCase();
+  if (msg.includes("rate limit") || msg.includes("too many requests")) {
+    return `${rawMessage} Reduce request frequency or wait before retrying.`;
+  }
+  if (msg.includes("insufficient credit") || msg.includes("budget") || msg.includes("spending cap")) {
+    return `${rawMessage} Call get_credit_balance to check remaining credits. Consider a cheaper model or wait for monthly refresh.`;
+  }
+  if (msg.includes("oauth") || msg.includes("token expired") || msg.includes("not connected") || msg.includes("reconnect")) {
+    return `${rawMessage} Call list_connected_accounts to check status. User may need to reconnect at socialneuron.com/settings/connections.`;
+  }
+  if (msg.includes("generation failed") || msg.includes("failed to start") || msg.includes("no job id") || msg.includes("could not be parsed")) {
+    return `${rawMessage} Try simplifying the prompt, using a different model, or check credits with get_credit_balance.`;
+  }
+  if (msg.includes("not found") || msg.includes("no ") && msg.includes(" found")) {
+    return `${rawMessage} Verify the ID is correct \u2014 use the corresponding list tool to find valid IDs.`;
+  }
+  if (msg.includes("not accessible") || msg.includes("unauthorized") || msg.includes("permission")) {
+    return `${rawMessage} Check API key scopes with get_credit_balance. A higher-tier plan may be required.`;
+  }
+  if (msg.includes("ssrf") || msg.includes("url blocked")) {
+    return `${rawMessage} The URL was blocked for security. Use a publicly accessible HTTPS URL.`;
+  }
+  if (msg.includes("failed to schedule") || msg.includes("scheduling failed")) {
+    return `${rawMessage} Verify platform OAuth is active with list_connected_accounts, then retry.`;
+  }
+  if (msg.includes("no posts") || msg.includes("plan") && msg.includes("has no")) {
+    return `${rawMessage} Generate a plan with plan_content_week first, then save with save_content_plan.`;
+  }
+  return rawMessage;
+}
+
+// src/tools/ideation.ts
 function registerIdeationTools(server) {
   server.tool(
     "generate_content",
@@ -886,6 +921,13 @@ function registerIdeationTools(server) {
         "Project ID to auto-load brand profile and performance context for prompt enrichment."
       )
     },
+    {
+      title: "Generate Content",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
     async ({
       prompt,
       content_type,
@@ -1019,7 +1061,7 @@ Content Type: ${content_type}`;
           content: [
             {
               type: "text",
-              text: `Content generation failed: ${error}`
+              text: formatToolError(`Content generation failed: ${error}`)
             }
           ],
           isError: true
@@ -1049,6 +1091,13 @@ Content Type: ${content_type}`;
       ),
       force_refresh: z.boolean().optional().describe("Skip the server-side cache and fetch fresh data.")
     },
+    {
+      title: "Fetch Trends",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
     async ({ source, category, niche, url, force_refresh }) => {
       if ((source === "rss" || source === "url") && !url) {
         return {
@@ -1077,7 +1126,7 @@ Content Type: ${content_type}`;
           content: [
             {
               type: "text",
-              text: `Failed to fetch trends: ${error}`
+              text: formatToolError(`Failed to fetch trends: ${error}`)
             }
           ],
           isError: true
@@ -1153,6 +1202,13 @@ Content Type: ${content_type}`;
         "Optional project ID to load platform voice overrides from brand profile."
       )
     },
+    {
+      title: "Adapt Content",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
     async ({
       content,
       source_platform,
@@ -1238,7 +1294,7 @@ ${content}`,
           content: [
             {
               type: "text",
-              text: `Content adaptation failed: ${error}`
+              text: formatToolError(`Content adaptation failed: ${error}`)
             }
           ],
           isError: true
@@ -1312,7 +1368,7 @@ function sanitizeDbError(error) {
 init_request_context();
 
 // src/lib/version.ts
-var MCP_VERSION = "1.5.0";
+var MCP_VERSION = "1.5.2";
 
 // src/tools/content.ts
 var MAX_CREDITS_PER_RUN = Math.max(
@@ -1454,6 +1510,13 @@ function registerContentTools(server) {
       ),
       response_format: z2.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
+    {
+      title: "Generate Video",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
     async ({
       prompt,
       model,
@@ -1545,7 +1608,7 @@ function registerContentTools(server) {
           content: [
             {
               type: "text",
-              text: `Video generation failed to start: ${error}`
+              text: formatToolError(`Video generation failed to start: ${error}`)
             }
           ],
           isError: true
@@ -1562,7 +1625,7 @@ function registerContentTools(server) {
           content: [
             {
               type: "text",
-              text: "Video generation failed: no job ID returned."
+              text: formatToolError("Video generation failed: no job ID returned.")
             }
           ],
           isError: true
@@ -1652,6 +1715,13 @@ function registerContentTools(server) {
       ),
       response_format: z2.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
+    {
+      title: "Generate Image",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
     async ({ prompt, model, aspect_ratio, image_url, response_format }) => {
       const format = response_format ?? "text";
       const startedAt = Date.now();
@@ -1731,7 +1801,7 @@ function registerContentTools(server) {
           content: [
             {
               type: "text",
-              text: `Image generation failed to start: ${error}`
+              text: formatToolError(`Image generation failed to start: ${error}`)
             }
           ],
           isError: true
@@ -1748,7 +1818,7 @@ function registerContentTools(server) {
           content: [
             {
               type: "text",
-              text: "Image generation failed: no job ID returned."
+              text: formatToolError("Image generation failed: no job ID returned.")
             }
           ],
           isError: true
@@ -1815,6 +1885,13 @@ function registerContentTools(server) {
       ),
       response_format: z2.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
+    {
+      title: "Check Job Status",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     async ({ job_id, response_format }) => {
       const format = response_format ?? "text";
       const startedAt = Date.now();
@@ -1865,7 +1942,7 @@ function registerContentTools(server) {
           content: [
             {
               type: "text",
-              text: `Failed to look up job: ${sanitizeDbError(jobError)}`
+              text: formatToolError(`Failed to look up job: ${sanitizeDbError(jobError)}`)
             }
           ],
           isError: true
@@ -1882,7 +1959,7 @@ function registerContentTools(server) {
           content: [
             {
               type: "text",
-              text: `No job found with ID "${job_id}". The ID may be incorrect or the job has expired.`
+              text: formatToolError(`No job found with ID "${job_id}". The ID may be incorrect or the job has expired.`)
             }
           ],
           isError: true
@@ -2012,6 +2089,13 @@ function registerContentTools(server) {
         "Response format. Defaults to json for structured storyboard data."
       )
     },
+    {
+      title: "Create Storyboard",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
     async ({
       concept,
       brand_context,
@@ -2123,7 +2207,7 @@ Return ONLY valid JSON in this exact format:
           content: [
             {
               type: "text",
-              text: `Storyboard generation failed: ${error}`
+              text: formatToolError(`Storyboard generation failed: ${error}`)
             }
           ],
           isError: true
@@ -2192,6 +2276,13 @@ Return ONLY valid JSON in this exact format:
       speed: z2.number().min(0.5).max(2).optional().describe("Speech speed multiplier. 1.0 is normal. Defaults to 1.0."),
       response_format: z2.enum(["text", "json"]).optional().describe("Response format. Defaults to text.")
     },
+    {
+      title: "Generate Voiceover",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
     async ({ text, voice, speed, response_format }) => {
       const format = response_format ?? "text";
       const startedAt = Date.now();
@@ -2251,7 +2342,7 @@ Return ONLY valid JSON in this exact format:
           content: [
             {
               type: "text",
-              text: `Voiceover generation failed: ${error}`
+              text: formatToolError(`Voiceover generation failed: ${error}`)
             }
           ],
           isError: true
@@ -2268,7 +2359,7 @@ Return ONLY valid JSON in this exact format:
           content: [
             {
               type: "text",
-              text: "Voiceover generation failed: no audio URL returned."
+              text: formatToolError("Voiceover generation failed: no audio URL returned.")
             }
           ],
           isError: true
@@ -2350,6 +2441,13 @@ Return ONLY valid JSON in this exact format:
       project_id: z2.string().optional().describe("Project ID to associate the carousel with."),
       response_format: z2.enum(["text", "json"]).optional().describe("Response format. Defaults to json.")
     },
+    {
+      title: "Generate Carousel",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
     async ({
       topic,
       template_id,
@@ -2424,7 +2522,7 @@ Return ONLY valid JSON in this exact format:
           content: [
             {
               type: "text",
-              text: `Carousel generation failed: ${error}`
+              text: formatToolError(`Carousel generation failed: ${error}`)
             }
           ],
           isError: true
@@ -2684,6 +2782,13 @@ function registerDistributionTools(server) {
         'If true, appends "Created with Social Neuron" to the caption. Default: false.'
       )
     },
+    {
+      title: "Schedule Post",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
     async ({
       media_url,
       media_urls,
@@ -2764,7 +2869,7 @@ Created with Social Neuron`;
           content: [
             {
               type: "text",
-              text: `Failed to schedule post: ${error}`
+              text: formatToolError(`Failed to schedule post: ${error}`)
             }
           ],
           isError: true
@@ -2835,6 +2940,13 @@ Created with Social Neuron`;
     {
       response_format: z3.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
+    {
+      title: "List Connected Accounts",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    },
     async ({ response_format }) => {
       const format = response_format ?? "text";
       const supabase = getSupabaseClient();
@@ -2845,7 +2957,7 @@ Created with Social Neuron`;
           content: [
             {
               type: "text",
-              text: `Failed to list connected accounts: ${sanitizeDbError(error)}`
+              text: formatToolError(`Failed to list connected accounts: ${sanitizeDbError(error)}`)
             }
           ],
           isError: true
@@ -2913,6 +3025,13 @@ Created with Social Neuron`;
       limit: z3.number().min(1).max(50).optional().describe("Maximum number of posts to return. Defaults to 20."),
       response_format: z3.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
+    {
+      title: "List Recent Posts",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    },
     async ({ platform: platform2, status, days, limit, response_format }) => {
       const format = response_format ?? "text";
       const supabase = getSupabaseClient();
@@ -2937,7 +3056,7 @@ Created with Social Neuron`;
           content: [
             {
               type: "text",
-              text: `Failed to list posts: ${sanitizeDbError(error)}`
+              text: formatToolError(`Failed to list posts: ${sanitizeDbError(error)}`)
             }
           ],
           isError: true
@@ -3012,7 +3131,7 @@ Created with Social Neuron`;
   };
   server.tool(
     "find_next_slots",
-    "Find optimal posting time slots based on best posting times and existing schedule. Returns non-conflicting slots sorted by engagement score.",
+    "Find the next available posting time slots that avoid conflicts with already-scheduled posts. Uses engagement data from get_best_posting_times to rank slots. Call this before schedule_content_plan to pick optimal, non-overlapping times for each post.",
     {
       platforms: z3.array(
         z3.enum([
@@ -3025,11 +3144,18 @@ Created with Social Neuron`;
           "threads",
           "bluesky"
         ])
-      ).min(1),
+      ).min(1).describe("Platforms to find posting slots for."),
       count: z3.number().min(1).max(20).default(7).describe("Number of slots to find"),
       start_after: z3.string().optional().describe("ISO datetime, defaults to now"),
       min_gap_hours: z3.number().min(1).max(24).default(4).describe("Minimum gap between posts on same platform"),
-      response_format: z3.enum(["text", "json"]).default("text")
+      response_format: z3.enum(["text", "json"]).default("text").describe("Response format. Defaults to text.")
+    },
+    {
+      title: "Find Next Posting Slots",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
     },
     async ({
       platforms,
@@ -3135,7 +3261,7 @@ Created with Social Neuron`;
         });
         return {
           content: [
-            { type: "text", text: `Failed to find slots: ${message}` }
+            { type: "text", text: formatToolError(`Failed to find slots: ${message}`) }
           ],
           isError: true
         };
@@ -3149,20 +3275,20 @@ Created with Social Neuron`;
       plan: z3.object({
         posts: z3.array(
           z3.object({
-            id: z3.string(),
-            caption: z3.string(),
-            platform: z3.string(),
-            title: z3.string().optional(),
-            media_url: z3.string().optional(),
-            schedule_at: z3.string().optional(),
-            hashtags: z3.array(z3.string()).optional()
+            id: z3.string().describe("Unique post identifier from the content plan."),
+            caption: z3.string().describe("Post caption/body text."),
+            platform: z3.string().describe("Target platform name (e.g. instagram, youtube)."),
+            title: z3.string().optional().describe("Post title, required for YouTube."),
+            media_url: z3.string().optional().describe("Public or R2 signed URL for the post media."),
+            schedule_at: z3.string().optional().describe("ISO 8601 UTC datetime to publish (e.g. 2026-03-20T14:00:00Z)."),
+            hashtags: z3.array(z3.string()).optional().describe("Hashtags to append to the caption.")
           })
         )
-      }).passthrough().optional(),
+      }).passthrough().optional().describe("Inline content plan object with a posts array. Provide this or plan_id."),
       plan_id: z3.string().uuid().optional().describe("Persisted content plan ID from content_plans table"),
       auto_slot: z3.boolean().default(true).describe("Auto-assign time slots for posts without schedule_at"),
       dry_run: z3.boolean().default(false).describe("Preview without actually scheduling"),
-      response_format: z3.enum(["text", "json"]).default("text"),
+      response_format: z3.enum(["text", "json"]).default("text").describe("Response format. Defaults to text."),
       enforce_quality: z3.boolean().default(true).describe(
         "When true, block scheduling for posts that fail quality checks."
       ),
@@ -3172,6 +3298,13 @@ Created with Social Neuron`;
       batch_size: z3.number().int().min(1).max(10).default(4).describe("Concurrent schedule calls per platform batch."),
       idempotency_seed: z3.string().max(128).optional().describe("Optional stable seed used when building idempotency keys.")
     },
+    {
+      title: "Schedule Content Plan",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
     async ({
       plan,
       plan_id,
@@ -3198,7 +3331,7 @@ Created with Social Neuron`;
               content: [
                 {
                   type: "text",
-                  text: `Failed to load content plan: ${sanitizeDbError(storedError)}`
+                  text: formatToolError(`Failed to load content plan: ${sanitizeDbError(storedError)}`)
                 }
               ],
               isError: true
@@ -3209,7 +3342,7 @@ Created with Social Neuron`;
               content: [
                 {
                   type: "text",
-                  text: `No content plan found for plan_id=${plan_id}`
+                  text: formatToolError(`No content plan found for plan_id=${plan_id}`)
                 }
               ],
               isError: true
@@ -3224,7 +3357,7 @@ Created with Social Neuron`;
               content: [
                 {
                   type: "text",
-                  text: `Stored plan ${plan_id} has no posts array.`
+                  text: formatToolError(`Stored plan ${plan_id} has no posts array.`)
                 }
               ],
               isError: true
@@ -3263,7 +3396,7 @@ Created with Social Neuron`;
               content: [
                 {
                   type: "text",
-                  text: `Failed to load plan approvals: ${sanitizeDbError(approvalsError)}`
+                  text: formatToolError(`Failed to load plan approvals: ${sanitizeDbError(approvalsError)}`)
                 }
               ],
               isError: true
@@ -3698,7 +3831,7 @@ Created with Social Neuron`;
           content: [
             {
               type: "text",
-              text: `Batch scheduling failed: ${message}`
+              text: formatToolError(`Batch scheduling failed: ${message}`)
             }
           ],
           isError: true
@@ -3742,6 +3875,7 @@ function registerAnalyticsTools(server) {
       limit: z4.number().min(1).max(100).optional().describe("Maximum number of posts to return. Defaults to 20."),
       response_format: z4.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
+    { title: "Fetch Analytics", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     async ({ platform: platform2, days, content_id, limit, response_format }) => {
       const format = response_format ?? "text";
       const supabase = getSupabaseClient();
@@ -3788,7 +3922,7 @@ function registerAnalyticsTools(server) {
             content: [
               {
                 type: "text",
-                text: `Failed to fetch user-scoped posts: ${sanitizeDbError(postsError)}`
+                text: formatToolError(`Failed to fetch user-scoped posts: ${sanitizeDbError(postsError)}`)
               }
             ],
             isError: true
@@ -3835,7 +3969,7 @@ function registerAnalyticsTools(server) {
             content: [
               {
                 type: "text",
-                text: `Failed to fetch analytics: ${sanitizeDbError(simpleError)}`
+                text: formatToolError(`Failed to fetch analytics: ${sanitizeDbError(simpleError)}`)
               }
             ],
             isError: true
@@ -3919,6 +4053,13 @@ function registerAnalyticsTools(server) {
     {
       response_format: z4.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
+    {
+      title: "Refresh Platform Analytics",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
     async ({ response_format }) => {
       const format = response_format ?? "text";
       const startedAt = Date.now();
@@ -3958,7 +4099,7 @@ function registerAnalyticsTools(server) {
           content: [
             {
               type: "text",
-              text: `Error refreshing analytics: ${error}`
+              text: formatToolError(`Error refreshing analytics: ${error}`)
             }
           ],
           isError: true
@@ -4318,6 +4459,13 @@ function registerBrandTools(server) {
       ),
       response_format: z5.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
+    {
+      title: "Extract Brand",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     async ({ url, response_format }) => {
       const ssrfCheck = await validateUrlForSSRF(url);
       if (!ssrfCheck.isValid) {
@@ -4338,7 +4486,7 @@ function registerBrandTools(server) {
           content: [
             {
               type: "text",
-              text: `Brand extraction failed: ${error}`
+              text: formatToolError(`Brand extraction failed: ${error}`)
             }
           ],
           isError: true
@@ -4401,6 +4549,13 @@ function registerBrandTools(server) {
       project_id: z5.string().uuid().optional().describe("Project ID. Defaults to active project context."),
       response_format: z5.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
+    {
+      title: "Get Brand Profile",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    },
     async ({ project_id, response_format }) => {
       const supabase = getSupabaseClient();
       const userId = await getDefaultUserId();
@@ -4441,7 +4596,7 @@ function registerBrandTools(server) {
           content: [
             {
               type: "text",
-              text: `Failed to load brand profile: ${sanitizeDbError(error)}`
+              text: formatToolError(`Failed to load brand profile: ${sanitizeDbError(error)}`)
             }
           ],
           isError: true
@@ -4498,8 +4653,17 @@ function registerBrandTools(server) {
         "product_showcase"
       ]).optional().describe("Extraction method metadata."),
       overall_confidence: z5.number().min(0).max(1).optional().describe("Optional overall confidence score in range 0..1."),
-      extraction_metadata: z5.record(z5.string(), z5.unknown()).optional(),
-      response_format: z5.enum(["text", "json"]).optional()
+      extraction_metadata: z5.record(z5.string(), z5.unknown()).optional().describe(
+        "Arbitrary key-value metadata about the extraction process."
+      ),
+      response_format: z5.enum(["text", "json"]).optional().describe("Response format. Defaults to text.")
+    },
+    {
+      title: "Save Brand Profile",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false
     },
     async ({
       project_id,
@@ -4563,7 +4727,7 @@ function registerBrandTools(server) {
           content: [
             {
               type: "text",
-              text: `Failed to save brand profile: ${sanitizeDbError(error)}`
+              text: formatToolError(`Failed to save brand profile: ${sanitizeDbError(error)}`)
             }
           ],
           isError: true
@@ -4612,15 +4776,32 @@ Version: ${payload.version ?? "N/A"}`
         "facebook",
         "threads",
         "bluesky"
-      ]),
+      ]).describe("Social platform to set voice overrides for."),
       project_id: z5.string().uuid().optional().describe("Project ID. Defaults to active project context."),
       samples: z5.string().max(3e3).optional().describe("3-5 real platform post examples for style anchoring."),
-      tone: z5.array(z5.string()).optional(),
-      style: z5.array(z5.string()).optional(),
-      avoid_patterns: z5.array(z5.string()).optional(),
-      hashtag_strategy: z5.string().max(300).optional(),
-      cta_style: z5.string().max(300).optional(),
-      response_format: z5.enum(["text", "json"]).optional()
+      tone: z5.array(z5.string()).optional().describe(
+        'Tone descriptors for this platform (e.g. ["casual", "witty", "informative"]).'
+      ),
+      style: z5.array(z5.string()).optional().describe(
+        'Writing style tags (e.g. ["short-form", "emoji-heavy", "storytelling"]).'
+      ),
+      avoid_patterns: z5.array(z5.string()).optional().describe(
+        'Phrases or patterns the brand should never use on this platform (e.g. ["click here", "buy now"]).'
+      ),
+      hashtag_strategy: z5.string().max(300).optional().describe(
+        'Hashtag usage guidelines for this platform (e.g. "3-5 niche hashtags, no generic tags").'
+      ),
+      cta_style: z5.string().max(300).optional().describe(
+        'Preferred call-to-action style (e.g. "soft CTA with question" or "direct link in bio").'
+      ),
+      response_format: z5.enum(["text", "json"]).optional().describe("Response format. Defaults to text.")
+    },
+    {
+      title: "Update Platform Voice",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false
     },
     async ({
       platform: platform2,
@@ -4722,7 +4903,7 @@ Version: ${payload.version ?? "N/A"}`
           content: [
             {
               type: "text",
-              text: `Failed to update platform voice: ${saveError.message}`
+              text: formatToolError(`Failed to update platform voice: ${saveError.message}`)
             }
           ],
           isError: true
@@ -4869,6 +5050,13 @@ function registerScreenshotTools(server) {
         "Extra milliseconds to wait after page load before capturing. Useful for animations. Defaults to 2000."
       )
     },
+    {
+      title: "Capture App Page",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false
+    },
     async ({ page: pageName, viewport, theme, selector, wait_ms }) => {
       const startedAt = Date.now();
       let rateLimitKey = "anonymous";
@@ -4989,6 +5177,13 @@ function registerScreenshotTools(server) {
       ),
       wait_ms: z6.number().min(0).max(3e4).optional().describe("Extra milliseconds to wait after page load before capturing. Defaults to 1000.")
     },
+    {
+      title: "Capture Screenshot",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
     async ({ url, viewport, selector, output_path, wait_ms }) => {
       const startedAt = Date.now();
       let rateLimitKey = "anonymous";
@@ -5251,6 +5446,13 @@ function registerRemotionTools(server) {
     "list_compositions",
     "List all available Remotion video compositions defined in Social Neuron. Returns composition IDs, dimensions, duration, and descriptions. Use this to discover what videos can be rendered with render_demo_video.",
     {},
+    {
+      title: "List Compositions",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    },
     async () => {
       const lines = [`${COMPOSITIONS.length} Remotion compositions available:`, ""];
       for (const comp of COMPOSITIONS) {
@@ -5279,6 +5481,13 @@ function registerRemotionTools(server) {
         "JSON string of input props to pass to the composition. Each composition accepts different props. Omit for defaults."
       )
     },
+    {
+      title: "Render Demo Video",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false
+    },
     async ({ composition_id, output_format, props }) => {
       const startedAt = Date.now();
       const userId = await getDefaultUserId();
@@ -5459,6 +5668,13 @@ function registerInsightsTools(server) {
       limit: z8.number().min(1).max(50).optional().describe("Maximum number of insights to return. Defaults to 10."),
       response_format: z8.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
+    {
+      title: "Get Performance Insights",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    },
     async ({ insight_type, days, limit, response_format }) => {
       const format = response_format ?? "text";
       const supabase = getSupabaseClient();
@@ -5586,6 +5802,13 @@ function registerInsightsTools(server) {
       days: z8.number().min(1).max(90).optional().describe("Number of days to analyze. Defaults to 30. Max 90."),
       response_format: z8.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
+    {
+      title: "Get Best Posting Times",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    },
     async ({ platform: platform2, days, response_format }) => {
       const format = response_format ?? "text";
       const supabase = getSupabaseClient();
@@ -5734,6 +5957,13 @@ function registerYouTubeAnalyticsTools(server) {
       video_id: z9.string().optional().describe('YouTube video ID. Required when action is "video".'),
       max_results: z9.number().min(1).max(50).optional().describe('Max videos to return for "topVideos" action. Defaults to 10.')
     },
+    {
+      title: "Fetch YouTube Analytics",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     async ({ action, start_date, end_date, video_id, max_results }) => {
       if (action === "video" && !video_id) {
         return {
@@ -5852,6 +6082,13 @@ function registerCommentsTools(server) {
       page_token: z10.string().optional().describe("Pagination cursor from previous list_comments response nextPageToken field. Omit for first page of results."),
       response_format: z10.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
+    {
+      title: "List Comments",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     async ({ video_id, max_results, page_token, response_format }) => {
       const format = response_format ?? "text";
       const { data, error } = await callEdgeFunction("youtube-comments", {
@@ -5863,7 +6100,7 @@ function registerCommentsTools(server) {
       if (error) {
         return {
           content: [
-            { type: "text", text: `Error listing comments: ${error}` }
+            { type: "text", text: formatToolError(`Error listing comments: ${error}`) }
           ],
           isError: true
         };
@@ -5922,6 +6159,13 @@ function registerCommentsTools(server) {
       text: z10.string().min(1).describe("The reply text."),
       response_format: z10.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
+    {
+      title: "Reply to Comment",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
     async ({ parent_id, text, response_format }) => {
       const format = response_format ?? "text";
       const startedAt = Date.now();
@@ -5960,7 +6204,7 @@ function registerCommentsTools(server) {
           content: [
             {
               type: "text",
-              text: `Error replying to comment: ${error}`
+              text: formatToolError(`Error replying to comment: ${error}`)
             }
           ],
           isError: true
@@ -6003,6 +6247,13 @@ function registerCommentsTools(server) {
       text: z10.string().min(1).describe("The comment text."),
       response_format: z10.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
+    {
+      title: "Post Comment",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
     async ({ video_id, text, response_format }) => {
       const format = response_format ?? "text";
       const startedAt = Date.now();
@@ -6039,7 +6290,7 @@ function registerCommentsTools(server) {
         });
         return {
           content: [
-            { type: "text", text: `Error posting comment: ${error}` }
+            { type: "text", text: formatToolError(`Error posting comment: ${error}`) }
           ],
           isError: true
         };
@@ -6081,6 +6332,13 @@ function registerCommentsTools(server) {
       moderation_status: z10.enum(["published", "rejected"]).describe('"published" to approve, "rejected" to hide.'),
       response_format: z10.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
+    {
+      title: "Moderate Comment",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     async ({ comment_id, moderation_status, response_format }) => {
       const format = response_format ?? "text";
       const startedAt = Date.now();
@@ -6119,7 +6377,7 @@ function registerCommentsTools(server) {
           content: [
             {
               type: "text",
-              text: `Error moderating comment: ${error}`
+              text: formatToolError(`Error moderating comment: ${error}`)
             }
           ],
           isError: true
@@ -6166,6 +6424,13 @@ function registerCommentsTools(server) {
       comment_id: z10.string().describe("The comment ID to delete."),
       response_format: z10.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
+    {
+      title: "Delete Comment",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     async ({ comment_id, response_format }) => {
       const format = response_format ?? "text";
       const startedAt = Date.now();
@@ -6201,7 +6466,7 @@ function registerCommentsTools(server) {
         });
         return {
           content: [
-            { type: "text", text: `Error deleting comment: ${error}` }
+            { type: "text", text: formatToolError(`Error deleting comment: ${error}`) }
           ],
           isError: true
         };
@@ -6314,12 +6579,19 @@ function asEnvelope7(data) {
 function registerIdeationContextTools(server) {
   server.tool(
     "get_ideation_context",
-    "Get synthesized ideation context from performance insights. Returns the same prompt-injection context used by ideation generation.",
+    "Load performance-derived context (top hooks, optimal timing, winning patterns) that should inform your next content generation. Call this before generate_content or plan_content_week to ground new content in what has actually performed well. Returns a promptInjection string ready to pass into generation tools.",
     {
       project_id: z11.string().uuid().optional().describe("Project ID to scope insights."),
       days: z11.number().min(1).max(90).optional().describe("Lookback window for insights. Defaults to 30 days."),
       response_format: z11.enum(["text", "json"]).optional().describe("Optional output format. Defaults to text.")
     },
+    {
+      title: "Get Ideation Context",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    },
     async ({ project_id, days, response_format }) => {
       const supabase = getSupabaseClient();
       const userId = await getDefaultUserId();
@@ -6449,6 +6721,13 @@ function registerCreditsTools(server) {
     {
       response_format: z12.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
+    {
+      title: "Get Credit Balance",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    },
     async ({ response_format }) => {
       const supabase = getSupabaseClient();
       const userId = await getDefaultUserId();
@@ -6461,7 +6740,7 @@ function registerCreditsTools(server) {
           content: [
             {
               type: "text",
-              text: `Failed to fetch credit balance: ${sanitizeDbError(profileResult.error)}`
+              text: formatToolError(`Failed to fetch credit balance: ${sanitizeDbError(profileResult.error)}`)
             }
           ],
           isError: true
@@ -6502,6 +6781,13 @@ Monthly used: ${payload.monthlyUsed}` + (payload.monthlyLimit ? ` / ${payload.mo
     {
       response_format: z12.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
+    {
+      title: "Get Budget Status",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    },
     async ({ response_format }) => {
       const budget = getCurrentBudgetStatus();
       const payload = {
@@ -6555,11 +6841,18 @@ function asEnvelope9(data) {
 function registerLoopSummaryTools(server) {
   server.tool(
     "get_loop_summary",
-    "Get a one-call dashboard summary of the feedback loop state (brand profile, recent content, and current insights).",
+    "Get a single-call health check of the content feedback loop: brand profile status, recent content, and active insights. Call at the start of a session to decide what to do next. The response includes a recommendedNextAction field that tells you which tool to call.",
     {
       project_id: z13.string().uuid().optional().describe("Project ID. Defaults to active project context."),
       response_format: z13.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
+    {
+      title: "Get Loop Summary",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    },
     async ({ project_id, response_format }) => {
       const supabase = getSupabaseClient();
       const userId = await getDefaultUserId();
@@ -6657,6 +6950,13 @@ function registerUsageTools(server) {
     {
       response_format: z14.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
+    {
+      title: "Get MCP Usage",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    },
     async ({ response_format }) => {
       const format = response_format ?? "text";
       const supabase = getSupabaseClient();
@@ -6746,6 +7046,13 @@ function registerAutopilotTools(server) {
       active_only: z15.boolean().optional().describe("If true, only return active configs. Defaults to false (show all)."),
       response_format: z15.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
+    {
+      title: "List Autopilot Configs",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    },
     async ({ active_only, response_format }) => {
       const format = response_format ?? "text";
       const supabase = getSupabaseClient();
@@ -6823,11 +7130,18 @@ ${"=".repeat(40)}
     {
       config_id: z15.string().uuid().describe("The autopilot config ID to update."),
       is_active: z15.boolean().optional().describe("Enable or disable this autopilot config."),
-      schedule_days: z15.array(z15.enum(["mon", "tue", "wed", "thu", "fri", "sat", "sun"])).optional().describe('Days of the week to run (e.g., ["mon", "wed", "fri"]).'),
+      schedule_days: z15.array(z15.enum(["mon", "tue", "wed", "thu", "fri", "sat", "sun"]).describe("Three-letter lowercase day abbreviation.")).optional().describe('Days of the week to run (e.g. ["mon", "wed", "fri"]).'),
       schedule_time: z15.string().optional().describe('Time to run in HH:MM format (24h, user timezone). E.g., "09:00".'),
       max_credits_per_run: z15.number().optional().describe("Maximum credits per execution."),
       max_credits_per_week: z15.number().optional().describe("Maximum credits per week.")
     },
+    {
+      title: "Update Autopilot Config",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    },
     async ({
       config_id,
       is_active,
@@ -6891,6 +7205,13 @@ Schedule: ${JSON.stringify(updated.schedule_config)}`
     {
       response_format: z15.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
+    {
+      title: "Get Autopilot Status",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    },
     async ({ response_format }) => {
       const format = response_format ?? "text";
       const supabase = getSupabaseClient();
@@ -7010,7 +7331,14 @@ function registerExtractionTools(server) {
       extract_type: z16.enum(["auto", "transcript", "article", "product"]).default("auto").describe("Type of extraction"),
       include_comments: z16.boolean().default(false).describe("Include top comments (YouTube only)"),
       max_results: z16.number().min(1).max(100).default(10).describe("Max comments to include"),
-      response_format: z16.enum(["text", "json"]).default("text")
+      response_format: z16.enum(["text", "json"]).default("text").describe("Response format. Defaults to text.")
+    },
+    {
+      title: "Extract URL Content",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
     },
     async ({
       url,
@@ -7053,7 +7381,7 @@ function registerExtractionTools(server) {
               content: [
                 {
                   type: "text",
-                  text: `Failed to extract YouTube video: ${error ?? "No data returned"}`
+                  text: formatToolError(`Failed to extract YouTube video: ${error ?? "No data returned"}`)
                 }
               ],
               isError: true
@@ -7093,7 +7421,7 @@ function registerExtractionTools(server) {
               content: [
                 {
                   type: "text",
-                  text: `Failed to extract YouTube channel: ${error ?? "No data returned"}`
+                  text: formatToolError(`Failed to extract YouTube channel: ${error ?? "No data returned"}`)
                 }
               ],
               isError: true
@@ -7124,7 +7452,7 @@ function registerExtractionTools(server) {
               content: [
                 {
                   type: "text",
-                  text: `Failed to extract URL content: ${error ?? "No data returned"}`
+                  text: formatToolError(`Failed to extract URL content: ${error ?? "No data returned"}`)
                 }
               ],
               isError: true
@@ -7181,7 +7509,7 @@ function registerExtractionTools(server) {
         });
         return {
           content: [
-            { type: "text", text: `Extraction failed: ${message}` }
+            { type: "text", text: formatToolError(`Extraction failed: ${message}`) }
           ],
           isError: true
         };
@@ -7220,9 +7548,16 @@ function registerQualityTools(server) {
       ).min(1).describe("Target platforms"),
       threshold: z17.number().min(0).max(35).default(26).describe("Minimum total score to pass (max 35, scored across 7 categories at 0-5 each). Default 26 (~75%). Use 20 for rough drafts, 28+ for final posts going to large audiences."),
       brand_keyword: z17.string().optional().describe("Brand keyword for alignment check"),
-      brand_avoid_patterns: z17.array(z17.string()).optional(),
-      custom_banned_terms: z17.array(z17.string()).optional(),
-      response_format: z17.enum(["text", "json"]).default("text")
+      brand_avoid_patterns: z17.array(z17.string()).optional().describe("Phrases the brand should never use (e.g. competitor names, off-brand slang). Matched case-insensitively."),
+      custom_banned_terms: z17.array(z17.string()).optional().describe("Additional banned words beyond the built-in safety list. Useful for industry-specific compliance terms."),
+      response_format: z17.enum(["text", "json"]).default("text").describe("'text' for human-readable report, 'json' for structured scores suitable for pipeline automation.")
+    },
+    {
+      title: "Quality Check",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
     },
     async ({
       caption,
@@ -7294,15 +7629,22 @@ function registerQualityTools(server) {
       plan: z17.object({
         posts: z17.array(
           z17.object({
-            id: z17.string(),
-            caption: z17.string(),
-            title: z17.string().optional(),
-            platform: z17.string()
+            id: z17.string().describe("Unique post identifier."),
+            caption: z17.string().describe("Post caption/body text to quality-check."),
+            title: z17.string().optional().describe("Post title (important for YouTube)."),
+            platform: z17.string().describe("Target platform (e.g. instagram, youtube).")
           })
         )
-      }).passthrough().describe("Content plan with posts array"),
+      }).passthrough().describe("Content plan with posts array."),
       threshold: z17.number().min(0).max(35).default(26).describe("Minimum total score to pass (max 35, scored across 7 categories at 0-5 each). Default 26 (~75%). Use 20 for rough drafts, 28+ for final posts going to large audiences."),
-      response_format: z17.enum(["text", "json"]).default("text")
+      response_format: z17.enum(["text", "json"]).default("text").describe("Response format. Defaults to text.")
+    },
+    {
+      title: "Quality Check Plan",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
     },
     async ({ plan, threshold, response_format }) => {
       const startedAt = Date.now();
@@ -7503,7 +7845,14 @@ function registerPlanningTools(server) {
       start_date: z18.string().optional().describe("ISO date, defaults to tomorrow"),
       brand_voice: z18.string().optional().describe("Override brand voice description"),
       project_id: z18.string().optional().describe("Project ID for brand/insights context"),
-      response_format: z18.enum(["text", "json"]).default("json")
+      response_format: z18.enum(["text", "json"]).default("json").describe("Response format. Defaults to json.")
+    },
+    {
+      title: "Plan Content Week",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
     },
     async ({
       topic,
@@ -7658,7 +8007,7 @@ ${ideationContext.promptInjection.slice(0, 1500)}` : "",
             content: [
               {
                 type: "text",
-                text: `Plan generation failed: ${aiError ?? "No response from AI"}`
+                text: formatToolError(`Plan generation failed: ${aiError ?? "No response from AI"}`)
               }
             ],
             isError: true
@@ -7678,10 +8027,10 @@ ${ideationContext.promptInjection.slice(0, 1500)}` : "",
             content: [
               {
                 type: "text",
-                text: `AI response could not be parsed as JSON.
+                text: formatToolError(`AI response could not be parsed as JSON.
 
 Raw output (first 1000 chars):
-${rawText.slice(0, 1e3)}`
+${rawText.slice(0, 1e3)}`)
               }
             ],
             isError: true
@@ -7808,7 +8157,7 @@ ${rawText.slice(0, 1e3)}`
           content: [
             {
               type: "text",
-              text: `Plan generation failed: ${message}`
+              text: formatToolError(`Plan generation failed: ${message}`)
             }
           ],
           isError: true
@@ -7821,12 +8170,19 @@ ${rawText.slice(0, 1e3)}`
     "Save a content plan to the database for team review, approval workflows, and scheduled publishing. Creates a plan_id you can reference in get_content_plan, update_content_plan, and schedule_content_plan.",
     {
       plan: z18.object({
-        topic: z18.string(),
-        posts: z18.array(z18.record(z18.string(), z18.unknown()))
-      }).passthrough(),
-      project_id: z18.string().uuid().optional(),
-      status: z18.enum(["draft", "in_review", "approved", "scheduled", "completed"]).default("draft"),
-      response_format: z18.enum(["text", "json"]).default("json")
+        topic: z18.string().describe("Content plan topic or theme."),
+        posts: z18.array(z18.record(z18.string(), z18.unknown())).describe("Array of post objects to save.")
+      }).passthrough().describe("Content plan object with topic and posts array."),
+      project_id: z18.string().uuid().optional().describe("Project ID. Defaults to active project context."),
+      status: z18.enum(["draft", "in_review", "approved", "scheduled", "completed"]).default("draft").describe("Initial plan status. Defaults to draft."),
+      response_format: z18.enum(["text", "json"]).default("json").describe("Response format. Defaults to json.")
+    },
+    {
+      title: "Save Content Plan",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false
     },
     async ({ plan, project_id, status, response_format }) => {
       const startedAt = Date.now();
@@ -7914,7 +8270,7 @@ ${rawText.slice(0, 1e3)}`
           content: [
             {
               type: "text",
-              text: `Failed to save content plan: ${message}`
+              text: formatToolError(`Failed to save content plan: ${message}`)
             }
           ],
           isError: true
@@ -7924,10 +8280,17 @@ ${rawText.slice(0, 1e3)}`
   );
   server.tool(
     "get_content_plan",
-    "Retrieve a persisted content plan by ID.",
+    "Retrieve a saved content plan to review its posts, status, and applied insights. Use after plan_content_week or save_content_plan to inspect what was generated. Feed the result into update_content_plan to revise posts or submit_content_plan_for_approval to start the review workflow.",
     {
       plan_id: z18.string().uuid().describe("Persisted content plan ID"),
-      response_format: z18.enum(["text", "json"]).default("json")
+      response_format: z18.enum(["text", "json"]).default("json").describe("Response format. Defaults to json.")
+    },
+    {
+      title: "Get Content Plan",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
     },
     async ({ plan_id, response_format }) => {
       const supabase = getSupabaseClient();
@@ -7940,7 +8303,7 @@ ${rawText.slice(0, 1e3)}`
           content: [
             {
               type: "text",
-              text: `Failed to load content plan: ${sanitizeDbError(error)}`
+              text: formatToolError(`Failed to load content plan: ${sanitizeDbError(error)}`)
             }
           ],
           isError: true
@@ -7951,7 +8314,7 @@ ${rawText.slice(0, 1e3)}`
           content: [
             {
               type: "text",
-              text: `No content plan found for plan_id=${plan_id}`
+              text: formatToolError(`No content plan found for plan_id=${plan_id}`)
             }
           ],
           isError: true
@@ -7992,25 +8355,32 @@ ${rawText.slice(0, 1e3)}`
   );
   server.tool(
     "update_content_plan",
-    "Update individual posts in a persisted content plan.",
+    "Revise specific posts in a saved content plan -- edit captions, hooks, hashtags, schedule times, or mark posts as approved/rejected. Call after reviewing a plan with get_content_plan. When all posts are approved, the plan status auto-advances so it can be scheduled.",
     {
-      plan_id: z18.string().uuid(),
+      plan_id: z18.string().uuid().describe("Content plan ID to update."),
       post_updates: z18.array(
         z18.object({
-          post_id: z18.string(),
-          caption: z18.string().optional(),
-          title: z18.string().optional(),
-          hashtags: z18.array(z18.string()).optional(),
-          hook: z18.string().optional(),
-          angle: z18.string().optional(),
-          visual_direction: z18.string().optional(),
-          media_url: z18.string().optional(),
-          schedule_at: z18.string().optional(),
-          platform: z18.string().optional(),
-          status: z18.enum(["approved", "rejected", "needs_edit"]).optional()
+          post_id: z18.string().describe("ID of the post to update within this plan."),
+          caption: z18.string().optional().describe("Revised caption/body text."),
+          title: z18.string().optional().describe("Revised post title."),
+          hashtags: z18.array(z18.string()).optional().describe("Revised hashtags array."),
+          hook: z18.string().optional().describe("Revised attention-grabbing opening line."),
+          angle: z18.string().optional().describe("Revised content angle or perspective."),
+          visual_direction: z18.string().optional().describe("Revised visual/media direction notes."),
+          media_url: z18.string().optional().describe("Revised media URL (public or R2 signed URL)."),
+          schedule_at: z18.string().optional().describe("Revised ISO 8601 UTC publish datetime."),
+          platform: z18.string().optional().describe("Revised target platform."),
+          status: z18.enum(["approved", "rejected", "needs_edit"]).optional().describe("Review status for this post.")
         })
-      ).min(1),
-      response_format: z18.enum(["text", "json"]).default("json")
+      ).min(1).describe("Array of post-level updates to apply."),
+      response_format: z18.enum(["text", "json"]).default("json").describe("Response format. Defaults to json.")
+    },
+    {
+      title: "Update Content Plan",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
     },
     async ({ plan_id, post_updates, response_format }) => {
       const supabase = getSupabaseClient();
@@ -8032,7 +8402,7 @@ ${rawText.slice(0, 1e3)}`
           content: [
             {
               type: "text",
-              text: `No content plan found for plan_id=${plan_id}`
+              text: formatToolError(`No content plan found for plan_id=${plan_id}`)
             }
           ],
           isError: true
@@ -8076,7 +8446,7 @@ ${rawText.slice(0, 1e3)}`
           content: [
             {
               type: "text",
-              text: `Failed to update content plan: ${sanitizeDbError(saveError)}`
+              text: formatToolError(`Failed to update content plan: ${sanitizeDbError(saveError)}`)
             }
           ],
           isError: true
@@ -8111,10 +8481,17 @@ ${rawText.slice(0, 1e3)}`
   );
   server.tool(
     "submit_content_plan_for_approval",
-    "Create pending approval items for each post in a plan and mark plan status as in_review.",
+    "Submit an entire saved content plan for team review in one call -- creates approval items for every post and sets the plan to in_review status. Call after plan_content_week and any update_content_plan edits are done. Use list_plan_approvals to track reviewer decisions.",
     {
-      plan_id: z18.string().uuid(),
-      response_format: z18.enum(["text", "json"]).default("json")
+      plan_id: z18.string().uuid().describe("Content plan ID to submit for review."),
+      response_format: z18.enum(["text", "json"]).default("json").describe("Response format. Defaults to json.")
+    },
+    {
+      title: "Submit Plan for Approval",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
     },
     async ({ plan_id, response_format }) => {
       const supabase = getSupabaseClient();
@@ -8136,7 +8513,7 @@ ${rawText.slice(0, 1e3)}`
           content: [
             {
               type: "text",
-              text: `No content plan found for plan_id=${plan_id}`
+              text: formatToolError(`No content plan found for plan_id=${plan_id}`)
             }
           ],
           isError: true
@@ -8149,7 +8526,7 @@ ${rawText.slice(0, 1e3)}`
           content: [
             {
               type: "text",
-              text: `Plan ${plan_id} has no posts to submit.`
+              text: formatToolError(`Plan ${plan_id} has no posts to submit.`)
             }
           ],
           isError: true
@@ -8169,7 +8546,7 @@ ${rawText.slice(0, 1e3)}`
           content: [
             {
               type: "text",
-              text: `Failed to create approvals: ${sanitizeDbError(approvalError)}`
+              text: formatToolError(`Failed to create approvals: ${sanitizeDbError(approvalError)}`)
             }
           ],
           isError: true
@@ -8181,7 +8558,7 @@ ${rawText.slice(0, 1e3)}`
           content: [
             {
               type: "text",
-              text: `Failed to update plan status: ${sanitizeDbError(statusError)}`
+              text: formatToolError(`Failed to update plan status: ${sanitizeDbError(statusError)}`)
             }
           ],
           isError: true
@@ -8238,21 +8615,28 @@ async function assertProjectAccess(supabase, userId, projectId) {
 function registerPlanApprovalTools(server) {
   server.tool(
     "create_plan_approvals",
-    "Create pending approval rows for each post in a content plan.",
+    "Create individual approval items for posts you supply explicitly, useful when building a custom approval queue outside the standard plan workflow. Requires the post array as input. Use list_plan_approvals to check status afterward, and respond_plan_approval to approve or reject each item.",
     {
       plan_id: z19.string().uuid().describe("Content plan ID"),
       posts: z19.array(
         z19.object({
-          id: z19.string(),
-          platform: z19.string().optional(),
-          caption: z19.string().optional(),
-          title: z19.string().optional(),
-          media_url: z19.string().optional(),
-          schedule_at: z19.string().optional()
+          id: z19.string().describe("Unique post identifier from the content plan."),
+          platform: z19.string().optional().describe("Target platform (e.g. instagram, youtube)."),
+          caption: z19.string().optional().describe("Post caption/body text."),
+          title: z19.string().optional().describe("Post title, used by YouTube and LinkedIn articles."),
+          media_url: z19.string().optional().describe("Public or R2 signed URL for the post media."),
+          schedule_at: z19.string().optional().describe("ISO 8601 UTC datetime to publish (e.g. 2026-03-20T14:00:00Z).")
         }).passthrough()
       ).min(1).describe("Posts to create approval entries for."),
       project_id: z19.string().uuid().optional().describe("Project ID. Defaults to active project context."),
-      response_format: z19.enum(["text", "json"]).optional()
+      response_format: z19.enum(["text", "json"]).optional().describe("Response format. Defaults to text.")
+    },
+    {
+      title: "Create Plan Approvals",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false
     },
     async ({ plan_id, posts, project_id, response_format }) => {
       const supabase = getSupabaseClient();
@@ -8332,8 +8716,15 @@ function registerPlanApprovalTools(server) {
     "List MCP-native approval items for a specific content plan.",
     {
       plan_id: z19.string().uuid().describe("Content plan ID"),
-      status: z19.enum(["pending", "approved", "rejected", "edited"]).optional(),
-      response_format: z19.enum(["text", "json"]).optional()
+      status: z19.enum(["pending", "approved", "rejected", "edited"]).optional().describe("Filter approvals by status. Omit to return all statuses."),
+      response_format: z19.enum(["text", "json"]).optional().describe("Response format. Defaults to text.")
+    },
+    {
+      title: "List Plan Approvals",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
     },
     async ({ plan_id, status, response_format }) => {
       const supabase = getSupabaseClient();
@@ -8400,10 +8791,19 @@ function registerPlanApprovalTools(server) {
     "Approve, reject, or edit a pending plan approval item.",
     {
       approval_id: z19.string().uuid().describe("Approval item ID"),
-      decision: z19.enum(["approved", "rejected", "edited"]),
-      edited_post: z19.record(z19.string(), z19.unknown()).optional(),
-      reason: z19.string().max(1e3).optional(),
-      response_format: z19.enum(["text", "json"]).optional()
+      decision: z19.enum(["approved", "rejected", "edited"]).describe("Approval decision for this post."),
+      edited_post: z19.record(z19.string(), z19.unknown()).optional().describe(
+        'Revised post fields when decision is "edited" (e.g. {caption: "...", hashtags: [...]}).'
+      ),
+      reason: z19.string().max(1e3).optional().describe("Optional reason for the decision, visible to the plan author."),
+      response_format: z19.enum(["text", "json"]).optional().describe("Response format. Defaults to text.")
+    },
+    {
+      title: "Respond to Plan Approval",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
     },
     async ({ approval_id, decision, edited_post, reason, response_format }) => {
       const supabase = getSupabaseClient();
@@ -8840,6 +9240,13 @@ function registerDiscoveryTools(server) {
         'Detail level: "name" for just tool names, "summary" for names + descriptions, "full" for complete info including scope and module'
       )
     },
+    {
+      title: "Search Tools",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    },
     async ({ query, module, scope, detail }) => {
       let results = [...TOOL_CATALOG];
       if (query) {