Reader Radius MCP docs

Ask your assistant: “What should I do next with my book marketing?”

The author's next steps in Reader Radius, worked out from their account: no connected accounts, no Instagram for trial reels, nothing scheduled in the next 7 days, nothing posted in the last 7, every ad paused, no comment-to-DM rule. Each step says how to fix it, with the page link when the fix is on the website. Use it when the user asks what to do next or seems stuck, and at the start of a planning session. `unchecked` lists checks that couldn't run. Pass profileId for a non-primary pen name.

Ask your assistant: “Read the Reader Radius playbook, then plan my launch.”

The Reader Radius publisher playbook as markdown: how to plan and run book marketing here (trial reels, vertical shorts, 30 days of posts, lead magnets by DM), with example prompts. Read it before planning anyone's marketing, and whenever the user mentions the Reader Radius playbook. Also available as the resource readerradius://playbook.

Ask your assistant: “List my connected accounts.”

List the user's connected social media accounts for a given pen-name profile. Returns account IDs (needed for creating posts), platform names, and usernames. Pass profileId to target a non-primary pen name (call aa_list_profiles first to discover). For large account sets, pass page (1-based) to page through results; the response includes a `pagination` object ({ page, limit, total, pages }) so you can tell when more accounts exist beyond the current page. Omit page to get all accounts.

Ask your assistant: “Post this image to Instagram and Facebook tomorrow at 9am with a caption about my new release.”

