posterly-mcp-server 0.43.5 → 0.43.7

package/README.md

@@ -122,7 +122,7 @@ Add the same server definition to your Cursor MCP settings:
 
 ## Available tools
 
-`posterly-mcp-server@0.43.5` exposes 90 tools.
+`posterly-mcp-server@0.43.7` exposes 90 tools.
 
 Public setup tools work before `POSTERLY_API_KEY` exists:
 

package/SUBMISSIONS.md

@@ -34,7 +34,12 @@ person who applies the production migration and files the directory forms.
 
 ## Anthropic Connectors Directory
 
-Submit the remote MCP server at https://clau.de/mcp-directory-submission.
+This is the remote MCP connector listing (Claude.ai / Claude desktop
+connectors). It is distinct from the Claude Code plugin already pending review.
+
+Submit the remote MCP server at
+https://claude.ai/admin-settings/directory/submissions/new or
+https://clau.de/mcp-directory-submission.
 
 Fallback contact: mcp-review@anthropic.com.
 
@@ -49,12 +54,45 @@ Use:
   refresh tokens (1-hour access, 30-day refresh for DCR clients)
 - Platforms: all 18 production platforms
 
+Connectors Connect (the in-product connect form) uses a Client ID Metadata
+Document, not DCR, for this flow:
+
+- `client_id`: `https://claude.ai/oauth/mcp-oauth-client-metadata`
+- `redirect_uri`: `https://claude.ai/api/mcp/auth_callback`
+
+DCR at `POST /api/oauth/register` remains available for other hosts. It is
+not what Claude Connectors uses for Connect.
+
 Do not claim Autopilot ships. Do not claim the connector is already listed.
 
 Optional after deploy: bump and publish `posterly-mcp-server` if you want the
 stdio README changes on npm. Hosted `/api/mcp` picks up this repo deploy
 without an npm publish.
 
+## ChatGPT / OpenAI Plugins Directory
+
+This is a different form from the Claude plugin directory (already submitted)
+and from the Anthropic Connectors Directory above. File it after the OAuth DCR
+deploy is live. An agent cannot submit the form: Alex must complete OpenAI org
+verification / Apps Management write access.
+
+Portal: https://platform.openai.com/plugins
+
+Use:
+
+- MCP URL: `https://www.poster.ly/api/mcp`
+- Auth: OAuth 2.1 + PKCE + DCR at `POST /api/oauth/register` (now live on prod)
+- Domain verification: set `OPENAI_APPS_CHALLENGE_TOKEN` in Vercel to the
+  portal token, deploy, then Scan Tools. OpenAI fetches
+  `https://www.poster.ly/.well-known/openai-apps-challenge` and expects the
+  exact token as `text/plain` (no JSON).
+- Homepage: `https://www.poster.ly/agents`
+- Privacy: `https://www.poster.ly/privacy`
+- Terms: `https://www.poster.ly/terms`
+- Support: `https://www.poster.ly/dashboard/support` (or `/agents`)
+
+Do not claim the plugin is listed until OpenAI publishes it.
+
 ## Other hosted hosts
 
 ChatGPT-style hosts follow the same DCR + authorize + token flow. HTTPS
@@ -62,9 +100,7 @@ callbacks such as `https://chatgpt.com/oauth/callback` are already accepted by
 the redirect URI validator. Extra browser origins can be added with
 `MCP_TRUSTED_ORIGINS` (comma-separated hostnames or full URLs).
 
-The ChatGPT plugin / app directory is a separate OpenAI form. File it after
-this OAuth DCR deploy is live; it is not covered by the Anthropic connector
-submission.
+The ChatGPT plugin / app directory form is covered in the section above.
 
 ## Registry metadata
 

package/dist/lib/version.d.ts

@@ -1 +1 @@
-export declare const POSTERLY_MCP_VERSION = "0.43.5";
+export declare const POSTERLY_MCP_VERSION = "0.43.7";

package/dist/lib/version.js

