posterly-mcp-server 0.44.0 → 0.45.0

package/src/tools/connect-account.ts

@@ -31,7 +31,7 @@ const PLATFORM_CREDENTIAL_FIELDS: Record<string, string[]> = {
 export const connectAccountTool = {
   name: 'connect_account',
   description:
-    'Connect a credential-based social account (telegram, bluesky, discord, wordpress, devto, hashnode, lemmy) directly, without a browser session. Call get_connect_link first to discover the exact credential fields the platform needs. Prefer scoped secrets: app passwords (Bluesky, WordPress), bot tokens (Telegram), webhook URLs (Discord), and API tokens (Dev.to, Hashnode) over primary passwords. Warn the user that any credential they share passes through this conversation. For OAuth platforms (Instagram, X, LinkedIn, ...) use create_connect_session instead.',
+    'Connect a credential-based social account (telegram, bluesky, discord, wordpress, devto, hashnode, lemmy) directly, without a browser session. Call list_platforms with view=connect_link first to discover the exact credential fields the platform needs. Prefer scoped secrets: app passwords (Bluesky, WordPress), bot tokens (Telegram), webhook URLs (Discord), and API tokens (Dev.to, Hashnode) over primary passwords. Warn the user that any credential they share passes through this conversation. For OAuth platforms (Instagram, X, LinkedIn, ...) use create_connect_session instead.',
   inputSchema: z.object({
     platform: z
       .enum(CREDENTIAL_PLATFORMS)
@@ -70,7 +70,7 @@ export const connectAccountTool = {
 
     const missing = allowedFields.filter((field) => !(field in credentials));
     if (missing.length > 0) {
-      return `Missing credential field(s) for ${input.platform}: ${missing.join(', ')}. Call get_connect_link with platform=${input.platform} to see field descriptions.`;
+      return `Missing credential field(s) for ${input.platform}: ${missing.join(', ')}. Call list_platforms with view=connect_link and target=${input.platform} to see field descriptions.`;
     }
 
     const result = await client.connectAccountCredentials({

package/src/tools/create-connect-session.ts

@@ -6,7 +6,7 @@ import { CONNECT_INPUTS } from '../generated/platform-manifest.js';
 export const createConnectSessionTool = {
   name: 'create_connect_session',
   description:
-    'Create a short-lived posterly dashboard handoff session for connecting a social account. Send the secure connection URL to the user, then poll get_connect_session to narrate progress. Do not ask for social media passwords or OAuth codes; posterly handles those browser steps.',
+    'Create a short-lived posterly dashboard handoff session for connecting a social account. Send the secure connection URL to the user, then poll list_accounts with view=connect_session to narrate progress. Do not ask for social media passwords or OAuth codes; posterly handles those browser steps.',
   inputSchema: z.object({
     platform: z
       .enum(CONNECT_INPUTS)
@@ -49,7 +49,7 @@ function formatConnectSession(session: ConnectSession, includeRaw: boolean): str
     `Expires: ${formatLocalDateTime(session.expires_at)}`,
     `Dashboard connect page: ${DASHBOARD_CONNECT_URL}`,
     '',
-    'Next step for the AI agent: send the secure connection URL to the user, explain that posterly will handle the browser OAuth step, then poll get_connect_session until the account is connected or the session ends.',
+    'Next step for the AI agent: send the secure connection URL to the user, explain that posterly will handle the browser OAuth step, then poll list_accounts with view=connect_session until the account is connected or the session ends.',
     includeRaw ? `\nRaw connect session:\n${JSON.stringify(session, null, 2)}` : '',
   ].filter(Boolean).join('\n');
 }

package/src/tools/create-post.ts

@@ -156,7 +156,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. If “tag” is ambiguous, distinguish caption @mentions (put @username in caption), native media tags (user_tags), and co-author invitations (collaborators). Native media tags work with eligible direct or Meta-linked accounts; collaborators require an eligible Meta-linked account. Call get_platform_schema(account_id) first.'),
+      .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 work with eligible direct or Meta-linked accounts; collaborators require an eligible Meta-linked account. Call list_platforms with view=schema and 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.'),
@@ -237,9 +237,9 @@ export const createPostTool = {
     '4. If scheduling multiple posts in one turn, list every post first and confirm the batch as a whole, then prefer `create_posts_batch` so they are created in one API request.\n\n' +
     'AFTER CALLING: Tell the user the post was created, include the posterly dashboard link returned by the tool, and offer the next natural action. Do not narrate raw HTTP, curl, or API plumbing.\n\n' +
     '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' +
+    '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` with `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/brandPartner, LinkedIn document titles/mentions/polls/content_call_to_action_label (including BUY_NOW and SHOP_NOW), TikTok direct-post privacy/toggles/commercial disclosure, Pinterest board/title/link/product_tags, GBP event/offer/CTA/recurrence, X reply settings/polls/paid_partnership, Threads reply controls/text attachments/ghost posts/spoilers/reply approvals/GIPHY, Telegram polls/buttons/video cover/live photo, Slack markdown/blocks, Mastodon visibility/quote/poll (media+poll allowed), and Instagram feed/story/reel/carousel/native media tags/collaborators/first comments/trial Reels/is_ai_generated/audio_id. 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' +
+    'PLATFORM SETTINGS: Pass `platform_settings` for composer-equivalent controls: Facebook story/reel/backgrounds, YouTube title/privacy/thumbnail/brandPartner, LinkedIn document titles/mentions/polls/content_call_to_action_label (including BUY_NOW and SHOP_NOW), TikTok direct-post privacy/toggles/commercial disclosure, Pinterest board/title/link/product_tags, GBP event/offer/CTA/recurrence, X reply settings/polls/paid_partnership, Threads reply controls/text attachments/ghost posts/spoilers/reply approvals/GIPHY, Telegram polls/buttons/video cover/live photo, Slack markdown/blocks, Mastodon visibility/quote/poll (media+poll allowed), and Instagram feed/story/reel/carousel/native media tags/collaborators/first comments/trial Reels/is_ai_generated/audio_id. 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 `list_platforms` with `view: "schema"` and 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/delete-post.ts

@@ -1,31 +1,72 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
-import { dashboardUrlForPosts } from '../lib/format.js';
+import { code, dashboardUrlForPosts } from '../lib/format.js';
+import { previewThenConfirm, validateArgs, type ToolContext } from '../lib/tool-runtime.js';
+
+type DeletePostInput = {
+  post_id?: number;
+  group_id?: string;
+  confirm?: boolean;
+  preview_id?: string;
+};
 
 export const deletePostTool = {
   name: 'delete_post',
   description:
-    'Delete a scheduled or draft post. DESTRUCTIVE and IRREVERSIBLE - the post and its caption cannot be recovered. Cannot delete published or currently publishing posts.\n\n' +
-    'REQUIRED BEFORE CALLING: Fetch the post with `get_post` first and show the user what will be deleted (caption, account, scheduled time). Get explicit confirmation ("yes delete it", "remove it") before calling. Never delete multiple posts in a single batch without listing each one and confirming the full list.',
+    'Delete posts. DESTRUCTIVE and IRREVERSIBLE: deleted posts and captions cannot be recovered, and published or currently publishing posts are never deleted. post_id: delete one scheduled or draft post; fetch it with `get_post` first, show the user what will be deleted (caption, account, scheduled time), and pass confirm=true only after explicit confirmation ("yes delete it", "remove it"). group_id: delete every draft, scheduled, failed, or paused post matching a caller-defined group_id, post_group_id, api_group_id, or release_id; preview then confirm: call without confirm to get a preview and preview_id, show it, then call again with confirm=true and that preview_id. Never delete several posts one by one without listing each and confirming the full list.',
   inputSchema: z.object({
-    post_id: z.number().describe('The post ID to delete'),
-    confirm: z.literal(true).describe('Must be true after explicit user confirmation of the post deletion.'),
+    post_id: z.number().optional().describe('Delete this one post.'),
+    group_id: z.string().min(1).max(160).optional().describe('Delete every unpublished post in this group or release instead.'),
+    confirm: z
+      .boolean()
+      .optional()
+      .describe('post_id: true after explicit user confirmation of the deletion. group_id: leave out to get a preview; true only with the preview_id after the user approved it.'),
+    preview_id: z.string().optional().describe('group_id: the preview_id from the preview call. Required with confirm: true.'),
   }),
+  /** The old tools' exact input schemas, for alias calls (see alias-transport.ts). */
+  legacySchemas: {
+    delete_post_group: z.object({
+      group_id: z.string().min(1).max(160),
+      confirm: z.literal(true),
+    }),
+  },
 
-  async execute(
-    client: PosterlyClient,
-    input: { post_id: number; confirm: true },
-  ) {
-    if (input.confirm !== true) {
-      throw new Error('Refusing to delete post without confirm=true after explicit user confirmation.');
+  async execute(client: PosterlyClient, input: DeletePostInput, ctx: ToolContext) {
+    const { mode, args } = validateArgs(ctx, 'delete_post', input);
+    if (mode === 'group') {
+      return previewThenConfirm({
+        tool: 'delete_post',
+        action: 'group',
+        args,
+        nonce: false,
+        legacyRefusal: 'Refusing to delete post group without confirm=true after explicit user confirmation.',
+        ctx,
+        // GET /api/v1/posts has no group filter, so the preview says in plain
+        // words which posts match instead of listing them.
+        describe: async () => [
+          `Deletes every draft, scheduled, failed, or paused post whose group_id, post_group_id, api_group_id, or release_id is ${code(args.group_id)}. Published posts are never deleted. This cannot be undone.`,
+          'To see the posts first, call list_posts and check each post\'s group or release ID.',
+        ].join('\n\n'),
+        run: async () => {
+          const result = await client.deletePostGroup(args.group_id);
+          return JSON.stringify(result, null, 2);
+        },
+      });
     }
-    const result = await client.deletePost(input.post_id);
-    return [
-      `Post #${result.id} deleted successfully.`,
-      'It has been removed from the posterly queue.',
-      `View queue in posterly: ${dashboardUrlForPosts()}`,
-      '',
-      'Next step for the AI agent: tell the user the post is gone and offer to create, reschedule, or review the next post.',
-    ].join('\n');
+    return deleteOne(client, args as { post_id: number; confirm?: boolean });
   },
 };
+
+async function deleteOne(client: PosterlyClient, input: { post_id: number; confirm?: boolean }): Promise<string> {
+  if (input.confirm !== true) {
+    throw new Error('Refusing to delete post without confirm=true after explicit user confirmation.');
+  }
+  const result = await client.deletePost(input.post_id);
+  return [
+    `Post #${result.id} deleted successfully.`,
+    'It has been removed from the posterly queue.',
+    `View queue in posterly: ${dashboardUrlForPosts()}`,
+    '',
+    'Next step for the AI agent: tell the user the post is gone and offer to create, reschedule, or review the next post.',
+  ].join('\n');
+}

package/src/tools/generate-image.ts

@@ -5,7 +5,7 @@ import { mdKeyValue, mdTitle } from '../lib/format.js';
 export const generateImageTool = {
   name: 'generate_image',
   description:
-    'Queue an AI image job via posterly using Nano Banana (Gemini) or Grok Imagine Image 2.0 (xAI). Returns job_id. Poll get_image_job until status is completed, then pass urls to create_post as media_url / media_urls. Gemini thinking high does not change the credit price.\n\n' +
+    'Queue an AI image job via posterly using Nano Banana (Gemini) or Grok Imagine Image 2.0 (xAI). Returns job_id. Poll list_jobs with type=image until status is completed, then pass urls to create_post as media_url / media_urls. Gemini thinking high does not change the credit price.\n\n' +
     'COSTS CREDITS. Every call consumes part of the user\'s monthly AI image quota (or purchased credits once the quota is exhausted). Do NOT call speculatively - always describe the image you\'re about to generate (subject, style, aspect ratio, quality/thinking, resolution) to the user and get confirmation before calling.\n\n' +
     'If the user is over their plan limit and has no credits, this tool returns a 402 with upgrade info. Surface that message verbatim - do not retry.\n\n' +
     'Common aspect ratios by platform:\n' +
@@ -100,7 +100,7 @@ export const generateImageTool = {
         ['Credits used', result.credits_used],
         ['Billed from', result.usage?.billed_from],
       ]),
-      result.message || 'Poll get_image_job with this job_id until status is completed, then pass urls to create_post.',
+      result.message || 'Poll list_jobs with type=image and this job_id until status is completed, then pass urls to create_post.',
     ].filter(Boolean).join('\n\n');
   },
 };

package/src/tools/generate-video.ts

@@ -4,7 +4,7 @@ import type { PosterlyClient } from '../lib/api-client.js';
 export const generateVideoTool = {
   name: 'generate_video',
   description:
-    'Queue an AI video generation job with Google Veo 3.1 or xAI Grok Imagine Video 1.5. COSTS CREDITS: confirm provider, prompt, duration, resolution, aspect ratio, audio choice, and credit cost with the user before calling. Grok supports 1–15 seconds and 480p–1080p; reference-to-video is capped at 720p. Poll get_video_job for status and final video_url.',
+    'Queue an AI video generation job with Google Veo 3.1 or xAI Grok Imagine Video 1.5. COSTS CREDITS: confirm provider, prompt, duration, resolution, aspect ratio, audio choice, and credit cost with the user before calling. Grok supports 1 to 15 seconds and 480p to 1080p; reference-to-video is capped at 720p. Poll list_jobs with type=video for status and final video_url.',
   inputSchema: z.object({
     provider: z.enum(['google', 'xai']).default('google').optional(),
     prompt: z.string().min(5).max(4000),

package/src/tools/get-agent-signup-info.ts

@@ -18,14 +18,14 @@ export const getAgentSignupInfoTool = {
       authState,
       '',
       'Pre-auth tools:',
-      '- get_mcp_status: checks the installed server version, latest npm version, MCP endpoint health, API auth health, and whether POSTERLY_API_KEY is configured.',
+      '- whoami with view=status: checks the installed server version, latest npm version, MCP endpoint health, API auth health, and whether POSTERLY_API_KEY is configured.',
       '- start_signup: starts paid signup and returns a signup poll URL, a browser Checkout fallback, and, when enabled, a prepaid PaymentIntent for a Link virtual card (credential_type: card).',
       '- get_signup_session: polls payment, password, and agent-access status.',
       '',
       'After posterly access is installed, onboard the user IN THIS chat (do not send them to /onboarding-v2):',
       '- whoami: confirm the paid account and read onboarding.next_step.',
       '- About you: confirm name and IANA timezone.',
-      '- create_connect_session / get_connect_session: first social account in the browser.',
+      '- create_connect_session, then list_accounts with view=connect_session: first social account in the browser.',
       '- Brand voice: ask how they want to sound, then use that on captions.',
       '- create_post: first scheduled post after validate_post and explicit confirm.',
       '',

package/src/tools/get-post.ts

@@ -1,35 +1,49 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
 import { dashboardUrlForPost, formatLocalDateTime } from '../lib/format.js';
+import { validateArgs, type ToolContext } from '../lib/tool-runtime.js';
 
 export const getPostTool = {
   name: 'get_post',
   description:
-    'Get details of a specific post by ID. Returns caption, status, scheduled time, media, and platform info.',
+    'One post by ID. view=post (default): caption, status, scheduled time, media, and platform info. view=missing: whether the post is missing required content, media, account, platform settings, or metadata before it can publish; use it to repair failed or imported posts.',
   inputSchema: z.object({
     post_id: z.number().describe('The post ID to look up'),
+    view: z.enum(['post', 'missing']).optional().describe('post (default) or missing.'),
   }),
+  /** The old tools' exact input schemas, for alias calls (see alias-transport.ts). */
+  legacySchemas: {
+    get_post_missing: z.object({ post_id: z.number().int().positive() }),
+  },
 
-  async execute(
-    client: PosterlyClient,
-    input: { post_id: number },
-  ) {
-    const result = await client.getPost(input.post_id);
-    const p = result.post as Record<string, any>;
+  async execute(client: PosterlyClient, input: { post_id: number; view?: 'post' | 'missing' }, ctx: ToolContext) {
+    const { mode, args } = validateArgs(ctx, 'get_post', input);
+    if (mode === 'missing') return postMissing(client, args as { post_id: number });
+    return post(client, args as { post_id: number });
+  },
+};
 
-    const lines = [
-      `Post #${p.id}`,
-      `• Status: ${p.status}`,
-      `• Caption: ${p.content || '(empty)'}`,
-      `• Type: ${p.post_type || 'unknown'}`,
-      `• Scheduled: ${formatLocalDateTime(p.scheduled_at)}`,
-      `• View in posterly: ${dashboardUrlForPost({ id: p.id, scheduled_at: p.scheduled_at })}`,
-    ];
+async function post(client: PosterlyClient, input: { post_id: number }): Promise<string> {
+  const result = await client.getPost(input.post_id);
+  const p = result.post as Record<string, any>;
 
-    if (p.platform_post_url) lines.push(`• Published URL: ${p.platform_post_url}`);
-    if (p.media_url) lines.push(`• Media: ${p.media_url}`);
-    if (p.media_urls?.length) lines.push(`• Media (${p.media_urls.length}): ${p.media_urls.join(', ')}`);
+  const lines = [
+    `Post #${p.id}`,
+    `• Status: ${p.status}`,
+    `• Caption: ${p.content || '(empty)'}`,
+    `• Type: ${p.post_type || 'unknown'}`,
+    `• Scheduled: ${formatLocalDateTime(p.scheduled_at)}`,
+    `• View in posterly: ${dashboardUrlForPost({ id: p.id, scheduled_at: p.scheduled_at })}`,
+  ];
 
-    return lines.join('\n');
-  },
-};
+  if (p.platform_post_url) lines.push(`• Published URL: ${p.platform_post_url}`);
+  if (p.media_url) lines.push(`• Media: ${p.media_url}`);
+  if (p.media_urls?.length) lines.push(`• Media (${p.media_urls.length}): ${p.media_urls.join(', ')}`);
+
+  return lines.join('\n');
+}
+
+async function postMissing(client: PosterlyClient, input: { post_id: number }): Promise<string> {
+  const result = await client.getPostMissing(input.post_id);
+  return JSON.stringify(result, null, 2);
+}

package/src/tools/list-accounts.ts

@@ -1,54 +1,202 @@
 import { z } from 'zod';
-import type { PosterlyClient } from '../lib/api-client.js';
-import { code, mdEmpty, mdTable, mdTitle } from '../lib/format.js';
+import type { ConnectSession, PosterlyClient } from '../lib/api-client.js';
+import {
+  DASHBOARD_CONNECT_URL,
+  code,
+  formatConnectedAccounts,
+  formatDateTime,
+  formatLocalDateTime,
+  formatPercent,
+  mdBullets,
+  mdEmpty,
+  mdKeyValue,
+  mdLearnedVoice,
+  mdQuote,
+  mdSection,
+  mdTable,
+  mdTitle,
+} from '../lib/format.js';
+import { validateArgs, type ToolContext } from '../lib/tool-runtime.js';
+
+type ListAccountsInput = {
+  view?: 'accounts' | 'learned_voice' | 'performance_profile' | 'connect_session';
+  workspace_id?: string;
+  account_id?: string | number;
+  session_id?: string;
+  debug?: boolean;
+};
 
 export const listAccountsTool = {
   name: 'list_accounts',
   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.',
+    "Connected social accounts and what posterly has learned about them. view=accounts (default): connected accounts, optionally one workspace_id or one account_id; Instagram rows identify direct-login versus Meta-linked connections and whether native media tags/collaborators are available, so check this before Instagram user_tags or collaborators. view=learned_voice (account_id): the voice learned from the account's real published captions (summary, traits, style guidelines, habits); read-only, never overwrites the saved brand profile. view=performance_profile (account_id): 90-day coaching stats, engagement-rate trend, and summary (Pro plan or higher; platforms without per-post analytics never get one). view=connect_session (session_id): poll a session from create_connect_session and keep the user updated in plain language; stop when status is connected, failed, cancelled, or expired.",
   inputSchema: z.object({
+    view: z
+      .enum(['accounts', 'learned_voice', 'performance_profile', 'connect_session'])
+      .optional()
+      .describe('accounts (default), learned_voice, performance_profile, or connect_session.'),
     workspace_id: z
       .string()
       .optional()
-      .describe('Filter to accounts in a specific workspace (get IDs via whoami).'),
+      .describe('view=accounts: filter to accounts in a specific workspace (get IDs via whoami).'),
+    account_id: z
+      .union([z.string(), z.number()])
+      .optional()
+      .describe('Social account ID from list_accounts. Required for learned_voice and performance_profile; with view=accounts it returns just that account.'),
+    session_id: z.string().optional().describe('view=connect_session: connect session ID returned by create_connect_session.'),
+    debug: z
+      .boolean()
+      .optional()
+      .describe('view=connect_session: when true, include the raw connect session JSON for debugging. Keep false for normal user-facing agent flows.'),
   }),
+  /** The old tools' exact input schemas, for alias calls (see alias-transport.ts). */
+  legacySchemas: {
+    get_learned_voice: z.object({ account_id: z.union([z.string(), z.number()]) }),
+    get_performance_profile: z.object({ account_id: z.union([z.string(), z.number()]) }),
+    get_connect_session: z.object({ session_id: z.string(), debug: z.boolean().optional() }),
+  },
 
-  async execute(client: PosterlyClient, input: { workspace_id?: string }) {
-    const accounts = await client.listAccounts({ workspace_id: input.workspace_id });
-
-    if (accounts.length === 0) {
-      return input.workspace_id
-        ? 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.');
+  async execute(client: PosterlyClient, input: ListAccountsInput, ctx: ToolContext) {
+    const { mode, args } = validateArgs(ctx, 'list_accounts', input);
+    if (mode === 'learned_voice') return learnedVoice(client, args as { account_id: string | number });
+    if (mode === 'performance_profile') return performanceProfile(client, args as { account_id: string | number });
+    if (mode === 'connect_session') {
+      const result = await client.getConnectSession(args.session_id);
+      return formatConnectSession(result.connect_session, Boolean(args.debug));
     }
+    return accountsList(client, args as ListAccountsInput);
+  },
+};
 
-    const hasInstagram = accounts.some((account) => account.platform === 'instagram');
+async function accountsList(client: PosterlyClient, input: ListAccountsInput): Promise<string> {
+  const listed = await client.listAccounts({ workspace_id: input.workspace_id });
+  // There is no GET /accounts/:id, so account_id filters the list here.
+  const accounts = input.account_id !== undefined
+    ? listed.filter((account) => String(account.id) === String(input.account_id))
+    : listed;
 
-    return [
-      mdTitle(`Connected accounts (${accounts.length})`),
-      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',
-                ]
-              : ['—', '—', '—']
-            : []),
-        ]),
-      ),
+  if (input.account_id !== undefined && accounts.length === 0) {
+    return mdEmpty('connected account', `No connected account has the ID ${String(input.account_id)}.`);
+  }
+
+  if (accounts.length === 0) {
+    return input.workspace_id
+      ? 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(
       hasInstagram
-        ? '_Instagram caption @mentions use @username in caption text. Native media tags work with eligible direct or Meta-linked accounts; collaborator invitations require an eligible Meta-linked account._'
-        : '',
-    ].filter(Boolean).join('\n\n');
-  },
-};
+        ? ['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',
+              ]
+            : ['n/a', 'n/a', 'n/a']
+          : []),
+      ]),
+    ),
+    hasInstagram
+      ? '_Instagram caption @mentions use @username in caption text. Native media tags work with eligible direct or Meta-linked accounts; collaborator invitations require an eligible Meta-linked account._'
+      : '',
+  ].filter(Boolean).join('\n\n');
+}
+
+async function learnedVoice(client: PosterlyClient, input: { account_id: string | number }): Promise<string> {
+  const { learned_voice } = await client.getAccountLearnedVoice(input.account_id);
+
+  const body = mdLearnedVoice(learned_voice);
+  if (!body) {
+    return [
+      mdTitle('No learned voice yet'),
+      'posterly has not learned a voice for this account yet. It learns automatically once the account has enough published posts (the captions are analyzed; the saved brand profile is never overwritten).',
+    ].join('\n\n');
+  }
+
+  return [mdTitle('Learned voice (from published captions)'), body].join('\n\n');
+}
+
+async function performanceProfile(client: PosterlyClient, input: { account_id: string | number }): Promise<string> {
+  const { performance_profile, reason } = await client.getAccountPerformanceProfile(input.account_id);
+
+  if (!performance_profile) {
+    const detail = reason === 'platform_not_measurable'
+      ? 'This platform does not produce per-post analytics, so posterly cannot build a performance profile for it.'
+      : reason === 'feature_not_available'
+        ? 'Performance profiles require a Pro plan or higher.'
+        : 'posterly has not built a performance profile for this account yet. It needs about 90 days of tracked posts to learn from.';
+    return mdEmpty('performance profile yet', detail);
+  }
+
+  const label = performance_profile.username
+    ? `@${performance_profile.username}${performance_profile.platform ? ` (${performance_profile.platform})` : ''}`
+    : `account ${performance_profile.social_account_id}`;
+
+  const rate = performance_profile.engagement_rate_avg != null
+    ? formatPercent(performance_profile.engagement_rate_avg * 100)
+    : 'n/a';
+
+  return [
+    mdTitle('Account performance profile', `${label} · last ${performance_profile.window_days ?? 90} days`),
+    performance_profile.narrative_summary ? mdSection('Summary', mdQuote(performance_profile.narrative_summary)) : '',
+    performance_profile.bullets.length ? mdSection('What is working', mdBullets(performance_profile.bullets)) : '',
+    mdSection('Stats', mdKeyValue([
+      ['Posts sampled', performance_profile.sample_size],
+      ['Avg engagement rate', rate],
+      ['Engagement trend', performance_profile.engagement_rate_trend],
+      ['Derived at', formatDateTime(performance_profile.derived_at)],
+    ])),
+  ].filter(Boolean).join('\n\n');
+}
+
+function formatConnectSession(session: ConnectSession, includeRaw: boolean): string {
+  const connected = session.connected_count ?? session.connected_accounts?.length ?? 0;
+  return [
+    `posterly connect session: ${session.id}`,
+    `Platform: ${session.platform}`,
+    `Status: ${session.status}`,
+    `Message: ${session.status_message}`,
+    `Connected accounts: ${connected}`,
+    `Accounts: ${formatConnectedAccounts(session.connected_accounts)}`,
+    session.error_message ? `Error: ${session.error_message}` : '',
+    `Expires: ${formatLocalDateTime(session.expires_at)}`,
+    `Dashboard connect page: ${DASHBOARD_CONNECT_URL}`,
+    '',
+    guidanceForStatus(session),
+    includeRaw ? `\nRaw connect session:\n${JSON.stringify(session, null, 2)}` : '',
+  ].filter(Boolean).join('\n');
+}
+
+function guidanceForStatus(session: ConnectSession): string {
+  switch (session.status) {
+    case 'created':
+    case 'opened':
+    case 'awaiting_provider':
+      return 'Next step for the AI agent: tell the user posterly is waiting for browser approval, then keep polling this session. Do not ask for social passwords or OAuth codes.';
+    case 'awaiting_credentials':
+      return 'Next step for the AI agent: tell the user posterly needs them to finish the browser credential step, then keep polling. Do not ask the user to paste credentials into chat.';
+    case 'connected':
+      return `Next step for the AI agent: tell the user ${formatConnectedAccounts(session.connected_accounts)} is connected, then ask what they want to schedule first or offer to create a test post.`;
+    case 'failed':
+      return 'Next step for the AI agent: tell the user the connection failed, share the error if present, and offer to create a fresh connect session.';
+    case 'cancelled':
+      return 'Next step for the AI agent: tell the user the connection was cancelled and offer to create a fresh connect session when they are ready.';
+    case 'expired':
+      return 'Next step for the AI agent: tell the user the connection link expired and create a fresh connect session if they still want to connect this account.';
+    default:
+      return 'Next step for the AI agent: explain the current connection status in plain language and keep polling unless the session is terminal.';
+  }
+}