Create and schedule a social media post. Use accountIds from aa_list_accounts. Set publishNow:true to post immediately, or scheduledAt for a specific time. ═══ PER-PLATFORM OPTIONS — TWO LAYERS ═══ 1) TYPED options (instagramOptions, tiktokOptions, threadsOptions, etc). Validated locally → fast 422 with a clear suggestion when something's off. 2) RAW platformOptions: { instagram: {...}, threads: {...}, twitter: {...}, ... }. Forwarded directly to the upstream platformSpecificData payload. Use this for anything not in the typed list, OR for platforms we haven't typed yet (twitter, bluesky, telegram, snapchat, googlebusiness, discord, whatsapp). Typed options take precedence; raw fills the rest. Both merge per platform. ═══ INSTAGRAM ═══ Aspect ratios: Feed = 0.75:1 to 1.91:1 (use 1080×1080, 1080×1350, or 1080×566). Stories/Reels = 9:16 single media only (use 1080×1920). If user has 4 vertical (9:16) images for IG, post 4 separate Stories — NOT one carousel. Carousels: up to 10 items, all same media type (no mixing image+video). instagramOptions: contentType: 'story' | 'reel' — omit for Feed (default) coverImage: URL of a 9:16 image — Reel cover coverFromTimestamp: ms into video — Reel cover from a video frame trialParams: { graduationStrategy: 'MANUAL' | 'SS_PERFORMANCE' } — Trial Reel: shown to non-followers first shareToFeed, collaborators, firstComment, audioName, userTags ═══ TIKTOK ═══ tiktokOptions: draft (save to TikTok Inbox to review before publish), privacyLevel (PUBLIC_TO_EVERYONE | MUTUAL_FOLLOW_FRIENDS | FOLLOWER_OF_CREATOR | SELF_ONLY), allowComment, allowDuet, allowStitch (videos only), autoAddMusic (TikTok adds trending music to photo carousels), videoCoverTimestampMs / videoCoverImageUrl, photoCoverIndex, commercialContentType: 'none' | 'brand_organic' | 'brand_content' — when set to anything other than 'none', TikTok REQUIRES the paired flag: brand_organic → isBrandOrganicPost=true; brand_content → brandPartnerPromote=true. Forgetting the pair rejects the post. contentPreviewConfirmed + expressConsentGiven — TikTok policy attestations. Default both to true for any non-draft publish; the user agreed by submitting via the tool. videoMadeWithAi — AI-generated content disclosure (REQUIRED if the video is AI-generated or significantly AI-edited). description — long-form caption for photo carousels (up to 4000 chars; separate from the main caption). ASK THE USER: if they're posting AI-generated video → set videoMadeWithAi=true. If the post promotes a brand or is a paid partnership → set commercialContentType. If they want to review before publishing → draft=true. ═══ THREADS ═══ threadsOptions.topicTag (1–50 chars, NO '.' or '&'). Use platformOptions.threads.threadItems for chains. ═══ YOUTUBE ═══ youtubeOptions.title is REQUIRED for video posts. visibility, madeForKids, containsSyntheticMedia, firstComment, categoryId, playlistId. ═══ REDDIT ═══ redditOptions.subreddit + title both REQUIRED. url, forceSelf, flairId, nsfw, spoiler, nativeVideo (upload to Reddit's video player; default true), videogif (post video as a looping GIF), videoPosterUrl (thumbnail URL for the native video). ═══ FACEBOOK ═══ facebookOptions: contentType ('story' | 'reel'; omit for Feed default), title (Reel title, only honored when contentType=reel), firstComment (Feed-post only; auto-posted as comment 1 below the post). On Pages Meta has limited, it still counts as one of the 2 free link posts a month. draft (true → stages the post as an unpublished draft in Facebook Publishing Tools; expires in ~30 days). ASK THE USER: if they want to review or get sign-off before publishing → draft=true. ═══ LINKEDIN ═══ linkedinOptions: firstComment (LinkedIn DOWN-RANKS posts with external links by 40-50% — put URLs in the first comment, NOT the main caption), disableLinkPreview (suppresses LinkedIn's auto-generated URL card), documentTitle (REQUIRED when posting a PDF/document — headline above the preview). ═══ TWITTER / X ═══ Use platformOptions.twitter for threadItems / poll / replyToTweetId (mutually exclusive with replySettings). replySettings: 'following' | 'mentionedUsers' | 'subscribers' | 'verified' — restricts who can reply. longVideo: true → upload up to ~10 min via amplify_video (requires X Premium + API allowlisting). ═══ PINTEREST ═══ Use platformOptions.pinterest: link (destination URL for each pin), boardId, title, coverImageUrl, coverImageKeyFrameTime. ASK: what URL should the pin send clicks to? (often a book sales link) ═══ EVERYTHING ELSE ═══ Use raw platformOptions: bluesky, telegram, snapchat, googlebusiness, discord, whatsapp. Field names match the platform's verbatim docs. Discord: tts (text-to-speech), webhookUsername (display name override, max 80 chars), webhookAvatarUrl, crosspost (publish to following servers — announcement channels only). Pass width/height on each image mediaItem when known — server skips a probe-fetch and validates IG faster. tags: root-level array of YouTube video tags (≤500 chars total including commas). The network puts this at the post ROOT, not inside youtubeOptions.

Ask your assistant: “Move Friday's post to Saturday at 10am.”

Update a scheduled post's content or time. Pass profileId for posts that belong to a non-primary pen name (the same id you used when creating the post or campaign) — without it, the server scopes to the user's primary profile and returns 404.

Ask your assistant: “Show me everything scheduled for next week.”

List the user's posts with optional filters. Two read sources: 'mirror' (DEFAULT — local 15-min-synced snapshot, fast, matches what the dashboard shows, survives upstream outages) and 'live' (read-through to the network, always current, costs an upstream API call). Use mirror for general 'what's my week look like?' / 'show me scheduled Threads posts' / 'what published last month?' questions — that's the conversational default. Use live ONLY when (a) the user explicitly says 'check directly' / 'are you sure?' / 'right now', (b) the user just made a change in the dashboard and wants you to see it before the next 15-min sync, or (c) the mirror response shows _oldest_synced_at older than ~1 hour (means the cron lagged). Pass profileId to scope to a specific pen name (default is primary). dateFrom/dateTo accept YYYY-MM-DD or ISO. Status filter accepts scheduled / published / failed / publishing / draft / cancelled / partial. 'partial' (some platform legs published, others failed) is an upstream rollup only — ask for it with source='live', because the mirror stores a per-leg status and never holds 'partial' itself. For a failed or partial post, follow up with aa_get_post_logs to read why.

Ask your assistant: “What posting slots do I have set up?”

List the user's posting queues (queue definitions, not next-slot previews — use aa_queue_preview for that). Each queue has optional per-platform decoration (the `platforms[]` field — e.g., a queue with ["instagram", "tiktok"] populates the next IG slot AND the next TikTok slot independently when a multi-platform post is added). Each queue also has optional persona scope (the `tag` field — NULL means the queue is shared across every persona under this pen name; a tag string scopes the queue to that persona only). Personas come from the user's content guides; see aa_list_guide_sets.

Ask your assistant: “When will my next three queued posts go out?”

Preview upcoming queue slots for a pen-name profile. Pass profileId to inspect a non-primary pen name's queue.

Ask your assistant: “How did my posts do last week? Show reach and engagement by platform.”

Cross-platform post analytics for a pen-name profile (impressions, reach, engagement, etc., per post). Optional fromDate / toDate (YYYY-MM-DD or ISO), platform, accountId filters. Start here for any 'how did my posts perform?' question; drill down with aa_get_daily_metrics or aa_get_facebook_page_insights if needed. If it returns ANALYTICS_ADDON_REQUIRED, analytics isn't switched on for this account yet: say so and point the user to support; never suggest buying anything.

Ask your assistant: “Show me new comments on my last three posts.”

List comments on published posts across connected accounts (e.g., people commenting on your Instagram, Facebook or TikTok posts). Optional accountId / platform filters. Use aa_reply_inbox_comment, aa_hide_comment, aa_like_inbox_comment or aa_pin_inbox_comment (TikTok) to act on entries.

Ask your assistant: “Reply to that comment and thank them for reading.”

Reply to a comment on one of the user's published posts. postId + commentId from aa_list_inbox_comments; accountId is the social account that owns the post.

Ask your assistant: “Do I have any unanswered DMs?”

List DM / messaging conversations across connected accounts. Optional accountId scopes to one social account; optional platform filters by network (instagram, facebook, tiktok, telegram, whatsapp, etc.). TikTok DMs are reply-only (the business can never open a conversation) and need an account connected through TikTok for Business. Returns conversation summaries (id, participants, latest message, unread count) — use aa_get_inbox_thread to load full message history.

Ask your assistant: “When someone comments READ, DM them my free chapter.”

Create a comment-automation rule (comment or Instagram story-reply keyword → automatic DM). accountId + name + dmMessage required. Omit platformPostId to watch EVERY post/story on the account. Supports word/contains/exact matching with typoTolerance and excludeKeywords, DM buttons (1-3) or a generic template card carousel, audience targeting with follow gates, message variations, link tracking, and delivery delays.

Ask your assistant: “Which comment-to-DM rules are running?”

List the user's comment-automation rules (e.g., 'auto-DM anyone who comments BOOK on this post'). Returns the active rule set.

Ask your assistant: “Plan a 30-day launch campaign for my new book.”

Create a new campaign for a pen-name profile. After creating, use aa_save_campaign_plan to add the content plan. Pass profileId to attach the campaign to a non-primary pen name. Pass guideTag to use a specific persona for this campaign's AI generations — call aa_list_guide_sets first if the user mentioned a series, sub-brand, or specific voice. Omitting guideTag uses the user's default persona. The choice persists on the campaign row so regenerations stay on the same voice.

Ask your assistant: “How are all my ads doing this month?”

Normalized campaign list across EVERY connected ad network in one call — Meta, Google, TikTok, LinkedIn, Pinterest, X, ChatGPT, and Amazon — each row with status, spend, results, and any book-title mapping attached (see aa_get_ad_title_map). Optional accounts[] (connected-account ids from aa_list_accounts) narrows the sweep; from/to (YYYY-MM-DD) sets the window, default last 30 days. Partial network failures come back in `errors` rather than failing the whole call. Start here for any 'how are all my ads doing?' question. Pass profileId for a non-primary pen name. Ads tools are included on the $19 MCP plan and with StorytellerOS; the $29 plan needs the ads add-on.

Ask your assistant: “Create a $10 a day Meta ad for my book, paused, so I can check it first.”

REAL MONEY — create a brand-new ad (not boosting an existing post). accountId + adAccountId required. Never pass postId or platformPostId: those make it a boost (postId is stripped here; use aa_boost_post for existing posts). The body is forwarded as-is, so ad fields go FLAT inside `extra` — nested creative/budget objects are not translated. A typical ad: extra: { name, goal: 'traffic', status: 'PAUSED', headline, body, imageUrl, linkUrl, callToAction: 'LEARN_MORE', budgetAmount: 20, budgetType: 'daily'|'lifetime', startDate, endDate } (lifetime budgets need endDate) Always pass status 'PAUSED' (it works on every network) unless the user explicitly says launch live; PAUSED holds the new campaign with its ad set and ad switched on. Start it in-app with aa_update_ad_campaign_status, never in a network's own ads manager. Google Performance Max and Demand Gen are always created paused and need their nested `assetGroup` / `demandGen` payloads in extra. Lead ads: aa_create_lead_form first, then extra: { goal: 'lead_generation', leadGenFormId }. Catalog ads (Meta only, goal 'catalog_sales'): Meta builds one ad per product from a catalog, with each product's own image. Pick a set first: aa_list_ad_catalogs → aa_list_ad_catalog_product_sets (a Shopify store fills a catalog via aa_create_catalog_sync). extra: { goal: 'catalog_sales', promotedObject: { productSetId, pixelId, customEventType: 'PURCHASE', productCatalogId? }, headline, body, linkUrl, callToAction: 'SHOP_NOW', budget fields }. Copy may use tags like {{product.name}}. One template only: no imageUrl, video, creatives, carouselCards, adSetId, dynamicCreative or placementAssets (refused with a 400 naming them). targeting (forwarded as-is): countries, regions, cities, zips, metros, ageMin/ageMax, gender ('all'|'male'|'female'), languages, interests (ids from aa_search_ad_interests), excludedLocations: { countries, regions, cities, zips }. Age and gender apply on Meta, TikTok, Pinterest, LinkedIn, X and Google Search/Display; languages everywhere but ChatGPT; Google interests only on Search/Display. ChatGPT takes none of age, gender, languages or interests, and Google Performance Max / Demand Gen refuse age, gender and interests. A field a network can't use is refused with an error naming it, not ignored. rawTargeting: raw Meta targeting JSON (places, neighborhoods, custom audiences). It is the base layer and `targeting` merges on top; usually pass one or the other. Networks: Meta (full fields incl. creatives/bid/lead forms), TikTok (imageUrl may be a video URL; min budget $20), LinkedIn (LinkedIn conversions run as a boost), Google (campaignType search|display, also pmax|demand_gen; goals engagement/traffic/awareness; keywords, businessName, longHeadline; headline max 30 / body max 90), Pinterest (boardId optional; headline max 100 / body max 500; $5 min), ChatGPT (openaiads account; goals traffic/awareness/conversions), X. Goals differ by network (Pinterest: engagement/traffic/awareness/video_views); an unsupported goal is refused. adAccountId comes from aa_list_ad_accounts; if a connection lists none, connect that network's ads with aa_connect_ads_account first (ChatGPT: aa_connect_openai_ads). Amazon: use aa_create_amazon_campaign. ALWAYS confirm budget + duration with the user before calling. Ads tools are included on the $19 MCP plan and with StorytellerOS; the $29 plan needs the ads add-on.

Ask your assistant: “Pause the ads that aren't getting clicks.”

Pause or resume a paid ad campaign. This flips the campaign's own switch only: pausing stops all delivery under it, resuming restarts the ad sets and ads that are switched on (any paused on their own stay paused), except on Google, where resuming a campaign also switches its ad groups and ads back on. id is the platform campaign id; accountId is the connected social account (tenant boundary); platform names the network. REAL MONEY — confirm with the user before resuming a paused campaign. Ads tools are included on the $19 MCP plan and with StorytellerOS; the $29 plan needs the ads add-on.

Ask your assistant: “Show my Amazon campaigns with spend and ACOS for the last 14 days.”

Per-campaign Amazon Ads rollups (spend, sales, clicks, impressions, ACOS) over a date window. Optional from/to (YYYY-MM-DD); default last 30 days. Covers every synced Amazon advertiser profile on the connection. Pass profileId for a non-primary pen name. Ads tools are included on the $19 MCP plan and with StorytellerOS; the $29 plan needs the ads add-on.

Ask your assistant: “Are my Amazon ads profitable once page reads are counted?”

Ad-attributed Amazon P&L over a date window — spend vs attributed sales/royalties rolled up from the synced Amazon reports. Optional from/to (YYYY-MM-DD); default last 30 days. Pass profileId for a non-primary pen name. Ads tools are included on the $19 MCP plan and with StorytellerOS; the $29 plan needs the ads add-on.

Ask your assistant: “Create a $10 a day Sponsored Products campaign for my paperback with automatic targeting, and leave it paused for me to check.”

Create an Amazon Sponsored Products campaign for a book: campaign, ad group, product ad (the book's ASIN), optional manual keywords, and optional negative keywords (exact/phrase terms the ad must NOT show for) in one chain. REAL MONEY: always created PAUSED — the author starts it from the dashboard's "Start these ads" button (or aa_amazon_ads_campaign_state) after review. The ASIN must come from the book's listing (never guessed). For the other two Amazon products use aa_amazon_ads_create_sb (Sponsored Brands, live) or aa_amazon_ads_create_sd (Sponsored Display) instead — Sponsored Brands is also accepted here as campaignType "sb" and creates the image ad. Requires an enrolled Amazon advertiser profile (aa_amazon_ads_status lists them). Pass profileId for a non-primary pen name. Ads tools are included on the $19 MCP plan and with StorytellerOS; the $29 plan needs the ads add-on.

Ask your assistant: “Is my Shopify store connected, and what can Reader Radius do with it?”

Show a connected Shopify store (name, domain, currency) and its permissions. When `permissions.complete` is false, tell the user what to do: `fix: grant` means open `grantPermissionsUrl` and approve in Shopify; `fix: custom_app_scopes` means add the missing Admin API scopes to their own custom app and reconnect. Call this first when a product call answers STORE_PERMISSIONS_MISSING. Pass profileId for a non-primary pen name.

The Reader Radius publisher playbook as markdown: how to plan and run book marketing here (trial reels, vertical shorts, 30 days of posts, lead magnets by DM), with example prompts. Read it before planning anyone's marketing, and whenever the user mentions the Reader Radius playbook. Also available as the resource readerradius://playbook.

The author's next steps in Reader Radius, worked out from their account: no connected accounts, no Instagram for trial reels, nothing scheduled in the next 7 days, nothing posted in the last 7, every ad paused, no comment-to-DM rule. Each step says how to fix it, with the page link when the fix is on the website. Use it when the user asks what to do next or seems stuck, and at the start of a planning session. `unchecked` lists checks that couldn't run. Pass profileId for a non-primary pen name.

Create an account group. accountIds are connected-account ids from aa_list_accounts (they must belong to the active pen name). Pass profileId for a non-primary pen name.

Delete an account group. The member accounts themselves are unaffected — only the grouping is removed. Pass profileId for a non-primary pen name.

Delete a persona entirely (all four guide texts disappear). The server refuses to delete the default persona — every fallback lookup resolves to it, so removing it would leave generations with empty guides. To delete the current default, mark a different persona as the default first via the dashboard, then retry. Returns 404 if the tag doesn't exist on this pen name.

Live health check for ONE account — token validity, needsReconnect, canPost. Single-account equivalent of aa_get_accounts_health; use when you already know which account to check.

Per-account diagnostic health: token validity, granted vs missing OAuth scopes, canFetchAnalytics, and recommendations[]. Use this to explain why a platform (e.g. TikTok Personal) is returning no analytics, or to nudge the user to reconnect. Optional platform / status filters.

Get AI provider connection flags and account defaults for text, images, video, and music. Never returns plaintext keys.

Get the Facebook Page IDs currently attached to the active pen name (these are the pages the user has opted in for posting / insights). Returns { attachedPageIds: string[] }.

Get a persona — the brand voice the AI uses when writing for a given pen-name profile. A persona has four guides (prose, brand, copywriting, social-media) plus a user-defined name. Read this before drafting captions or campaign content to match the user's voice. One pen name can have many personas — e.g. fiction vs. nonfiction, different genres, different series. Pass `tag` to pick a specific persona by name. Without a tag, returns the user's default persona (the one marked as the fallback for unspecified generations). If you don't know which persona to pick and the user has multiple, call aa_list_guide_sets first to see the options. Persona names are user-defined — the user may have renamed their default to something like 'Cozy Mystery' or 'Author Brand', so don't assume a tag of 'primary' exists.

List the pen name's account groups — named sets of connected social accounts (e.g. 'Fiction brand', 'All video platforms') used to target several accounts at once. Returns each group's id, name, and member accountIds. Pass profileId for a non-primary pen name.

List the user's connected social media accounts for a given pen-name profile. Returns account IDs (needed for creating posts), platform names, and usernames. Pass profileId to target a non-primary pen name (call aa_list_profiles first to discover). For large account sets, pass page (1-based) to page through results; the response includes a `pagination` object ({ page, limit, total, pages }) so you can tell when more accounts exist beyond the current page. Omit page to get all accounts.

List the Facebook Pages a connected Facebook account can publish to. accountId required (a Facebook account from aa_list_accounts). Returns [{ id, name, username, category, fanCount }]. Call this BEFORE aa_set_attached_facebook_pages to discover available pageIds.

List every persona configured for a pen-name profile. A persona is a distinct brand voice — fiction author, nonfiction coach, cozy mystery series, spicy romance, etc. — each with its own prose / brand / copywriting / social-media guides. Returns [{ tag, is_default, prose_guide, brand_guide, copywriting_guide, social_media_guide, updated_at }]. Exactly one persona has is_default=true; that's the fallback for any aa_get_guides call without an explicit tag. Call this BEFORE aa_get_guides when the user mentions a specific voice / series / sub-brand and you need to pick the right tag (e.g. 'use my Cozy Mystery voice' → list personas, match the tag case-insensitively, then aa_get_guides with that tag). If the user has multiple personas and gave no signal, ASK which to use rather than guessing.

List LinkedIn organizations (Company Pages) the connected LinkedIn user administers. Use before aa_set_linkedin_organization to pick a valid organization.

List every pen-name profile the user has access to. Returns each profile's ID, name, and which one is the user's primary. USE THIS FIRST when: - The user mentions a pen name by name (e.g., 'post to my Indie Author Magazine account', 'schedule under chelle') - The user might have multiple pen names — call this once to find out - A previous tool returned an empty result and you suspect you're querying the wrong profile Then pass the chosen profile's ID as the `profileId` argument on subsequent tools (aa_list_accounts, aa_create_post, aa_list_posts, aa_list_campaigns, aa_create_campaign, aa_queue_preview, aa_get_guides). The default behavior (no profileId) targets the user's primary profile.

Move a connected social account to another pen-name profile. Pass the account's ID (from aa_list_accounts) and the destination profile's ID (from aa_list_profiles). The account must belong to the current pen name (pass profileId if it lives under a non-primary pen name) and the destination must be a pen name the user can access. Fails with a 409 conflict if the destination pen name already has an account connected on the same platform — each pen name can hold one account per platform; relay that message to the user as-is.

Rename a persona in-place. Both from_tag and to_tag are required. The persona's is_default flag and all four guide texts travel with the rename — fallback lookups continue to resolve correctly. Returns 404 if from_tag doesn't exist on this pen name; 409 if to_tag already exists (each persona name must be unique per pen name).

Replace the Facebook Page attachment set for the active pen name. pageIds from aa_list_facebook_pages. Pass [] to detach all pages.

Change which Facebook Page a connected Facebook account publishes to. Call aa_list_facebook_pages first to get valid pageIds.

Switch a connected LinkedIn account between posting as the personal profile or as an organization (Company Page). accountType 'organization' requires selectedOrganization (from aa_list_linkedin_organizations).

Rename a connected social account (username and/or display name — whatever the platform allows to be changed via API). To move an account to a different pen name, use aa_move_account instead.

Rename an account group and/or replace its member accountIds (the array you pass REPLACES the membership — send the full desired set). Only the fields you pass change. Pass profileId for a non-primary pen name.

Configure the shared Pollinations account and AI defaults. The key is encrypted and synchronized with StorytellerOS. Omit pollinationsKey to retain it or pass null to clear it.

Upsert one or more guide texts under a persona tag. Use to: - Edit an existing guide for a persona (read with aa_get_guides → modify → write back). - Create a new persona by writing initial guide content under a never-before-seen tag. Body is { tag?, prose_guide?, brand_guide?, copywriting_guide?, social_media_guide?, image_style_prompt? } with at least one guide field. Omitting `tag` targets the user's default persona. image_style_prompt is the persona's IMAGE STYLE GUIDE — the visual brand-look document that grounds every AI image for campaigns using this persona (it gets distilled into a short style capsule at generation time). There is deliberately NO account-level image style doc. Empty string clears that field (stored as NULL). When the persona is brand new AND it's the user's first persona on the pen name, the server marks it as the default automatically. Subsequent personas don't change the default. EDITING UX HINT: read the current guide with aa_get_guides, show the user a SHORT diff (what's changing), confirm, THEN write. Don't silently rewrite hundreds of lines.

Archive a post — snapshots it into archived_posts (recoverable history) and removes it from the active calendar. For published posts, best-effort calls unpublishPost first (Instagram and TikTok stay live publicly even after archive — surface that caveat to the user). Use when the user says 'archive that post' / 'move this off my calendar' / 'soft-delete'. Pass profileId for posts on a non-primary pen name.

Bulk operate on multiple scheduled posts in one call. Three actions: 'delete' (archives + removes from platform — snapshots into archived_posts first, best-effort unpublish for already-published), 'retry' (re-queues failed posts), or 'reschedule' (moves all listed posts to a new scheduledFor time). Cap of 200 deliveryIds per request. Returns per-row { id, ok, error?, status? } so partial failures are visible — the call always returns 200 with a summary, never aborts the whole batch on one bad row.

Bookmark a tweet via a connected Twitter/X account.

Check a list of hashtags for Instagram restrictions (banned, shadowbanned, or otherwise flagged) before using them in a post.

Create a calendar note. scheduledFor (ISO datetime) is required; title / body / color (hex like #1f6feb) are optional.

Create a new post label. Both name (1–60 chars) and color (hex like #1f6feb) are required.

Create and schedule a social media post. Use accountIds from aa_list_accounts. Set publishNow:true to post immediately, or scheduledAt for a specific time. ═══ PER-PLATFORM OPTIONS — TWO LAYERS ═══ 1) TYPED options (instagramOptions, tiktokOptions, threadsOptions, etc). Validated locally → fast 422 with a clear suggestion when something's off. 2) RAW platformOptions: { instagram: {...}, threads: {...}, twitter: {...}, ... }. Forwarded directly to the upstream platformSpecificData payload. Use this for anything not in the typed list, OR for platforms we haven't typed yet (twitter, bluesky, telegram, snapchat, googlebusiness, discord, whatsapp). Typed options take precedence; raw fills the rest. Both merge per platform. ═══ INSTAGRAM ═══ Aspect ratios: Feed = 0.75:1 to 1.91:1 (use 1080×1080, 1080×1350, or 1080×566). Stories/Reels = 9:16 single media only (use 1080×1920). If user has 4 vertical (9:16) images for IG, post 4 separate Stories — NOT one carousel. Carousels: up to 10 items, all same media type (no mixing image+video). instagramOptions: contentType: 'story' | 'reel' — omit for Feed (default) coverImage: URL of a 9:16 image — Reel cover coverFromTimestamp: ms into video — Reel cover from a video frame trialParams: { graduationStrategy: 'MANUAL' | 'SS_PERFORMANCE' } — Trial Reel: shown to non-followers first shareToFeed, collaborators, firstComment, audioName, userTags ═══ TIKTOK ═══ tiktokOptions: draft (save to TikTok Inbox to review before publish), privacyLevel (PUBLIC_TO_EVERYONE | MUTUAL_FOLLOW_FRIENDS | FOLLOWER_OF_CREATOR | SELF_ONLY), allowComment, allowDuet, allowStitch (videos only), autoAddMusic (TikTok adds trending music to photo carousels), videoCoverTimestampMs / videoCoverImageUrl, photoCoverIndex, commercialContentType: 'none' | 'brand_organic' | 'brand_content' — when set to anything other than 'none', TikTok REQUIRES the paired flag: brand_organic → isBrandOrganicPost=true; brand_content → brandPartnerPromote=true. Forgetting the pair rejects the post. contentPreviewConfirmed + expressConsentGiven — TikTok policy attestations. Default both to true for any non-draft publish; the user agreed by submitting via the tool. videoMadeWithAi — AI-generated content disclosure (REQUIRED if the video is AI-generated or significantly AI-edited). description — long-form caption for photo carousels (up to 4000 chars; separate from the main caption). ASK THE USER: if they're posting AI-generated video → set videoMadeWithAi=true. If the post promotes a brand or is a paid partnership → set commercialContentType. If they want to review before publishing → draft=true. ═══ THREADS ═══ threadsOptions.topicTag (1–50 chars, NO '.' or '&'). Use platformOptions.threads.threadItems for chains. ═══ YOUTUBE ═══ youtubeOptions.title is REQUIRED for video posts. visibility, madeForKids, containsSyntheticMedia, firstComment, categoryId, playlistId. ═══ REDDIT ═══ redditOptions.subreddit + title both REQUIRED. url, forceSelf, flairId, nsfw, spoiler, nativeVideo (upload to Reddit's video player; default true), videogif (post video as a looping GIF), videoPosterUrl (thumbnail URL for the native video). ═══ FACEBOOK ═══ facebookOptions: contentType ('story' | 'reel'; omit for Feed default), title (Reel title, only honored when contentType=reel), firstComment (Feed-post only; auto-posted as comment 1 below the post). On Pages Meta has limited, it still counts as one of the 2 free link posts a month. draft (true → stages the post as an unpublished draft in Facebook Publishing Tools; expires in ~30 days). ASK THE USER: if they want to review or get sign-off before publishing → draft=true. ═══ LINKEDIN ═══ linkedinOptions: firstComment (LinkedIn DOWN-RANKS posts with external links by 40-50% — put URLs in the first comment, NOT the main caption), disableLinkPreview (suppresses LinkedIn's auto-generated URL card), documentTitle (REQUIRED when posting a PDF/document — headline above the preview). ═══ TWITTER / X ═══ Use platformOptions.twitter for threadItems / poll / replyToTweetId (mutually exclusive with replySettings). replySettings: 'following' | 'mentionedUsers' | 'subscribers' | 'verified' — restricts who can reply. longVideo: true → upload up to ~10 min via amplify_video (requires X Premium + API allowlisting). ═══ PINTEREST ═══ Use platformOptions.pinterest: link (destination URL for each pin), boardId, title, coverImageUrl, coverImageKeyFrameTime. ASK: what URL should the pin send clicks to? (often a book sales link) ═══ EVERYTHING ELSE ═══ Use raw platformOptions: bluesky, telegram, snapchat, googlebusiness, discord, whatsapp. Field names match the platform's verbatim docs. Discord: tts (text-to-speech), webhookUsername (display name override, max 80 chars), webhookAvatarUrl, crosspost (publish to following servers — announcement channels only). Pass width/height on each image mediaItem when known — server skips a probe-fetch and validates IG faster. tags: root-level array of YouTube video tags (≤500 chars total including commas). The network puts this at the post ROOT, not inside youtubeOptions.

Permanently delete an archived post snapshot. No undo — this removes the row from archived_posts entirely. Use only when the user explicitly confirms they want to throw away the history (e.g. 'delete that archive permanently' / 'clear out my archive'). For normal soft-delete from the calendar, use aa_archive_post instead. The id is the archived_posts row id from aa_list_archived_posts. Pass profileId for a non-primary pen name.

Delete a calendar note.

Delete a label. Removes the label from any posts it was attached to.

Delete a SCHEDULED post. Already-published posts cannot be deleted via the API — they're already live on the platform. If the user asks to delete a published post, tell them the post is already live and they need to delete it on the platform itself (Facebook, Instagram, etc.) — there's no in-app shortcut. For scheduled posts, this tool removes them cleanly so they don't publish. Pass profileId for posts on a non-primary pen name (same id you used when creating it) — otherwise the server scopes to the primary profile and returns 404.

Duplicate a post: creates an unscheduled draft copy of an existing scheduled or published post, so the user can change it and then schedule or post it. The copy keeps the caption exactly as written, the media, each account's own caption and media, and every platform option (Pinterest board, Instagram trial reel, privacy, first comment, alt text); it does not copy the schedule, published links, results, labels or campaign membership. It never publishes or schedules anything and never changes the original. Each call makes another draft, so call it once per copy the user asks for. Every account on the original must belong to the pen name; a 422 ACCOUNTS_UNAVAILABLE means one is no longer connected (the user reconnects it at /dashboard/accounts). To schedule the draft afterwards use aa_update_post with the new post id. Pass profileId if the post belongs to a non-primary pen name.

Search the user's books and ingested RSS items for content to repurpose into posts. source: 'books' | 'feeds' | 'all' (default all). q is a substring filter.

Follow a Twitter/X user via a connected account. targetUserId is the target's NUMERIC Twitter user id (not @handle). Protected accounts return pending_follow:true instead of an immediate follow.

Fetch one archived post snapshot by id. The id here is the archived_posts row id (returned by aa_list_archived_posts as _id), NOT the original post id. Use when the user references a specific archived post and you need its full content/media/platforms before deciding whether to restore or permanently delete. Pass profileId for a non-primary pen name.

List posts that the reconciler flagged as 'deleted on the platform' — rows AA knew about that disappeared from the upstream network. Use to explain to the user that posts they're looking for were removed elsewhere (deleted directly on Facebook/Instagram/etc.), or to surface a conflict banner when STOS calendar / dashboard renders. Read-only; resolution (dismiss/restore) happens in the dashboard UI.

Get the labels attached to one post. postId from aa_list_posts.

Per-platform publish-attempt history for one post — why it failed, retries, HTTP status, timestamps. Use when a post shows failed/partial status and the user asks why. Every row that carries an error also carries `explanation` with `kind` (policy_link, policy, disconnect, rate_limit, media, content, capacity, provider, unknown), `headline` (one sentence naming what happened), `detail`, `fix` (what the author does next) and `retryable`. Read the explanation rather than the raw provider string, and tell the user the `fix`. `explanation.retryable` false means aa_retry_post cannot help until the author changes something.

Day-by-day engagement (impressions, reach, likes, comments, shares, saves, clicks, views) for ONE post across its platform legs. postId is an upstream post id (from aa_list_posts). Optional fromDate/toDate (YYYY-MM-DD). If it returns ANALYTICS_ADDON_REQUIRED, analytics isn't switched on for this account yet: say so and point the user to support; never suggest buying anything.

Fetch a subreddit's feed (or the connected account's home feed if subreddit is omitted) via a connected Reddit account.

TikTok creator settings (privacy-level options, duet/stitch/comment defaults, max video duration). Fetch before TikTok posting so you can pick a valid privacyLevel for aa_create_post. Optional mediaType (video|photo).

Fetch a timestamped transcript for a public YouTube video — useful for summarizing or repurposing video content into other posts.

List archived post snapshots for the active pen name, newest first. Archived posts were soft-deleted via aa_archive_post (or the dashboard's archive action) — they're recoverable history, not live posts. Use when the user asks 'what did I archive' / 'show me my archive' / 'find that post I deleted last week', or before calling aa_restore_archived_post so the user can pick which one to bring back. Optional campaignId filter. Pass profileId for a non-primary pen name.

List the user's calendar notes — non-publishing annotations (campaign milestones, launch reminders, content themes) that appear on the calendar view. Optional from / to (ISO datetime) window filter.

List the user's post labels (color-coded tags they attach to posts for organization / filtering). Returns [{ id, name, color }]. Results are paginated (50 per page); the response includes a `pagination` object ({ page, limit, total, pages }). If `total` exceeds the labels returned, page through with page=2, page=3, … before concluding a named label doesn't exist.

List the user's posts with optional filters. Two read sources: 'mirror' (DEFAULT — local 15-min-synced snapshot, fast, matches what the dashboard shows, survives upstream outages) and 'live' (read-through to the network, always current, costs an upstream API call). Use mirror for general 'what's my week look like?' / 'show me scheduled Threads posts' / 'what published last month?' questions — that's the conversational default. Use live ONLY when (a) the user explicitly says 'check directly' / 'are you sure?' / 'right now', (b) the user just made a change in the dashboard and wants you to see it before the next 15-min sync, or (c) the mirror response shows _oldest_synced_at older than ~1 hour (means the cron lagged). Pass profileId to scope to a specific pen name (default is primary). dateFrom/dateTo accept YYYY-MM-DD or ISO. Status filter accepts scheduled / published / failed / publishing / draft / cancelled / partial. 'partial' (some platform legs published, others failed) is an upstream rollup only — ask for it with source='live', because the mirror stores a per-leg status and never holds 'partial' itself. For a failed or partial post, follow up with aa_get_post_logs to read why.

List playlists on a connected YouTube channel. Use to find a valid playlistId for youtubeOptions.playlistId on aa_create_post.

Reconcile ONE post against the upstream network — single-post equivalent of aa_refresh_posts. Use when the user is asking about a specific post and you want to make sure your read is current before answering, or when STOS opens an edit dialog and needs fresh state. If upstream returns 404 the post is flagged as deleted-on-platform; response sets deletedOnPlatform=true so the caller can react.

Force an on-demand reconcile of the active pen name's posts from the upstream network into the local mirror. Use this BEFORE a follow-up aa_list_posts (mirror) when the user just made a change in the dashboard, says 'right now' / 'are you sure?', or reports that something looks stale. The mirror normally syncs every 15 min; this triggers a fresh pull immediately. Cost: one upstream listPosts call, ~1-2s. Returns { success, upserted, markedDeleted, syncedAt }.

Remove a bookmarked tweet via a connected Twitter/X account.

Resolve a LinkedIn person or organization profile URL into the URN + ready-to-use mention format for embedding an @mention in a LinkedIn post. displayName is required to get a clickable person mention.

Restore an archived post — recreates it as a DRAFT (publishNow=false, no scheduledFor) so the user can edit and reschedule before it goes live. On success the snapshot is deleted from the archive so it doesn't appear in both places. Returns the NEW post id (different from the original — the original was removed when it was archived). Includes a cross-tenant defense: if any account id on the snapshot no longer belongs to this pen name (disconnected/reconnected since archive), the restore fails with a 403 instructing the user to reconnect. The id is the archived_posts row id from aa_list_archived_posts. Pass profileId for a non-primary pen name.

Retry a failed post. Use after the user fixes whatever caused the failure (e.g. reconnected the account, took the link out of the caption, changed an image that violated platform specs). The post must already exist in AA — this re-queues it for publish rather than creating a new post. A 409 with `reason`, `fix` and `kind` means the cause is still present right now, checked against the post as it stands: `kind` policy_link means a non-Meta link is still in the caption or the Facebook first comment (edit the post with aa_update_post to take it out), and `kind` disconnect means the account is still unhealthy (the user reconnects it at /dashboard/accounts). Change that one thing, then retry; retrying unchanged returns the same 409. Any other failure goes through to the publisher, so a media or caption failure the user has already edited is worth one retry. Pass profileId if the post belongs to a non-primary pen name.

Retweet a tweet via a connected Twitter/X account.

Search Reddit posts via a connected Reddit account's read access. Optionally scope to one subreddit. Useful for finding content to react to, or research before composing a post.

Set the default Pinterest board a connected account posts to when no boardId is specified on a post.

Set the default subreddit a connected Reddit account posts to when no subreddit is specified.

Replace the labels attached to a post. labelIds must come from aa_list_labels — ids from other pen names are silently dropped. Pass [] to clear all labels.

Shorten a URL through the user's connected link shortener — for tracked links inside captions (book sales pages, signup forms). Returns { shortUrl, linkId, domain }. Optional note, tags, and customSlug. If the user hasn't connected a shortener the call returns a 501 explaining how to set it up — relay that, don't retry. Pass profileId for a non-primary pen name.

Undo a previous retweet via a connected Twitter/X account.

Unfollow a Twitter/X user via a connected account. targetUserId is the target's NUMERIC Twitter user id (not @handle).

Unpublish a post that has already gone live — removes it from the platform while keeping the AA record. Instagram and TikTok don't support unpublish via their APIs; for those, tell the user to delete on the platform itself. Use when the user says 'take that post down' / 'unpublish that' about a post that's already published. With no platform every published copy is unpublished and `results` reports each one. Pass platform (and accountId when the post went to several accounts on it — the call answers ambiguous_account with the choices otherwise) to take down one copy. Pass profileId for posts on a non-primary pen name.

Patch a calendar note. Provide at least one of scheduledFor / title / body / color. Pass null for title / body / color to clear that field.

Rename or recolor a label. Provide at least one of name / color.

Update a scheduled post's content or time. Pass profileId for posts that belong to a non-primary pen name (the same id you used when creating the post or campaign) — without it, the server scopes to the user's primary profile and returns 404.

Update a PUBLISHED post's platform metadata without republishing — currently YouTube only (title, description, tags, visibility on the live video). postId from aa_list_posts; platform names the leg to update; all other fields forward verbatim. When the post went to several YouTube accounts, include accountId in fields (the call answers ambiguous_account with the choices otherwise). For scheduled (not yet published) posts use aa_update_post instead. Pass profileId for a non-primary pen name.

Pre-flight a post BEFORE calling aa_create_post. Returns { ok, blockers[], warnings[] } where each entry has { rule, platform, accountLabel, severity, title, fix, message, detail } — surface the `title` + `fix` to the user as guidance, not as 'validation failed'. Catches: account-needs-reconnect / account-disabled / account-disconnected (highest priority — fix before anything else), caption-too-long per platform (Threads 500, X 280, Bluesky 300, IG 2200, etc.), carousel-over-max / carousel-under-min (IG 2-10, X 1-4, Threads 1-20), image/video aspect-ratio mismatches, image-too-large / video-too-large, video-too-long, missing required fields (YouTube title, Reddit subreddit+title), Threads topic-tag rules, empty posts, facebook-link-slot (warn: a non-Meta link in a Facebook caption or first comment spends one of the 2 organic link posts a month a Page without Meta One gets — facebook.com/help/1929252614431792; skipped for Stories and drafts), and instagram-caption-link (warn: an Instagram caption link is never tappable). Pass mediaItems' optional width/height/durationSec/sizeBytes when known so media-spec rules can run; without them only caption + count rules fire. Call proactively when (a) any platform with strict caps is in the target list, (b) media count > 1, (c) you uploaded media with known dimensions, or (d) the user reported recent connection issues.

Full pre-publish dry-run validation against the network's live Tools API — checks content + media + per-platform requirements WITHOUT scheduling anything. platforms is required: array of { platform, accountId, customContent?, platformSpecificData? } (same shape as aa_create_post's internal platforms[]). Any accountId inside platforms[] is ownership-checked. For the app's own local pre-flight checks (used internally by aa_create_post), no separate tool call is needed — that runs automatically.

Character count for a piece of text against every platform's caption limit — quick check before deciding whether to trim. Optional mediaType: "photo" (TikTok photo/carousel post) adds a tiktokPhoto block with separate results for the title (90 chars; a longer caption is shortened on send — sentAs shows the title — and the full caption goes in the description) and the description (4,000 chars; tiktokPhoto.ok is false only when this is over). Optional description measures an explicit TikTok photo description instead of the caption. Without mediaType the response is unchanged.

Check whether a subreddit accepts a given post type, requires a flair, or has other posting restrictions. Optional accountId scopes the check to a connected Reddit account.

Create a posting queue. Slots fire on the given timezone at the given days/times. Optional `platforms` scopes the queue to specific networks (multi-platform queue: the next slot fires per-platform independently). Optional `tag` scopes the queue to a specific persona under this pen name (use a value from aa_list_guide_sets). Omit `tag` for a queue shared across personas.

Delete a queue. The queueId must belong to the resolved pen name; the server rejects cross-tenant attempts. Drops the local platforms[] + persona_tag decoration too.

Resolve the NEXT open queue slot without scheduling anything — use it to tell the user exactly when 'add to queue' would publish. Three modes: platforms[] → per-platform slot resolution ({ perPlatform, unresolved }); queueId → that queue's next slot; neither → the pen name's default queue's next slot. Pass profileId for a non-primary pen name.

List the user's posting queues (queue definitions, not next-slot previews — use aa_queue_preview for that). Each queue has optional per-platform decoration (the `platforms[]` field — e.g., a queue with ["instagram", "tiktok"] populates the next IG slot AND the next TikTok slot independently when a multi-platform post is added). Each queue also has optional persona scope (the `tag` field — NULL means the queue is shared across every persona under this pen name; a tag string scopes the queue to that persona only). Personas come from the user's content guides; see aa_list_guide_sets.

Preview upcoming queue slots for a pen-name profile. Pass profileId to inspect a non-primary pen name's queue.

Update an existing queue. queueId is required; every other field is optional. Tristate semantics on the locally-owned fields: - `platforms`: omit to leave existing platforms untouched; pass [] to clear (= serves any). - `tag`: omit to leave persona scope untouched; pass null to move to shared; pass a string to set.

Create a new campaign for a pen-name profile. After creating, use aa_save_campaign_plan to add the content plan. Pass profileId to attach the campaign to a non-primary pen name. Pass guideTag to use a specific persona for this campaign's AI generations — call aa_list_guide_sets first if the user mentioned a series, sub-brand, or specific voice. Omitting guideTag uses the user's default persona. The choice persists on the campaign row so regenerations stay on the same voice.

Write (or rewrite) the captions for a campaign's posts, keyed by post id then platform, using the campaign's themes, the images' visual direction, the pen name's guides and the book. Fills only posts that have no captions unless overwrite is true. Use after a plan exists and the look is approved. Runs in the background: waits up to ~90 s by default (wait: false answers at once; call again to read progress). Returns { status: generating|ready|failed, written, total, error } — written counts posts whose captions are complete for every platform. A partial finish may also carry code: captions_incomplete or captions_write_failed and missing[], the post/platform pairs still needing captions. Pass profileId for a non-primary pen name.

Paint the campaign's ONE look-check sample image before any plan exists: built from the batch's working look (image_style_capsule), the book (title, synopsis, genre; the cover for product_mockups) and the head of the source material. No text model runs. This is the first thing to do after aa_create_campaign; approve the look by setting look_locked_at via aa_update_campaign, then generate the plan and the media. Waits up to ~90 s for the image by default (wait: false returns at once; call again to read the state). Returns { status: generating|ready|failed, url, prompt, error }. Pass profileId for a non-primary pen name.

List campaign posts that are still unscheduled — draft / ready / failed campaign posts joined to their parent campaign. Use to resume an unfinished campaign ('you have 6 unscheduled posts in Launch Week — want me to schedule them?') before creating a new one. Pass profileId for a non-primary pen name.

List the user's campaigns. Pass profileId to scope to a non-primary pen name. Results are paginated (50 per page); the response includes a `pagination` object ({ page, limit, total, pages }). If `total` exceeds the number of campaigns returned, request the next page with page=2, page=3, … before concluding a named campaign doesn't exist.

Save the content plan to a campaign. Each plan item should have index, theme, captions per platform, imagePrompt, contentType. index is 1-based (first post = 1); the server renumbers every item to its array position 1..N and returns the saved plan, so read item numbers from the response. Pass profileId for campaigns on a non-primary pen name (same id you used in aa_create_campaign) — without it, the server scopes to the user's primary profile and returns 404 'Campaign not found'.

Schedule all the campaign's ready posts. Timing is governed entirely by the user's per-platform queues (each platform's queue decides its own cadence) — there is no campaign-level start date or per-post time. Pass profileId for campaigns on a non-primary pen name (same id you used in aa_create_campaign) — without it, the server scopes to the primary profile and returns 404. Pass queueMap ({ platform: queueId }) to pick each platform's queue; when it's omitted and the pen name has more than one queue that posts to every platform, the call fails with AMBIGUOUS_QUEUE (listing queueIds) rather than guessing — retry with queueMap. The response includes warnings[] (day = post number, platform, accountId, rule, title, message, fix): non-blocking notes on posts that were scheduled, e.g. a link in a Facebook first comment using one of the Page's monthly link slots. Relay them to the user.

Update fields on an existing campaign (name, objective, platforms, media_kind, objective_kind, variety, carousel settings incl. carousel_recipes + carousel_image_strategy, book reference selection via reference_doc_ids, guide_tag persona, reference_text). reference_doc_ids: null = use the book's WHOLE reference library (default — future uploads ride along), [] = none, else the explicit doc-id list from aa_list_book_reference_docs. Pass profileId for campaigns on a non-primary pen name.

Save a labeled reference document to a book's library. Pass the TEXT directly (no file upload) — e.g. paste the user's best quotes, a scene excerpt, or character sketches. kind controls HOW generation uses it: 'quotes' are used VERBATIM in captions/slide text and outrank invention; 'scenes' ground image prompts; 'characters' keep names/traits accurate; 'world' drives settings + atmosphere; 'voice' is absorbed into caption voice but never quoted; 'other' is supporting context.

Bulk operate on multiple Media Studio assets in one call. Five actions: 'delete' (removes the assets, cleans up any ad carousels that referenced them, and reaps the underlying storage object once nothing else references it), 'move_folder' (files them into folderId, or unfiles them when folderId is null), 'add_tags' (merges tags onto each asset's existing list), 'remove_tags' (removes exact-case matching tags), 'set_tags' (replaces each asset's tag list outright). Cap of 200 assetIds per request. Returns per-row { id, ok, error?, status? } so partial failures are visible — the call always returns 200 with a summary, never aborts the whole batch on one bad row. Use aa_transfer_studio_assets to copy or move assets to a different pen name. Pass profileId for a non-primary pen name.

Switch a campaign post back to publishing as a slide deck, discarding the video and cancelling any build still running. Returns { job: null, video: null, postStatus, finishJob } — the post re-finishes its slides in the background. This is also the way to cancel a build you no longer want before starting a different one. Pass profileId for campaigns on a non-primary pen name (same id you used in aa_create_campaign) — without it, the server scopes to the primary profile and returns 404.

Turn one carousel campaign post into a single video (each slide held for a few seconds, optional generated background music) instead of a slide deck. Returns immediately with { job, video } — the build runs server-side, so poll aa_carousel_video_status until job.status is completed or failed. The post must be a carousel post on a campaign with at least one platform selected and 2–20 finished slides, or you get a 422 explaining which condition failed. Only one build per post at a time: a second start while one is running returns 409 — use aa_carousel_video_clear to cancel. Pass profileId for campaigns on a non-primary pen name (same id you used in aa_create_campaign) — without it, the server scopes to the primary profile and returns 404.

Check the carousel-to-video build for one campaign post. Returns { job, video, pending, options, postStatus, finishJob, error } — job.status is queued | running | completed | failed with a stage label and progress percent, and video carries the finished preview URL once it's ready. Poll every 5 seconds at most, and stop at completed or failed — each MCP call counts 2 against the 2,000/hour limit. A build that died mid-flight is reported as failed here rather than hanging. Pass profileId for campaigns on a non-primary pen name (same id you used in aa_create_campaign) — without it, the server scopes to the primary profile and returns 404.

Check the progress of media generation for a campaign. Pass profileId for campaigns on a non-primary pen name (same id you used in aa_create_campaign) — without it, the server scopes to the primary profile and returns 404.

Create a folder in the pen name's shared Media Studio library. Pass profileId for a non-primary pen name.

Remove one document from a book's reference library (ids from aa_list_book_reference_docs). Campaigns using the default 'whole library' selection simply stop receiving it.

Delete a Media Studio folder. Assets remain in the library and become unfiled. Pass profileId for a non-primary pen name.

Delete one Media Studio asset from the library (does not touch posts that already used its URL). id from aa_list_studio_assets. Pass profileId for a non-primary pen name.

Download a public post's media (video/images) from another creator's post via the network's Tools API — useful for repurposing/reacting to content. platform is the SOURCE platform of the url (not your posting account).

Replace the media (and optionally caption / scheduledAt) on a SCHEDULED or DRAFT post. Under the hood: deletes the original upstream post and creates a new one with the updated payload, because the upstream update path can't swap media on a scheduled container. Returns the NEW post id (different from the original) — route navigation / future updates must use the new id. Published posts cannot be edited this way; tell the user to delete on the platform and create fresh. mediaItems is required (this tool exists to change media).

Kick off image/video generation for a campaign's posts. Poll aa_check_media_status until done. Returns { status: 'started', total } — or { status: 'skipped', reason, message } when there is nothing to do (every post already has its media, or none is eligible), which is a normal answer, not a failure. Pass postIds to (re)generate specific posts — an explicit postIds list processes those posts regardless of status, so regenerating an already-READY post works. Narrow further with slideIndices (0-based slide numbers on a per_slide carousel — regenerate just slide 2 and 5 instead of the whole deck) and retryMissing (fill only the slots a partial run left empty, leaving everything already generated untouched). Both apply to EVERY post the run touches, so pair either one with postIds scoping the single post you mean — that is what the dashboard does. Generated images are normalized to their exact requested dimensions (cover-cropped) so no model's native size ever fails platform validation. Pass profileId for campaigns on a non-primary pen name (same id you used in aa_create_campaign) — without it, the server scopes to the primary profile and returns 404. Provider defaults from Settings are preferences only — pass imageProvider: 'pollinations' to use the included 12-images/day tier (no API key needed) or any provider the user has a key for.

Register an already-uploaded file in the Media Studio library so it sits beside generations and can be offered as a reference image or video start frame. url must be a file uploaded via aa_upload_media (this app's own storage — arbitrary external hosts are rejected). Image or video only. Pass profileId for a non-primary pen name.

List a book's reference library — labeled supplemental documents (quotes, scenes, character sketches, world notes, voice samples) saved to the book and reused by campaign generation to ground captions and image prompts. Find book ids with aa_find_content (source: 'books'). Campaigns attached to the book use the WHOLE library by default; scope a campaign with aa_update_campaign's reference_doc_ids.

List folders in the pen name's shared Media Studio library. Folder ids can be passed to aa_update_studio_asset. Pass profileId for a non-primary pen name.

List the pen name's Media Studio library — generations AND imported uploads, newest first, 120 per page; pass nextCursor from the previous result to page. Each row has status (generating / completed / failed), storage URL, prompt, and dimensions. Filter with folderId ('none' lists unfiled), tag (exact match), type, q (search prompt/reference name), references (saved references only), provider. Also returns the included-images allowance ({ used, limit } for today — counted per USER across all their pen names). Pass profileId for a non-primary pen name.

List the tags in use on the pen name's Media Studio library with usage counts, most-used first — use for autocomplete before aa_update_studio_asset or aa_batch_studio_assets. Pass profileId for a non-primary pen name.

Mark or unmark a Media Studio asset as a saved REFERENCE — named references are offered as style anchors (referenceUrls) in future generations. id from aa_list_studio_assets; name labels the reference (max 60 chars). Pass profileId for a non-primary pen name.

Generate standalone media in the Media Studio — images, video, or audio NOT tied to a campaign (for that use aa_generate_media). The result lands in the shared media library (aa_list_studio_assets) and can be used in any post. Images: pick platform size keys (instagram_feed, instagram_story, tiktok, facebook_feed, linkedin, twitter, pinterest, youtube_thumb, bluesky, threads, googlebusiness, reddit, telegram, snapchat, whatsapp), count 1–4 per size, optional referenceUrls (up to 3 library/rehosted image URLs to steer style). Images can run on the INCLUDED tier — 12 generations/day — when no image-provider key is on file. Video/audio are USER-KEY-ONLY (per-second pricing; no included tier): duration, aspectRatio, startImageUrl (opening frame), voice + voiceoverScript (spoken verbatim and muxed). enhance (default true) runs the creative-director prompt rewrite. Pass profileId for a non-primary pen name.

Copy or move assets between the user's pen names. Copy leaves two independent assets (tags travel; folder resets to targetFolderId or unfiled); move re-homes the asset and removes it from the source pen name's carousels. Assets synced from StorytellerOS can be copied, not moved. Both pen names must be accessible to this credential. Get ids from aa_list_profiles and aa_list_studio_assets. Pass profileId for a non-primary pen name.

Update a Media Studio asset's organization metadata. tags replaces the complete tag list; folderId moves the asset to a folder, and null removes it from its folder. Use aa_list_studio_assets and aa_list_media_folders for ids. Pass profileId for a non-primary pen name.

Get a signed URL for uploading media to durable storage. Three-step pattern: 1) Call this tool → returns { uploadUrl, publicUrl }. 2) PUT the file bytes to uploadUrl. YOU do this step. 3) Use publicUrl in a post's mediaItems. publicUrl is PERMANENT — it never expires. Upload each file ONCE, then reuse its publicUrl freely. If a LATER step fails (e.g. aa_create_post errors), retry only that step with the SAME publicUrl — do NOT re-upload the media. Re-uploading on every retry wastes time and tokens and fixes nothing. If step 2 fails with a network error, the user's environment is blocking outbound traffic to storage. In Claude Cowork: Settings → Capabilities → Allow Network Egress should be ON, set to 'All Domains'.