@@ -5,4 +5,4 @@
 // tool set (minus the intentional pre-auth signup tools that only this stdio
 // package exposes). `npm run check:mcp-parity` enforces both the version match
 // and the tool-list match, and runs in the pre-commit hook.
-export const POSTERLY_MCP_VERSION = '0.43.5';
+export const POSTERLY_MCP_VERSION = '0.43.7';

package/dist/tools/cancel-subscription.js

@@ -23,11 +23,11 @@ function formatCanceled(result) {
 }
 export const cancelSubscriptionTool = {
     name: 'cancel_subscription',
-    description: "Cancel the authenticated user's posterly subscription. DESTRUCTIVE billing action; requires the billing:write scope. ALWAYS ask the user why they are cancelling FIRST and pass their answer as `reason` (one of the allowed values). By default the subscription is set to cancel at the end of the current period; pass immediate=true only if the user explicitly wants it cancelled right now. Only call after the user explicitly confirms.",
+    description: "Cancel the authenticated user's posterly subscription. DESTRUCTIVE billing action; requires the billing:write scope. ALWAYS ask the user why they are cancelling FIRST and pass their answer as `reason` (one of the allowed values). By default an active or trialing plan is set to cancel at the end of the current period. A past_due or unpaid plan always ends now, even when immediate is false: the unpaid renewal is dropped and payment retries stop. Pass immediate=true only when the user explicitly wants an active plan cancelled right now. Only call after the user explicitly confirms.",
     inputSchema: z.object({
         reason: z.enum(CANCELLATION_REASONS).describe('Why the user is cancelling. Ask the user before calling; do not guess.'),
         feedback: z.string().max(2000).optional().describe('Optional free-text detail the user gave about why they are cancelling.'),
-        immediate: z.boolean().optional().describe('Cancel immediately instead of at period end. Defaults to false (cancel at period end).'),
+        immediate: z.boolean().optional().describe('Cancel immediately instead of at period end. Defaults to false. Ignored for past_due and unpaid plans, which always end now.'),
         confirm: z.literal(true).describe('Must be true after the user explicitly confirms the cancellation.'),
     }),
     async execute(client, input) {

package/dist/tools/delete-comment.js

@@ -4,7 +4,7 @@ export const deleteCommentTool = {
     description: 'Delete an Instagram or Facebook Page inbox comment. DESTRUCTIVE and IRREVERSIBLE. Threads replies cannot be deleted; hide them with update_comment instead. Requires a Pro plan or higher, posts:write, and admin workspace access. Fetch with get_comment first and pass confirm=true only after explicit user confirmation.',
     inputSchema: z.object({
         comment_id: z.string().min(1).describe('Comment ID from list_comments or get_comment.'),
-        workspace_id: z.string().optional().describe('Workspace ID from whoami.'),
+        workspace_id: z.string().optional().describe('Optional. Omit to search every workspace you belong to; pass a workspace ID from whoami to limit to one.'),
         confirm: z.literal(true).describe('Must be true after explicit user confirmation of the comment deletion.'),
     }),
     async execute(client, input) {

package/dist/tools/get-comment.js

@@ -5,7 +5,7 @@ export const getCommentTool = {
     description: 'Get one social inbox comment and its replies. Instagram, Facebook Page, Threads, and LinkedIn Page comments. Requires a Pro plan or higher plus posts:read.',
     inputSchema: z.object({
         comment_id: z.string().min(1).describe('Comment ID from list_comments.'),
-        workspace_id: z.string().optional().describe('Filter to a workspace ID from whoami.'),
+        workspace_id: z.string().optional().describe('Optional. Omit to search every workspace you belong to; pass a workspace ID from whoami to limit to one.'),
     }),
     async execute(client, input) {
         const result = await client.getComment(input);

package/dist/tools/get-conversation.js

@@ -5,7 +5,7 @@ export const getConversationTool = {
     description: 'Get one social inbox DM conversation and its messages. Instagram and Facebook Page DMs only. Requires a Pro plan or higher plus posts:read.',
     inputSchema: z.object({
         conversation_id: z.string().min(1).describe('Conversation ID from list_conversations.'),
-        workspace_id: z.string().optional().describe('Filter to a workspace ID from whoami.'),
+        workspace_id: z.string().optional().describe('Optional. Omit to search every workspace you belong to; pass a workspace ID from whoami to limit to one.'),
         limit: z.number().int().min(1).max(100).optional().describe('Maximum messages to return. Default 50, max 100.'),
     }),
     async execute(client, input) {

package/dist/tools/list-comments.js

@@ -1,11 +1,28 @@
 import { z } from 'zod';
 import { truncateText } from '../lib/format.js';
 const INBOX_PLATFORMS = ['instagram', 'facebook', 'threads', 'linkedin'];
+/**
+ * The shared `InboxConversationsResponse`/`InboxCommentsResponse` types
+ * don't declare `workspaces_skipped` (a plain pass-through field from the
+ * API), so it's read here through a loose cast rather than widening those
+ * shared types for one caller.
+ */
+function describeSkippedWorkspaces(result) {
+    const skipped = result?.workspaces_skipped;
+    if (!Array.isArray(skipped) || skipped.length === 0)
+        return null;
+    const lines = skipped.map((skip) => {
+        const name = skip?.name || skip?.workspace_id || 'a workspace';
+        const reason = skip?.reason === 'plan' ? "owner's plan does not include inbox" : 'your role there is too low';
+        return `- ${name}: ${reason}`;
+    });
+    return [`Skipped ${skipped.length} workspace${skipped.length === 1 ? '' : 's'} you belong to:`, ...lines].join('\n');
+}
 export const listCommentsTool = {
     name: 'list_comments',
     description: 'List social inbox comments and replies for Instagram, Facebook Pages, Threads, and LinkedIn Pages. Filter by account, platform, unread/flagged, or search. Requires a Pro plan or higher plus posts:read.',
     inputSchema: z.object({
-        workspace_id: z.string().optional().describe('Filter to a workspace ID from whoami.'),
+        workspace_id: z.string().optional().describe('Optional. Omit to search every workspace you belong to; pass a workspace ID from whoami to limit to one.'),
         account_id: z.number().int().positive().optional().describe('Social account ID from list_accounts.'),
         platform: z.enum(INBOX_PLATFORMS).optional().describe('instagram, facebook, threads, or linkedin.'),
         filter: z.enum(['all', 'unread', 'flagged']).optional().describe('Comment filter. Defaults to all.'),
@@ -15,8 +32,12 @@ export const listCommentsTool = {
     }),
     async execute(client, input) {
         const result = await client.listComments(input);
+        const skippedNote = describeSkippedWorkspaces(result);
         if (result.comments.length === 0) {
-            return 'No inbox comments found matching your filters.';
+            return [
+                'No inbox comments found matching your filters.',
+                skippedNote,
+            ].filter(Boolean).join('\n\n');
         }
         const lines = [`Inbox comments (showing ${result.comments.length} of ${result.total}):`];
         for (const comment of result.comments) {
@@ -38,6 +59,8 @@ export const listCommentsTool = {
             const nextOffset = (input.offset ?? 0) + result.comments.length;
             lines.push('', `More comments available. Call again with offset: ${nextOffset}.`);
         }
+        if (skippedNote)
+            lines.push('', skippedNote);
         return lines.join('\n');
     },
 };

package/dist/tools/list-conversations.js

@@ -1,11 +1,28 @@
 import { z } from 'zod';
 import { truncateText } from '../lib/format.js';
 const INBOX_PLATFORMS = ['instagram', 'facebook', 'threads'];
+/**
+ * The shared `InboxConversationsResponse`/`InboxCommentsResponse` types
+ * don't declare `workspaces_skipped` (a plain pass-through field from the
+ * API), so it's read here through a loose cast rather than widening those
+ * shared types for one caller.
+ */
+function describeSkippedWorkspaces(result) {
+    const skipped = result?.workspaces_skipped;
+    if (!Array.isArray(skipped) || skipped.length === 0)
+        return null;
+    const lines = skipped.map((skip) => {
+        const name = skip?.name || skip?.workspace_id || 'a workspace';
+        const reason = skip?.reason === 'plan' ? "owner's plan does not include inbox" : 'your role there is too low';
+        return `- ${name}: ${reason}`;
+    });
+    return [`Skipped ${skipped.length} workspace${skipped.length === 1 ? '' : 's'} you belong to:`, ...lines].join('\n');
+}
 export const listConversationsTool = {
     name: 'list_conversations',
     description: 'List social inbox DM conversations for Instagram and Facebook Page inboxes. Filter by account, platform, unread/starred/archived, or search. Requires a Pro plan or higher plus posts:read. Threads has no DMs.',
     inputSchema: z.object({
-        workspace_id: z.string().optional().describe('Filter to a workspace ID from whoami.'),
+        workspace_id: z.string().optional().describe('Optional. Omit to search every workspace you belong to; pass a workspace ID from whoami to limit to one.'),
         account_id: z.number().int().positive().optional().describe('Social account ID from list_accounts.'),
         platform: z.enum(INBOX_PLATFORMS).optional().describe('instagram or facebook. Threads has no DMs.'),
         filter: z.enum(['all', 'unread', 'starred', 'archived']).optional().describe('Conversation filter. Defaults to all (excludes archived).'),
@@ -15,8 +32,12 @@ export const listConversationsTool = {
     }),
     async execute(client, input) {
         const result = await client.listConversations(input);
+        const skippedNote = describeSkippedWorkspaces(result);
         if (result.conversations.length === 0) {
-            return 'No inbox conversations found matching your filters.';
+            return [
+                'No inbox conversations found matching your filters.',
+                skippedNote,
+            ].filter(Boolean).join('\n\n');
         }
         const lines = [`Inbox conversations (showing ${result.conversations.length} of ${result.total}):`];
         for (const conversation of result.conversations) {
@@ -30,6 +51,8 @@ export const listConversationsTool = {
             const nextOffset = (input.offset ?? 0) + result.conversations.length;
             lines.push('', `More conversations available. Call again with offset: ${nextOffset}.`);
         }
+        if (skippedNote)
+            lines.push('', skippedNote);
         return lines.join('\n');
     },
 };

package/dist/tools/list-posts.js

@@ -3,7 +3,7 @@ import { dashboardUrlForPostList, formatLocalDateTime, truncateText } from '../l
 import { SUPPORTED_PLATFORM_INPUTS, SUPPORTED_PLATFORM_IDS } from '../generated/platform-manifest.js';
 export const listPostsTool = {
     name: 'list_posts',
-    description: 'List upcoming or recent posts. Filter by status (scheduled, published, failed, draft), platform, account_id, workspace_id, approval_status, or brand_id. If workspace_id is omitted, posts across every workspace the caller is a member of are returned.',
+    description: 'List upcoming or recent posts. Filter by status (scheduled, published, failed, draft), platform, account_id, workspace_id, approval_status, or brand_id. If workspace_id is omitted, this returns your own posts, across workspaces, not every post in those workspaces.',
     inputSchema: z.object({
         status: z
             .string()

package/dist/tools/reply-to-comment.js

@@ -6,7 +6,7 @@ export const replyToCommentTool = {
         comment_id: z.string().min(1).describe('Comment ID from list_comments.'),
         content: z.string().min(1).describe('Reply text to post.'),
         type: z.enum(['public', 'private']).optional().describe('public (default) or private. Private is Instagram only.'),
-        workspace_id: z.string().optional().describe('Workspace ID from whoami.'),
+        workspace_id: z.string().optional().describe('Optional. Omit to search every workspace you belong to; pass a workspace ID from whoami to limit to one.'),
         confirm: z.literal(true).describe('Must be true after explicit user confirmation.'),
     }),
     async execute(client, input) {

package/dist/tools/send-message.js

@@ -5,7 +5,7 @@ export const sendMessageTool = {
     inputSchema: z.object({
         conversation_id: z.string().min(1).describe('Conversation ID from list_conversations.'),
         content: z.string().min(1).describe('Message text to send.'),
-        workspace_id: z.string().optional().describe('Workspace ID from whoami.'),
+        workspace_id: z.string().optional().describe('Optional. Omit to search every workspace you belong to; pass a workspace ID from whoami to limit to one.'),
         confirm: z.literal(true).describe('Must be true after explicit user confirmation.'),
     }),
     async execute(client, input) {

package/dist/tools/sync-inbox.js

@@ -5,7 +5,7 @@ export const syncInboxTool = {
     inputSchema: z.object({
         account_id: z.number().int().positive().describe('Social account ID from list_accounts.'),
         sync_type: z.enum(['all', 'dm', 'comments']).optional().describe('What to sync. Defaults to all. Threads and LinkedIn are comments-only.'),
-        workspace_id: z.string().optional().describe('Workspace ID from whoami.'),
+        workspace_id: z.string().optional().describe('Optional. Omit to use the connected account\'s own workspace; pass a workspace ID from whoami to require that specific workspace.'),
     }),
     async execute(client, input) {
         const result = await client.syncInbox(input);

package/dist/tools/update-comment.js

@@ -6,7 +6,7 @@ export const updateCommentTool = {
         comment_id: z.string().min(1).describe('Comment ID from list_comments.'),
         is_hidden: z.boolean().optional().describe('Hide or unhide the comment on Instagram, Facebook, or Threads.'),
         is_read: z.boolean().optional().describe('Mark the comment read or unread in posterly.'),
-        workspace_id: z.string().optional().describe('Workspace ID from whoami.'),
+        workspace_id: z.string().optional().describe('Optional. Omit to search every workspace you belong to; pass a workspace ID from whoami to limit to one.'),
     }),
     async execute(client, input) {
         const result = await client.updateComment(input);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posterly-mcp-server",
-  "version": "0.43.5",
+  "version": "0.43.7",
   "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/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.awpthorp/posterly",
   "title": "posterly",
   "description": "Validate, schedule, publish, and analyze social content across 18 platforms with posterly.",
-  "version": "0.43.5",
+  "version": "0.43.7",
   "websiteUrl": "https://www.poster.ly/mcp",
   "repository": {
     "url": "https://github.com/awpthorp/posterly",
@@ -14,7 +14,7 @@
     {
       "registryType": "npm",
       "identifier": "posterly-mcp-server",
-      "version": "0.43.5",
+      "version": "0.43.7",
       "transport": {
         "type": "stdio"
       },

package/src/lib/version.ts

@@ -5,4 +5,4 @@
 // tool set (minus the intentional pre-auth signup tools that only this stdio
 // package exposes). `npm run check:mcp-parity` enforces both the version match
 // and the tool-list match, and runs in the pre-commit hook.
-export const POSTERLY_MCP_VERSION = '0.43.5';
+export const POSTERLY_MCP_VERSION = '0.43.7';

package/src/tools/cancel-subscription.ts

@@ -28,11 +28,11 @@ function formatCanceled(result: CancelSubscriptionResponse): string {
 export const cancelSubscriptionTool = {
   name: 'cancel_subscription',
   description:
-    "Cancel the authenticated user's posterly subscription. DESTRUCTIVE billing action; requires the billing:write scope. ALWAYS ask the user why they are cancelling FIRST and pass their answer as `reason` (one of the allowed values). By default the subscription is set to cancel at the end of the current period; pass immediate=true only if the user explicitly wants it cancelled right now. Only call after the user explicitly confirms.",
+    "Cancel the authenticated user's posterly subscription. DESTRUCTIVE billing action; requires the billing:write scope. ALWAYS ask the user why they are cancelling FIRST and pass their answer as `reason` (one of the allowed values). By default an active or trialing plan is set to cancel at the end of the current period. A past_due or unpaid plan always ends now, even when immediate is false: the unpaid renewal is dropped and payment retries stop. Pass immediate=true only when the user explicitly wants an active plan cancelled right now. Only call after the user explicitly confirms.",
   inputSchema: z.object({
     reason: z.enum(CANCELLATION_REASONS).describe('Why the user is cancelling. Ask the user before calling; do not guess.'),
     feedback: z.string().max(2000).optional().describe('Optional free-text detail the user gave about why they are cancelling.'),
-    immediate: z.boolean().optional().describe('Cancel immediately instead of at period end. Defaults to false (cancel at period end).'),
+    immediate: z.boolean().optional().describe('Cancel immediately instead of at period end. Defaults to false. Ignored for past_due and unpaid plans, which always end now.'),
     confirm: z.literal(true).describe('Must be true after the user explicitly confirms the cancellation.'),
   }),
 

package/src/tools/delete-comment.ts

@@ -7,7 +7,7 @@ export const deleteCommentTool = {
     'Delete an Instagram or Facebook Page inbox comment. DESTRUCTIVE and IRREVERSIBLE. Threads replies cannot be deleted; hide them with update_comment instead. Requires a Pro plan or higher, posts:write, and admin workspace access. Fetch with get_comment first and pass confirm=true only after explicit user confirmation.',
   inputSchema: z.object({
     comment_id: z.string().min(1).describe('Comment ID from list_comments or get_comment.'),
-    workspace_id: z.string().optional().describe('Workspace ID from whoami.'),
+    workspace_id: z.string().optional().describe('Optional. Omit to search every workspace you belong to; pass a workspace ID from whoami to limit to one.'),
     confirm: z.literal(true).describe('Must be true after explicit user confirmation of the comment deletion.'),
   }),
 

package/src/tools/get-comment.ts

@@ -8,7 +8,7 @@ export const getCommentTool = {
     'Get one social inbox comment and its replies. Instagram, Facebook Page, Threads, and LinkedIn Page comments. Requires a Pro plan or higher plus posts:read.',
   inputSchema: z.object({
     comment_id: z.string().min(1).describe('Comment ID from list_comments.'),
-    workspace_id: z.string().optional().describe('Filter to a workspace ID from whoami.'),
+    workspace_id: z.string().optional().describe('Optional. Omit to search every workspace you belong to; pass a workspace ID from whoami to limit to one.'),
   }),
 
   async execute(

package/src/tools/get-conversation.ts

@@ -8,7 +8,7 @@ export const getConversationTool = {
     'Get one social inbox DM conversation and its messages. Instagram and Facebook Page DMs only. Requires a Pro plan or higher plus posts:read.',
   inputSchema: z.object({
     conversation_id: z.string().min(1).describe('Conversation ID from list_conversations.'),
-    workspace_id: z.string().optional().describe('Filter to a workspace ID from whoami.'),
+    workspace_id: z.string().optional().describe('Optional. Omit to search every workspace you belong to; pass a workspace ID from whoami to limit to one.'),
     limit: z.number().int().min(1).max(100).optional().describe('Maximum messages to return. Default 50, max 100.'),
   }),
 

package/src/tools/list-comments.ts

@@ -4,12 +4,29 @@ import { truncateText } from '../lib/format.js';
 
 const INBOX_PLATFORMS = ['instagram', 'facebook', 'threads', 'linkedin'] as const;
 
+/**
+ * The shared `InboxConversationsResponse`/`InboxCommentsResponse` types
+ * don't declare `workspaces_skipped` (a plain pass-through field from the
+ * API), so it's read here through a loose cast rather than widening those
+ * shared types for one caller.
+ */
+function describeSkippedWorkspaces(result: unknown): string | null {
+  const skipped = (result as { workspaces_skipped?: Array<{ workspace_id?: string; name?: string; reason?: string }> })?.workspaces_skipped;
+  if (!Array.isArray(skipped) || skipped.length === 0) return null;
+  const lines = skipped.map((skip) => {
+    const name = skip?.name || skip?.workspace_id || 'a workspace';
+    const reason = skip?.reason === 'plan' ? "owner's plan does not include inbox" : 'your role there is too low';
+    return `- ${name}: ${reason}`;
+  });
+  return [`Skipped ${skipped.length} workspace${skipped.length === 1 ? '' : 's'} you belong to:`, ...lines].join('\n');
+}
+
 export const listCommentsTool = {
   name: 'list_comments',
   description:
     'List social inbox comments and replies for Instagram, Facebook Pages, Threads, and LinkedIn Pages. Filter by account, platform, unread/flagged, or search. Requires a Pro plan or higher plus posts:read.',
   inputSchema: z.object({
-    workspace_id: z.string().optional().describe('Filter to a workspace ID from whoami.'),
+    workspace_id: z.string().optional().describe('Optional. Omit to search every workspace you belong to; pass a workspace ID from whoami to limit to one.'),
     account_id: z.number().int().positive().optional().describe('Social account ID from list_accounts.'),
     platform: z.enum(INBOX_PLATFORMS).optional().describe('instagram, facebook, threads, or linkedin.'),
     filter: z.enum(['all', 'unread', 'flagged']).optional().describe('Comment filter. Defaults to all.'),
@@ -31,8 +48,12 @@ export const listCommentsTool = {
     },
   ) {
     const result = await client.listComments(input);
+    const skippedNote = describeSkippedWorkspaces(result);
     if (result.comments.length === 0) {
-      return 'No inbox comments found matching your filters.';
+      return [
+        'No inbox comments found matching your filters.',
+        skippedNote,
+      ].filter(Boolean).join('\n\n');
     }
 
     const lines = [`Inbox comments (showing ${result.comments.length} of ${result.total}):`];
@@ -54,6 +75,8 @@ export const listCommentsTool = {
       lines.push('', `More comments available. Call again with offset: ${nextOffset}.`);
     }
 
+    if (skippedNote) lines.push('', skippedNote);
+
     return lines.join('\n');
   },
 };

package/src/tools/list-conversations.ts

@@ -4,12 +4,29 @@ import { truncateText } from '../lib/format.js';
 
 const INBOX_PLATFORMS = ['instagram', 'facebook', 'threads'] as const;
 
+/**
+ * The shared `InboxConversationsResponse`/`InboxCommentsResponse` types
+ * don't declare `workspaces_skipped` (a plain pass-through field from the
+ * API), so it's read here through a loose cast rather than widening those
+ * shared types for one caller.
+ */
+function describeSkippedWorkspaces(result: unknown): string | null {
+  const skipped = (result as { workspaces_skipped?: Array<{ workspace_id?: string; name?: string; reason?: string }> })?.workspaces_skipped;
+  if (!Array.isArray(skipped) || skipped.length === 0) return null;
+  const lines = skipped.map((skip) => {
+    const name = skip?.name || skip?.workspace_id || 'a workspace';
+    const reason = skip?.reason === 'plan' ? "owner's plan does not include inbox" : 'your role there is too low';
+    return `- ${name}: ${reason}`;
+  });
+  return [`Skipped ${skipped.length} workspace${skipped.length === 1 ? '' : 's'} you belong to:`, ...lines].join('\n');
+}
+
 export const listConversationsTool = {
   name: 'list_conversations',
   description:
     'List social inbox DM conversations for Instagram and Facebook Page inboxes. Filter by account, platform, unread/starred/archived, or search. Requires a Pro plan or higher plus posts:read. Threads has no DMs.',
   inputSchema: z.object({
-    workspace_id: z.string().optional().describe('Filter to a workspace ID from whoami.'),
+    workspace_id: z.string().optional().describe('Optional. Omit to search every workspace you belong to; pass a workspace ID from whoami to limit to one.'),
     account_id: z.number().int().positive().optional().describe('Social account ID from list_accounts.'),
     platform: z.enum(INBOX_PLATFORMS).optional().describe('instagram or facebook. Threads has no DMs.'),
     filter: z.enum(['all', 'unread', 'starred', 'archived']).optional().describe('Conversation filter. Defaults to all (excludes archived).'),
@@ -31,8 +48,12 @@ export const listConversationsTool = {
     },
   ) {
     const result = await client.listConversations(input);
+    const skippedNote = describeSkippedWorkspaces(result);
     if (result.conversations.length === 0) {
-      return 'No inbox conversations found matching your filters.';
+      return [
+        'No inbox conversations found matching your filters.',
+        skippedNote,
+      ].filter(Boolean).join('\n\n');
     }
 
     const lines = [`Inbox conversations (showing ${result.conversations.length} of ${result.total}):`];
@@ -49,6 +70,8 @@ export const listConversationsTool = {
       lines.push('', `More conversations available. Call again with offset: ${nextOffset}.`);
     }
 
+    if (skippedNote) lines.push('', skippedNote);
+
     return lines.join('\n');
   },
 };

package/src/tools/list-posts.ts

@@ -6,7 +6,7 @@ import { SUPPORTED_PLATFORM_INPUTS, SUPPORTED_PLATFORM_IDS } from '../generated/
 export const listPostsTool = {
   name: 'list_posts',
   description:
-    'List upcoming or recent posts. Filter by status (scheduled, published, failed, draft), platform, account_id, workspace_id, approval_status, or brand_id. If workspace_id is omitted, posts across every workspace the caller is a member of are returned.',
+    'List upcoming or recent posts. Filter by status (scheduled, published, failed, draft), platform, account_id, workspace_id, approval_status, or brand_id. If workspace_id is omitted, this returns your own posts, across workspaces, not every post in those workspaces.',
   inputSchema: z.object({
     status: z
       .string()

package/src/tools/reply-to-comment.ts

@@ -9,7 +9,7 @@ export const replyToCommentTool = {
     comment_id: z.string().min(1).describe('Comment ID from list_comments.'),
     content: z.string().min(1).describe('Reply text to post.'),
     type: z.enum(['public', 'private']).optional().describe('public (default) or private. Private is Instagram only.'),
-    workspace_id: z.string().optional().describe('Workspace ID from whoami.'),
+    workspace_id: z.string().optional().describe('Optional. Omit to search every workspace you belong to; pass a workspace ID from whoami to limit to one.'),
     confirm: z.literal(true).describe('Must be true after explicit user confirmation.'),
   }),
 

package/src/tools/send-message.ts

@@ -8,7 +8,7 @@ export const sendMessageTool = {
   inputSchema: z.object({
     conversation_id: z.string().min(1).describe('Conversation ID from list_conversations.'),
     content: z.string().min(1).describe('Message text to send.'),
-    workspace_id: z.string().optional().describe('Workspace ID from whoami.'),
+    workspace_id: z.string().optional().describe('Optional. Omit to search every workspace you belong to; pass a workspace ID from whoami to limit to one.'),
     confirm: z.literal(true).describe('Must be true after explicit user confirmation.'),
   }),
 

package/src/tools/sync-inbox.ts

@@ -8,7 +8,7 @@ export const syncInboxTool = {
   inputSchema: z.object({
     account_id: z.number().int().positive().describe('Social account ID from list_accounts.'),
     sync_type: z.enum(['all', 'dm', 'comments']).optional().describe('What to sync. Defaults to all. Threads and LinkedIn are comments-only.'),
-    workspace_id: z.string().optional().describe('Workspace ID from whoami.'),
+    workspace_id: z.string().optional().describe('Optional. Omit to use the connected account\'s own workspace; pass a workspace ID from whoami to require that specific workspace.'),
   }),
 
   async execute(

package/src/tools/update-comment.ts

@@ -9,7 +9,7 @@ export const updateCommentTool = {
     comment_id: z.string().min(1).describe('Comment ID from list_comments.'),
     is_hidden: z.boolean().optional().describe('Hide or unhide the comment on Instagram, Facebook, or Threads.'),
     is_read: z.boolean().optional().describe('Mark the comment read or unread in posterly.'),
-    workspace_id: z.string().optional().describe('Workspace ID from whoami.'),
+    workspace_id: z.string().optional().describe('Optional. Omit to search every workspace you belong to; pass a workspace ID from whoami to limit to one.'),
   }),
 
   async execute(