SMAT

Use when the user asks for their connected brand's saved content pillars, positioning, content direction or plan before choosing social topics. See the brand's saved content plan, themes and topic ideas. Read the brand's saved strategy: applied direction, plan, topics and programs. Stored data only; does not generate, translate or refresh. Read-only.

smat_get_strategy

Check how an earlier job is going, such as writing a caption, creating images or publishing. Read the durable result of an earlier operation, such as caption generation, an image generation, a carousel run or a publication, by its operation id. A carousel run reports each slot separately. Read-only. currentSnapshot is complete; include ["snapshot"] also returns acceptedSnapshot from admission.

smat_get_operation

Use when the user asks which social posts worked, how their connected brand performed or what to repeat based on saved results. Do not invent metrics or treat unavailable measurements as zero. See how the brand's posts performed. Read the brand's saved performance metrics, time series, top posts and SMAT-attributed format, time-block and program stats. Stored data only. Read-only.

smat_get_insights

Use when the user asks to plan this or next week's social posts, inspect upcoming publication times, find gaps or check the connected brand's calendar. This reads the schedule; it does not schedule anything. See the brand's publishing schedule for one week: every post and story slot with its time, placementKind (feed_post or story), what is in it or that it is free, missed slots, the weekly rhythm against the rules, and the rules themselves. The week counts and rhythm count post slots only; story slots follow storySlotsPerWeek. weekOffset 0 is this week, 1 next week, -1 last week. A free future slot carries its slotId and time for smat_schedule_publish. The rules carry the revision and pendingProposal the rhythm SMAT proposed, both for smat_manage_schedule. Read-only; spends no credits. Resolve each shortcut.hintKey in the result hints dictionary; tools, args and studioUrl stay on each entry.

smat_get_schedule

Use when the user asks what to post today, what needs attention, what is unfinished or what to do next for their connected brand. See what needs the user's attention in SMAT right now, the same list as the Start page: posts waiting for a decision, topic suggestions, free schedule slots this week and next, missed slots, rhythm and schedule problems, account setup, and background jobs that are running or failed. Start here when the user asks what to do next. Every entry has a shortcut naming the existing tools and ids that resolve it, or a Studio link when only SMAT can. Read-only; spends no credits. Resolve each shortcut.hintKey in the result hints dictionary; tools, args and studioUrl stay on each entry.

smat_get_attention