Check a media URL's dimensions/codec/size against a platform's requirements before posting. platform and contentType are optional hints.

Fetch a single activity-log entry by id (from aa_list_activity_logs).

Cross-platform post analytics for a pen-name profile (impressions, reach, engagement, etc., per post). Optional fromDate / toDate (YYYY-MM-DD or ISO), platform, accountId filters. Start here for any 'how did my posts perform?' question; drill down with aa_get_daily_metrics or aa_get_facebook_page_insights if needed. If it returns ANALYTICS_ADDON_REQUIRED, analytics isn't switched on for this account yet: say so and point the user to support; never suggest buying anything.

Recommended posting times derived from historical engagement. Optional platform narrows the recommendation to one network. Useful when the user asks 'when should I post?' or wants to seed a queue.

Content-decay analysis — how quickly the pen name's posts stop earning engagement after publishing, useful for deciding repost/recycle cadence. Optional accountId narrows to one connected account; other upstream filter params via `extra`. Pass profileId for a non-primary pen name. If it returns ANALYTICS_ADDON_REQUIRED, analytics isn't switched on for this account yet: say so and point the user to support; never suggest buying anything.

Daily time-series metrics across platforms — useful for charting follower / engagement growth. Same optional filters as aa_get_analytics.

Facebook Page-level insights (page reach, impressions, engaged users, fan adds, etc.) for ONE Facebook account. accountId is required (connected social account id). Optional since / until (Unix seconds or ISO) and metricType narrow the window. For per-post analytics use aa_get_analytics instead.

