@socialneuron/mcp-server 1.4.2 → 1.5.1

package/dist/index.js

@@ -14,7 +14,7 @@ var MCP_VERSION;
 var init_version = __esm({
   "src/lib/version.ts"() {
     "use strict";
-    MCP_VERSION = "1.4.2";
+    MCP_VERSION = "1.5.1";
   }
 });
 
@@ -400,7 +400,9 @@ async function getDefaultUserId() {
   if (authenticatedUserId) return authenticatedUserId;
   const envUserId = process.env.SOCIALNEURON_USER_ID;
   if (envUserId) return envUserId;
-  throw new Error("No user ID available. Set SOCIALNEURON_USER_ID or authenticate via API key.");
+  throw new Error(
+    "No user ID available. Set SOCIALNEURON_USER_ID or authenticate via API key."
+  );
 }
 async function getDefaultProjectId() {
   const userId = await getDefaultUserId().catch(() => null);
@@ -444,7 +446,9 @@ async function initializeAuth() {
       console.error("[MCP] Scopes: " + authenticatedScopes.join(", "));
       if (authenticatedExpiresAt) {
         const expiresMs = new Date(authenticatedExpiresAt).getTime();
-        const daysLeft = Math.ceil((expiresMs - Date.now()) / (1e3 * 60 * 60 * 24));
+        const daysLeft = Math.ceil(
+          (expiresMs - Date.now()) / (1e3 * 60 * 60 * 24)
+        );
         console.error("[MCP] Key expires: " + authenticatedExpiresAt);
         if (daysLeft <= 7) {
           console.error(
@@ -467,8 +471,12 @@ async function initializeAuth() {
     console.error(
       "[MCP] \u26A0 DEPRECATED: Service role keys grant full admin access to your database."
     );
-    console.error("[MCP]   Migrate to API key auth: npx @socialneuron/mcp-server setup");
-    console.error("[MCP]   Then remove SOCIALNEURON_SERVICE_KEY from your environment.");
+    console.error(
+      "[MCP]   Migrate to API key auth: npx @socialneuron/mcp-server setup"
+    );
+    console.error(
+      "[MCP]   Then remove SOCIALNEURON_SERVICE_KEY from your environment."
+    );
     if (!process.env.SOCIALNEURON_USER_ID) {
       console.error(
         "[MCP] Warning: SOCIALNEURON_USER_ID not set. Tools requiring a user will fail."
@@ -2947,7 +2955,9 @@ __export(setup_exports, {
   runSetup: () => runSetup
 });
 import { createHash as createHash4, randomBytes, randomUUID as randomUUID3 } from "node:crypto";
-import { createServer } from "node:http";
+import {
+  createServer
+} from "node:http";
 import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "node:fs";
 import { homedir as homedir3, platform as platform2 } from "node:os";
 import { join as join3 } from "node:path";
@@ -2962,7 +2972,7 @@ function generatePKCE() {
   return { codeVerifier, codeChallenge };
 }
 function getAppBaseUrl() {
-  return process.env.SOCIALNEURON_APP_URL || "https://app.socialneuron.com";
+  return process.env.SOCIALNEURON_APP_URL || "https://www.socialneuron.com";
 }
 function getDefaultSupabaseUrl() {
   return process.env.SOCIALNEURON_SUPABASE_URL || process.env.SUPABASE_URL || CLOUD_SUPABASE_URL;
@@ -3033,11 +3043,14 @@ function readBody(req) {
 async function completePkceExchange(codeVerifier, state) {
   const supabaseUrl = getDefaultSupabaseUrl();
   try {
-    const response = await fetch(`${supabaseUrl}/functions/v1/mcp-auth?action=exchange-key`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ code_verifier: codeVerifier, state })
-    });
+    const response = await fetch(
+      `${supabaseUrl}/functions/v1/mcp-auth?action=exchange-key`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ code_verifier: codeVerifier, state })
+      }
+    );
     if (!response.ok) {
       const text = await response.text();
       console.error(`  PKCE exchange failed: ${text}`);
@@ -3046,7 +3059,9 @@ async function completePkceExchange(codeVerifier, state) {
     const data = await response.json();
     return data.success === true;
   } catch (err) {
-    console.error(`  PKCE exchange error: ${err instanceof Error ? err.message : String(err)}`);
+    console.error(
+      `  PKCE exchange error: ${err instanceof Error ? err.message : String(err)}`
+    );
     return false;
   }
 }
@@ -3057,9 +3072,13 @@ async function runSetup() {
   console.error("");
   console.error("  Privacy Notice:");
   console.error("  - Your API key is stored locally in your OS keychain");
-  console.error("  - Tool invocations are logged for usage metering (no content stored)");
+  console.error(
+    "  - Tool invocations are logged for usage metering (no content stored)"
+  );
   console.error("  - Set DO_NOT_TRACK=1 to disable telemetry");
-  console.error("  - Data export/delete: https://app.socialneuron.com/settings");
+  console.error(
+    "  - Data export/delete: https://www.socialneuron.com/settings"
+  );
   console.error("");
   const { codeVerifier, codeChallenge } = generatePKCE();
   const state = randomUUID3();
@@ -3092,49 +3111,54 @@ async function runSetup() {
     console.error("");
     console.error("  Waiting for authorization (timeout: 120s)...");
   }
-  const result = await new Promise((resolve3) => {
-    const timeout = setTimeout(() => {
-      server2.close();
-      resolve3({ error: "Authorization timed out after 120 seconds." });
-    }, 12e4);
-    server2.on("request", async (req, res) => {
-      res.setHeader("Access-Control-Allow-Origin", "*");
-      res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
-      res.setHeader("Access-Control-Allow-Headers", "Content-Type");
-      if (req.method === "OPTIONS") {
-        res.writeHead(204);
-        res.end();
-        return;
-      }
-      if (req.method === "POST" && req.url === "/callback") {
-        try {
-          const body = await readBody(req);
-          const data = JSON.parse(body);
-          if (data.state !== state) {
-            res.writeHead(400, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({ error: "State mismatch" }));
+  const result = await new Promise(
+    (resolve3) => {
+      const timeout = setTimeout(() => {
+        server2.close();
+        resolve3({ error: "Authorization timed out after 120 seconds." });
+      }, 12e4);
+      server2.on(
+        "request",
+        async (req, res) => {
+          res.setHeader("Access-Control-Allow-Origin", "*");
+          res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
+          res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+          if (req.method === "OPTIONS") {
+            res.writeHead(204);
+            res.end();
             return;
           }
-          if (!data.api_key) {
-            res.writeHead(400, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({ error: "Missing api_key" }));
+          if (req.method === "POST" && req.url === "/callback") {
+            try {
+              const body = await readBody(req);
+              const data = JSON.parse(body);
+              if (data.state !== state) {
+                res.writeHead(400, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "State mismatch" }));
+                return;
+              }
+              if (!data.api_key) {
+                res.writeHead(400, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "Missing api_key" }));
+                return;
+              }
+              res.writeHead(200, { "Content-Type": "application/json" });
+              res.end(JSON.stringify({ success: true }));
+              clearTimeout(timeout);
+              server2.close();
+              resolve3({ apiKey: data.api_key });
+            } catch {
+              res.writeHead(400, { "Content-Type": "application/json" });
+              res.end(JSON.stringify({ error: "Invalid request" }));
+            }
             return;
           }
-          res.writeHead(200, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ success: true }));
-          clearTimeout(timeout);
-          server2.close();
-          resolve3({ apiKey: data.api_key });
-        } catch {
-          res.writeHead(400, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ error: "Invalid request" }));
+          res.writeHead(404);
+          res.end("Not found");
         }
-        return;
-      }
-      res.writeHead(404);
-      res.end("Not found");
-    });
-  });
+      );
+    }
+  );
   if ("error" in result) {
     console.error("");
     console.error(`  Error: ${result.error}`);
@@ -3146,7 +3170,9 @@ async function runSetup() {
   const exchangeSuccess = await completePkceExchange(codeVerifier, state);
   if (!exchangeSuccess) {
     console.error("  Warning: PKCE exchange failed. Key may not be activated.");
-    console.error("  The key will still work if the server was in legacy mode.");
+    console.error(
+      "  The key will still work if the server was in legacy mode."
+    );
   } else {
     console.error("  PKCE verification complete.");
   }
@@ -3167,7 +3193,9 @@ async function runSetup() {
   }
   if (!configured) {
     console.error("");
-    console.error("  No MCP client config found. Add this to your MCP config manually:");
+    console.error(
+      "  No MCP client config found. Add this to your MCP config manually:"
+    );
     console.error("");
     console.error('    "socialneuron": {');
     console.error('      "command": "npx",');
@@ -3870,10 +3898,10 @@ init_supabase();
 function registerIdeationTools(server2) {
   server2.tool(
     "generate_content",
-    "Generate AI-powered content (scripts, captions, hooks, blog posts) using Google Gemini or Anthropic Claude. Provide a detailed prompt describing what you need, choose the content type, and optionally specify a target platform and brand voice guidelines.",
+    "Create a script, caption, hook, or blog post tailored to a specific platform. Pass project_id to auto-load brand profile and performance context, or call get_ideation_context first for full context. Output is draft text ready for quality_check then schedule_post.",
     {
       prompt: z.string().max(1e4).describe(
-        "Detailed prompt describing the content to generate. Include context like topic, angle, audience, and any specific requirements."
+        'Detailed content prompt. Include topic, angle, audience, and requirements. Example: "LinkedIn post about AI productivity for CTOs, 300 words, include 3 actionable tips, conversational tone." Richer prompts produce better results.'
       ),
       content_type: z.enum(["script", "caption", "blog", "hook"]).describe(
         'Type of content to generate. "script" for video scripts, "caption" for social media captions, "blog" for blog posts, "hook" for attention-grabbing hooks.'
@@ -3891,7 +3919,7 @@ function registerIdeationTools(server2) {
         "Target social media platform. Helps tailor tone, length, and format."
       ),
       brand_voice: z.string().max(500).optional().describe(
-        'Brand voice guidelines to follow (e.g. "professional and empathetic", "playful and Gen-Z"). Leave blank to use a neutral tone.'
+        'Tone directive (e.g. "direct, no jargon, second person" or "witty Gen-Z energy with emoji"). Leave blank to auto-load from project brand profile if project_id is set.'
       ),
       model: z.enum(["gemini-2.0-flash", "gemini-2.5-flash", "gemini-2.5-pro"]).optional().describe(
         "AI model to use. Defaults to gemini-2.5-flash. Use gemini-2.5-pro for highest quality."
@@ -3900,6 +3928,13 @@ function registerIdeationTools(server2) {
         "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: prompt2,
       content_type,
@@ -4047,7 +4082,7 @@ Content Type: ${content_type}`;
   );
   server2.tool(
     "fetch_trends",
-    "Fetch current trending topics from YouTube, Google Trends, RSS feeds, or a custom URL. Results are cached for efficiency. Use this to discover what is popular right now for content ideation.",
+    'Get current trending topics for content inspiration. Source "youtube" returns trending videos with view counts, "google_trends" returns rising search terms, "rss"/"url" extracts topics from any feed or page. Results cached 1 hour \u2014 set force_refresh=true for real-time. Feed results into generate_content or plan_content_week.',
     {
       source: z.enum(["youtube", "google_trends", "rss", "url"]).describe(
         'Data source. "youtube" fetches trending videos, "google_trends" fetches daily search trends, "rss" fetches from a custom RSS feed URL, "url" extracts trend data from a web page.'
@@ -4063,6 +4098,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 {
@@ -4133,7 +4175,7 @@ Content Type: ${content_type}`;
   );
   server2.tool(
     "adapt_content",
-    "Adapt existing content for a different social media platform. Rewrites content to match the target platform's norms including character limits, hashtag style, tone, and CTA conventions.",
+    "Rewrite existing content for a different platform \u2014 adjusts character limits, hashtag style, tone, and CTA format automatically. Use after generate_content when you need the same message across multiple platforms. Pass project_id to apply platform-specific voice overrides from your brand profile.",
     {
       content: z.string().max(5e3).describe(
         "The content to adapt. Can be a caption, script, blog excerpt, or any text."
@@ -4167,6 +4209,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,
@@ -4431,10 +4480,10 @@ function checkAssetBudget() {
 function registerContentTools(server2) {
   server2.tool(
     "generate_video",
-    "Start an AI video generation job. This is an async operation -- it returns a job_id immediately. Use check_status to poll for completion. Supports Veo 3, Runway, Sora 2, Kling 2.6, and Kling 3.0 models via the Kie.ai API.",
+    "Start an async AI video generation job \u2014 returns a job_id immediately. Poll with check_status every 10-30s until complete. Cost varies by model: veo3-fast (~15 credits/5s), kling-3 (~30 credits/5s), sora2-pro (~60 credits/10s). Check get_credit_balance first for expensive generations.",
     {
       prompt: z2.string().max(2500).describe(
-        "Text prompt describing the video to generate. Be specific about visual style, camera angles, movement, lighting, and mood."
+        'Video prompt \u2014 be specific about visual style, camera movement, lighting, and mood. Example: "Aerial drone shot of coastal cliffs at golden hour, slow dolly forward, cinematic 24fps, warm color grading." Vague prompts produce generic results.'
       ),
       model: z2.enum([
         "veo3-fast",
@@ -4446,13 +4495,13 @@ function registerContentTools(server2) {
         "kling-3",
         "kling-3-pro"
       ]).describe(
-        "Video generation model. veo3-fast is fastest (~60s), veo3-quality is highest quality (~120s). sora2-pro is OpenAI Sora premium tier. kling-3 is Kling 3.0 standard (4K, 15s, audio). kling-3-pro is Kling 3.0 pro (higher quality)."
+        "Video model. veo3-fast: fastest (~15 credits/5s, ~60s render). veo3-quality: highest quality (~20 credits/5s, ~120s). sora2-pro: OpenAI premium (~60 credits/10s). kling-3: 4K with audio (~30 credits/5s). kling-3-pro: best Kling quality (~40 credits/5s)."
       ),
       duration: z2.number().min(3).max(30).optional().describe(
         "Video duration in seconds. kling: 5-30s, kling-3/kling-3-pro: 3-15s, sora2: 10-15s. Defaults to 5 seconds."
       ),
       aspect_ratio: z2.enum(["16:9", "9:16", "1:1"]).optional().describe(
-        "Aspect ratio. 16:9 for landscape/YouTube, 9:16 for vertical/Reels/TikTok, 1:1 for square. Defaults to 16:9."
+        "Video aspect ratio. 16:9 for YouTube/landscape, 9:16 for TikTok/Reels/Shorts, 1:1 for Instagram feed/square. Defaults to 16:9."
       ),
       enable_audio: z2.boolean().optional().describe(
         "Enable native audio generation. Kling 2.6: doubles cost. Kling 3.0: 50% more (std 30/sec, pro 40/sec). 5+ languages."
@@ -4465,6 +4514,13 @@ function registerContentTools(server2) {
       ),
       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: prompt2,
       model,
@@ -4639,7 +4695,7 @@ function registerContentTools(server2) {
   );
   server2.tool(
     "generate_image",
-    "Start an AI image generation job. This is an async operation -- it returns a job_id immediately. Use check_status to poll for completion. Supports Midjourney, Imagen 4, Flux, GPT-4o Image, and Seedream models.",
+    "Start an async AI image generation job \u2014 returns a job_id immediately. Poll with check_status every 5-15s until complete. Costs 2-10 credits depending on model. Use for social media posts, carousel slides, or as input to generate_video (image-to-video).",
     {
       prompt: z2.string().max(2e3).describe(
         "Text prompt describing the image to generate. Be specific about style, composition, colors, lighting, and subject matter."
@@ -4663,6 +4719,13 @@ function registerContentTools(server2) {
       ),
       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: prompt2, model, aspect_ratio, image_url, response_format }) => {
       const format = response_format ?? "text";
       const startedAt = Date.now();
@@ -4819,13 +4882,20 @@ function registerContentTools(server2) {
   );
   server2.tool(
     "check_status",
-    "Check the status of an async generation job (video or image). Returns the current status, progress percentage, and result URL when complete. Call this tool periodically after generate_video or generate_image.",
+    'Poll an async job started by generate_video or generate_image. Returns status (queued/processing/completed/failed), progress %, and result URL on completion. Poll every 10-30s for video, 5-15s for images. On "failed" status, the error field explains why \u2014 check credits or try a different model.',
     {
       job_id: z2.string().describe(
         "The job ID returned by generate_video or generate_image. This is the asyncJobId or taskId value."
       ),
       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();
@@ -4995,7 +5065,7 @@ function registerContentTools(server2) {
   );
   server2.tool(
     "create_storyboard",
-    "Generate a structured scene-by-scene storyboard for video production. Returns an array of StoryboardFrames with prompts, durations, captions, and voiceover text. Use the output to drive image/video generation.",
+    "Plan a multi-scene video storyboard with AI-generated prompts, durations, captions, and voiceover text per frame. Use before generate_video or generate_image to create cohesive multi-shot content. Include brand_context from get_brand_profile for consistent visual branding across frames.",
     {
       concept: z2.string().max(2e3).describe(
         'The video concept/idea. Include: hook, key messages, target audience, and desired outcome (e.g., "TikTok ad for VPN app targeting privacy-conscious millennials, hook with shocking stat about data leaks").'
@@ -5023,6 +5093,13 @@ function registerContentTools(server2) {
         "Response format. Defaults to json for structured storyboard data."
       )
     },
+    {
+      title: "Create Storyboard",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
     async ({
       concept,
       brand_context,
@@ -5182,7 +5259,7 @@ Return ONLY valid JSON in this exact format:
   );
   server2.tool(
     "generate_voiceover",
-    "Generate a professional voiceover audio file using ElevenLabs TTS. Returns an audio URL stored in R2. Use this for narration in video production.",
+    "Generate a voiceover audio file for video narration. Returns an R2-hosted audio URL. Use after create_storyboard to add narration to each scene, or standalone for podcast intros and ad reads. Costs ~2 credits per generation.",
     {
       text: z2.string().max(5e3).describe("The script/text to convert to speech."),
       voice: z2.enum([
@@ -5203,6 +5280,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();
@@ -5333,10 +5417,10 @@ Return ONLY valid JSON in this exact format:
   );
   server2.tool(
     "generate_carousel",
-    "Generate an Instagram carousel with AI-powered slide content. Supports multiple templates including Hormozi-style authority carousels. Returns slide data (headlines, body text, emphasis words). Use schedule_post with media_urls to publish the carousel to Instagram.",
+    "Generate carousel slide content (headlines, body text, emphasis words per slide). Supports Hormozi-style authority format and educational templates. Returns structured slide data \u2014 render visually then publish via schedule_post with media_type=CAROUSEL_ALBUM and 2-10 media_urls on Instagram.",
     {
       topic: z2.string().max(200).describe(
-        'The carousel topic/subject. Be specific about the angle or hook. Example: "5 reasons your startup will fail in 2026"'
+        'Carousel hook/angle \u2014 specific beats general. Example: "5 pricing mistakes that kill SaaS startups" beats "SaaS tips". Include a curiosity gap or strong opinion for better Hook Strength scores.'
       ),
       template_id: z2.enum([
         "educational-series",
@@ -5361,6 +5445,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,
@@ -5543,14 +5634,12 @@ function asEnvelope2(data) {
 function registerDistributionTools(server2) {
   server2.tool(
     "schedule_post",
-    "Schedule or immediately publish a post to one or more social media platforms. Requires the target platforms to have active OAuth connections configured in Social Neuron Settings. Supports YouTube, TikTok, Instagram, Facebook, LinkedIn, Twitter, Threads, and Bluesky. For Instagram carousels, provide media_urls (2-10 image URLs) and set media_type to CAROUSEL_ALBUM.",
+    'Publish or schedule a post to connected social platforms. Check list_connected_accounts first to verify active OAuth for each target platform. For Instagram carousels: use media_type=CAROUSEL_ALBUM with 2-10 media_urls. For YouTube: title is required. schedule_at uses ISO 8601 (e.g. "2026-03-20T14:00:00Z") \u2014 omit to post immediately.',
     {
       media_url: z3.string().optional().describe(
         "Optional URL of the media file (video or image) to post. This should be a publicly accessible URL or a Cloudflare R2 signed URL from a previous generation. Required for platforms that enforce media uploads. Not needed if media_urls is provided."
       ),
-      media_urls: z3.array(z3.string()).optional().describe(
-        "Array of image URLs for Instagram carousel posts (2-10 images). Each URL should be publicly accessible or a Cloudflare R2 URL. When provided with media_type=CAROUSEL_ALBUM, creates an Instagram carousel."
-      ),
+      media_urls: z3.array(z3.string()).optional().describe("Array of 2-10 image URLs for Instagram carousel posts. Each URL must be publicly accessible or a Cloudflare R2 signed URL. Use with media_type=CAROUSEL_ALBUM."),
       media_type: z3.enum(["IMAGE", "VIDEO", "CAROUSEL_ALBUM"]).optional().describe(
         "Media type. Set to CAROUSEL_ALBUM with media_urls for Instagram carousels. Default: auto-detected from media_url."
       ),
@@ -5566,22 +5655,23 @@ function registerDistributionTools(server2) {
           "threads",
           "bluesky"
         ])
-      ).min(1).describe(
-        "Target platforms to post to. Each must have an active OAuth connection."
-      ),
+      ).min(1).describe("Target platforms (array). Each must have active OAuth \u2014 check list_connected_accounts first. Values: youtube, tiktok, instagram, twitter, linkedin, facebook, threads, bluesky."),
       title: z3.string().optional().describe("Post title (used by YouTube and some other platforms)."),
-      hashtags: z3.array(z3.string()).optional().describe(
-        'Hashtags to append to the caption. Include or omit the "#" prefix.'
-      ),
-      schedule_at: z3.string().optional().describe(
-        'ISO 8601 datetime for scheduled posting (e.g. "2026-03-15T14:00:00Z"). Omit for immediate posting.'
-      ),
+      hashtags: z3.array(z3.string()).optional().describe('Hashtags to append to caption. Include or omit the "#" prefix \u2014 both work. Example: ["ai", "contentcreator"] or ["#ai", "#contentcreator"].'),
+      schedule_at: z3.string().optional().describe('ISO 8601 UTC datetime for scheduled posting (e.g. "2026-03-20T14:00:00Z"). Omit to post immediately. Must be in the future.'),
       project_id: z3.string().optional().describe("Social Neuron project ID to associate this post with."),
       response_format: z3.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text."),
       attribution: z3.boolean().optional().describe(
         '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,
@@ -5729,10 +5819,17 @@ Created with Social Neuron`;
   );
   server2.tool(
     "list_connected_accounts",
-    "List all social media accounts connected to Social Neuron via OAuth. Shows which platforms are available for posting.",
+    "Check which social platforms have active OAuth connections for posting. Call this before schedule_post to verify credentials. If a platform is missing or expired, the user needs to reconnect at socialneuron.com/settings/connections.",
     {
       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();
@@ -5794,7 +5891,7 @@ Created with Social Neuron`;
   );
   server2.tool(
     "list_recent_posts",
-    "List recent posts from Social Neuron. Shows status, platform, title, and timestamps. Useful for checking what has been published or scheduled recently.",
+    "List recent published and scheduled posts with status, platform, title, and timestamps. Use to check what has been posted before planning new content, or to find post IDs for fetch_analytics. Filter by platform or status to narrow results.",
     {
       platform: z3.enum([
         "youtube",
@@ -5811,6 +5908,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: platform3, status, days, limit, response_format }) => {
       const format = response_format ?? "text";
       const supabase = getSupabaseClient();
@@ -5910,7 +6014,7 @@ Created with Social Neuron`;
   };
   server2.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([
@@ -5923,11 +6027,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,
@@ -6047,20 +6158,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."
       ),
@@ -6070,6 +6181,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,
@@ -6635,13 +6753,14 @@ function registerAnalyticsTools(server2) {
         "threads",
         "bluesky"
       ]).optional().describe("Filter analytics to a specific platform."),
-      days: z4.number().min(1).max(365).optional().describe("Number of days to look back. Defaults to 30. Max 365."),
+      days: z4.number().min(1).max(365).optional().describe("Lookback window in days (1-365). Default 30. Use 7 for weekly review, 30 for monthly summary, 90 for quarterly trends."),
       content_id: z4.string().uuid().optional().describe(
         "Filter to a specific content_history ID to see performance of one piece of content."
       ),
       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: platform3, days, content_id, limit, response_format }) => {
       const format = response_format ?? "text";
       const supabase = getSupabaseClient();
@@ -6815,10 +6934,17 @@ function registerAnalyticsTools(server2) {
   );
   server2.tool(
     "refresh_platform_analytics",
-    "Trigger an analytics refresh for all recently posted content across all connected platforms. Queues analytics fetch jobs for posts from the last 7 days.",
+    "Queue analytics refresh jobs for all posts from the last 7 days across connected platforms. Call this before fetch_analytics if you need fresh data. Returns immediately \u2014 data updates asynchronously over the next 1-5 minutes.",
     {
       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();
@@ -7220,6 +7346,13 @@ function registerBrandTools(server2) {
       ),
       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) {
@@ -7303,6 +7436,13 @@ function registerBrandTools(server2) {
       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();
@@ -7400,8 +7540,17 @@ function registerBrandTools(server2) {
         "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,
@@ -7514,15 +7663,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: platform3,
@@ -7771,6 +7937,13 @@ function registerScreenshotTools(server2) {
         "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";
@@ -7891,6 +8064,13 @@ function registerScreenshotTools(server2) {
       ),
       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";
@@ -8153,6 +8333,13 @@ function registerRemotionTools(server2) {
     "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) {
@@ -8181,6 +8368,13 @@ function registerRemotionTools(server2) {
         "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();
@@ -8362,6 +8556,13 @@ function registerInsightsTools(server2) {
       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();
@@ -8489,6 +8690,13 @@ function registerInsightsTools(server2) {
       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: platform3, days, response_format }) => {
       const format = response_format ?? "text";
       const supabase = getSupabaseClient();
@@ -8638,6 +8846,13 @@ function registerYouTubeAnalyticsTools(server2) {
       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 {
@@ -8751,15 +8966,20 @@ function asEnvelope6(data) {
 function registerCommentsTools(server2) {
   server2.tool(
     "list_comments",
-    "List YouTube comments. Without a video_id, returns recent comments across all channel videos. With a video_id, returns comments for that specific video.",
+    'List YouTube comments \u2014 pass video_id (11-char string, e.g. "dQw4w9WgXcQ") for a specific video, or omit for recent comments across all channel videos. Returns comment text, author, like count, and reply count. Use page_token from previous response for pagination.',
     {
-      video_id: z10.string().optional().describe(
-        "YouTube video ID. If omitted, returns comments across all channel videos."
-      ),
+      video_id: z10.string().optional().describe('YouTube video ID \u2014 the 11-character string from the URL (e.g. "dQw4w9WgXcQ" from youtube.com/watch?v=dQw4w9WgXcQ). Omit to get recent comments across all channel videos.'),
       max_results: z10.number().min(1).max(100).optional().describe("Maximum number of comments to return. Defaults to 50."),
-      page_token: z10.string().optional().describe("Pagination token from a previous list_comments call."),
+      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", {
@@ -8822,7 +9042,7 @@ function registerCommentsTools(server2) {
   );
   server2.tool(
     "reply_to_comment",
-    "Reply to a YouTube comment. Requires the parent comment ID and reply text.",
+    "Reply to a YouTube comment. Get the parent_id from list_comments results. Reply appears as the authenticated channel. Use for community engagement after checking list_comments for questions or feedback.",
     {
       parent_id: z10.string().describe(
         "The ID of the parent comment to reply to (from list_comments)."
@@ -8830,6 +9050,13 @@ function registerCommentsTools(server2) {
       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();
@@ -8911,6 +9138,13 @@ function registerCommentsTools(server2) {
       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();
@@ -8989,6 +9223,13 @@ function registerCommentsTools(server2) {
       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();
@@ -9074,6 +9315,13 @@ function registerCommentsTools(server2) {
       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();
@@ -9223,12 +9471,19 @@ function asEnvelope7(data) {
 function registerIdeationContextTools(server2) {
   server2.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();
@@ -9355,10 +9610,17 @@ function asEnvelope8(data) {
 function registerCreditsTools(server2) {
   server2.tool(
     "get_credit_balance",
-    "Get current subscription credit balance and plan.",
+    "Check remaining credits, monthly limit, spending cap, and plan tier. Call this before expensive operations \u2014 generate_video costs 15-80 credits, generate_image costs 2-10. Returns current balance, monthly allocation, and spending cap (2.5x allocation).",
     {
       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();
@@ -9408,10 +9670,17 @@ Monthly used: ${payload.monthlyUsed}` + (payload.monthlyLimit ? ` / ${payload.mo
   );
   server2.tool(
     "get_budget_status",
-    "Get current MCP run budget consumption for credits/assets.",
+    "Check how much of the per-session budget has been consumed. Tracks credits spent and assets created in this MCP session against configured limits. Use to avoid hitting budget caps mid-workflow.",
     {
       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 = {
@@ -9466,11 +9735,18 @@ function asEnvelope9(data) {
 function registerLoopSummaryTools(server2) {
   server2.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();
@@ -9569,6 +9845,13 @@ function registerUsageTools(server2) {
     {
       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();
@@ -9654,11 +9937,18 @@ function asEnvelope11(data) {
 function registerAutopilotTools(server2) {
   server2.tool(
     "list_autopilot_configs",
-    "List all autopilot configurations for your account. Shows active schedules, associated recipes, credit budgets, and last run times.",
+    "List autopilot configurations showing schedules, credit budgets, last run times, and active/inactive status. Use to check what is automated before creating new configs, or to find config_id for update_autopilot_config.",
     {
       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();
@@ -9736,11 +10026,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,
@@ -9800,10 +10097,17 @@ Schedule: ${JSON.stringify(updated.schedule_config)}`
   );
   server2.tool(
     "get_autopilot_status",
-    "Get the current status of your autopilot system, including active configs, recent runs, and next scheduled execution.",
+    "Get autopilot system overview: active config count, recent execution results, credits consumed, and next scheduled run time. Use as a dashboard check before modifying autopilot settings.",
     {
       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();
@@ -9919,13 +10223,20 @@ ${content.suggested_hooks.map((h) => `  - ${h}`).join("\n")}`
 function registerExtractionTools(server2) {
   server2.tool(
     "extract_url_content",
-    "Extract content from a URL (YouTube video transcript, article text, product page). Routes to scrape-youtube for YouTube URLs or fetch-url-content for other URLs.",
+    "Extract text content from any URL \u2014 YouTube video transcripts, article text, or product page features/benefits/USP. YouTube URLs auto-route to transcript extraction with optional comments. Use before generate_content to repurpose existing content, or before plan_content_week to base a content plan on a source URL.",
     {
       url: z16.string().url().describe("URL to extract content from"),
       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,
@@ -10119,9 +10430,9 @@ function asEnvelope13(data) {
 function registerQualityTools(server2) {
   server2.tool(
     "quality_check",
-    "Score a single post's content quality across 7 categories (Hook Strength, Message Clarity, Platform Fit, Brand Alignment, Novelty, CTA Strength, Safety/Claims). Returns pass/fail with per-category scores.",
+    "Score post quality across 7 categories: Hook Strength, Message Clarity, Platform Fit, Brand Alignment, Novelty, CTA Strength, and Safety/Claims. Each scored 0-5, total 35. Default pass threshold is 26 (~75%). Run after generate_content and before schedule_post. Include hashtags in caption if they will be published \u2014 they affect Platform Fit and Safety scores.",
     {
-      caption: z17.string().describe("Post caption/body text"),
+      caption: z17.string().describe("The post text to score. Include hashtags if they will be published \u2014 they affect Platform Fit and Safety/Claims scores."),
       title: z17.string().optional().describe("Post title (important for YouTube)"),
       platforms: z17.array(
         z17.enum([
@@ -10135,11 +10446,18 @@ function registerQualityTools(server2) {
           "bluesky"
         ])
       ).min(1).describe("Target platforms"),
-      threshold: z17.number().min(0).max(35).default(26).describe("Minimum total score to pass"),
+      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,
@@ -10206,20 +10524,27 @@ function registerQualityTools(server2) {
   );
   server2.tool(
     "quality_check_plan",
-    "Run quality checks on all posts in a content plan. Returns per-post scores and aggregate summary.",
+    "Batch quality check all posts in a content plan. Returns per-post scores and aggregate pass/fail summary. Use after plan_content_week and before schedule_content_plan to catch low-quality posts before publishing.",
     {
       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"),
-      threshold: z17.number().min(0).max(35).default(26).describe("Minimum total score to pass"),
-      response_format: z17.enum(["text", "json"]).default("text")
+      }).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").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();
@@ -10401,7 +10726,7 @@ function formatPlanAsText(plan) {
 function registerPlanningTools(server2) {
   server2.tool(
     "plan_content_week",
-    "Generate a full week's content plan with platform-specific drafts. Takes a topic or source URL, loads brand context and performance insights, and returns structured posts with hooks, angles, captions, and suggested schedule times.",
+    "Generate a full content plan with platform-specific drafts, hooks, angles, and optimal schedule times. Pass a topic or source_url \u2014 brand context and performance insights auto-load via project_id. Output feeds directly into quality_check_plan then schedule_content_plan. Costs ~5-15 credits depending on post count.",
     {
       topic: z18.string().describe("Main topic or content theme"),
       source_url: z18.string().optional().describe("URL to extract content from (YouTube, article)"),
@@ -10422,7 +10747,14 @@ function registerPlanningTools(server2) {
       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,
@@ -10737,15 +11069,22 @@ ${rawText.slice(0, 1e3)}`
   );
   server2.tool(
     "save_content_plan",
-    "Persist a content plan payload for later review, approvals, and scheduling.",
+    "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();
@@ -10843,10 +11182,17 @@ ${rawText.slice(0, 1e3)}`
   );
   server2.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();
@@ -10911,25 +11257,32 @@ ${rawText.slice(0, 1e3)}`
   );
   server2.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();
@@ -11030,10 +11383,17 @@ ${rawText.slice(0, 1e3)}`
   );
   server2.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().describe("Content plan ID to submit for review."),
+      response_format: z18.enum(["text", "json"]).default("json").describe("Response format. Defaults to json.")
+    },
     {
-      plan_id: z18.string().uuid(),
-      response_format: z18.enum(["text", "json"]).default("json")
+      title: "Submit Plan for Approval",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
     },
     async ({ plan_id, response_format }) => {
       const supabase = getSupabaseClient();
@@ -11158,21 +11518,28 @@ async function assertProjectAccess(supabase, userId, projectId) {
 function registerPlanApprovalTools(server2) {
   server2.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();
@@ -11252,8 +11619,15 @@ function registerPlanApprovalTools(server2) {
     "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();
@@ -11320,10 +11694,19 @@ function registerPlanApprovalTools(server2) {
     "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();
@@ -11402,7 +11785,7 @@ import { z as z20 } from "zod";
 function registerDiscoveryTools(server2) {
   server2.tool(
     "search_tools",
-    'Search and discover available MCP tools. Use detail level to control token usage: "name" (~50 tokens), "summary" (~500 tokens), "full" (complete schemas).',
+    'Search available tools by name, description, module, or scope. Use "name" detail (~50 tokens) for quick lookup, "summary" (~500 tokens) for descriptions, "full" for complete input schemas. Start here if unsure which tool to call \u2014 filter by module (e.g. "planning", "content", "analytics") to narrow results.',
     {
       query: z20.string().optional().describe("Search query to filter tools by name or description"),
       module: z20.string().optional().describe('Filter by module name (e.g. "planning", "content", "analytics")'),
@@ -11411,6 +11794,13 @@ function registerDiscoveryTools(server2) {
         '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) {