posterly-mcp-server 0.44.0 → 0.45.1

package/dist/tools/delete-post.d.ts

@@ -1,20 +1,44 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { type ToolContext } from '../lib/tool-runtime.js';
+type DeletePostInput = {
+    post_id?: number;
+    group_id?: string;
+    confirm?: boolean;
+    preview_id?: string;
+};
 export declare const deletePostTool: {
     name: string;
     description: string;
     inputSchema: z.ZodObject<{
-        post_id: z.ZodNumber;
-        confirm: z.ZodLiteral<true>;
+        post_id: z.ZodOptional<z.ZodNumber>;
+        group_id: z.ZodOptional<z.ZodString>;
+        confirm: z.ZodOptional<z.ZodBoolean>;
+        preview_id: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
-        confirm: true;
-        post_id: number;
+        confirm?: boolean | undefined;
+        preview_id?: string | undefined;
+        post_id?: number | undefined;
+        group_id?: string | undefined;
     }, {
-        confirm: true;
-        post_id: number;
+        confirm?: boolean | undefined;
+        preview_id?: string | undefined;
+        post_id?: number | undefined;
+        group_id?: string | undefined;
     }>;
-    execute(client: PosterlyClient, input: {
-        post_id: number;
-        confirm: true;
-    }): Promise<string>;
+    /** The old tools' exact input schemas, for alias calls (see alias-transport.ts). */
+    legacySchemas: {
+        delete_post_group: z.ZodObject<{
+            group_id: z.ZodString;
+            confirm: z.ZodLiteral<true>;
+        }, "strip", z.ZodTypeAny, {
+            confirm: true;
+            group_id: string;
+        }, {
+            confirm: true;
+            group_id: string;
+        }>;
+    };
+    execute(client: PosterlyClient, input: DeletePostInput, ctx: ToolContext): Promise<string>;
 };
+export {};

package/dist/tools/delete-post.js

@@ -1,24 +1,60 @@
 import { z } from 'zod';
-import { dashboardUrlForPosts } from '../lib/format.js';
+import { code, dashboardUrlForPosts } from '../lib/format.js';
+import { previewThenConfirm, validateArgs } from '../lib/tool-runtime.js';
 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.',
+    description: '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.'),
     }),