Follower counts and growth across the pen name's connected accounts. Optional accountId narrows to one account; other upstream filter params can be forwarded via `extra`. Pass profileId for a non-primary pen name. If it returns ANALYTICS_ADDON_REQUIRED, analytics isn't switched on for this account yet: say so and point the user to support; never suggest buying anything.

Instagram account-level reach/views/engagement insights for a connected account. Optional metrics (comma list), metricType (total_value|time_series), breakdown, since/until. If it returns ANALYTICS_ADDON_REQUIRED, analytics isn't switched on for this account yet: say so and point the user to support; never suggest buying anything.

Instagram follower demographics (age / gender / location split) for a connected Instagram account. accountId required (from aa_list_accounts). Optional upstream params (breakdown, timeframe, …) via `extra`. Complements aa_get_instagram_account_insights, which covers reach/engagement. Pass profileId for a non-primary pen name. If it returns ANALYTICS_ADDON_REQUIRED, analytics isn't switched on for this account yet: say so and point the user to support; never suggest buying anything.

LinkedIn analytics for a connected account. WITHOUT `urn`: aggregate account analytics — optional aggregation TOTAL | DAILY, startDate/endDate (YYYY-MM-DD), metrics (comma list). WITH `urn` (a LinkedIn post/share URN): that single post's analytics instead (the other filters don't apply). accountId from aa_list_accounts. Pass profileId for a non-primary pen name. If it returns ANALYTICS_ADDON_REQUIRED, analytics isn't switched on for this account yet: say so and point the user to support; never suggest buying anything.

