posterly-mcp-server 0.32.0 → 0.33.0

package/dist/lib/api-client.d.ts

@@ -5,6 +5,15 @@ export interface Account {
     account_type?: string;
     profile_picture_url?: string;
     workspace_id?: string | null;
+    connection_mode?: 'meta' | 'instagram_direct' | null;
+    instagram_tagging?: {
+        media_user_tags?: {
+            supported?: boolean;
+        };
+        collaborators?: {
+            supported?: boolean;
+        };
+    };
 }
 export interface Brand {
     id: string;

package/dist/tools/create-connect-session.d.ts

@@ -9,12 +9,12 @@ export declare const createConnectSessionTool: {
         auto_start: z.ZodOptional<z.ZodBoolean>;
         debug: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
-        platform: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "slack" | "mastodon" | "devto" | "hashnode" | "wordpress" | "lemmy" | "reddit" | "medium" | "skool" | "whop" | "gmb" | "google-business" | "google_business_profile" | "meta" | "linkedin_page" | "facebook_instagram" | "facebook_pages" | "instagram_direct" | "linkedin-company" | "linkedin-page" | "linkedin_company" | "linkedin_personal" | "meta_business" | "x_twitter";
+        platform: "meta" | "instagram_direct" | "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "slack" | "mastodon" | "devto" | "hashnode" | "wordpress" | "lemmy" | "reddit" | "medium" | "skool" | "whop" | "gmb" | "google-business" | "google_business_profile" | "linkedin_page" | "facebook_instagram" | "facebook_pages" | "linkedin-company" | "linkedin-page" | "linkedin_company" | "linkedin_personal" | "meta_business" | "x_twitter";
         workspace_id?: string | undefined;
         auto_start?: boolean | undefined;
         debug?: boolean | undefined;
     }, {
-        platform: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "slack" | "mastodon" | "devto" | "hashnode" | "wordpress" | "lemmy" | "reddit" | "medium" | "skool" | "whop" | "gmb" | "google-business" | "google_business_profile" | "meta" | "linkedin_page" | "facebook_instagram" | "facebook_pages" | "instagram_direct" | "linkedin-company" | "linkedin-page" | "linkedin_company" | "linkedin_personal" | "meta_business" | "x_twitter";
+        platform: "meta" | "instagram_direct" | "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "slack" | "mastodon" | "devto" | "hashnode" | "wordpress" | "lemmy" | "reddit" | "medium" | "skool" | "whop" | "gmb" | "google-business" | "google_business_profile" | "linkedin_page" | "facebook_instagram" | "facebook_pages" | "linkedin-company" | "linkedin-page" | "linkedin_company" | "linkedin_personal" | "meta_business" | "x_twitter";
         workspace_id?: string | undefined;
         auto_start?: boolean | undefined;
         debug?: boolean | undefined;

package/dist/tools/create-post.js

@@ -8,10 +8,13 @@ export const instagramSettingsSchema = z.object({
     graduation_strategy: z.enum(['MANUAL', 'SS_PERFORMANCE']).optional(),
     collaborators: z
         .array(z.union([z.string(), z.object({ label: z.string().optional(), username: z.string().optional(), handle: z.string().optional() })]))
-        .optional(),
+        .max(3)
+        .optional()
+        .describe('Native Instagram co-author invitations. Meta-linked accounts only; feed images, Reels, and carousels; not Stories.'),
     user_tags: z
         .array(z.union([z.string(), z.object({ username: z.string().optional(), label: z.string().optional(), handle: z.string().optional() })]))
-        .optional(),
+        .optional()
+        .describe('Native clickable media tags, not caption @mentions. Requires an eligible Meta-linked Instagram connection with publishing permission; feed images, Reels/video, and Stories. Tags apply to each carousel item and the first Story in a Story Series.'),
     first_comment: z.string().optional(),
     media_alt_texts: z.record(z.string(), z.string()).optional(),
     reel_cover_url: z.string().optional(),
@@ -94,7 +97,7 @@ export const createPostPayloadInputSchema = z.object({
         .enum(SUPPORTED_PLATFORM_INPUTS)
         .optional()
         .describe(`Platform name (required with username). Supported: ${SUPPORTED_PLATFORM_IDS.join(', ')}. Aliases such as x, gmb, and instagram-standalone are accepted.`),
-    caption: z.string().optional().describe('The post caption/text content. Ignored when `thread_posts` is provided.'),
+    caption: z.string().optional().describe('The post caption/text content. On Instagram, @username creates a caption mention only; it is not a native media tag or collaborator invitation. Ignored when `thread_posts` is provided.'),
     scheduled_at: z
         .string()
         .optional()
@@ -114,7 +117,7 @@ export const createPostPayloadInputSchema = z.object({
         .describe('For X or Threads only: array of 2+ strings, one per post in the thread. The first entry leads, the rest reply in order. When set, the platform must be twitter or threads.'),
     instagram_settings: instagramSettingsSchema
         .optional()
-        .describe('Instagram-specific settings: post_type (post/feed/story/reel/carousel), collaborators, user_tags, first_comment, media_alt_texts, is_trial_reel, graduation_strategy (defaults to MANUAL), reel_cover_url, reel_thumb_offset.'),
+        .describe('Instagram-specific settings. If “tag” is ambiguous, distinguish caption @mentions (put @username in caption), native media tags (user_tags), and co-author invitations (collaborators). Native media tags and collaborators require an eligible Meta-linked connection. Call get_platform_schema(account_id) first.'),
     platform_settings: platformSettingsSchema
         .optional()
         .describe('Platform-specific settings for the selected account. Use this for non-Instagram settings and prefer it over raw metadata.'),
@@ -183,7 +186,7 @@ export const createPostTool = {
         'Provide either account_id OR username+platform to identify the account. If scheduled_at is omitted, the post publishes immediately. If workspace_id is omitted, the server resolves one from the social account, falling back to the caller\'s default (personal) workspace - pass workspace_id explicitly if the user has more than one workspace.\n\n' +
         'MEDIA URLS: Posterly storage URLs are used as-is. Third-party HTTP(S) media URLs are copied into Posterly storage before the post is saved, so API-created posts do not later fail on expired signed URLs. Short-lived signed URLs must still be live when this tool runs. You can also call `upload_media_from_url` first if you want to upload once and reuse the returned Posterly URL across posts.\n\n' +
         'THREADS: Pass `thread_posts` (an array of 2+ strings) to schedule a multi-post thread on X (Twitter) or Threads (Meta). The first entry is the lead post; the rest are published as replies in the same chain. X entries are capped at 280 characters each (4000 for verified, 25000 for organization accounts); Threads entries are capped at 500 characters each. When `thread_posts` is set, `caption` is ignored.\n\n' +
-        'PLATFORM SETTINGS: Pass `platform_settings` for composer-equivalent controls: Facebook story/reel/backgrounds, YouTube title/privacy/thumbnail/playlist, LinkedIn document titles/mentions/polls (poll.question, poll.options 2-4, poll.duration ONE_DAY|THREE_DAYS|SEVEN_DAYS|FOURTEEN_DAYS; text-only)/video thumbnails, TikTok direct-post privacy/toggles/commercial disclosure, Pinterest post_type (image/video/carousel), board (from pinterest.boards helper), title, link, and cover_image_url (video Pins), GBP event/offer/CTA, X reply settings/polls, Threads reply controls/text attachments, Bluesky languages/alt text, and Instagram feed/story/reel/carousel/collaborators/first comments/trial Reels. `instagram_settings` remains as a backwards-compatible alias.\n\n' +
+        'PLATFORM SETTINGS: Pass `platform_settings` for composer-equivalent controls: Facebook story/reel/backgrounds, YouTube title/privacy/thumbnail/playlist, LinkedIn document titles/mentions/polls (poll.question, poll.options 2-4, poll.duration ONE_DAY|THREE_DAYS|SEVEN_DAYS|FOURTEEN_DAYS; text-only)/video thumbnails, TikTok direct-post privacy/toggles/commercial disclosure, Pinterest post_type (image/video/carousel), board (from pinterest.boards helper), title, link, and cover_image_url (video Pins), GBP event/offer/CTA, X reply settings/polls, Threads reply controls/text attachments, Bluesky languages/alt text, and Instagram feed/story/reel/carousel/native media tags/collaborators/first comments/trial Reels. For Instagram, @username in caption is only a caption mention; `user_tags` creates native media tags and `collaborators` sends co-author invitations only when the selected Meta-linked account reports those capabilities. Call `get_platform_schema` with the account ID first. `instagram_settings` remains as a backwards-compatible alias.\n\n' +
         'TIKTOK MEDIA: TikTok supports a single video or a photo slideshow of 1 to 35 images, never multiple videos. Image media auto-detects as a slideshow, so you usually do not set post_type or media_type for photos and every image is posted. Pass `platform_settings.media_type: "PHOTO"` to force a slideshow explicitly.',
     inputSchema: createPostInputSchema,
     async execute(client, input) {

package/dist/tools/get-connect-link.d.ts

@@ -11,12 +11,12 @@ export declare const getConnectLinkTool: {
     }, "strip", z.ZodTypeAny, {
         workspace_id?: string | undefined;
         include_planned?: boolean | undefined;
-        platform?: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "slack" | "mastodon" | "devto" | "hashnode" | "wordpress" | "lemmy" | "reddit" | "medium" | "skool" | "whop" | "gmb" | "google-business" | "google_business_profile" | "meta" | "linkedin_page" | "facebook_instagram" | "facebook_pages" | "instagram_direct" | "linkedin-company" | "linkedin-page" | "linkedin_company" | "linkedin_personal" | "meta_business" | "x_twitter" | undefined;
+        platform?: "meta" | "instagram_direct" | "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "slack" | "mastodon" | "devto" | "hashnode" | "wordpress" | "lemmy" | "reddit" | "medium" | "skool" | "whop" | "gmb" | "google-business" | "google_business_profile" | "linkedin_page" | "facebook_instagram" | "facebook_pages" | "linkedin-company" | "linkedin-page" | "linkedin_company" | "linkedin_personal" | "meta_business" | "x_twitter" | undefined;
         debug?: boolean | undefined;
     }, {
         workspace_id?: string | undefined;
         include_planned?: boolean | undefined;
-        platform?: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "slack" | "mastodon" | "devto" | "hashnode" | "wordpress" | "lemmy" | "reddit" | "medium" | "skool" | "whop" | "gmb" | "google-business" | "google_business_profile" | "meta" | "linkedin_page" | "facebook_instagram" | "facebook_pages" | "instagram_direct" | "linkedin-company" | "linkedin-page" | "linkedin_company" | "linkedin_personal" | "meta_business" | "x_twitter" | undefined;
+        platform?: "meta" | "instagram_direct" | "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "slack" | "mastodon" | "devto" | "hashnode" | "wordpress" | "lemmy" | "reddit" | "medium" | "skool" | "whop" | "gmb" | "google-business" | "google_business_profile" | "linkedin_page" | "facebook_instagram" | "facebook_pages" | "linkedin-company" | "linkedin-page" | "linkedin_company" | "linkedin_personal" | "meta_business" | "x_twitter" | undefined;
         debug?: boolean | undefined;
     }>;
     execute(client: PosterlyClient, input: {

package/dist/tools/get-platform-schema.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { ALL_PLATFORM_INPUTS, SUPPORTED_PLATFORM_IDS } from '../generated/platform-manifest.js';
 export const getPlatformSchemaTool = {
     name: 'get_platform_schema',
-    description: 'Get the platform schema for a specific connected account or platform. Call this before creating posts with platform_settings so you know allowed post types, media limits, helper tools, and field names.',
+    description: 'Get the platform schema for a specific connected account or platform. For Instagram, pass account_id before native tags/collaborators so connection-specific capabilities are returned.',
     inputSchema: z.object({
         account_id: z
             .string()
@@ -24,9 +24,13 @@ export const getPlatformSchemaTool = {
         const accountLine = result.account
             ? `Account: ${result.account.username || result.account.id} (${result.account.platform})\n`
             : '';
+        const instagramTaggingLine = result.account?.instagram_tagging
+            ? `Instagram tagging capabilities: ${JSON.stringify(result.account.instagram_tagging)}`
+            : '';
         return [
             `${schema.label} (${schema.id}) schema`,
             accountLine.trim(),
+            instagramTaggingLine,
             `Status: ${schema.status}`,
             `Post types: ${schema.post_types.join(', ') || 'n/a'}`,
             `Content limit: ${schema.content_limit ?? 'n/a'}`,

package/dist/tools/list-accounts.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { code, mdEmpty, mdTable, mdTitle } from '../lib/format.js';
 export const listAccountsTool = {
     name: 'list_accounts',
-    description: 'List connected social media accounts. Returns platform, username, account ID, and workspace ID for each. Pass workspace_id to filter to a specific workspace; otherwise returns all accounts the caller owns across every workspace.',
+    description: 'List connected social media accounts. Instagram rows identify direct-login versus Meta-linked connections and whether native media tags/collaborators are available. Check this before using Instagram user_tags or collaborators.',
     inputSchema: z.object({
         workspace_id: z
             .string()
@@ -16,14 +16,29 @@ export const listAccountsTool = {
                 ? mdEmpty('connected accounts', 'This workspace does not have any social accounts connected yet.')
                 : mdEmpty('connected accounts', 'Posterly does not see any connected social accounts yet.', 'Connect accounts in the Posterly dashboard, then run this again.');
         }
+        const hasInstagram = accounts.some((account) => account.platform === 'instagram');
         return [
             mdTitle(`Connected accounts (${accounts.length})`),
-            mdTable(['Platform', 'Account', 'Account ID', 'Workspace'], accounts.map((account) => [
+            mdTable(hasInstagram
+                ? ['Platform', 'Account', 'Account ID', 'Workspace', 'Connection', 'Native tags', 'Collaborators']
+                : ['Platform', 'Account', 'Account ID', 'Workspace'], accounts.map((account) => [
                 account.platform,
                 `@${account.username}`,
                 code(account.id),
                 account.workspace_id ? code(account.workspace_id) : 'default',
+                ...(hasInstagram
+                    ? account.platform === 'instagram'
+                        ? [
+                            account.connection_mode === 'meta' ? 'Meta-linked' : account.connection_mode === 'instagram_direct' ? 'Direct login' : 'unknown',
+                            account.instagram_tagging?.media_user_tags?.supported ? 'yes' : 'no',
+                            account.instagram_tagging?.collaborators?.supported ? 'yes' : 'no',
+                        ]
+                        : ['—', '—', '—']
+                    : []),
             ])),
-        ].join('\n\n');
+            hasInstagram
+                ? '_Instagram caption @mentions use @username in caption text. Native media tags and collaborator invitations require an eligible Meta-linked account with the required publishing permissions._'
+                : '',
+        ].filter(Boolean).join('\n\n');
     },
 };

package/dist/tools/start-signup.js

@@ -75,7 +75,7 @@ function formatSignupStart(response, includeRaw) {
         completeUrl ? `Completion URL: ${completeUrl}` : '',
         '',
         'Next steps for the AI agent:',
-        '1. Send the Checkout handoff URL to the user so they can pay securely in their browser. Use the raw Stripe checkout URL only if you preserve the full URL including any fragment.',
+        '1. Send the Checkout handoff URL to the user so they can pay securely in their browser. Use the raw Stripe checkout URL only if you preserve the full URL including any fragment. posterly does not email this link, so do not tell the user to check their inbox at this stage.',
         '2. Call get_signup_session with the signup session ID until the status changes.',
         '3. Tell the user when Posterly sends the password setup email.',
         '4. If status becomes agent_access_required, ask the user to install or paste the Posterly MCP/API setup instructions into this trusted AI chat.',

package/dist/tools/update-post.js

@@ -7,10 +7,13 @@ const instagramSettingsSchema = z.object({
     graduation_strategy: z.enum(['MANUAL', 'SS_PERFORMANCE']).optional(),
     collaborators: z
         .array(z.union([z.string(), z.object({ label: z.string().optional(), username: z.string().optional(), handle: z.string().optional() })]))
-        .optional(),
+        .max(3)
+        .optional()
+        .describe('Native Instagram co-author invitations. Meta-linked accounts only; feed images, Reels, and carousels; not Stories.'),
     user_tags: z
         .array(z.union([z.string(), z.object({ username: z.string().optional(), label: z.string().optional(), handle: z.string().optional() })]))
-        .optional(),
+        .optional()
+        .describe('Native clickable media tags, not caption @mentions. Requires an eligible Meta-linked Instagram connection with publishing permission; feed images, Reels/video, and Stories. Tags apply to each carousel item and the first Story in a Story Series.'),
     first_comment: z.string().optional(),
     media_alt_texts: z.record(z.string(), z.string()).optional(),
     reel_cover_url: z.string().optional(),
@@ -93,7 +96,7 @@ export const updatePostTool = {
         reel_thumb_offset: z.number().nonnegative().optional().describe('Frame offset in milliseconds to use as the reel cover.'),
         instagram_settings: instagramSettingsSchema
             .optional()
-            .describe('Instagram-specific updates: post_type, collaborators, user_tags, first_comment, media_alt_texts, is_trial_reel, graduation_strategy (defaults to MANUAL), reel_cover_url, reel_cover_method, reel_thumb_offset.'),
+            .describe('Instagram-specific updates. Distinguish caption @mentions, native media user_tags, and collaborators. Native media tags and collaborators require an eligible Meta-linked connection. Call get_platform_schema(account_id) first.'),
         platform_settings: platformSettingsSchema
             .optional()
             .describe('Platform-specific settings to merge into the post. Prefer this over raw metadata.'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posterly-mcp-server",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "mcpName": "io.github.awpthorp/posterly",
   "description": "MCP server for posterly: schedule and publish social media posts across 18 platforms from any MCP client (Claude, ChatGPT, Cursor, Windsurf, Cline, and more)",
   "license": "MIT",

package/scripts/test-tool-annotations.mjs

@@ -1,7 +1,14 @@
 import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const annotations = JSON.parse(readFileSync(resolve(root, 'tool-annotations.json'), 'utf8'));
+const expectedToolCount = annotations.knownTools.length;
+
 const transport = new StdioClientTransport({
   command: process.execPath,
   args: ['dist/index.js'],
@@ -12,7 +19,11 @@ try {
   await client.connect(transport);
   const { tools } = await client.listTools();
 
-  assert.equal(tools.length, 76);
+  assert.equal(
+    tools.length,
+    expectedToolCount,
+    `stdio tool count ${tools.length} must match tool-annotations.json knownTools (${expectedToolCount})`,
+  );
   for (const tool of tools) {
     assert(tool.annotations, `${tool.name} is missing annotations`);
     assert(tool.annotations.title, `${tool.name} is missing an annotation title`);

package/src/lib/api-client.ts

@@ -8,6 +8,11 @@ export interface Account {
   account_type?: string;
   profile_picture_url?: string;
   workspace_id?: string | null;
+  connection_mode?: 'meta' | 'instagram_direct' | null;
+  instagram_tagging?: {
+    media_user_tags?: { supported?: boolean };
+    collaborators?: { supported?: boolean };
+  };
 }
 
 export interface Brand {

package/src/tools/create-post.ts

@@ -10,10 +10,13 @@ export const instagramSettingsSchema = z.object({
   graduation_strategy: z.enum(['MANUAL', 'SS_PERFORMANCE']).optional(),
   collaborators: z
     .array(z.union([z.string(), z.object({ label: z.string().optional(), username: z.string().optional(), handle: z.string().optional() })]))
-    .optional(),
+    .max(3)
+    .optional()
+    .describe('Native Instagram co-author invitations. Meta-linked accounts only; feed images, Reels, and carousels; not Stories.'),
   user_tags: z
     .array(z.union([z.string(), z.object({ username: z.string().optional(), label: z.string().optional(), handle: z.string().optional() })]))
-    .optional(),
+    .optional()
+    .describe('Native clickable media tags, not caption @mentions. Requires an eligible Meta-linked Instagram connection with publishing permission; feed images, Reels/video, and Stories. Tags apply to each carousel item and the first Story in a Story Series.'),
   first_comment: z.string().optional(),
   media_alt_texts: z.record(z.string(), z.string()).optional(),
   reel_cover_url: z.string().optional(),
@@ -98,7 +101,7 @@ export const createPostPayloadInputSchema = z.object({
     .enum(SUPPORTED_PLATFORM_INPUTS)
     .optional()
     .describe(`Platform name (required with username). Supported: ${SUPPORTED_PLATFORM_IDS.join(', ')}. Aliases such as x, gmb, and instagram-standalone are accepted.`),
-  caption: z.string().optional().describe('The post caption/text content. Ignored when `thread_posts` is provided.'),
+  caption: z.string().optional().describe('The post caption/text content. On Instagram, @username creates a caption mention only; it is not a native media tag or collaborator invitation. Ignored when `thread_posts` is provided.'),
   scheduled_at: z
     .string()
     .optional()
@@ -118,7 +121,7 @@ export const createPostPayloadInputSchema = z.object({
     .describe('For X or Threads only: array of 2+ strings, one per post in the thread. The first entry leads, the rest reply in order. When set, the platform must be twitter or threads.'),
   instagram_settings: instagramSettingsSchema
     .optional()
-    .describe('Instagram-specific settings: post_type (post/feed/story/reel/carousel), collaborators, user_tags, first_comment, media_alt_texts, is_trial_reel, graduation_strategy (defaults to MANUAL), reel_cover_url, reel_thumb_offset.'),
+      .describe('Instagram-specific settings. If “tag” is ambiguous, distinguish caption @mentions (put @username in caption), native media tags (user_tags), and co-author invitations (collaborators). Native media tags and collaborators require an eligible Meta-linked connection. Call get_platform_schema(account_id) first.'),
   platform_settings: platformSettingsSchema
     .optional()
     .describe('Platform-specific settings for the selected account. Use this for non-Instagram settings and prefer it over raw metadata.'),
@@ -201,7 +204,7 @@ export const createPostTool = {
     'Provide either account_id OR username+platform to identify the account. If scheduled_at is omitted, the post publishes immediately. If workspace_id is omitted, the server resolves one from the social account, falling back to the caller\'s default (personal) workspace - pass workspace_id explicitly if the user has more than one workspace.\n\n' +
     'MEDIA URLS: Posterly storage URLs are used as-is. Third-party HTTP(S) media URLs are copied into Posterly storage before the post is saved, so API-created posts do not later fail on expired signed URLs. Short-lived signed URLs must still be live when this tool runs. You can also call `upload_media_from_url` first if you want to upload once and reuse the returned Posterly URL across posts.\n\n' +
     'THREADS: Pass `thread_posts` (an array of 2+ strings) to schedule a multi-post thread on X (Twitter) or Threads (Meta). The first entry is the lead post; the rest are published as replies in the same chain. X entries are capped at 280 characters each (4000 for verified, 25000 for organization accounts); Threads entries are capped at 500 characters each. When `thread_posts` is set, `caption` is ignored.\n\n' +
-    'PLATFORM SETTINGS: Pass `platform_settings` for composer-equivalent controls: Facebook story/reel/backgrounds, YouTube title/privacy/thumbnail/playlist, LinkedIn document titles/mentions/polls (poll.question, poll.options 2-4, poll.duration ONE_DAY|THREE_DAYS|SEVEN_DAYS|FOURTEEN_DAYS; text-only)/video thumbnails, TikTok direct-post privacy/toggles/commercial disclosure, Pinterest post_type (image/video/carousel), board (from pinterest.boards helper), title, link, and cover_image_url (video Pins), GBP event/offer/CTA, X reply settings/polls, Threads reply controls/text attachments, Bluesky languages/alt text, and Instagram feed/story/reel/carousel/collaborators/first comments/trial Reels. `instagram_settings` remains as a backwards-compatible alias.\n\n' +
+    'PLATFORM SETTINGS: Pass `platform_settings` for composer-equivalent controls: Facebook story/reel/backgrounds, YouTube title/privacy/thumbnail/playlist, LinkedIn document titles/mentions/polls (poll.question, poll.options 2-4, poll.duration ONE_DAY|THREE_DAYS|SEVEN_DAYS|FOURTEEN_DAYS; text-only)/video thumbnails, TikTok direct-post privacy/toggles/commercial disclosure, Pinterest post_type (image/video/carousel), board (from pinterest.boards helper), title, link, and cover_image_url (video Pins), GBP event/offer/CTA, X reply settings/polls, Threads reply controls/text attachments, Bluesky languages/alt text, and Instagram feed/story/reel/carousel/native media tags/collaborators/first comments/trial Reels. For Instagram, @username in caption is only a caption mention; `user_tags` creates native media tags and `collaborators` sends co-author invitations only when the selected Meta-linked account reports those capabilities. Call `get_platform_schema` with the account ID first. `instagram_settings` remains as a backwards-compatible alias.\n\n' +
     'TIKTOK MEDIA: TikTok supports a single video or a photo slideshow of 1 to 35 images, never multiple videos. Image media auto-detects as a slideshow, so you usually do not set post_type or media_type for photos and every image is posted. Pass `platform_settings.media_type: "PHOTO"` to force a slideshow explicitly.',
   inputSchema: createPostInputSchema,
 

package/src/tools/get-platform-schema.ts

@@ -5,7 +5,7 @@ import { ALL_PLATFORM_INPUTS, SUPPORTED_PLATFORM_IDS } from '../generated/platfo
 export const getPlatformSchemaTool = {
   name: 'get_platform_schema',
   description:
-    'Get the platform schema for a specific connected account or platform. Call this before creating posts with platform_settings so you know allowed post types, media limits, helper tools, and field names.',
+    'Get the platform schema for a specific connected account or platform. For Instagram, pass account_id before native tags/collaborators so connection-specific capabilities are returned.',
   inputSchema: z.object({
     account_id: z
       .string()
@@ -31,10 +31,14 @@ export const getPlatformSchemaTool = {
     const accountLine = result.account
       ? `Account: ${(result.account.username as string) || result.account.id} (${result.account.platform})\n`
       : '';
+    const instagramTaggingLine = result.account?.instagram_tagging
+      ? `Instagram tagging capabilities: ${JSON.stringify(result.account.instagram_tagging)}`
+      : '';
 
     return [
       `${schema.label} (${schema.id}) schema`,
       accountLine.trim(),
+      instagramTaggingLine,
       `Status: ${schema.status}`,
       `Post types: ${schema.post_types.join(', ') || 'n/a'}`,
       `Content limit: ${schema.content_limit ?? 'n/a'}`,

package/src/tools/list-accounts.ts

@@ -5,7 +5,7 @@ import { code, mdEmpty, mdTable, mdTitle } from '../lib/format.js';
 export const listAccountsTool = {
   name: 'list_accounts',
   description:
-    'List connected social media accounts. Returns platform, username, account ID, and workspace ID for each. Pass workspace_id to filter to a specific workspace; otherwise returns all accounts the caller owns across every workspace.',
+    'List connected social media accounts. Instagram rows identify direct-login versus Meta-linked connections and whether native media tags/collaborators are available. Check this before using Instagram user_tags or collaborators.',
   inputSchema: z.object({
     workspace_id: z
       .string()
@@ -22,17 +22,33 @@ export const listAccountsTool = {
         : mdEmpty('connected accounts', 'Posterly does not see any connected social accounts yet.', 'Connect accounts in the Posterly dashboard, then run this again.');
     }
 
+    const hasInstagram = accounts.some((account) => account.platform === 'instagram');
+
     return [
       mdTitle(`Connected accounts (${accounts.length})`),
       mdTable(
-        ['Platform', 'Account', 'Account ID', 'Workspace'],
+        hasInstagram
+          ? ['Platform', 'Account', 'Account ID', 'Workspace', 'Connection', 'Native tags', 'Collaborators']
+          : ['Platform', 'Account', 'Account ID', 'Workspace'],
         accounts.map((account) => [
           account.platform,
           `@${account.username}`,
           code(account.id),
           account.workspace_id ? code(account.workspace_id) : 'default',
+          ...(hasInstagram
+            ? account.platform === 'instagram'
+              ? [
+                  account.connection_mode === 'meta' ? 'Meta-linked' : account.connection_mode === 'instagram_direct' ? 'Direct login' : 'unknown',
+                  account.instagram_tagging?.media_user_tags?.supported ? 'yes' : 'no',
+                  account.instagram_tagging?.collaborators?.supported ? 'yes' : 'no',
+                ]
+              : ['—', '—', '—']
+            : []),
         ]),
       ),
-    ].join('\n\n');
+      hasInstagram
+        ? '_Instagram caption @mentions use @username in caption text. Native media tags and collaborator invitations require an eligible Meta-linked account with the required publishing permissions._'
+        : '',
+    ].filter(Boolean).join('\n\n');
   },
 };

package/src/tools/start-signup.ts

@@ -96,7 +96,7 @@ function formatSignupStart(response: PublicSignupResponse, includeRaw: boolean):
     completeUrl ? `Completion URL: ${completeUrl}` : '',
     '',
     'Next steps for the AI agent:',
-    '1. Send the Checkout handoff URL to the user so they can pay securely in their browser. Use the raw Stripe checkout URL only if you preserve the full URL including any fragment.',
+    '1. Send the Checkout handoff URL to the user so they can pay securely in their browser. Use the raw Stripe checkout URL only if you preserve the full URL including any fragment. posterly does not email this link, so do not tell the user to check their inbox at this stage.',
     '2. Call get_signup_session with the signup session ID until the status changes.',
     '3. Tell the user when Posterly sends the password setup email.',
     '4. If status becomes agent_access_required, ask the user to install or paste the Posterly MCP/API setup instructions into this trusted AI chat.',

package/src/tools/update-post.ts

@@ -9,10 +9,13 @@ const instagramSettingsSchema = z.object({
   graduation_strategy: z.enum(['MANUAL', 'SS_PERFORMANCE']).optional(),
   collaborators: z
     .array(z.union([z.string(), z.object({ label: z.string().optional(), username: z.string().optional(), handle: z.string().optional() })]))
-    .optional(),
+    .max(3)
+    .optional()
+    .describe('Native Instagram co-author invitations. Meta-linked accounts only; feed images, Reels, and carousels; not Stories.'),
   user_tags: z
     .array(z.union([z.string(), z.object({ username: z.string().optional(), label: z.string().optional(), handle: z.string().optional() })]))
-    .optional(),
+    .optional()
+    .describe('Native clickable media tags, not caption @mentions. Requires an eligible Meta-linked Instagram connection with publishing permission; feed images, Reels/video, and Stories. Tags apply to each carousel item and the first Story in a Story Series.'),
   first_comment: z.string().optional(),
   media_alt_texts: z.record(z.string(), z.string()).optional(),
   reel_cover_url: z.string().optional(),
@@ -98,7 +101,7 @@ export const updatePostTool = {
     reel_thumb_offset: z.number().nonnegative().optional().describe('Frame offset in milliseconds to use as the reel cover.'),
     instagram_settings: instagramSettingsSchema
       .optional()
-      .describe('Instagram-specific updates: post_type, collaborators, user_tags, first_comment, media_alt_texts, is_trial_reel, graduation_strategy (defaults to MANUAL), reel_cover_url, reel_cover_method, reel_thumb_offset.'),
+      .describe('Instagram-specific updates. Distinguish caption @mentions, native media user_tags, and collaborators. Native media tags and collaborators require an eligible Meta-linked connection. Call get_platform_schema(account_id) first.'),
     platform_settings: platformSettingsSchema
       .optional()
       .describe('Platform-specific settings to merge into the post. Prefer this over raw metadata.'),