-    async execute(client, input) {
-        if (input.confirm !== true) {
-            throw new Error('Refusing to delete post without confirm=true after explicit user confirmation.');
+    /** 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, input, ctx) {
+        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);
     },
 };
+async function deleteOne(client, input) {
+    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/dist/tools/generate-captions.d.ts

@@ -35,12 +35,12 @@ export declare const generateCaptionsTool: {
         platforms: ("instagram" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business")[];
         workspace_id?: string | undefined;
         count?: number | undefined;
+        mode?: "generate" | "adapt" | undefined;
         social_account_id?: string | undefined;
         brief?: string | undefined;
         tone?: string | undefined;
         allow_emojis?: boolean | undefined;
         hashtag_strategy?: "none" | "smart" | "minimal" | "aggressive" | undefined;
-        mode?: "generate" | "adapt" | undefined;
         source_caption?: string | undefined;
         source_platform?: "instagram" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | undefined;
         preserve_links?: boolean | undefined;
@@ -55,12 +55,12 @@ export declare const generateCaptionsTool: {
         platforms: ("instagram" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business")[];
         workspace_id?: string | undefined;
         count?: number | undefined;
+        mode?: "generate" | "adapt" | undefined;
         social_account_id?: string | undefined;
         brief?: string | undefined;
         tone?: string | undefined;
         allow_emojis?: boolean | undefined;
         hashtag_strategy?: "none" | "smart" | "minimal" | "aggressive" | undefined;
-        mode?: "generate" | "adapt" | undefined;
         source_caption?: string | undefined;
         source_platform?: "instagram" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | undefined;
         preserve_links?: boolean | undefined;

package/dist/tools/generate-image.d.ts

@@ -20,10 +20,10 @@ export declare const generateImageTool: {
         prompt: string;
         provider?: "google" | "xai" | undefined;
         aspect_ratio?: "1:1" | "16:9" | "9:16" | "4:3" | "3:4" | "3:2" | "2:3" | "4:5" | "1:4" | "1:8" | "21:9" | "4:1" | "8:1" | "5:4" | undefined;
+        resolution?: "512" | "1K" | "2K" | "4K" | undefined;
+        model?: "pro" | "lite" | "flash" | undefined;
         style?: "minimal" | "professional" | "photographic" | "illustration" | "vibrant" | "youtube_thumbnail" | "reel_cover" | "review_background" | undefined;
         variations?: number | undefined;
-        model?: "pro" | "lite" | "flash" | undefined;
-        resolution?: "512" | "1K" | "2K" | "4K" | undefined;
         quality?: "low" | "medium" | "high" | undefined;
         thinking_level?: "minimal" | "high" | undefined;
         reference_image_urls?: string[] | undefined;
@@ -32,10 +32,10 @@ export declare const generateImageTool: {
         prompt: string;
         provider?: "google" | "xai" | undefined;
         aspect_ratio?: "1:1" | "16:9" | "9:16" | "4:3" | "3:4" | "3:2" | "2:3" | "4:5" | "1:4" | "1:8" | "21:9" | "4:1" | "8:1" | "5:4" | undefined;
+        resolution?: "512" | "1K" | "2K" | "4K" | undefined;
+        model?: "pro" | "lite" | "flash" | undefined;
         style?: "minimal" | "professional" | "photographic" | "illustration" | "vibrant" | "youtube_thumbnail" | "reel_cover" | "review_background" | undefined;
         variations?: number | undefined;
-        model?: "pro" | "lite" | "flash" | undefined;
-        resolution?: "512" | "1K" | "2K" | "4K" | undefined;
         quality?: "low" | "medium" | "high" | undefined;
         thinking_level?: "minimal" | "high" | undefined;
         reference_image_urls?: string[] | undefined;

package/dist/tools/generate-image.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 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' +
+    description: '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' +
@@ -80,7 +80,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/dist/tools/generate-video.d.ts

@@ -30,11 +30,11 @@ export declare const generateVideoTool: {
         confirm: true;
         prompt: string;
         provider?: "google" | "xai" | undefined;
-        aspect_ratio?: "1:1" | "16:9" | "9:16" | "4:3" | "3:4" | "3:2" | "2:3" | undefined;
-        model?: "lite" | "fast" | "standard" | undefined;
-        resolution?: "480p" | "720p" | "1080p" | undefined;
         negative_prompt?: string | undefined;
+        aspect_ratio?: "1:1" | "16:9" | "9:16" | "4:3" | "3:4" | "3:2" | "2:3" | undefined;
         duration_seconds?: number | undefined;
+        resolution?: "480p" | "720p" | "1080p" | undefined;
+        model?: "lite" | "fast" | "standard" | undefined;
         image_url?: string | undefined;
         end_image_url?: string | undefined;
         reference_images?: {
@@ -47,11 +47,11 @@ export declare const generateVideoTool: {
         confirm: true;
         prompt: string;
         provider?: "google" | "xai" | undefined;
-        aspect_ratio?: "1:1" | "16:9" | "9:16" | "4:3" | "3:4" | "3:2" | "2:3" | undefined;
-        model?: "lite" | "fast" | "standard" | undefined;
-        resolution?: "480p" | "720p" | "1080p" | undefined;
         negative_prompt?: string | undefined;
+        aspect_ratio?: "1:1" | "16:9" | "9:16" | "4:3" | "3:4" | "3:2" | "2:3" | undefined;
         duration_seconds?: number | undefined;
+        resolution?: "480p" | "720p" | "1080p" | undefined;
+        model?: "lite" | "fast" | "standard" | undefined;
         image_url?: string | undefined;
         end_image_url?: string | undefined;
         reference_images?: {

package/dist/tools/generate-video.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 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.',
+    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 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/dist/tools/get-agent-signup-info.js

@@ -13,14 +13,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/dist/tools/get-post.d.ts

@@ -1,16 +1,31 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { type ToolContext } from '../lib/tool-runtime.js';
 export declare const getPostTool: {
     name: string;
     description: string;
     inputSchema: z.ZodObject<{
         post_id: z.ZodNumber;
+        view: z.ZodOptional<z.ZodEnum<["post", "missing"]>>;
     }, "strip", z.ZodTypeAny, {
         post_id: number;
+        view?: "post" | "missing" | undefined;
     }, {
         post_id: number;
+        view?: "post" | "missing" | undefined;
     }>;
+    /** The old tools' exact input schemas, for alias calls (see alias-transport.ts). */
+    legacySchemas: {
+        get_post_missing: z.ZodObject<{
+            post_id: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            post_id: number;
+        }, {
+            post_id: number;
+        }>;
+    };
     execute(client: PosterlyClient, input: {
         post_id: number;
-    }): Promise<string>;
+        view?: "post" | "missing";
+    }, ctx: ToolContext): Promise<string>;
 };