Reactions breakdown (like/celebrate/support/etc.) for a LinkedIn organization post. urn is the LinkedIn post URN (from analytics or the post record).

Posting-frequency analysis for the pen name's connected accounts — how often posts go out per platform over time, for spotting gaps versus the intended cadence. Optional accountId narrows to one account; other upstream filter params via `extra`. Pass profileId for a non-primary pen name. If it returns ANALYTICS_ADDON_REQUIRED, analytics isn't switched on for this account yet: say so and point the user to support; never suggest buying anything.

Plan name, uploads/profiles used vs. limit, and next billing-anchor reset day. NOTE: this reflects the whole shared workspace API key, not just the active pen name — every pen name routed to the same key sees the same numbers.

Day-by-day view counts for a connected YouTube channel. accountId required. If the account is missing the yt-analytics.readonly scope, the response includes scopeStatus.reauthorizeUrl — tell the user to reconnect YouTube via that URL. Optional upstream params (startDate, endDate, …) via `extra`. Pass profileId for a non-primary pen name. If it returns ANALYTICS_ADDON_REQUIRED, analytics isn't switched on for this account yet: say so and point the user to support; never suggest buying anything.

YouTube viewer age/gender/country demographic split for a connected channel. If the account is missing the yt-analytics.readonly scope, the response includes scopeStatus.reauthorizeUrl — tell the user to reconnect YouTube via that URL. Optional breakdown, startDate, endDate. If it returns ANALYTICS_ADDON_REQUIRED, analytics isn't switched on for this account yet: say so and point the user to support; never suggest buying anything.