Use when planning or writing social content in a connected brand's own voice, audience and visual style, or inspecting its saved Brand DNA. Do not infer a brand profile from general marketing advice. See the brand's profile: who it serves, its voice, colours, logo, fonts and connected channels. Also returns available formats and up to 5 competitor patterns already adapted to this brand (competitorPatterns; adaptationStale means the profile changed since). Before ordering an overlay, read overlay.presets, overlay.fonts and overlay.controls. Prefer brandRole primary/secondary/accent for colours (the user's brand); send hex only when the client explicitly wants a different colour. A key that covers all brands passes brand (a brandSlug from smat_list_brands) on this and every other tool. Read-only.

smat_get_brand_context

Choose which image version a post or slide uses. Make one of the generated or uploaded variants the active image of the target (a post or a carousel_slot). Selecting a sibling on a slot invalidates that slot approval; a stale sibling does not keep the new photo approved. Responses are compact by default; pass include: ["snapshot"] to receive the full snapshot.

smat_select_variant

Create a new AI photo for a post or a carousel slide in the brand's style. Order an AI image for the post, or for one carousel slide when target.kind is carousel_slot. On a single post prefer savedSceneRevision from the saved, approved scene. A directly supplied sceneDescription must exactly match that scene; otherwise save it with smat_update_post and ask for acceptance first. The scene describes what the picture shows in 7 short facets; SMAT applies the brand's visual style, presets, format and safety checks and builds the generator prompt. On a post that shows text on the image, save the overlay text with smat_apply_overlay text_only before ordering the photo; choose the look after the photo; if the user wants the photo without text, turn it off with smat_update_post textOnImage false instead. For a new or source-changed carousel slide after style/plan acceptance use mode=initial; mode=retry_failed_slot is only for a known failed slide and never rebuilds successful photos. The style master itself is smat_generate_carousel phase=style, not this tool. Needs a fresh quote from smat_estimate_action. Paid by actual usage from the brand's credits; never quote an amount before it runs (after it completes you may say what it actually used, only when the result reports it). Responses are compact by default; pass include: ["snapshot"] to receive the full snapshot.

smat_generate_image

For graphic_design slides and video_create, save the draft first and pass its contentId. Create one picture element with a transparent background (PNG with alpha) for slides or video scenes you design yourself (graphic_design or video_create guide): an object, a person, a product or a shape to layer over type, break a frame or sit on a colour field. Paid from the brand's credits: first get a quote from smat_estimate_action with actionKind element_image, the same elementDescription and aspectRatio. SMAT adds only the isolation (a single element, transparent background, no text, logos or frame); describe everything else yourself in elementDescription. The result's element.url is a PNG to download into your working folder; contentId, when supplied, is kept in the element result and generation metadata. A retry with the same clientOperationId returns the same element without a second charge. Responses are compact by default; pass include: ["snapshot"] to receive the full snapshot.

smat_generate_element

Create AI photos for a carousel: first one sample slide that sets the look, then the rest. Order AI photos for a carousel in two paid phases. First call phase=style on exactly one eligible AI master (styleSlotId), preview that slide, then accept it with smat_accept_carousel_style. Then estimate carousel_remaining and call phase=remaining, which follows that accepted master. Never send phase full, autoContinue or a variant count. Style does not start remaining. A ready upload as the master is not generated — SMAT refuses with STYLE_MASTER_IS_UPLOAD; accept that upload with smat_accept_carousel_style instead. An all-upload deck returns completed with status no_billable_slots and starts no paid run. Needs a fresh quote from smat_estimate_action for that phase. Paid by actual usage from the brand's credits; never quote an amount before it runs (after it completes you may say what it actually used, only when the result reports it). Responses are compact by default; pass include: ["snapshot"] to receive the full snapshot.

smat_generate_carousel

Delete a draft post or carousel the user no longer wants. This is permanent: the draft, its photos and its history cannot be restored. Before calling, name the post to the user, say that deleting cannot be undone, and delete only after their explicit yes to deleting that post; never delete to tidy up on your own. Only unpublished content can go: a draft, one waiting for text or photo review, or a failed generation. A cancelled or superseded schedule does not prevent deletion if the content is in one of those states and has no publish evidence. Anything currently scheduled, bound to a publication schedule, publishing, published or ready to publish is refused (STATUS_PROTECTED), as is any content with a publication, provider attempt, publish lease or earlier publishing/published/publish_failed state. A post with a job still running is refused (CONTENT_RUN_ACTIVE). expected.postRevision is the revision the user saw. If the draft held a calendar slot, the slot becomes free (freedScheduleSlot). A retry after success answers RESOURCE_NOT_FOUND because the draft is already gone. Responses are compact by default; pass include: ["snapshot"] to receive the full snapshot.

smat_delete_draft

Use to revise an existing social post draft, such as its caption, call to action or channels, within the connected brand. Use the caption workflow for new copy and show the changed text for approval. Change a post draft, for example its caption or channels. A new caption comes from smat_generate_caption with contentId by default (brand voice and post history); put your own caption here only when the user supplied it or explicitly requested assistant-authored copy without SMAT generation; a generic request to write a caption does not select this exception. Change fields of an existing draft post, guarded by the expected post revision. On a carousel only caption, topic, platforms and publishMetadata change here; slide copy, scenes and photos go through smat_update_carousel. A caption change withdraws the caption approval, so show the user the new caption and approve it again with smat_review_content. When the user decides the photo should carry no text, set textOnImage false: the photo is then used without text and AI photos no longer wait for a saved overlay. On a carousel this is chosen once, at creation: smat_create_carousel textOnImage false for finished slides. publishMetadata sets Instagram tagged people (userTags: public accounts; feed image, carousel, reel, story; x/y only on images and stories) and collaborators (max 3, never on a story); a field the format does not support is refused with PUBLISH_METADATA_UNSUPPORTED. Instagram tag checks may contact Meta and create unpublished test containers; this tool does not publish. Channels (platforms) can change until the post is published, also while it is ready or scheduled: on a scheduled post send platforms alone; the slot and time stay and the scheduled publication goes to the new channels, so do not cancel, prepare or schedule it again. On a scheduled post, change only publishMetadata userTags and/or collaborators in one smat_update_post call; the slot and time stay, with no cancel, prepare or reschedule. All other scheduled edits are refused (CONTENT_NOT_EDITABLE_IN_STATUS); cancel the schedule first. A reel or video story may target Facebook, Instagram, or both; each channel uses its matching format. A post that is publishing or published, fully or partly, cannot change. Update video shots with patch.storyboard before rebuilding; image formats refuse it with WRONG_MEDIA. Responses are compact by default; pass include: ["snapshot"] to receive the full snapshot.

smat_update_post

Change an existing image with AI, for example remove or replace an element. Order an AI edit of the post's own image from plain-language instructions or a preset; creates a new iteration on the current base while the parent stays. Say only what should change; SMAT keeps the brand style and format. Fixed corrections (no instructions): instagram_polish = overall finishing for Instagram; correct_exposure = too dark or too bright; correct_white_balance = colour cast; reduce_noise = grainy or low-light photo; gentle_color_correction = a mood-matched Instagram filter. Presets that need instructions saying what to change: change_background = new background, subject stays; change_subject = replace the main subject, scene stays; change_palette = recolour; change_mood = light and atmosphere; add_element = add something; remove_element = remove something and fill the gap. expand_frame (no instructions) = zoom out: keeps the photo, makes it smaller in the same format and extends the surroundings, e.g. to leave calm room for text; optional expandDirection around, top, bottom, left or right. SMAT cannot move the camera, change the angle or crop to a different format; do not promise that. Needs a fresh quote from smat_estimate_action with the same preset and instructions. Paid by actual usage from the brand's credits; never quote an amount before it runs (after it completes you may say what it actually used, only when the result reports it). Responses are compact by default; pass include: ["snapshot"] to receive the full snapshot.

smat_edit_image

Change one carousel slide: edit, add, move or remove it. Apply exactly one carousel change: edit_slide, insert_slide, move_slide, remove_slide or set_source. Address slides by server slotId, never by position. When a headline changes, send 1-2 highlightPhrases that match the new headline. Send expected outlineRevision and the card, source or selection pins that operation needs. Refuses growing past 10, shrinking below 2, moving or removing the required cover/CTA, mutating a protected master, or editing during an active generation or publication. Removing a slide permanently deletes its photos and their version history. Does not generate images. Caption changes go through smat_update_post. Responses are compact by default; pass include: ["snapshot"] to receive the full snapshot.

smat_update_carousel

Ask SMAT to look for new topic ideas for the brand (news, competitors and the brand's own themes), the same refresh as the Topics page. Paid by actual usage from the brand's credits: first get a quote from smat_estimate_action with actionKind topic_refresh and continue only after the user says yes. Returns refreshRunId; follow it with smat_get_topics {refreshRunId} until completed, then show the new active topics. Only one refresh runs at a time. Responses are compact by default; pass include: ["snapshot"] to receive the full snapshot.

smat_refresh_topics

Use when the user wants to find an existing social draft, reopen a carousel, inspect posts waiting for approval or find previously published content in their connected brand. List the brand's posts and carousels and the stage each one is at. Filter by query, kind or status. Posts that went out (any path: this assistant, the schedule or SMAT Studio) carry publication.channels with the post link (permalink) and platform post id per channel, or which channel failed. Read-only.

smat_find_content

Finish adding an uploaded file to the post or slide. For up to 10 carousel slots, send items with uploadId and a separate clientOperationId per item; results.items reports every outcome independently. Finish a started upload and attach the processed image to the target. A brand_logo upload is only checked (PNG or WebP, at least 200×200 px) and attached to nothing; pass its uploadId to smat_update_brand section look. A video complete is accepted (processing) with a stable assetRef (generationId null), domainRef asset_result and pollAfterMs; the same uploadId under another clientOperationId returns that asset, a different file is UPLOAD_REPLACEMENT_REFUSED. Incomplete video shots return STORYBOARD_INCOMPLETE; storyboard videos wait for explicit smat_review_content approve_media after processing. Responses are compact by default; pass include: ["snapshot"] to receive the full snapshot.

smat_complete_upload

Put together the exact version that would be published so the user can check it. Nothing is posted yet. Freeze the exact images, captions, accounts and metadata that a publication would use. Instagram tag checks may contact Meta and create unpublished test containers; safety checks may use external AI providers. This tool does not publish. For a carousel the deck must be complete: every slot has a current final, slide approval and no unknown; the shared design is approved; caption is current — otherwise DECK_INCOMPLETE with blockedPublishReasons. The sealed manifest items[] is outline order, 2–10, with finalSha256 per slot. Retry: a single post (image or video) with status publish_failed or partially_published (availableActions lists retry_publish) is prepared and published again the same way, only when the user explicitly asks; channels already published are kept and never posted twice, and an outcome_unknown channel is not re-posted. A carousel whose album failed cannot be retried here; share the Studio link. Responses are compact by default; pass include: ["snapshot"] to receive the full snapshot.

smat_prepare_publish

Use when choosing which authorized business or personal brand to work on, especially when the connection covers multiple brands. List the brands this connection can use: brandSlug, name and whether Instagram and Facebook are connected. A key for one brand lists that brand. A key for all brands of the account must pass brand (a brandSlug from this list) to every other tool. Read-only.

smat_list_brands

Open one post or carousel to see its caption, images and what still needs approval. Read one post or carousel: caption, status, assets, approvals and the pins needed for later edits. publishMetadata shows the current Instagram userTags and collaborators so edits can preserve them. Optional history returns prior caption revisions and asset versions. Optional includeEditor asks only for the saved overlay design, caption variants or scene proposals; omit it and the result stays the same. After publication (by any path) publication.channels gives per channel the state, post link (permalink; null when Meta did not return one) and platform post id; publication.results gives the stored reach, likes, comments, shares and saves per channel. Empty results right after publishing mean SMAT has not fetched the numbers from Meta yet; say so instead of reporting zero. Read-only. Exact duplicate assets and slot blockers/actions appear once; omitted slot blockers/actions inherit the content fields when slotBlockersSameAsContent/slotAvailableActionsSameAsContent is true. Saved video storyboard shots are returned in storyboard.

smat_get_content

Prepare to add a photo or video file to a post or slide. Start a single-use upload for a file the client already has; returns a signed upload address and limits. POST the file as multipart field "file" to uploadUrl exactly as given, with no Authorization header (for example curl -F file=@/path/video.mp4 "<uploadUrl>"), then call smat_complete_upload. The address works for 10 minutes and only for the declared file. For up to 10 carousel slots, send items with the same fields and a separate clientOperationId per item; results.items reports every outcome independently. Several uploads (a whole carousel or several reels) may be open at once. For a new brand logo use target {kind: brand_logo} with expected {} (PNG or WebP, up to 2 MB); complete it, then set it with smat_update_brand section look. For a carousel slide, target.kind must be carousel_slot with that slide's slotId and matching pins; user_files uploads auto-approve, assistant_design uploads wait for smat_review_carousel_slide after the user's yes. Video must already be at the media review gate: a reel needs smat_review_content submit_for_review and then approve_text; a video story reaches that gate on submit_for_review. Video uses MIME video/mp4 or video/quicktime, cap videoUploadMaxBytes (100 MiB), and at most ten open upload intents per connection. Incomplete video shots return STORYBOARD_INCOMPLETE; videos with a saved storyboard require explicit smat_review_content approve_media after processing and are never auto-approved. Responses are compact by default; pass include: ["snapshot"] to receive the full snapshot.

smat_begin_upload

Publish the prepared post to the brand's Facebook or Instagram. This makes it public. Publish the prepared package to the connected Facebook or Instagram accounts. The published post becomes publicly visible and cannot be withdrawn through this tool. For a carousel album the parent post/album ID is the only published proof; a child container success without a parent is not published. Lost Meta response is outcome_unknown with reconcile_only. No whole-deck retry. Story repost uses the frozen prepared plan. Responses are compact by default; pass include: ["snapshot"] to receive the full snapshot.

smat_publish

Put the carousel's text design onto the chosen slides. Render the one shared overlay design onto an explicit set of carousel slots (1–10 slide IDs). Copy comes from each slide's card, never from shared single-post textBlocks. Requires a current approved design (approvalRevision) — otherwise APPROVAL_REQUIRED. Pins outlineRevision, designRevision, designSourceRevision, approvalRevision and per-slot {slotId, cardRevision, base}. A global style change invalidates every dependent final and visual approval while keeping base photos. Local copy repair renders only the named slot on that pinned base. Zero image generation. Responses are compact by default; pass include: ["snapshot"] to receive the full snapshot.

smat_render_carousel_overlay

Use when the user wants to inspect a saved competitor's actual posts as evidence for topic or content decisions. Do not claim a new scrape or current market coverage. Read a saved competitor's posts: stored posts of one competitor, newest first or by engagement. Captions are truncated at 2000 characters. Does not fetch new posts or run vision. Read-only.

smat_get_competitor_posts

Open SMAT Studio to choose a brand and inspect its work alongside the conversation.

smat_open_studio

SMAT skills (umiejętności/skille SMAT): read the guide matching the current task before work, together with smat_get_brand_context; lead without waiting for hints. 'Use SMAT skills / użyj umiejętności/skilli SMAT' means read that matching guide. Only for the connected brand; clarify an unclear brand, never access personal posts or supplied-material-only requests. start: 'what next / co dalej' leads to one next step. single_post: 'make a post / zrób post, relację' prepares one post. carousel: 'carousel with photos / karuzela ze zdjęć' uses SMAT text on photos. graphic_design: 'designed, graphic, poster, cover / zaprojektowane, graficzne, plakat, okładka, bardzo graficzne karuzele' designs slides and returns guideRef, valid for 24 hours; own_design is an input alias. video: 'I have a video / mam film' posts the user's finished file. video_create: 'make a reel / zrób rolkę, film' composes a new video where code runs; proprietary guide requires a current trial or paid MCP plan (including billing grace), otherwise SUBSCRIPTION_READ_ONLY. weekly_planning: 'campaign, plan the week / kampania, zaplanuj tydzień' plans content. topics: 'ideas, what to post / pomysły, o czym pisać' finds subjects. competitors_insights: 'results, competitors / wyniki, konkurencja' inspects saved evidence. brand: 'brand profile, colours / profil marki, kolory' updates the brand. Guides give order, user decisions, paid steps and blockers: save a textual SMAT draft before images and render. Read-only, no credits.

smat_get_workflow_guide

Use to save an Instagram or Facebook carousel after the user approves its authored slide outline. First read smat_get_workflow_guide (carousel for photos with SMAT text, graphic_design for designed graphic slides) and smat_get_brand_context; this tool does not write slides or generate images. Save a new carousel draft with 2–10 slides the user approved. Create a carousel draft of 2–10 authored slides. Each slide needs a unique clientSlideRef, role (first hook/cover, last cta), card copy stored verbatim (emoji, hashtags and quotes stay; only length, schema and safety are checked), a 7-facet sceneDescription, and a source (upload may stay pending; ai_generate is a declaration only). Does not generate copy, images or an outline. With textOnImage false declare slidesBy: user_files for finished user files (auto-approved), assistant_design for your designs (valid graphic_design guideRef required; plan and uploaded slides wait for user approval). Save the full text and composition before elements or render. Caption is a post field, not a slide. Replay with the same clientOperationId returns the same contentId and slot mapping. Responses are compact by default; pass include: ["snapshot"] to receive the full snapshot.

smat_create_carousel

Use to save a social post after the user approves the exact caption they supplied or explicitly requested as assistant-authored copy without SMAT generation. A request to prepare a post starts with the workflow and brand context; this tool only saves an authored draft. Save a new post draft with the caption the user approved. By default SMAT writes captions with smat_generate_caption (brand voice and post history), which saves the draft itself; use this tool only for a caption the user supplied or explicitly requested as assistant-authored copy without SMAT generation; a generic request to write a caption does not select this exception. Create a new draft post from an authored caption (stored verbatim; only length and safety are checked) and an optional scene for a later image; never generates copy or images. Video formats ig_reels, fb_reels, ig_stories_video and fb_stories_video set mediaType video; sceneDescription and an AI image source are WRONG_MEDIA. A reel or video story may target Facebook, Instagram, or both; each channel uses its matching format. Before uploading a reel, call smat_review_content with submit_for_review and then approve_text. A video story moves directly to the media review gate on submit_for_review. Video drafts accept storyboard (2–20 shots), saved before building; image formats refuse it with WRONG_MEDIA. Responses are compact by default; pass include: ["snapshot"] to receive the full snapshot.

smat_create_post

Save text or the chosen text-on-image look. On a single post, mode=text_only takes textBlocks and saves the literal copy without a base image, look selection, render or look approval. Use only user-supplied words or accepted copy from the existing paid routes; this never generates copy. Accept text separately from the look. Later previews and apply_and_render default to saved copy and its design revision. Pass candidateId from this connection's smat_preview_overlay receipt (same content, base, copy and design revision) or a full configuration with the same rules as preview. mode=design_only stores the design without rendering; mode=apply_and_render saves copy and design, then queues a free deterministic render of the exact base. Overlay text is stored verbatim. Does not approve the image. Save only a look the user has seen (smat_preview_overlay or smat_get_preview) and chosen; never save it just to unlock paid photos. Approving the design is a separate user decision in smat_review_content. One shared ContentOverlayDesign per carousel; card copy stays on the slide. On carousel_slot, design_only writes that shared deck design; apply_and_render renders the named slot and marks other dependent slides stale (base photos stay). Render an explicit 1–6 slot set with smat_render_carousel_overlay. Responses are compact by default; pass include: ["snapshot"] to receive the full snapshot.

smat_apply_overlay

Schedule, move or cancel a prepared post. It is published later, at the chosen time. Schedule, move or cancel a prepared publication. Completing this command stores the timetable; it does not publish. Cron later publishes the live post. Occupied slots are refused (no displacement). A time at the exact instant of a free slot, such as the one a cancel just freed, reuses that slot. To change the channels of a scheduled post use smat_update_post with platforms; no cancel is needed. Revoking the MCP connection does not cancel an already admitted schedule — use cancel or Studio. Contacts no social network and spends no credits. Responses are compact by default; pass include: ["snapshot"] to receive the full snapshot.

smat_schedule_publish

Use when the user asks what to post about, wants relevant ideas or wants to choose from the connected brand's saved topic suggestions. This reads existing suggestions; fetching new suggestions is a separate paid action. See the topic ideas SMAT found for the brand, the same list as the Topics page in Studio: title, why it was suggested (reason, whyNow), angle, source and whether a post already uses it. Filter by status (active by default; approved, used, dismissed, expired). The refresh block says whether new ideas can be fetched now, why not, when the last refresh ran and how a started refresh is going (pass refreshRunId). Every refresh is paid by actual usage; SMAT has no free refresh. Read-only; spends no credits.

smat_get_topics

Use when the user asks to see an existing post image, carousel slide or video cover before deciding what to change or publish. This is a preview, not image generation. Show the user an image, a carousel slide or a video cover. The image for you is reduced; if you cannot read small text, call again with detail "full". Use proactively to show available media after an upload, selection, overlay or completed generation, and when the user asks to see or compare visuals. Return the image bytes of an asset, a generated candidate or a prepared publication, plus a short-lived link. The image is shown to the user in the SMAT preview card; refer to it as shown and do not repeat it as a Markdown image. Give link.url only when the user asks for the image link or cannot see the card, labelled, never as a raw URL. A preview never replaces your reply: always add at least one plain sentence saying what happened and the next step, also after several carousel previews. For a carousel slide, target.kind must be carousel_slot with that slide's slotId — this is that slot's exact base or final, never another slide's asset. For video (asset or prepared), image/link are only an existing cover and metadata, never MP4 bytes. A ready saved asset can also include playback: a short-lived authorized video stream for native controls, separate from the image path. Never return raw/processed storage keys or permanent storage URLs, transcode or a new analysis. Renders nothing new. Read-only.

smat_get_preview

Snooze or dismiss one insight from the Start page (listed in smat_get_attention insights), the same buttons as in SMAT. Snooze hides it until a time (default 24 hours), dismiss removes it for the whole team. Run only on the user's explicit decision about that insight. Spends no credits. Responses are compact by default; pass include: ["snapshot"] to receive the full snapshot.

smat_act_on_suggestion

Get 3 ideas for the post's picture based on its caption. Paid. Ask SMAT for 3 image-scene cards from the current caption, the same path Studio uses. Spends the brand's credits; first get a quote from smat_estimate_action with actionKind scene_from_brief. Each card has proposalId, label, summary and sceneDescription (7 facets). Paste the chosen sceneDescription into smat_generate_image. Does not return visualBrief, imagePromptJson or brand review. Responses are compact by default; pass include: ["snapshot"] to receive the full snapshot.

smat_generate_scene

Try the text on an image in up to 3 looks without saving anything; free. Render 1–3 overlay variants on the same base image and the same overlay copy, without saving the design. The editorial card puts the photo above the card and only works when the photo is wider than the post frame, for example 16:9 in a 4:5 post or 4:5 in a 9:16 story. If the photo fills the frame, the card looks are refused; use template classic (text on the photo). First read overlay.presets, overlay.fonts and overlay.controls from smat_get_brand_context. Unless the user asked for a specific look, send 3 candidates in one call that differ in treatment, all in brandRole colours: the brand default look (only overlay.defaults.presetId and overlay.defaults.template as style) and at least one text on the photo with a scrim (template classic with a system preset, style.position on the photo's free edge such as sky or an empty wall). Put overlay words in textBlocks exactly as they should appear (emoji, hashtags and quotes stay; never HTML, CSS, SVG or URLs). When no copy is saved and the user gave no exact words, get them from smat_generate_overlay_text (paid, needs a yes; it uses the brand's voice). Only when the user asks you to write the copy, write it like a hook from the caption: know the reader, their situation, the payoff and the proof; headline is 3–8 words naming the reader's concrete gain or problem, never a bare feature label; supporting is one short line of proof; cta is 2–4 words pointing at the real next step. Keep one clear hierarchy: headline, then either one supporting line or 2–3 short list items (not both), then the cta; add meta only when it adds a fact; never repeat the same fact in two slots. A headline alone leaves an empty card. No hype words or em dashes. If a candidate says the text does not fit, shorten the copy instead of accepting smaller type. Read each candidate image; show only those where the text is readable and the photo's subject (the product, person or place the post is about) stays visible, lead with the one that hides the least of it and looks cleanest (optionally the runner-up) and say why in one line. SMAT places the card on the photo's free edge and the card grows with the text, so when the subject fills the middle of the photo keep the copy to headline and cta; you can put the text at the top or bottom with style.position, for example to keep the product visible. To compare looks of one saved preset, keep its presetId and template and make each candidate differ visibly in headlineFontKey, textSizeDelta, highlightStyle, ctaStyle or (news-card-panel) panelInset. Pick template classic or news-card-panel and style only from those presets, fonts and controls. Prefer brandRole primary/secondary/accent for colours (the user's brand); hex only when the client explicitly wants a different colour. Read each candidate with smat_get_preview kind=candidate. On a single post, omit textBlocks to use saved copy with expected.designRevision; supplied textBlocks are explicit copy changes and must be accepted first. On target.kind=carousel_slot, overlay copy is that slide's card — do not copy shared single-post textBlocks onto the deck. One shared ContentOverlayDesign per carousel; preview does not write it. Responses are compact by default; pass include: ["snapshot"] to receive the full snapshot.

smat_preview_overlay

Put a photo the brand already has in SMAT onto another post or carousel slide, for example a photo from an earlier carousel. Copies the original photo without its text on the image; the source stays unchanged. Read both items with smat_get_content first: from.asset is the source asset reference, expected are the target's pins. Free; nothing is generated. Responses are compact by default; pass include: ["snapshot"] to receive the full snapshot.

smat_use_existing_photo

Act on one topic idea the user chose: approve it for later, dismiss it (optional reason), create a post draft from it, or put it into a free schedule slot (action.kind assign_slot with the slotId from smat_get_schedule or smat_get_attention). Creating a draft or filling a slot approves the topic and saves an empty draft with the topic; it writes no caption and spends no credits. Continue with smat_generate_caption (paid; uses the brand's voice and post history) on that draft; smat_update_post only for a caption the user supplied or explicitly requested as assistant-authored copy without SMAT generation; a generic request to write a caption does not select this exception. Run only on the user's explicit decision about that topic. Responses are compact by default; pass include: ["snapshot"] to receive the full snapshot.

smat_act_on_topic

Use for a request to write a social post caption, describe an Instagram photo or rewrite an existing post in a connected brand's voice. Resolve the brand and follow the caption workflow first; the request alone does not authorize paid generation. Have SMAT write a caption in the brand's voice. Paid. Within a SMAT post workflow, the default caption author is SMAT unless the user supplies copy or explicitly requests assistant-authored copy without SMAT generation. A generic request to write a caption does not select that exception: it uses the brand's data and the user's post history. Ask SMAT to write the post caption in the brand's voice, with the same Studio text path (hooks, style rules, quality gates). Spends the brand's credits; first get a quote from smat_estimate_action with actionKind caption_from_brief. Put in the brief: topic, goal/CTA, tone, facts to use, what to avoid, and language. You receive only the selected caption plus variantCount, not both variants. New post: newPost {topic, brief, formatKey, platforms}. Existing post: contentId, expected.postRevision and optional feedback. Poll smat_get_operation until text_review. Responses are compact by default; pass include: ["snapshot"] to receive the full snapshot.

smat_generate_caption

Have SMAT write the text on the image for a post, the same hook writer Studio uses: headline with highlighted words, supporting line, label, cta and list items, checked by a quality judge. Paid. First get a quote from smat_estimate_action with actionKind overlay_text. Use it when the user has not given the exact words. Put the returned textBlocks into smat_preview_overlay, dropping slots the chosen look does not need. Nothing is saved to the design. Responses are compact by default; pass include: ["snapshot"] to receive the full snapshot.

smat_generate_overlay_text