@omnisocials/mcp-server 1.20.0 → 1.21.0

package/build/tools/posts.js

@@ -83,6 +83,91 @@ const LINKEDIN_PAGE_OPTIONS = z
 })
     .optional()
     .describe("LinkedIn Company Page options");
+const LINKEDIN_POLL_OPTIONS = z
+    .object({
+    question: z.string().max(140).describe("The poll question (max 140 characters)."),
+    options: z
+        .array(z.string().max(30))
+        .min(2)
+        .max(4)
+        .describe("2-4 answer options (max 30 characters each)."),
+    duration: z
+        .enum(["ONE_DAY", "THREE_DAYS", "SEVEN_DAYS", "FOURTEEN_DAYS"])
+        .describe("How long the poll stays open for votes."),
+})
+    .nullable()
+    .optional()
+    .describe("Non-sponsored LinkedIn poll, posted to whichever of `linkedin`/`linkedin_page` is selected in `accounts`. Mutually exclusive with media and a link share — a poll takes priority over both at publish time. Still requires `content.linkedin` (or `content.default`) as the post's caption; the poll itself only carries the question/options/duration. Pass `null` on update_post to clear a poll and revert to a normal post.");
+// Per-platform option schemas shared verbatim by create_post,
+// create_and_publish_post and update_post (they were byte-identical in all
+// three). Platform blocks that genuinely differ per tool (instagram, youtube,
+// google_business, and the thread_parts wrappers with their per-tool
+// nullability/descriptions) stay inline in each tool.
+const TIKTOK_OPTIONS = z.object({
+    privacy_level: z.enum(["PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "FOLLOWER_OF_CREATOR", "SELF_ONLY"]).optional(),
+    disable_comment: z.boolean().optional(),
+    disable_duet: z.boolean().optional().describe("Reels only. Disable Duet on the video."),
+    disable_stitch: z.boolean().optional().describe("Reels only. Disable Stitch on the video."),
+    video_cover_timestamp_ms: z.number().optional().describe("Reels only. Timestamp (ms) of the video frame to use as the cover."),
+    is_aigc: z.boolean().optional().describe("Mark as AI-generated content."),
+    brand_content_toggle: z.boolean().optional().describe("Paid partnership disclosure (promotes a third-party brand)."),
+    brand_organic_toggle: z.boolean().optional().describe("Your own brand disclosure (promotes your own business)."),
+    auto_add_music: z.boolean().optional().describe("Photo carousels only. When true, TikTok auto-selects a soundtrack. Defaults to false to avoid unsuitable tracks."),
+}).optional().describe("TikTok options");
+const PINTEREST_OPTIONS = z.object({
+    board_id: z.string().optional().describe("Pinterest board ID. Required for Pinterest. Use get_account to list boards."),
+    title: z.string().optional().describe("Pin title (max 100 characters). For carousel pins (2–5 images) this title applies to the whole pin, not individual slides."),
+    link: z.string().optional().describe("Destination URL the pin clicks through to"),
+    video_cover: z.string().optional().describe("Cover image URL for video pins (JPEG/PNG). Falls back to a video keyframe if omitted."),
+    alt_text: z.string().optional().describe("Accessibility alt text for the pin image (max 500 characters)"),
+}).optional().describe("Pinterest-specific options. Attach 2–5 images via media_urls.pinterest (or default) to publish a single carousel pin instead of separate pins. More than 5 images is rejected with a 400 validation_error at create/schedule time — carousels hard-cap at 5. Carousel slides MUST share the same aspect ratio (1% tolerance) — the API returns 400 validation_error with `mismatched_slides: [n, ...]` if you pass mixed-ratio images and try to schedule or publish. Drafts are exempt so you can iterate.");
+// One Instagram photo tag. The wrapping z.array(...).describe(...) stays
+// per-tool because update_post documents replace/clear semantics.
+const USER_TAG_ENTRY = z.object({
+    username: z.string().describe("Public Instagram username to tag. Leading '@' is stripped."),
+    x: z.number().min(0).max(1).describe("Horizontal position 0.0–1.0 from the photo's left edge."),
+    y: z.number().min(0).max(1).describe("Vertical position 0.0–1.0 from the photo's top edge."),
+    image_index: z.number().int().min(0).optional().describe("0-based carousel slide this tag belongs to. Omit (or 0) for a single image."),
+});
+// Inner thread-part schemas for the chained-thread platforms. The wrapping
+// z.array(...).min(2).max(25)[.nullable()].optional().describe(...) stays
+// per-tool (update_post allows null to clear the thread).
+const X_THREAD_PART = z.object({
+    text: z.string().describe("Tweet text (≤ 280 chars). X counts every link as 23 characters (its t.co length), so a short link still uses 23 toward the limit."),
+    media_ids: z.array(mediaIdEntry).max(4).optional().describe("Per-tweet media as Library IDs from upload_media (max 4 combined with media_urls). Each entry is a plain ID string or { id, alt } to attach alt text (X applies it to photos/GIFs). Attach your uploaded graphics to any tweet in the thread."),
+    media_urls: z.array(mediaUrlEntry).max(4).optional().describe("Per-tweet media as external URLs (max 4 combined with media_ids). Each entry is a plain URL string or { url, alt } to attach alt text (X applies it to photos/GIFs)."),
+});
+const BLUESKY_THREAD_PART = z.object({
+    text: z.string().describe("Post text (≤ 300 characters, counted as graphemes — one emoji counts as 1)."),
+    media_ids: z.array(mediaIdEntry).max(4).optional().describe("Per-post media as Library IDs from upload_media. A part is one video OR up to 4 images. Each entry is a plain ID string or { id, alt } to attach alt text (set as the image's embed alt on Bluesky)."),
+    media_urls: z.array(mediaUrlEntry).max(4).optional().describe("Per-post media as external URLs. A part is one video OR up to 4 images. Each entry is a plain URL string or { url, alt } to attach alt text (set as the image's embed alt on Bluesky)."),
+});
+const MASTODON_THREAD_PART = z.object({
+    text: z.string().describe("Status text (≤ 500 characters by default; some instances allow more)."),
+    media_ids: z.array(mediaIdEntry).max(4).optional().describe("Per-status media as Library IDs from upload_media (max 4). Each entry is a plain ID string or { id, alt } to attach alt text (set as the media description — the Mastodon community strongly values alt text on images)."),
+    media_urls: z.array(mediaUrlEntry).max(4).optional().describe("Per-status media as external URLs (max 4). Each entry is a plain URL string or { url, alt } to attach alt text (set as the media description — the Mastodon community strongly values alt text on images)."),
+});
+const GOOGLE_BUSINESS_OPTIONS = z.object({
+    topic_type: z.enum(["STANDARD", "EVENT", "OFFER"]).optional().describe("Local post type. Defaults to STANDARD. ALERT is reserved by Google and not exposed."),
+    cta: z.object({
+        actionType: z.enum(["LEARN_MORE", "BOOK", "ORDER", "SHOP", "SIGN_UP", "CALL"]).describe("Button rendered under the caption. Phone numbers belong on a CALL button and links on a LEARN_MORE / BOOK / SHOP button — they're rejected if placed in the caption text."),
+        url: z.string().optional().describe("Required for every actionType except CALL. Must be http:// or https://. CALL uses the location's phone number from the business profile."),
+    }).optional().describe("Optional call-to-action button."),
+    event: z.object({
+        title: z.string().max(58).describe("Event title (max 58 chars)."),
+        schedule: z.object({
+            startDate: z.object({ year: z.number(), month: z.number(), day: z.number() }),
+            startTime: z.object({ hours: z.number(), minutes: z.number() }).optional(),
+            endDate: z.object({ year: z.number(), month: z.number(), day: z.number() }).optional(),
+            endTime: z.object({ hours: z.number(), minutes: z.number() }).optional(),
+        }).optional().describe("Google's split date+time shape. startDate required; end (if present) must be ≥ start."),
+    }).optional().describe("Required when topic_type is EVENT."),
+    offer: z.object({
+        couponCode: z.string().max(58).optional(),
+        redeemOnlineUrl: z.string().optional().describe("Must be https://. http URLs are rejected."),
+        termsConditions: z.string().max(4000).optional(),
+    }).optional().describe("Required when topic_type is OFFER. Must include at least one of couponCode or redeemOnlineUrl."),
+}).optional().describe("Google Business Profile options. Use to publish EVENT or OFFER posts, attach a CTA button, or both. Shape mirrors Google's LocalPost resource (see https://developers.google.com/my-business/reference/rest/v4/accounts.locations.localPosts#LocalPost).\n\nGoogle Business caption rules (enforced at scheduling — text that violates these will return a `validation_error` 400 before the post is saved):\n  • Phone numbers in the caption are rejected — use a CALL button instead.\n  • Inline URLs / bare domains / emails are rejected — use LEARN_MORE / BOOK / SHOP / SIGN_UP / ORDER buttons instead.\n  • Caption max 1500 characters.\n  • Media is optional (text-only posts are allowed). If attached: exactly one JPEG/PNG/WebP image (no video, no carousels).\n  • The workspace must have a Google Business location selected (Settings → Organisation → Workspaces → Google Business) before scheduling — otherwise returns a 400.");
 // Render full content for get_post — preserves per-platform overrides so Claude
 // can see custom captions (e.g. a shorter X version) instead of only `default`.
 function renderContent(content) {
@@ -152,7 +237,7 @@ export function registerPostTools(server, getClient) {
                 content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
             };
         }
-        const posts = Array.isArray(result.data) ? result.data : result.data?.posts || [];
+        const posts = Array.isArray(result.data) ? result.data : [];
         if (!posts.length) {
             return {
                 content: [{ type: "text", text: `No posts found${params.status ? ` with status "${params.status}"` : ""}.` }],
@@ -164,12 +249,13 @@ export function registerPostTools(server, getClient) {
         md += `|---|---------|----------|--------|------|----|\n`;
         for (let i = 0; i < posts.length; i++) {
             const p = posts[i];
-            const isObj = typeof p.content === "object" && p.content !== null;
-            const rawContent = isObj
-                ? (p.content.default || Object.values(p.content).find((v) => typeof v === "string" && v) || "")
-                : (p.content || "");
-            const hasOverrides = isObj && Object.keys(p.content).filter((k) => k !== "default" && typeof p.content[k] === "string" && p.content[k]).length > 0;
-            const threadParts = Array.isArray(p.x?.thread_parts) ? p.x.thread_parts : [];
+            const contentObj = typeof p.content === "object" && p.content !== null ? p.content : null;
+            const rawContent = contentObj
+                ? (contentObj.default || Object.values(contentObj).find((v) => typeof v === "string" && v) || "")
+                : (typeof p.content === "string" ? p.content : "");
+            const hasOverrides = !!contentObj && Object.keys(contentObj).filter((k) => k !== "default" && typeof contentObj[k] === "string" && contentObj[k]).length > 0;
+            const xParts = p.x?.thread_parts;
+            const threadParts = Array.isArray(xParts) ? xParts : [];
             const isThread = threadParts.length >= 2;
             let content;
             if (isThread && !rawContent) {
@@ -188,7 +274,7 @@ export function registerPostTools(server, getClient) {
             content: [{ type: "text", text: md }],
         };
     });
-    server.tool("get_post", "Get details of a specific post by ID — content, channels, media (with URLs + any per-media alt text), first comment, Instagram collaborators/user tags/location/Trial Reel state/Reel cover (thumbnail_type + thumb_offset in ms), dates and live URLs, enough to fully verify a scheduled post without opening the dashboard. When a post has per-platform caption overrides (e.g. a shorter X version alongside the default), every variant is rendered as its own labeled block under `### Content` so you can see exactly what each platform will publish. X threads are rendered under `### X Thread` with each tweet labeled in publish order — read this to see the full chained tweet text, since thread-only posts have no caption in `content`. After publishing, includes `published_urls` — a map of platform → live URL for each platform that successfully posted (e.g. facebook, instagram, linkedin, x). Useful for polling: when a post's status is `published`, read `published_urls` to surface the live links.", {
+    server.tool("get_post", "Get details of a specific post by ID — content, channels, media (with URLs + any per-media alt text), first comment, Instagram collaborators/user tags/location/Trial Reel state/Reel cover (thumbnail_type + thumb_offset in ms), dates and live URLs, enough to fully verify a scheduled post without opening the dashboard. When a post has per-platform caption overrides (e.g. a shorter X version alongside the default), every variant is rendered as its own labeled block under `### Content` so you can see exactly what each platform will publish. X threads are rendered under `### X Thread` with each tweet labeled in publish order — read this to see the full chained tweet text, since thread-only posts have no caption in `content`. A LinkedIn poll is rendered under `### LinkedIn Poll` with the question, options, and duration. After publishing, includes `published_urls` — a map of platform → live URL for each platform that successfully posted (e.g. facebook, instagram, linkedin, x). Useful for polling: when a post's status is `published`, read `published_urls` to surface the live links.", {
         id: z.string().describe("The post ID"),
     }, async ({ id }) => {
         const result = await getClient().getPost(id);
@@ -216,7 +302,7 @@ export function registerPostTools(server, getClient) {
             md += `| **Scheduled** | ${formatDateTime(schedAt)} |\n`;
         if (p.published_at)
             md += `| **Published** | ${formatDateTime(p.published_at)} |\n`;
-        md += `| **Created** | ${formatDateTime(p.created_at)} |\n`;
+        md += `| **Created** | ${formatDateTime(p.created_at ?? null)} |\n`;
         if (appUrl)
             md += `| **Open in OmniSocials** | ${appUrl} |\n`;
         // Retry linkage: a "published" post with `retries` set and empty
@@ -260,7 +346,7 @@ export function registerPostTools(server, getClient) {
                     md += `**${group === "default" ? "Default (all platforms)" : capitalize(group.replace(/_/g, " "))}**\n`;
                 }
                 items.forEach((m, i) => {
-                    const alt = typeof m?.alt === "string" && m.alt ? ` — alt: "${m.alt}"` : "";
+                    const alt = typeof m !== "string" && typeof m?.alt === "string" && m.alt ? ` — alt: "${m.alt}"` : "";
                     md += `${i + 1}. ${mediaUrlOf(m) || "*(no url)*"}${alt}\n`;
                 });
                 md += `\n`;
@@ -268,9 +354,8 @@ export function registerPostTools(server, getClient) {
             md = md.trimEnd();
         }
         // X thread: when present, the canonical tweet text lives here, not in `content`.
-        const threadParts = Array.isArray(p.x?.thread_parts)
-            ? p.x.thread_parts
-            : [];
+        const rawXParts = p.x?.thread_parts;
+        const threadParts = Array.isArray(rawXParts) ? rawXParts : [];
         if (threadParts.length >= 2) {
             md += `\n\n### X Thread (${threadParts.length} parts)\n\n`;
             for (let i = 0; i < threadParts.length; i++) {
@@ -287,9 +372,8 @@ export function registerPostTools(server, getClient) {
             }
         }
         // Bluesky thread: when present, the canonical post text lives here, not in `content`.
-        const bskyThreadParts = Array.isArray(p.bluesky?.thread_parts)
-            ? p.bluesky.thread_parts
-            : [];
+        const rawBskyParts = p.bluesky?.thread_parts;
+        const bskyThreadParts = Array.isArray(rawBskyParts) ? rawBskyParts : [];
         if (bskyThreadParts.length >= 2) {
             md += `\n\n### Bluesky Thread (${bskyThreadParts.length} parts)\n\n`;
             for (let i = 0; i < bskyThreadParts.length; i++) {
@@ -306,9 +390,8 @@ export function registerPostTools(server, getClient) {
             }
         }
         // Mastodon thread: when present, the canonical status text lives here, not in `content`.
-        const mastoThreadParts = Array.isArray(p.mastodon?.thread_parts)
-            ? p.mastodon.thread_parts
-            : [];
+        const rawMastoParts = p.mastodon?.thread_parts;
+        const mastoThreadParts = Array.isArray(rawMastoParts) ? rawMastoParts : [];
         if (mastoThreadParts.length >= 2) {
             md += `\n\n### Mastodon Thread (${mastoThreadParts.length} parts)\n\n`;
             for (let i = 0; i < mastoThreadParts.length; i++) {
@@ -324,6 +407,17 @@ export function registerPostTools(server, getClient) {
                 md += `\n`;
             }
         }
+        // LinkedIn poll: mutually exclusive with media/link-share, so surface
+        // it prominently rather than leaving callers to infer it's a poll.
+        if (p.linkedin_poll?.question) {
+            const poll = p.linkedin_poll;
+            md += `\n\n### LinkedIn Poll\n\n`;
+            md += `**${poll.question}**\n\n`;
+            for (const option of poll.options || []) {
+                md += `- ${option}\n`;
+            }
+            md += `\n_Duration: ${poll.duration}_\n`;
+        }
         const publishedUrls = (p.published_urls && typeof p.published_urls === "object" && !Array.isArray(p.published_urls))
             ? p.published_urls
             : {};
@@ -437,6 +531,7 @@ IMPORTANT — Before calling this tool, make sure you have all required informat
    - YouTube: Title, privacy status, tags?
    - TikTok: Privacy level?
    - **X threads vs long-form**: A chained "thread" (the user explicitly asks for one) → pass \`x.thread_parts\` as an array of 2–25 \`{ text }\` objects (each ≤ 280 chars); the \`content\` field is then ignored for X. A single **long-form** post on a Premium / Premium+ account → just put the full text (up to 25,000 chars) in \`content\` — no threading needed (check \`platform_details.subscription_type\` via list_accounts). On free / Basic, X caps a single post at 280 chars, so either split into a thread or shorten. Never cram "1/", "2/" prefixes into \`content\` — that posts one tweet, not a thread.
+   - **X posts containing a link cost credits**: X's API bills posts whose text contains a URL at a premium, and OmniSocials passes that through as prepaid credits at X's exact rate (20 credits ≈ $0.20 per URL-containing tweet; threads are charged per part that contains a link). The create response includes a \`warnings\` entry (\`x_url_post_credits\`) with the cost and current balance — relay it to the user. Credits are only deducted after the post successfully publishes; a failed publish is never charged. If the balance can't cover it at publish time, only the X target fails (message says to top up at https://app.omnisocials.com/credits) and the post can be retried after topping up. Posts without links stay free — never remove a user's link to dodge the fee without asking them. Scheduling is also gated up front: every scheduled X link post reserves its cost, and a create/schedule that would push the reserved total past the balance is refused with a 402 \`x_credits_insufficient\` error (details carry credits_required / credits_balance / credits_reserved) — tell the user to top up or remove the link, don't silently retry.
 
 Do NOT call this tool without media when creating stories, reels, Instagram posts, TikTok posts, or Pinterest posts — it will fail.
 
@@ -459,22 +554,11 @@ Do NOT call this tool without media when creating stories, reels, Instagram post
         link_thumbnail_url: z.string().optional().describe("Optional thumbnail image URL for the preview card. Reserved for future use — currently not yet applied to LinkedIn (would require uploading to LinkedIn's image API first)."),
         location_id: z.string().optional().describe("Instagram only. Facebook Place ID of a single physical venue (with a street address) to tag the post's location. Applied to single-image and carousel Instagram feed posts. To get a valid ID, call the `search_locations` tool with the place name and let the user pick. Ignored by other platforms."),
         collaborators: z.array(z.string()).max(3).optional().describe("Instagram only. Up to 3 public Instagram usernames to invite as co-authors (the 'Collab' feature). Works on image, carousel, and reel posts — NOT Stories. Invited users get an invite in the Instagram app; once they accept, the post also appears on their profile and feed. A leading '@' is stripped; usernames are case-insensitive. Private or non-existent usernames are rejected by Instagram at publish time with a clear error. Ignored by other platforms."),
-        user_tags: z.array(z.object({
-            username: z.string().describe("Public Instagram username to tag. Leading '@' is stripped."),
-            x: z.number().min(0).max(1).describe("Horizontal position 0.0–1.0 from the photo's left edge."),
-            y: z.number().min(0).max(1).describe("Vertical position 0.0–1.0 from the photo's top edge."),
-            image_index: z.number().int().min(0).optional().describe("0-based carousel slide this tag belongs to. Omit (or 0) for a single image."),
-        })).optional().describe("Instagram only. Tag public accounts at x/y positions on a PHOTO (not video/reels/stories). For a single image omit image_index; for a carousel, set image_index to the slide each tag belongs to. Private/non-existent usernames are rejected at publish time. Ignored by other platforms."),
+        user_tags: z.array(USER_TAG_ENTRY).optional().describe("Instagram only. Tag public accounts at x/y positions on a PHOTO (not video/reels/stories). For a single image omit image_index; for a carousel, set image_index to the slide each tag belongs to. Private/non-existent usernames are rejected at publish time. Ignored by other platforms."),
         hashtag_set: z.string().optional().describe("Name of a saved hashtag set (from list_hashtag_sets, matched case-insensitively) to apply. The set's tags are merged in ONCE at create time — tags already in a caption are skipped, and Instagram's 30-hashtag cap returns a clear hashtag_limit_exceeded error. When the user says 'add my usual hashtags', check list_hashtag_sets first."),
         hashtag_placement: z.enum(["caption_append", "first_comment"]).optional().describe("Where the set's tags land. caption_append (default): appended to each target caption after a blank line. first_comment: posted as the auto first comment on Instagram/Facebook/LinkedIn/LinkedIn Page/YouTube (appended after any explicit first_comment); platforms without a comment API fall back to caption_append. Stories always use captions."),
         hashtag_platforms: z.array(z.string()).optional().describe("Optional subset of the post's channels to apply the hashtag set to (e.g. [\"instagram\", \"tiktok\"]). Defaults to all selected channels."),
-        pinterest: z.object({
-            board_id: z.string().optional().describe("Pinterest board ID. Required for Pinterest. Use get_account to list boards."),
-            title: z.string().optional().describe("Pin title (max 100 characters). For carousel pins (2–5 images) this title applies to the whole pin, not individual slides."),
-            link: z.string().optional().describe("Destination URL the pin clicks through to"),
-            video_cover: z.string().optional().describe("Cover image URL for video pins (JPEG/PNG). Falls back to a video keyframe if omitted."),
-            alt_text: z.string().optional().describe("Accessibility alt text for the pin image (max 500 characters)"),
-        }).optional().describe("Pinterest-specific options. Attach 2–5 images via media_urls.pinterest (or default) to publish a single carousel pin instead of separate pins. More than 5 images is rejected with a 400 validation_error at create/schedule time — carousels hard-cap at 5. Carousel slides MUST share the same aspect ratio (1% tolerance) — the API returns 400 validation_error with `mismatched_slides: [n, ...]` if you pass mixed-ratio images and try to schedule or publish. Drafts are exempt so you can iterate."),
+        pinterest: PINTEREST_OPTIONS,
         youtube: z.object({
             title: z.string().optional().describe("Short title shown on YouTube. Falls back to \"YouTube Short\" when omitted."),
             tags: z.array(z.string()).optional(),
@@ -496,66 +580,26 @@ Do NOT call this tool without media when creating stories, reels, Instagram post
             first_comment: z.string().max(2200).optional().describe("Text auto-posted as the first comment on the post/reel right after it publishes. Common for keeping hashtags out of the caption. Not posted for Stories."),
             is_trial_reel: z.boolean().optional().describe("Publish the reel as an Instagram Trial Reel — shown to non-followers first to test performance before (optionally) graduating to everyone. ONLY set this when the user explicitly asks for a Trial Reel; never enable it by default. NOT available on every account: Instagram requires roughly 1,000+ followers and enables the feature per account (the user sees a 'Trial' toggle when creating a reel in the Instagram app). Ineligible accounts fail at publish time with a clear per-platform error. Reels only."),
             trial_graduation_strategy: z.enum(["MANUAL", "SS_PERFORMANCE"]).optional().describe("How a Trial Reel graduates to all followers. MANUAL (default): the user decides in the Instagram app. SS_PERFORMANCE: Instagram shares it with followers automatically if it performs well. Only used with is_trial_reel."),
+            is_ai_generated: z.boolean().optional().describe("Self-disclosure that this post's media is AI-generated — adds Instagram's 'AI info' label. Applies to single images, videos, Posts, carousels (whole post, not individual slides), and Reels. Cannot be changed after publish. Not available for Stories."),
         }).optional().describe("Instagram options"),
         facebook: FACEBOOK_OPTIONS,
         linkedin: LINKEDIN_OPTIONS,
         linkedin_page: LINKEDIN_PAGE_OPTIONS,
-        tiktok: z.object({
-            privacy_level: z.enum(["PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "FOLLOWER_OF_CREATOR", "SELF_ONLY"]).optional(),
-            disable_comment: z.boolean().optional(),
-            disable_duet: z.boolean().optional().describe("Reels only. Disable Duet on the video."),
-            disable_stitch: z.boolean().optional().describe("Reels only. Disable Stitch on the video."),
-            video_cover_timestamp_ms: z.number().optional().describe("Reels only. Timestamp (ms) of the video frame to use as the cover."),
-            is_aigc: z.boolean().optional().describe("Mark as AI-generated content."),
-            brand_content_toggle: z.boolean().optional().describe("Paid partnership disclosure (promotes a third-party brand)."),
-            brand_organic_toggle: z.boolean().optional().describe("Your own brand disclosure (promotes your own business)."),
-            auto_add_music: z.boolean().optional().describe("Photo carousels only. When true, TikTok auto-selects a soundtrack. Defaults to false to avoid unsuitable tracks."),
-        }).optional().describe("TikTok options"),
+        linkedin_poll: LINKEDIN_POLL_OPTIONS,
+        tiktok: TIKTOK_OPTIONS,
         x: z.object({
             reply_settings: z.enum(["", "following", "mentionedUsers"]).optional(),
             paid_partnership: z.boolean().optional().describe("Mark as paid partnership disclosure"),
             made_with_ai: z.boolean().optional().describe("Mark as AI-generated content"),
-            thread_parts: z.array(z.object({
-                text: z.string().describe("Tweet text (≤ 280 chars). X counts every link as 23 characters (its t.co length), so a short link still uses 23 toward the limit."),
-                media_ids: z.array(mediaIdEntry).max(4).optional().describe("Per-tweet media as Library IDs from upload_media (max 4 combined with media_urls). Each entry is a plain ID string or { id, alt } to attach alt text (X applies it to photos/GIFs). Attach your uploaded graphics to any tweet in the thread."),
-                media_urls: z.array(mediaUrlEntry).max(4).optional().describe("Per-tweet media as external URLs (max 4 combined with media_ids). Each entry is a plain URL string or { url, alt } to attach alt text (X applies it to photos/GIFs)."),
-            })).min(2).max(25).optional().describe("Publish as a chained X thread instead of a single tweet. Provide 2–25 parts; each is posted in order via in_reply_to_tweet_id. Attach media to any part (first tweet or reply) via media_ids (from upload_media) or media_urls — max 4 per part. For a single tweet, omit thread_parts and use content."),
+            thread_parts: z.array(X_THREAD_PART).min(2).max(25).optional().describe("Publish as a chained X thread instead of a single tweet. Provide 2–25 parts; each is posted in order via in_reply_to_tweet_id. Attach media to any part (first tweet or reply) via media_ids (from upload_media) or media_urls — max 4 per part. For a single tweet, omit thread_parts and use content."),
         }).optional().describe("X (Twitter) options"),
         bluesky: z.object({
-            thread_parts: z.array(z.object({
-                text: z.string().describe("Post text (≤ 300 characters, counted as graphemes — one emoji counts as 1)."),
-                media_ids: z.array(mediaIdEntry).max(4).optional().describe("Per-post media as Library IDs from upload_media. A part is one video OR up to 4 images. Each entry is a plain ID string or { id, alt } to attach alt text (set as the image's embed alt on Bluesky)."),
-                media_urls: z.array(mediaUrlEntry).max(4).optional().describe("Per-post media as external URLs. A part is one video OR up to 4 images. Each entry is a plain URL string or { url, alt } to attach alt text (set as the image's embed alt on Bluesky)."),
-            })).min(2).max(25).optional().describe("Publish as a chained Bluesky thread instead of a single post. Provide 2–25 parts; each is posted in order via AT Protocol reply refs (root + parent). Attach media to any part via media_ids (from upload_media) or media_urls — a part is one video OR up to 4 images. Links, mentions and hashtags are made clickable automatically. For a single post, omit thread_parts and use content."),
+            thread_parts: z.array(BLUESKY_THREAD_PART).min(2).max(25).optional().describe("Publish as a chained Bluesky thread instead of a single post. Provide 2–25 parts; each is posted in order via AT Protocol reply refs (root + parent). Attach media to any part via media_ids (from upload_media) or media_urls — a part is one video OR up to 4 images. Links, mentions and hashtags are made clickable automatically. For a single post, omit thread_parts and use content."),
         }).optional().describe("Bluesky options"),
         mastodon: z.object({
-            thread_parts: z.array(z.object({
-                text: z.string().describe("Status text (≤ 500 characters by default; some instances allow more)."),
-                media_ids: z.array(mediaIdEntry).max(4).optional().describe("Per-status media as Library IDs from upload_media (max 4). Each entry is a plain ID string or { id, alt } to attach alt text (set as the media description — the Mastodon community strongly values alt text on images)."),
-                media_urls: z.array(mediaUrlEntry).max(4).optional().describe("Per-status media as external URLs (max 4). Each entry is a plain URL string or { url, alt } to attach alt text (set as the media description — the Mastodon community strongly values alt text on images)."),
-            })).min(2).max(25).optional().describe("Publish as a chained Mastodon thread instead of a single status. Provide 2–25 parts; each is posted in order as a native reply to the previous status (in_reply_to_id). Attach media to any part via media_ids (from upload_media) or media_urls — max 4 per part. For a single status, omit thread_parts and use content."),
+            thread_parts: z.array(MASTODON_THREAD_PART).min(2).max(25).optional().describe("Publish as a chained Mastodon thread instead of a single status. Provide 2–25 parts; each is posted in order as a native reply to the previous status (in_reply_to_id). Attach media to any part via media_ids (from upload_media) or media_urls — max 4 per part. For a single status, omit thread_parts and use content."),
         }).optional().describe("Mastodon options"),
-        google_business: z.object({
-            topic_type: z.enum(["STANDARD", "EVENT", "OFFER"]).optional().describe("Local post type. Defaults to STANDARD. ALERT is reserved by Google and not exposed."),
-            cta: z.object({
-                actionType: z.enum(["LEARN_MORE", "BOOK", "ORDER", "SHOP", "SIGN_UP", "CALL"]).describe("Button rendered under the caption. Phone numbers belong on a CALL button and links on a LEARN_MORE / BOOK / SHOP button — they're rejected if placed in the caption text."),
-                url: z.string().optional().describe("Required for every actionType except CALL. Must be http:// or https://. CALL uses the location's phone number from the business profile."),
-            }).optional().describe("Optional call-to-action button."),
-            event: z.object({
-                title: z.string().max(58).describe("Event title (max 58 chars)."),
-                schedule: z.object({
-                    startDate: z.object({ year: z.number(), month: z.number(), day: z.number() }),
-                    startTime: z.object({ hours: z.number(), minutes: z.number() }).optional(),
-                    endDate: z.object({ year: z.number(), month: z.number(), day: z.number() }).optional(),
-                    endTime: z.object({ hours: z.number(), minutes: z.number() }).optional(),
-                }).optional().describe("Google's split date+time shape. startDate required; end (if present) must be ≥ start."),
-            }).optional().describe("Required when topic_type is EVENT."),
-            offer: z.object({
-                couponCode: z.string().max(58).optional(),
-                redeemOnlineUrl: z.string().optional().describe("Must be https://. http URLs are rejected."),
-                termsConditions: z.string().max(4000).optional(),
-            }).optional().describe("Required when topic_type is OFFER. Must include at least one of couponCode or redeemOnlineUrl."),
-        }).optional().describe("Google Business Profile options. Use to publish EVENT or OFFER posts, attach a CTA button, or both. Shape mirrors Google's LocalPost resource (see https://developers.google.com/my-business/reference/rest/v4/accounts.locations.localPosts#LocalPost).\n\nGoogle Business caption rules (enforced at scheduling — text that violates these will return a `validation_error` 400 before the post is saved):\n  • Phone numbers in the caption are rejected — use a CALL button instead.\n  • Inline URLs / bare domains / emails are rejected — use LEARN_MORE / BOOK / SHOP / SIGN_UP / ORDER buttons instead.\n  • Caption max 1500 characters.\n  • Media is optional (text-only posts are allowed). If attached: exactly one JPEG/PNG/WebP image (no video, no carousels).\n  • The workspace must have a Google Business location selected (Settings → Organisation → Workspaces → Google Business) before scheduling — otherwise returns a 400."),
+        google_business: GOOGLE_BUSINESS_OPTIONS,
     }, async (params) => {
         const result = await getClient().createPost({ ...params, source: "mcp" });
         if (result.error) {
@@ -564,6 +608,13 @@ Do NOT call this tool without media when creating stories, reels, Instagram post
             };
         }
         const p = result.data;
+        if (!p) {
+            // Impossible path (no error + no data) — never surface it as a tool
+            // error: agents retry on errors and that produces orphan duplicates.
+            return {
+                content: [{ type: "text", text: "Draft created, but the API returned no details. Verify with list_posts." }],
+            };
+        }
         // The post is already created by the time this runs. If response
         // formatting throws, we must NOT surface it as a tool error — agents
         // retry on errors and that produces orphan duplicate posts.
@@ -583,6 +634,12 @@ Do NOT call this tool without media when creating stories, reels, Instagram post
             if (appUrl)
                 md += `| **Open in OmniSocials** | ${appUrl} |\n`;
             md += `\n**Content:** ${truncate(p.content, 100)}\n\n`;
+            if (Array.isArray(result.warnings) && result.warnings.length > 0) {
+                for (const w of result.warnings) {
+                    md += `⚠️ ${w.message}\n`;
+                }
+                md += `\n`;
+            }
             md += `_Share the link above with the user so they can review or edit the draft. Publish later with \`publish_post\` once they confirm._`;
             return { content: [{ type: "text", text: md }] };
         }
@@ -621,6 +678,7 @@ IMPORTANT — Before calling this tool, make sure you have all required informat
    - **Video duration/size caps** (ffprobe at submit — over either returns 400 validation_error with the exact cap + the file's value): X **140s/512MB** (no video+image mix in one tweet), Bluesky 180s, Threads 5min, Instagram 15min, TikTok 10min, YouTube Short 3min, LinkedIn 10min, Facebook Reel 90s.
 4. **Pinterest board (auto-default to first board)**: If Pinterest is in \`channels\` and \`pinterest.board_id\` is NOT provided, do NOT block on asking — and do NOT skip Pinterest. Call \`get_account\` on the Pinterest account, take the FIRST board from the returned boards list, and pass its \`id\` as \`pinterest.board_id\`. In your reply, mention which board you used (e.g. "Published to your 'Marketing' board on Pinterest — let me know if you'd prefer a different one.") so the user can redirect. If the user named a specific board in the request, match it (case-insensitive) against the list and use that one instead.
 5. **X threads vs long-form**: A chained "thread" → pass \`x.thread_parts\` as a 2–25 entry array of \`{ text }\` objects (each ≤ 280 chars). A single long-form post on a Premium / Premium+ account → put the full text (up to 25,000 chars) in \`content\`; no threading needed. On free / Basic, X caps a single post at 280 chars. Do NOT split into "1/", "2/" inside \`content\` — that produces a single tweet, not a thread.
+6. **X posts containing a link cost credits**: X bills API posts whose text contains a URL at a premium; OmniSocials passes that through as prepaid credits at X's exact rate (20 credits ≈ $0.20 per URL-containing tweet, threads charged per link-containing part). Because this tool publishes IMMEDIATELY, the debit happens right away — if the company's balance can't cover it, the X target fails with a top-up message while other platforms still publish. Relay any \`x_url_post_credits\` warning and X publish failure to the user; never strip their link to avoid the fee without asking. If the balance (minus credits reserved by scheduled X link posts) can't cover this post, the request is refused up front with a 402 \`x_credits_insufficient\` error instead of failing at publish.
 
 Do NOT call without required media — it will fail.`, {
         content: z.union([z.string(), z.record(z.string(), z.string())]).describe("Post caption. String for same text on all channels, or object with platform keys for per-channel captions: { \"default\": \"fallback\", \"linkedin\": \"long version\", \"threads\": \"short version\" }. The \"default\" key is used for any selected channel without its own key."),
@@ -636,29 +694,23 @@ Do NOT call without required media — it will fail.`, {
         type: z.enum(["post", "story", "reel"]).optional().describe("Content type: 'post' (default), 'story', 'reel'"),
         location_id: z.string().optional().describe("Instagram only. Facebook Place ID of a single physical venue to tag the post's location. Applied to single-image and carousel Instagram feed posts. Use the `search_locations` tool to find a valid ID. Ignored by other platforms."),
         collaborators: z.array(z.string()).max(3).optional().describe("Instagram only. Up to 3 public Instagram usernames to invite as co-authors (the 'Collab' feature). Works on image, carousel, and reel posts — NOT Stories. A leading '@' is stripped; usernames are case-insensitive. Private or non-existent usernames are rejected by Instagram at publish time. Ignored by other platforms."),
-        user_tags: z.array(z.object({
-            username: z.string().describe("Public Instagram username to tag. Leading '@' is stripped."),
-            x: z.number().min(0).max(1).describe("Horizontal position 0.0–1.0 from the photo's left edge."),
-            y: z.number().min(0).max(1).describe("Vertical position 0.0–1.0 from the photo's top edge."),
-            image_index: z.number().int().min(0).optional().describe("0-based carousel slide this tag belongs to. Omit (or 0) for a single image."),
-        })).optional().describe("Instagram only. Tag public accounts at x/y positions on a PHOTO (not video/reels/stories). For a single image omit image_index; for a carousel, set image_index to the slide each tag belongs to. Private/non-existent usernames are rejected at publish time. Ignored by other platforms."),
+        user_tags: z.array(USER_TAG_ENTRY).optional().describe("Instagram only. Tag public accounts at x/y positions on a PHOTO (not video/reels/stories). For a single image omit image_index; for a carousel, set image_index to the slide each tag belongs to. Private/non-existent usernames are rejected at publish time. Ignored by other platforms."),
         hashtag_set: z.string().optional().describe("Name of a saved hashtag set (from list_hashtag_sets, matched case-insensitively) to apply. Tags are merged in once at create time; tags already in a caption are skipped."),
         hashtag_placement: z.enum(["caption_append", "first_comment"]).optional().describe("caption_append (default) appends tags to the captions; first_comment posts them as the auto first comment on comment-capable platforms (others fall back to caption)."),
         hashtag_platforms: z.array(z.string()).optional().describe("Optional subset of the post's channels to apply the hashtag set to. Defaults to all selected channels."),
-        pinterest: z.object({
-            board_id: z.string().optional().describe("Pinterest board ID. Required for Pinterest. Use get_account to list boards."),
-            title: z.string().optional().describe("Pin title (max 100 characters). For carousel pins (2–5 images) this title applies to the whole pin, not individual slides."),
-            link: z.string().optional().describe("Destination URL the pin clicks through to"),
-            video_cover: z.string().optional().describe("Cover image URL for video pins (JPEG/PNG). Falls back to a video keyframe if omitted."),
-            alt_text: z.string().optional().describe("Accessibility alt text for the pin image (max 500 characters)"),
-        }).optional().describe("Pinterest-specific options. Attach 2–5 images via media_urls.pinterest (or default) to publish a single carousel pin instead of separate pins. More than 5 images is rejected with a 400 validation_error at create/schedule time — carousels hard-cap at 5. Carousel slides MUST share the same aspect ratio (1% tolerance) — the API returns 400 validation_error with `mismatched_slides: [n, ...]` if you pass mixed-ratio images and try to schedule or publish. Drafts are exempt so you can iterate."),
+        pinterest: PINTEREST_OPTIONS,
         youtube: z.object({
             title: z.string().optional().describe("Short title shown on YouTube."),
             tags: z.array(z.string()).optional(),
             privacy_status: z.enum(["public", "private", "unlisted"]).optional(),
+            category_id: z.string().optional(),
+            made_for_kids: z.boolean().optional(),
+            notify_subscribers: z.boolean().optional(),
+            contains_synthetic_media: z.boolean().optional(),
             first_comment: z.string().max(10000).optional().describe("Text auto-posted as the first comment on the video right after it publishes. The video must have comments enabled."),
         }).optional().describe("YouTube Shorts options. Only applies when type is 'reel' and youtube is among the selected channels."),
         instagram: z.object({
+            share_to_feed: z.boolean().optional(),
             thumbnail_type: z.enum(["from-video", "from-library"]).optional().describe("How the Reel cover is chosen: 'from-video' picks a frame at thumb_offset; 'from-library' uses the image at cover_url. get_post reads the chosen cover back."),
             thumb_offset: z.number().optional().describe("Reel cover frame timestamp in MILLISECONDS from the start of the video (e.g. 3000 = 0:03). Used with thumbnail_type 'from-video'."),
             cover_url: z.string().optional().describe("Custom Reel cover image URL. Used with thumbnail_type 'from-library'."),
@@ -668,66 +720,26 @@ Do NOT call without required media — it will fail.`, {
             first_comment: z.string().max(2200).optional().describe("Text auto-posted as the first comment on the post/reel right after it publishes. Common for keeping hashtags out of the caption. Not posted for Stories."),
             is_trial_reel: z.boolean().optional().describe("Publish the reel as an Instagram Trial Reel — shown to non-followers first to test performance before (optionally) graduating to everyone. ONLY set this when the user explicitly asks for a Trial Reel; never enable it by default. NOT available on every account: Instagram requires roughly 1,000+ followers and enables the feature per account (the user sees a 'Trial' toggle when creating a reel in the Instagram app). Ineligible accounts fail at publish time with a clear per-platform error. Reels only."),
             trial_graduation_strategy: z.enum(["MANUAL", "SS_PERFORMANCE"]).optional().describe("How a Trial Reel graduates to all followers. MANUAL (default): the user decides in the Instagram app. SS_PERFORMANCE: Instagram shares it with followers automatically if it performs well. Only used with is_trial_reel."),
+            is_ai_generated: z.boolean().optional().describe("Self-disclosure that this post's media is AI-generated — adds Instagram's 'AI info' label. Applies to single images, videos, Posts, carousels (whole post, not individual slides), and Reels. Cannot be changed after publish. Not available for Stories."),
         }).optional().describe("Instagram options"),
         facebook: FACEBOOK_OPTIONS,
         linkedin: LINKEDIN_OPTIONS,
         linkedin_page: LINKEDIN_PAGE_OPTIONS,
-        tiktok: z.object({
-            privacy_level: z.enum(["PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "FOLLOWER_OF_CREATOR", "SELF_ONLY"]).optional(),
-            disable_comment: z.boolean().optional(),
-            disable_duet: z.boolean().optional().describe("Reels only. Disable Duet on the video."),
-            disable_stitch: z.boolean().optional().describe("Reels only. Disable Stitch on the video."),
-            video_cover_timestamp_ms: z.number().optional().describe("Reels only. Timestamp (ms) of the video frame to use as the cover."),
-            is_aigc: z.boolean().optional().describe("Mark as AI-generated content."),
-            brand_content_toggle: z.boolean().optional().describe("Paid partnership disclosure (promotes a third-party brand)."),
-            brand_organic_toggle: z.boolean().optional().describe("Your own brand disclosure (promotes your own business)."),
-            auto_add_music: z.boolean().optional().describe("Photo carousels only. When true, TikTok auto-selects a soundtrack. Defaults to false to avoid unsuitable tracks."),
-        }).optional().describe("TikTok options"),
+        linkedin_poll: LINKEDIN_POLL_OPTIONS,
+        tiktok: TIKTOK_OPTIONS,
         x: z.object({
             reply_settings: z.enum(["", "following", "mentionedUsers"]).optional(),
             paid_partnership: z.boolean().optional().describe("Mark as paid partnership disclosure"),
             made_with_ai: z.boolean().optional().describe("Mark as AI-generated content"),
-            thread_parts: z.array(z.object({
-                text: z.string().describe("Tweet text (≤ 280 chars). X counts every link as 23 characters (its t.co length), so a short link still uses 23 toward the limit."),
-                media_ids: z.array(mediaIdEntry).max(4).optional().describe("Per-tweet media as Library IDs from upload_media (max 4 combined with media_urls). Each entry is a plain ID string or { id, alt } to attach alt text (X applies it to photos/GIFs). Attach your uploaded graphics to any tweet in the thread."),
-                media_urls: z.array(mediaUrlEntry).max(4).optional().describe("Per-tweet media as external URLs (max 4 combined with media_ids). Each entry is a plain URL string or { url, alt } to attach alt text (X applies it to photos/GIFs)."),
-            })).min(2).max(25).optional().describe("Publish as a chained X thread (2–25 parts). Each is posted in order via in_reply_to_tweet_id. Attach media to any part via media_ids (from upload_media) or media_urls — max 4 per part."),
+            thread_parts: z.array(X_THREAD_PART).min(2).max(25).optional().describe("Publish as a chained X thread (2–25 parts). Each is posted in order via in_reply_to_tweet_id. Attach media to any part via media_ids (from upload_media) or media_urls — max 4 per part."),
         }).optional().describe("X (Twitter) options"),
         bluesky: z.object({
-            thread_parts: z.array(z.object({
-                text: z.string().describe("Post text (≤ 300 characters, counted as graphemes — one emoji counts as 1)."),
-                media_ids: z.array(mediaIdEntry).max(4).optional().describe("Per-post media as Library IDs from upload_media. A part is one video OR up to 4 images. Each entry is a plain ID string or { id, alt } to attach alt text (set as the image's embed alt on Bluesky)."),
-                media_urls: z.array(mediaUrlEntry).max(4).optional().describe("Per-post media as external URLs. A part is one video OR up to 4 images. Each entry is a plain URL string or { url, alt } to attach alt text (set as the image's embed alt on Bluesky)."),
-            })).min(2).max(25).optional().describe("Publish as a chained Bluesky thread (2–25 parts). Each is posted in order via AT Protocol reply refs (root + parent). Attach media to any part via media_ids or media_urls — one video OR up to 4 images per part. Links, mentions and hashtags are made clickable automatically."),
+            thread_parts: z.array(BLUESKY_THREAD_PART).min(2).max(25).optional().describe("Publish as a chained Bluesky thread (2–25 parts). Each is posted in order via AT Protocol reply refs (root + parent). Attach media to any part via media_ids or media_urls — one video OR up to 4 images per part. Links, mentions and hashtags are made clickable automatically."),
         }).optional().describe("Bluesky options"),
         mastodon: z.object({
-            thread_parts: z.array(z.object({
-                text: z.string().describe("Status text (≤ 500 characters by default; some instances allow more)."),
-                media_ids: z.array(mediaIdEntry).max(4).optional().describe("Per-status media as Library IDs from upload_media (max 4). Each entry is a plain ID string or { id, alt } to attach alt text (set as the media description — the Mastodon community strongly values alt text on images)."),
-                media_urls: z.array(mediaUrlEntry).max(4).optional().describe("Per-status media as external URLs (max 4). Each entry is a plain URL string or { url, alt } to attach alt text (set as the media description — the Mastodon community strongly values alt text on images)."),
-            })).min(2).max(25).optional().describe("Publish as a chained Mastodon thread (2–25 parts). Each is posted in order as a native reply (in_reply_to_id). Attach media to any part via media_ids or media_urls — max 4 per part."),
+            thread_parts: z.array(MASTODON_THREAD_PART).min(2).max(25).optional().describe("Publish as a chained Mastodon thread (2–25 parts). Each is posted in order as a native reply (in_reply_to_id). Attach media to any part via media_ids or media_urls — max 4 per part."),
         }).optional().describe("Mastodon options"),
-        google_business: z.object({
-            topic_type: z.enum(["STANDARD", "EVENT", "OFFER"]).optional(),
-            cta: z.object({
-                actionType: z.enum(["LEARN_MORE", "BOOK", "ORDER", "SHOP", "SIGN_UP", "CALL"]),
-                url: z.string().optional(),
-            }).optional(),
-            event: z.object({
-                title: z.string().max(58),
-                schedule: z.object({
-                    startDate: z.object({ year: z.number(), month: z.number(), day: z.number() }),
-                    startTime: z.object({ hours: z.number(), minutes: z.number() }).optional(),
-                    endDate: z.object({ year: z.number(), month: z.number(), day: z.number() }).optional(),
-                    endTime: z.object({ hours: z.number(), minutes: z.number() }).optional(),
-                }).optional(),
-            }).optional(),
-            offer: z.object({
-                couponCode: z.string().max(58).optional(),
-                redeemOnlineUrl: z.string().optional(),
-                termsConditions: z.string().max(4000).optional(),
-            }).optional(),
-        }).optional().describe("Google Business Profile options (STANDARD/EVENT/OFFER + optional CTA). Same shape as create_post.\n\nGoogle Business caption rules (enforced at scheduling — text that violates these returns a `validation_error` 400):\n  • No phone numbers in the caption — use a CALL button instead.\n  • No inline URLs / bare domains / emails — use LEARN_MORE / BOOK / SHOP / SIGN_UP / ORDER buttons.\n  • Caption max 1500 characters.\n  • Media is optional. If attached: exactly one JPEG/PNG/WebP image (no video, no carousels).\n  • Workspace must have a Google Business location selected before scheduling — otherwise returns a 400."),
+        google_business: GOOGLE_BUSINESS_OPTIONS,
     }, async (params) => {
         const result = await getClient().createAndPublishPost({ ...params, source: "mcp" });
         if (result.error) {
@@ -736,6 +748,13 @@ Do NOT call without required media — it will fail.`, {
             };
         }
         const p = result.data;
+        if (!p) {
+            // Impossible path (no error + no data) — the post is already queued;
+            // never let it look like an API error (agents would retry = repost).
+            return {
+                content: [{ type: "text", text: "Post created and queued for publishing, but the API returned no details. Verify with list_posts." }],
+            };
+        }
         const appUrl = postAppUrl(p);
         try {
             const channels = selectedChannels(p);
@@ -749,6 +768,12 @@ Do NOT call without required media — it will fail.`, {
             if (appUrl)
                 md += `| **Open in OmniSocials** | ${appUrl} |\n`;
             md += `\n**Content:** ${truncate(p.content, 100)}`;
+            if (Array.isArray(result.warnings) && result.warnings.length > 0) {
+                md += `\n`;
+                for (const w of result.warnings) {
+                    md += `\n⚠️ ${w.message}`;
+                }
+            }
             return { content: [{ type: "text", text: md }] };
         }
         catch {
@@ -778,12 +803,7 @@ Do NOT call without required media — it will fail.`, {
         ]).superRefine(pinterestImageCap).optional().describe("External URLs — flat array or per-platform object. Each entry is a plain URL string or { url, alt } to attach alt text — delivered to Mastodon, Bluesky, X, Pinterest, Instagram (images) and LinkedIn (images). Max 10 total (Pinterest: max 5 images per carousel pin), each file ≤ 100 MB (larger, up to 1 GB: upload_media with method 'url' → pass the media id in `media`). 'default' key is fallback for platforms without their own key. Empty array opts out."),
         location_id: z.string().optional().describe("Instagram only. Facebook Place/Page ID to tag the post's location with. Send an empty string to clear an existing location tag. Ignored by other platforms."),
         collaborators: z.array(z.string()).max(3).optional().describe("Instagram only. Up to 3 public Instagram usernames to invite as co-authors. Replaces the existing collaborator list. Send an empty array to clear collaborators. Works on image, carousel, and reel posts — NOT Stories. Ignored by other platforms."),
-        user_tags: z.array(z.object({
-            username: z.string().describe("Public Instagram username to tag. Leading '@' is stripped."),
-            x: z.number().min(0).max(1).describe("Horizontal position 0.0–1.0 from the photo's left edge."),
-            y: z.number().min(0).max(1).describe("Vertical position 0.0–1.0 from the photo's top edge."),
-            image_index: z.number().int().min(0).optional().describe("0-based carousel slide this tag belongs to. Omit (or 0) for a single image."),
-        })).optional().describe("Instagram only. Tag public accounts at x/y positions on a PHOTO (not video/reels/stories). Replaces the existing tag list. Send an empty array to clear. For carousels set image_index per tag. Ignored by other platforms."),
+        user_tags: z.array(USER_TAG_ENTRY).optional().describe("Instagram only. Tag public accounts at x/y positions on a PHOTO (not video/reels/stories). Replaces the existing tag list. Send an empty array to clear. For carousels set image_index per tag. Ignored by other platforms."),
         youtube: z.object({
             title: z.string().optional().describe("Short title shown on YouTube. To change the Short's title on an existing draft, set this — do NOT use `content` (which is the description)."),
             tags: z.array(z.string()).optional(),
@@ -794,13 +814,7 @@ Do NOT call without required media — it will fail.`, {
             contains_synthetic_media: z.boolean().optional(),
             first_comment: z.string().max(10000).optional().describe("Text auto-posted as the first comment on the video right after it publishes. The video must have comments enabled. Pass an empty string to clear a previously set first comment."),
         }).optional().describe("YouTube Shorts options. Only applies when type is 'reel' and youtube is among the selected channels."),
-        pinterest: z.object({
-            board_id: z.string().optional().describe("Pinterest board ID. Required for Pinterest. Use get_account to list boards."),
-            title: z.string().optional().describe("Pin title (max 100 characters). For carousel pins (2–5 images) this title applies to the whole pin, not individual slides."),
-            link: z.string().optional().describe("Destination URL the pin clicks through to"),
-            video_cover: z.string().optional().describe("Cover image URL for video pins (JPEG/PNG). Falls back to a video keyframe if omitted."),
-            alt_text: z.string().optional().describe("Accessibility alt text for the pin image (max 500 characters)"),
-        }).optional().describe("Pinterest-specific options. Attach 2–5 images via media_urls.pinterest (or default) to publish a single carousel pin instead of separate pins. More than 5 images is rejected with a 400 validation_error at create/schedule time — carousels hard-cap at 5. Carousel slides MUST share the same aspect ratio (1% tolerance) — the API returns 400 validation_error with `mismatched_slides: [n, ...]` if you pass mixed-ratio images and try to schedule or publish. Drafts are exempt so you can iterate."),
+        pinterest: PINTEREST_OPTIONS,
         instagram: z.object({
             share_to_feed: z.boolean().optional(),
             thumbnail_type: z.enum(["from-video", "from-library"]).optional().describe("How the Reel cover is chosen: 'from-video' picks a frame at thumb_offset; 'from-library' uses the image at cover_url. get_post reads the chosen cover back."),
@@ -812,66 +826,26 @@ Do NOT call without required media — it will fail.`, {
             first_comment: z.string().max(2200).optional().describe("Text auto-posted as the first comment on the post/reel right after it publishes. Pass an empty string to clear a previously set first comment."),
             is_trial_reel: z.boolean().optional().describe("Publish the reel as an Instagram Trial Reel — shown to non-followers first to test performance before (optionally) graduating to everyone. ONLY set this when the user explicitly asks for a Trial Reel; never enable it by default. NOT available on every account: Instagram requires roughly 1,000+ followers and enables the feature per account. Ineligible accounts fail at publish time with a clear per-platform error. Reels only. Pass false to turn a Trial Reel back into a regular reel."),
             trial_graduation_strategy: z.enum(["MANUAL", "SS_PERFORMANCE"]).optional().describe("How a Trial Reel graduates to all followers. MANUAL (default): the user decides in the Instagram app. SS_PERFORMANCE: Instagram shares it with followers automatically if it performs well. Only used with is_trial_reel."),
+            is_ai_generated: z.boolean().optional().describe("Self-disclosure that this post's media is AI-generated — adds Instagram's 'AI info' label. Applies to single images, videos, Posts, carousels (whole post, not individual slides), and Reels. Cannot be changed after publish. Not available for Stories."),
         }).optional().describe("Instagram options. MERGED into the post's stored options: omitted keys keep their current value (updating one option cannot clear a Trial Reel flag or reel music configured elsewhere)."),
         facebook: FACEBOOK_OPTIONS,
         linkedin: LINKEDIN_OPTIONS,
         linkedin_page: LINKEDIN_PAGE_OPTIONS,
-        tiktok: z.object({
-            privacy_level: z.enum(["PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "FOLLOWER_OF_CREATOR", "SELF_ONLY"]).optional(),
-            disable_comment: z.boolean().optional(),
-            disable_duet: z.boolean().optional().describe("Reels only. Disable Duet on the video."),
-            disable_stitch: z.boolean().optional().describe("Reels only. Disable Stitch on the video."),
-            video_cover_timestamp_ms: z.number().optional().describe("Reels only. Timestamp (ms) of the video frame to use as the cover."),
-            is_aigc: z.boolean().optional().describe("Mark as AI-generated content."),
-            brand_content_toggle: z.boolean().optional().describe("Paid partnership disclosure (promotes a third-party brand)."),
-            brand_organic_toggle: z.boolean().optional().describe("Your own brand disclosure (promotes your own business)."),
-            auto_add_music: z.boolean().optional().describe("Photo carousels only. When true, TikTok auto-selects a soundtrack. Defaults to false to avoid unsuitable tracks."),
-        }).optional().describe("TikTok options"),
+        linkedin_poll: LINKEDIN_POLL_OPTIONS,
+        tiktok: TIKTOK_OPTIONS,
         x: z.object({
             reply_settings: z.enum(["", "following", "mentionedUsers"]).optional(),
             paid_partnership: z.boolean().optional(),
             made_with_ai: z.boolean().optional(),
-            thread_parts: z.array(z.object({
-                text: z.string().describe("Tweet text (≤ 280 chars). X counts every link as 23 characters (its t.co length), so a short link still uses 23 toward the limit."),
-                media_ids: z.array(mediaIdEntry).max(4).optional().describe("Per-tweet media as Library IDs from upload_media (max 4 combined with media_urls). Each entry is a plain ID string or { id, alt } to attach alt text (X applies it to photos/GIFs). Attach your uploaded graphics to any tweet in the thread."),
-                media_urls: z.array(mediaUrlEntry).max(4).optional().describe("Per-tweet media as external URLs (max 4 combined with media_ids). Each entry is a plain URL string or { url, alt } to attach alt text (X applies it to photos/GIFs)."),
-            })).min(2).max(25).nullable().optional().describe("Replace the X thread shape on this post. Pass an array (2–25 parts) to update/create the thread (attach media to any part via media_ids or media_urls, max 4 per part), or `null` to revert to single-tweet mode."),
+            thread_parts: z.array(X_THREAD_PART).min(2).max(25).nullable().optional().describe("Replace the X thread shape on this post. Pass an array (2–25 parts) to update/create the thread (attach media to any part via media_ids or media_urls, max 4 per part), or `null` to revert to single-tweet mode."),
         }).optional().describe("X (Twitter) options"),
         bluesky: z.object({
-            thread_parts: z.array(z.object({
-                text: z.string().describe("Post text (≤ 300 characters, counted as graphemes — one emoji counts as 1)."),
-                media_ids: z.array(mediaIdEntry).max(4).optional().describe("Per-post media as Library IDs from upload_media. A part is one video OR up to 4 images. Each entry is a plain ID string or { id, alt } to attach alt text (set as the image's embed alt on Bluesky)."),
-                media_urls: z.array(mediaUrlEntry).max(4).optional().describe("Per-post media as external URLs. A part is one video OR up to 4 images. Each entry is a plain URL string or { url, alt } to attach alt text (set as the image's embed alt on Bluesky)."),
-            })).min(2).max(25).nullable().optional().describe("Replace the Bluesky thread shape on this post. Pass an array (2–25 parts) to update/create the thread (attach media to any part via media_ids or media_urls; one video OR up to 4 images per part), or `null` to revert to single-post mode."),
+            thread_parts: z.array(BLUESKY_THREAD_PART).min(2).max(25).nullable().optional().describe("Replace the Bluesky thread shape on this post. Pass an array (2–25 parts) to update/create the thread (attach media to any part via media_ids or media_urls; one video OR up to 4 images per part), or `null` to revert to single-post mode."),
         }).optional().describe("Bluesky options"),
         mastodon: z.object({
-            thread_parts: z.array(z.object({
-                text: z.string().describe("Status text (≤ 500 characters by default; some instances allow more)."),
-                media_ids: z.array(mediaIdEntry).max(4).optional().describe("Per-status media as Library IDs from upload_media (max 4). Each entry is a plain ID string or { id, alt } to attach alt text (set as the media description — the Mastodon community strongly values alt text on images)."),
-                media_urls: z.array(mediaUrlEntry).max(4).optional().describe("Per-status media as external URLs (max 4). Each entry is a plain URL string or { url, alt } to attach alt text (set as the media description — the Mastodon community strongly values alt text on images)."),
-            })).min(2).max(25).nullable().optional().describe("Replace the Mastodon thread shape on this post. Pass an array (2–25 parts) to update/create the thread (attach media to any part via media_ids or media_urls; max 4 per part), or `null` to revert to single-status mode."),
+            thread_parts: z.array(MASTODON_THREAD_PART).min(2).max(25).nullable().optional().describe("Replace the Mastodon thread shape on this post. Pass an array (2–25 parts) to update/create the thread (attach media to any part via media_ids or media_urls; max 4 per part), or `null` to revert to single-status mode."),
         }).optional().describe("Mastodon options"),
-        google_business: z.object({
-            topic_type: z.enum(["STANDARD", "EVENT", "OFFER"]).optional(),
-            cta: z.object({
-                actionType: z.enum(["LEARN_MORE", "BOOK", "ORDER", "SHOP", "SIGN_UP", "CALL"]),
-                url: z.string().optional(),
-            }).optional(),
-            event: z.object({
-                title: z.string().max(58),
-                schedule: z.object({
-                    startDate: z.object({ year: z.number(), month: z.number(), day: z.number() }),
-                    startTime: z.object({ hours: z.number(), minutes: z.number() }).optional(),
-                    endDate: z.object({ year: z.number(), month: z.number(), day: z.number() }).optional(),
-                    endTime: z.object({ hours: z.number(), minutes: z.number() }).optional(),
-                }).optional(),
-            }).optional(),
-            offer: z.object({
-                couponCode: z.string().max(58).optional(),
-                redeemOnlineUrl: z.string().optional(),
-                termsConditions: z.string().max(4000).optional(),
-            }).optional(),
-        }).optional().describe("Google Business Profile options (STANDARD/EVENT/OFFER + optional CTA). Same shape as create_post.\n\nGoogle Business caption rules (enforced at scheduling — text that violates these returns a `validation_error` 400):\n  • No phone numbers in the caption — use a CALL button instead.\n  • No inline URLs / bare domains / emails — use LEARN_MORE / BOOK / SHOP / SIGN_UP / ORDER buttons.\n  • Caption max 1500 characters.\n  • Media is optional. If attached: exactly one JPEG/PNG/WebP image (no video, no carousels).\n  • Workspace must have a Google Business location selected before scheduling — otherwise returns a 400."),
+        google_business: GOOGLE_BUSINESS_OPTIONS,
     }, async ({ id, ...data }) => {
         const result = await getClient().updatePost(id, data);
         if (result.error) {
@@ -880,6 +854,11 @@ Do NOT call without required media — it will fail.`, {
             };
         }
         const p = result.data;
+        if (!p) {
+            return {
+                content: [{ type: "text", text: "Post updated, but the API returned no details. Verify with get_post." }],
+            };
+        }
         const schedAt = p.schedule_at ?? p.scheduled_at;
         const appUrl = postAppUrl(p);
         let md = `## Post Updated\n\n`;
@@ -915,6 +894,11 @@ IMPORTANT: Before publishing, verify the post has all required media. If publish
             };
         }
         const p = result.data;
+        if (!p) {
+            return {
+                content: [{ type: "text", text: "Post queued for publishing. Check its status with get_post." }],
+            };
+        }
         let md = `## Post Queued for Publishing\n\n`;
         md += `| Field | Value |\n`;
         md += `|-------|-------|\n`;
@@ -936,6 +920,11 @@ The retry runs asynchronously (usually within a few minutes). Poll \`get_post\`
             };
         }
         const p = result.data;
+        if (!p) {
+            return {
+                content: [{ type: "text", text: "Retry queued. Check the outcome with get_post in a minute or two." }],
+            };
+        }
         let md = `## Retry Queued\n\n`;
         md += `| Field | Value |\n`;
         md += `|-------|-------|\n`;
@@ -964,7 +953,10 @@ Notes:
         const result = await getClient().searchLocations(query);
         const places = result?.data || [];
         if (!places.length) {
-            const why = result?.error ||
+            // The degraded path returns `error` as a plain string; the object form
+            // only appears on transport failures — render its message.
+            const err = result?.error;
+            const why = (typeof err === "string" ? err : err?.message) ||
                 `No taggable locations found for "${query}". Try a more specific venue name, or pass a known Facebook Place ID directly as location_id.`;
             return { content: [{ type: "text", text: why }] };
         }
@@ -992,7 +984,10 @@ Notes: only tracks Meta licenses for third-party publishing appear, so the selec
         const result = await getClient().searchInstagramAudio(query, type);
         const tracks = result?.data || [];
         if (!tracks.length) {
-            const why = result?.error ||
+            // Same nonstandard envelope as search_locations — string `error` on
+            // the degraded path, { code, message } only on transport failures.
+            const err = result?.error;
+            const why = (typeof err === "string" ? err : err?.message) ||
                 (query
                     ? `No tracks found for "${query}". Try another title or artist — only music licensed for third-party publishing appears here.`
                     : "No trending audio available right now.");
@@ -1011,11 +1006,11 @@ Notes: only tracks Meta licenses for third-party publishing appear, so the selec
         });
         return { content: [{ type: "text", text: md }] };
     });
-    server.tool("get_recent_platform_posts", "Fetch the user's most recent posts straight from their connected platform APIs (Instagram, TikTok, X, YouTube, Facebook, LinkedIn, and more), INCLUDING content published outside OmniSocials. Use this when list_posts is empty — e.g. a brand-new workspace that has not published through OmniSocials yet — so you can still analyze the user's real content. Each post includes normalized `engagement` plus every raw metric the platform reported (Instagram: reach/views/saves/shares from per-post insights). Metrics only appear where the platform exposes them for historical posts (X, TikTok, Bluesky, Mastodon, Instagram, Facebook, YouTube); Threads, Pinterest, and Google Business return captions only. Records also carry `duration_seconds` — the video length in whole seconds — where the platform's listing API reports it (currently TikTok and YouTube); null for images and platforms that don't expose it. LinkedIn personal profiles can't be listed live (LinkedIn grants apps no such permission), so their results are posts published through OmniSocials with their latest collected stats. Fetched live, so expect a few seconds of latency. Output is a human-readable summary table PLUS a 'Structured data' JSON block carrying, for every post, the platform's own post id (the stable dedupe key), a permalink, the FULL untruncated caption, and exact-integer metrics — use that block when ingesting or storing native posts rather than the rounded/truncated table. Requires the analytics:read scope.", {
+    server.tool("get_recent_platform_posts", "Fetch the user's most recent posts straight from their connected platform APIs (Instagram, TikTok, X, YouTube, Facebook, LinkedIn, and more), INCLUDING content published outside OmniSocials. Use this when list_posts is empty — e.g. a brand-new workspace that has not published through OmniSocials yet — so you can still analyze the user's real content. Each post includes normalized `engagement` plus every raw metric the platform reported (Instagram: reach/views/saves/shares from per-post insights). Metrics only appear where the platform exposes them for historical posts (X, TikTok, Bluesky, Mastodon, Instagram, Facebook, YouTube); Threads, Pinterest, and Google Business return captions only. Records also carry `duration_seconds` — the video length in whole seconds — where the platform's listing API reports it (currently TikTok and YouTube); null for images and platforms that don't expose it. LinkedIn personal profiles can't be listed live (LinkedIn grants apps no such permission), so their results are posts published through OmniSocials with their latest collected stats. Fetched live for most platforms, so expect a few seconds of latency; X results may come from a snapshot up to 24h old (X bills per returned post) — the snapshot refreshes right after the user publishes to X through OmniSocials. Output is a human-readable summary table PLUS a 'Structured data' JSON block carrying, for every post, the platform's own post id (the stable dedupe key), a permalink, the FULL untruncated caption, and exact-integer metrics — use that block when ingesting or storing native posts rather than the rounded/truncated table. Requires the analytics:read scope.", {
         limit: z
             .string()
             .optional()
-            .describe("Max posts per connected platform (1-50, default 25)."),
+            .describe("Max posts per connected platform (1-50, default 25; X defaults to 10 unless set explicitly — its API bills per returned post)."),
         platforms: z
             .string()
             .optional()