Unified activity log across your accounts — publishing, connections, webhooks, messaging events. Filtered to accounts you own. Optional filters: action, days, platform, search, status, type (publishing|connections|webhooks|messaging).

Archive or reactivate an inbox DM conversation thread. status 'archived' hides it from the active inbox; 'active' brings it back.

Delete a sent DM message from a conversation. Supported on Telegram, X, Bluesky, and Reddit. conversationId + messageId from aa_get_inbox_thread; accountId is the connected account that sent it. Pass profileId for a non-primary pen name.

Remove all Instagram DM ice-breaker prompts from a connected Instagram account.

Remove the Messenger persistent menu from an account.

Edit an already-sent DM message — TELEGRAM ONLY (other platforms don't allow edits). conversationId + messageId from aa_get_inbox_thread; accountId is the connected Telegram account. Pass new text and/or replyMarkup (forwarded verbatim). Pass profileId for a non-primary pen name.

Load full message history for one DM thread. conversationId is required; accountId is optional — the server auto-resolves it from the conversation when omitted. Returns the chronological message list. Pair with aa_send_inbox_message to reply.

Get the Instagram DM ice-breaker prompts (up to 4 quick-reply questions shown to new DM conversations) on a connected Instagram account.

Get the Facebook Messenger persistent menu configured for one connected account. id is the connected social account id.

Hide (or unhide) a comment on one of the user's published posts. Pass unhide=true to reverse a previous hide. postId + commentId from aa_list_inbox_comments; accountId required (owner of the post).

Like (or unlike) a comment from the inbox. Supported on Facebook, X, Bluesky, Reddit (where it upvotes), and TikTok. postId + commentId from aa_list_inbox_comments; accountId is the connected account acting. Bluesky quirks: pass the comment's `cid` when liking, and pass `likeUri` (returned by the like) when unliking. Set unlike:true to remove the like. Pass profileId for a non-primary pen name.

List comments on published posts across connected accounts (e.g., people commenting on your Instagram, Facebook or TikTok posts). Optional accountId / platform filters. Use aa_reply_inbox_comment, aa_hide_comment, aa_like_inbox_comment or aa_pin_inbox_comment (TikTok) to act on entries.

List DM / messaging conversations across connected accounts. Optional accountId scopes to one social account; optional platform filters by network (instagram, facebook, tiktok, telegram, whatsapp, etc.). TikTok DMs are reply-only (the business can never open a conversation) and need an account connected through TikTok for Business. Returns conversation summaries (id, participants, latest message, unread count) — use aa_get_inbox_thread to load full message history.

List incoming reviews / ratings on connected accounts (e.g., Facebook Page reviews, Google Business reviews). Optional accountId scopes to one account. Pair with aa_reply_inbox_review to respond.

Pin (or unpin) a top-level comment to the top of a post's comment thread. TikTok only today. postId is the TikTok video id and commentId comes from aa_list_inbox_comments; accountId is the connected TikTok account. Pass unpin=true to remove the pin. Pass profileId for a non-primary pen name.

Reply to a PUBLIC comment with a PRIVATE DM (Facebook / Instagram only — TikTok has no private reply; reply publicly or pin instead) — the classic 'comment X and I'll DM you' move. One private reply per comment, within 7 days of the comment, text message required. postId + commentId from aa_list_inbox_comments; accountId is the account sending the DM. Optional rich-reply fields (buttons, quickReplies, template, messageTag) forward verbatim. Pass profileId for a non-primary pen name.

Add (or remove) an emoji reaction on a DM message — Telegram and WhatsApp. conversationId + messageId from aa_get_inbox_thread; accountId is the connected account reacting; emoji is the literal emoji character. Set remove:true to clear the reaction. Pass profileId for a non-primary pen name.

Reply to a comment on one of the user's published posts. postId + commentId from aa_list_inbox_comments; accountId is the social account that owns the post.

Reply to a review left on the user's account. id from aa_list_inbox_reviews; accountId is the social account that received the review.

Send a reply in a DM conversation. Body is forwarded to the upstream messaging API so optional rich-reply fields (buttons, quickReplies, template, messageTag) pass straight through on Meta platforms. TikTok: reply-only, up to 10 messages within 48 hours of the user's last message, text up to 6,000 characters OR one JPG/PNG image (never both); Meta rich-reply fields are dropped. accountId required (the social account that owns the conversation).

Set the Instagram DM ice-breaker prompts on a connected Instagram account. Max 4 entries, each { question (≤80 chars), payload }.

Set / replace the Messenger persistent menu for one account. Body forwarded verbatim to upstream (menu items, locales, composer-input-disabled, etc.).

Activate or pause an inbox automation flow. active = the flow triggers on live comment/DM events; paused = it stops (parked delayed runs are skipped when they come due). Activation validates the graph first.

Activate a draft or paused sequence — enrolled contacts start/resume moving through its steps.

Create a comment-automation rule (comment or Instagram story-reply keyword → automatic DM). accountId + name + dmMessage required. Omit platformPostId to watch EVERY post/story on the account. Supports word/contains/exact matching with typoTolerance and excludeKeywords, DM buttons (1-3) or a generic template card carousel, audience targeting with follow gates, message variations, link tracking, and delivery delays.

Create an inbox automation flow (free on every plan). Flows start as drafts unless status is set; activate with aa_activate_flow once the graph is right. Example: trigger { kind: 'comment_keyword', keywords: ['guide'] } with a graph replying to the comment then sending a private reply. Any step whose namespace the workspace key doesn't support is skipped at run time with a log entry — no need to pre-check.

Create a new RSS feed subscription. url is required and must be a valid absolute URL. Optional: title (display label), accountIds (which social accounts get drafts), postTemplate (caption template with placeholders), schedule (cron-like or interval), autoPost (true → publish automatically, false/omitted → leave as draft), enabled.

Create a multi-step drip sequence (accountId, platform, name, steps[] required). Each step: { order, delayMinutes, message: {text} OR template: {name, language, variableMapping?} }. delayMinutes counts from enrollment for step 1, or from the previous step for later steps. template is WhatsApp-only; variableMapping keys are positional strings ('1','2',...) mapping to { field: 'name'|'phone'|'email'|'company'|'custom', customValue? (required when field is 'custom') }. exitOnReply / exitOnUnsubscribe default true. Activate with aa_activate_sequence once created (it starts in draft).

Delete a comment-automation rule.

Delete an RSS feed subscription.

Delete a sequence — stops all active enrollments. No undo.

Duplicate an inbox automation flow into a new DRAFT named 'Copy of <name>' on the same pen name. The trigger (including any account/post restrictions), every step and the settings are copied exactly; run history and the list of people already handled are not, so once activated the copy can respond to someone the original already answered. The copy never goes live on its own — review it, then use aa_activate_flow. Returns the new flow (its id and status 'draft'). Fails if 'Copy of ' plus the name would exceed 200 characters; rename the source first. Pass profileId for a non-primary pen name.

Enroll one or more contacts into a sequence. Already-enrolled contacts (or ones with no channel matching the sequence's platform) are skipped, not errored. Returns { enrolled, skipped }.