package/dist/tools/get-post.js

@@ -1,28 +1,44 @@
 import { z } from 'zod';
 import { dashboardUrlForPost, formatLocalDateTime } from '../lib/format.js';
+import { validateArgs } 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.',
+    description: '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.'),
     }),
-    async execute(client, input) {
-        const result = await client.getPost(input.post_id);
-        const p = result.post;
-        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 })}`,
-        ];
-        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');
+    /** 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, input, ctx) {
+        const { mode, args } = validateArgs(ctx, 'get_post', input);
+        if (mode === 'missing')
+            return postMissing(client, args);
+        return post(client, args);
     },
 };
+async function post(client, input) {
+    const result = await client.getPost(input.post_id);
+    const p = result.post;
+    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 })}`,
+    ];
+    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, input) {
+    const result = await client.getPostMissing(input.post_id);
+    return JSON.stringify(result, null, 2);
+}

package/dist/tools/list-accounts.d.ts

@@ -1,16 +1,62 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { 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 declare const listAccountsTool: {
     name: string;
     description: string;
     inputSchema: z.ZodObject<{
+        view: z.ZodOptional<z.ZodEnum<["accounts", "learned_voice", "performance_profile", "connect_session"]>>;
         workspace_id: z.ZodOptional<z.ZodString>;
+        account_id: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+        session_id: z.ZodOptional<z.ZodString>;
+        debug: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
         workspace_id?: string | undefined;
+        account_id?: string | number | undefined;
+        view?: "accounts" | "learned_voice" | "performance_profile" | "connect_session" | undefined;
+        session_id?: string | undefined;
+        debug?: boolean | undefined;
     }, {
         workspace_id?: string | undefined;
+        account_id?: string | number | undefined;
+        view?: "accounts" | "learned_voice" | "performance_profile" | "connect_session" | undefined;
+        session_id?: string | undefined;
+        debug?: boolean | undefined;
     }>;
-    execute(client: PosterlyClient, input: {
-        workspace_id?: string;
-    }): Promise<string>;
+    /** The old tools' exact input schemas, for alias calls (see alias-transport.ts). */
+    legacySchemas: {
+        get_learned_voice: z.ZodObject<{
+            account_id: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+        }, "strip", z.ZodTypeAny, {
+            account_id: string | number;
+        }, {
+            account_id: string | number;
+        }>;
+        get_performance_profile: z.ZodObject<{
+            account_id: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+        }, "strip", z.ZodTypeAny, {
+            account_id: string | number;
+        }, {
+            account_id: string | number;
+        }>;
+        get_connect_session: z.ZodObject<{
+            session_id: z.ZodString;
+            debug: z.ZodOptional<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            session_id: string;
+            debug?: boolean | undefined;
+        }, {
+            session_id: string;
+            debug?: boolean | undefined;
+        }>;
+    };
+    execute(client: PosterlyClient, input: ListAccountsInput, ctx: ToolContext): Promise<string>;
 };
+export {};

package/dist/tools/list-accounts.js

@@ -1,44 +1,159 @@
 import { z } from 'zod';
-import { code, mdEmpty, mdTable, mdTitle } from '../lib/format.js';
+import { DASHBOARD_CONNECT_URL, code, formatConnectedAccounts, formatDateTime, formatLocalDateTime, formatPercent, mdBullets, mdEmpty, mdKeyValue, mdLearnedVoice, mdQuote, mdSection, mdTable, mdTitle, } from '../lib/format.js';
+import { validateArgs } from '../lib/tool-runtime.js';
 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.',
+    description: "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.'),
     }),
-    async execute(client, input) {
-        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.');
+    /** 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, input, ctx) {
+        const { mode, args } = validateArgs(ctx, 'list_accounts', input);
+        if (mode === 'learned_voice')
+            return learnedVoice(client, args);
+        if (mode === 'performance_profile')
+            return performanceProfile(client, args);
+        if (mode === 'connect_session') {
+            const result = await client.getConnectSession(args.session_id);
+            return formatConnectSession(result.connect_session, Boolean(args.debug));
         }
-        const hasInstagram = accounts.some((account) => account.platform === 'instagram');
-        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',
-                        ]
-                        : ['—', '—', '—']
-                    : []),
-            ])),
-            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');
+        return accountsList(client, args);
     },
 };
+async function accountsList(client, input) {
+    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;
+    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
+            ? ['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, input) {
+    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, input) {
+    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, includeRaw) {
+    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) {
+    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.';
+    }
+}