Tolstoy

Finalizes a file after every signed upload request from start_library_asset_upload succeeded. This step is required: until it returns, the upload has no usable id and nothing else finalizes it for you. The result carries the Library asset id and the mediaId a Studio reference takes. Repeating a successful finish is safe. The returned asset id is what the rest of the file's metadata hangs off, with `type: "vod"`. To save what a file name told you: send the creator handle and platform and the expiration date to update_asset; resolve the product reference — a SKU through browse_products with `filters.sku`, which matches exactly, a product name through search_products, which is fuzzy — and only when exactly one product comes back, mark it with tag_video_product; then read the asset back with get_asset to confirm the creator, the expiry and the product. On zero or several product matches, report the file name and do not guess.

finish_library_asset_upload

You are briefing Studio Agent, Tolstoy's creative director, to produce marketing media. It owns the craft — writing the final generation prompt, handling brand names and identity, casting scenes, models, and settings, and keeping output on-policy. Your part is to relay the user's intent faithfully and let Studio Agent interpret it; the closer the brief stays to what the user actually said, the better it casts. Studio Agent works in sessions. A session is one ongoing chat that gathers everything made in it into a single gallery — the unit a person uses when they open a Studio chat and keep creating. One brief can cover a whole set: name three scenes, a run of PDP shots, or an image per email, and Studio Agent produces each as its own asset in that session, one at a time — so hand it the whole request in a single call rather than generating each asset separately. Reuse a session's chatId to keep building on that work; open a fresh session (no chatId) for a genuinely separate project. To rework the latest asset in place — animate, restyle, swap a background — hand off to iterate_studio_content. Reference images arrive as URLs or as mediaIds, up to 4 in total. An image already on the open web goes in as its URL in referenceImageUrls. A local or user-provided image *file* goes into the merchant's Library first, by either transport: where you can run a shell command, start_library_asset_upload hands you a signed plan and finish_library_asset_upload returns the id; where you cannot, or the transfer was refused, upload_library_assets_from_panel has the Tolstoy panel do it and report the ids back. An upload has to be finished before its id works here. Either way the mediaIds go in referenceImageMediaIds exactly as given. When you only have an image you can see but cannot read as bytes and no panel opens, describe what it shows in the prompt instead. To feature a real catalog product, identify it first with search_products or browse_products and pass its id in products instead of naming it in prose, so Studio Agent works from the true product and its images (include that result's appUrl when it isn't the connected store). To use a saved Tolstoy model such as Sara or Mike, call list_ai_models and pass its exact aiModelId; this is separate from the image/video generation engine. Content is screened for general-audience brand and product marketing; off-policy requests are refused. To reuse a saved creative recipe, call list_studio_templates and pass its templateId. The saved output type and aspect ratio are validated before a session starts. The tool returns as soon as the session starts, before the media is finished. Some clients show a live preview that fills in on its own; where yours does not, call get_studio_session to fetch the finished media.

generate_studio_content

Reads the saved analytics metrics for one AI widget — a widget the merchant built in the AI Widget Builder. These are the same metric definitions used by that widget's Analytics dashboard; this tool does not accept SQL or invent new calculations. Use the widgetId returned by list_ai_widgets. Ids from list_widgets are storefront video experiences and are rejected here. Omit metricIds to run every saved metric, up to 20, or pass metric ids from a previous result. Omit from/to to read the last 30 days, the same window as the Widget Analytics dashboard. Both dates are calendar dates (YYYY-MM-DD) and both are read as whole UTC days, from included and to included, over a span of at most 90 days. Use get_ads_performance for Meta advertising performance.

get_ai_widget_analytics

Gets raw Meta ads performance live from the Meta Insights API — including actions and action_values — aggregated per campaign, ad set, or ad. Use this for: "how are my ads doing", "what did I spend this week", "which ad is winning / losing". Return-on-ad-spend rules: this tool does not calculate ROAS. Use actions and action_values only after the merchant has confirmed which conversion event is their business result. Do not sum values from different action types because Meta can report one conversion through several aliases. Numbers use the ad account's timezone and Meta's default attribution window.

get_ads_performance

Fetches the finished images or videos from a Studio chat, and reports whether it is still working. You need this because generate_studio_content and iterate_studio_content return straight away, before anything is made. Clients that show a live preview fill in on their own; in a text-only client this tool is the only way to see the result. Pass `wait: true` to hold until the work finishes, up to about 50 seconds per call, then get the media back newest first. If it is still going when that window closes, the result says so — call again with `wait: true` to keep waiting. Pass `wait: false`, the default, for a snapshot of whatever is ready right now.

get_studio_session

Fetches one accessible Studio template by its stable id, including the exact saved prompt and output settings. User templates from another workspace are not visible.

get_studio_template

Full details for one or more pieces of media, including — for the merchant's own videos and images — which products are marked on them and which playlists they belong to. Input. Pass up to 50 items, each as an `id` and a `type` together. Both come from an earlier `list_assets` or `search_assets` result. The `type` is required because the merchant's own media and the AI-generated drafts are stored separately, so an id alone is ambiguous. Output. For each item: name, whether it is a video or an image, whether it is starred, a thumbnail, and its date. Studio drafts also carry their pixel dimensions. For the merchant's own media it also lists the products marked on it, the playlists it sits in, and — when they are set — the creator handle and platform and the expiration date. This is how you confirm what `update_asset` and `tag_video_product` saved. An expiration date is not a label. From that date Tolstoy hides the video from Library listings and from every widget fed by a Library search, so always read it back after setting one. A creator field is absent when nothing is saved, and the platform is absent when the video was imported under a provider other than TikTok or Instagram. `mediaUrl` — shown as the play link for a video and as `original` for an image — is the deliverable file. Give it to the merchant to share, paste, or download. For a Studio draft it is the full-resolution master; for the merchant's own video it is the rendition their store serves, so do not call it a master. The embedded thumbnail and `thumbnailUrl` are small compressed previews for display only; delivering one produces a blurry asset, so never substitute it for a missing `mediaUrl`. Only Studio drafts report dimensions. A video with no play link has no file that this tool can deliver. Do not say that it is still processing. Tell the merchant that the video is in their Tolstoy library.

get_asset

Everything about one video experience on the storefront: which type it is, whether shoppers can see it, how it looks, which playlists fill it, which videos are pinned or hidden, and the media it currently shows. Whether shoppers can see it is two separate facts, and both must be true. The **Tolstoy switch** is the merchant's switch inside Tolstoy. **Storefront** is what the store's live Shopify theme carries — the Tolstoy app embed, and for most widget types a Tolstoy theme block. It reads `visible` only for widget types that need no theme block; `theme ready` means the theme carries that type's block, but the read cannot tell which widget is inside it, so do not report this widget as visible. A storefront state of `unknown` means the theme could not be read; it does not mean the widget is off. Input. The widget id comes from `list_widgets`. `mediaLimit` sets how many videos to describe in full — raise it to see everything the widget carries. Pass a `productId` to ask a sharper question: what would a shopper see on *that* product's page. Output. The widget's name and type, the two visibility facts above, how it is set up, which playlists fill it, and the videos it shows. A video in that list carries a playable URL when one is available — give that URL to the merchant. A video with no URL has no file that this tool can deliver, and the merchant can reach that video in their Tolstoy library. Two things that mislead if you skip them. The media count can be a floor rather than an exact figure, and the result says when that is the case — do not report it as exact. And when the widget is limited to the product on the page, the video list here is the unfiltered set, so a shopper on any single product page sees fewer than what you get back.

get_widget

iterate_studio_content continues a session by handing Studio Agent a follow-up, with the session's prior context intact — so speak in continuations ("animate this with a slow zoom", "warmer palette", "swap the background to a beach") rather than restating the scene. It reworks the latest asset in place; to add a new asset to the session, generate_studio_content with the same chatId keeps creating instead. The chatId is on the most recent generate_studio_content or iterate_studio_content result (structuredContent.chatId). Bring a real product into an iteration the way generate does — by id from search_products/browse_products, not by name. Bind or replace a saved Tolstoy model with the exact aiModelId from list_ai_models; this is separate from the generation engine. New visual references travel as public URLs in referenceImageUrls, or, for a local image file, as mediaIds in referenceImageMediaIds — from start_library_asset_upload once finish_library_asset_upload has returned its id, or from the Tolstoy panel that upload_library_assets_from_panel opens when you cannot run a command or the transfer was refused; up to 4 in total. An upload has to be finished before its id works here. Describe an image you can see but cannot read as bytes, and cannot get through either transport, instead. Content is screened the same way as generate_studio_content, and the result comes back as soon as the follow-up starts, before the new media exists. Clients that show a live preview fill in on their own; where yours does not, call get_studio_session to fetch it.

iterate_studio_content

Lists the AI widgets this merchant built in the AI Widget Builder, most recently changed first. These are custom interactive widgets — a size finder, a quiz, a bundle builder — and they are a different thing from the video experiences that `list_widgets` returns. Use it to get an AI widget id (`widgetId`) before calling `get_ai_widget_analytics`. It is the only tool that returns ids that tool accepts. Filters. `appUrl` picks another of the merchant's stores (see `list_stores`); omit it for this connection's store. Output. Each AI widget's name, status, when it was last changed, and its id.

list_ai_widgets

Lists the Meta ad campaigns on the merchant's connected ad account — live from Meta, including campaigns created outside Tolstoy (Tolstoy-launched ones are flagged). Delivery truth: a campaign with `status` ACTIVE but a non-ACTIVE `effectiveStatus` (e.g. PENDING_REVIEW, ADSET_PAUSED, WITH_ISSUES) is NOT delivering — report it as such, never as "live". Output. Per campaign: name, objective, daily/lifetime budget, status, effectiveStatus, and whether it was launched through Tolstoy. `structuredContent` carries the raw rows.

list_ad_campaigns

Lists the Studio projects and folders the merchant already has, so new work can go inside one rather than starting loose at the top level. A project is a top-level folder that carries shared background — reference documents the merchant uploaded, and which of their stores it draws products from. Every chat started inside a project inherits that background, so work placed there comes out on-brand without you restating it. Folders are subfolders within a project. Use it to find a `folderId`, then pass that to generate_studio_content so the new work lands in the project and inherits its background, or to list_studio_chats to see what is already there. Output. For each entry: its id, name, whether it is a project or a folder, which folder it sits in, and which sets of brand background it carries.

list_studio_folders

Lists reusable Studio creative templates available to this workspace. Returns global templates and templates owned by the connected account, with stable ids for get_studio_template or generate_studio_content.

list_studio_templates

Lists the saved Tolstoy models available to this workspace, such as Sara or Mike. A Tolstoy model is a reusable visual identity with saved reference images. This is not an image/video generation engine and is not an LLM such as Claude Sonnet or Opus. Pass the exact `aiModelId` returned here to generate_studio_content or iterate_studio_content. Names are not identities. If several results have the same name, show every match and let the user choose one stable `aiModelId`; never guess from the name.

list_ai_models

Lists the work already under way inside a Studio project or folder, so you can carry on an existing thread instead of starting from nothing. Call list_studio_folders first to get a `folderId`, pass it here, then pick a chat and give its `chatId` to generate_studio_content. Everything that chat has already produced and been told stays available, so you do not need to repeat the brief. Output. For each chat: its id, name, when it started, where it came from, and what it makes. Newest first; `hasMore` means the folder holds more than were returned.

list_studio_chats

Lists the video experiences already placed on the storefront, newest first — story rows, carousels, full-screen feeds and the rest. Use it to answer "what do we have on the site", "what is switched on", or to get a widget's id (`publishId`) before calling `get_widget`. Filters. `liveOnly` returns only the ones switched on inside Tolstoy; omit it to include the switched-off ones too. `appUrl` picks another of the merchant's stores (see `list_stores`); omit it for this connection's store. Output. Each widget's name, type, when it was made, its id, and two separate facts that both have to be true before a shopper sees anything: `Tolstoy` is the switch inside Tolstoy, and `Storefront` is what the store's live Shopify theme actually carries. A widget switched on in Tolstoy on a theme that is not set up shows nothing. `visible` is only for widget types that need no theme block; `theme ready` means the theme carries that type's block, but the read cannot tell which widget is inside it, so do not report that widget as visible. `unknown` means the theme could not be read — it does not mean off.

list_widgets

List the store's collections — curated groups like New In, Dresses, or Sale. Use it to see how the store organises itself before browsing — the collections are a good read on what the brand actually sells. Pass a `collectionId` to `browse_products` to see what is inside one. For a specific named product, use `search_products` instead. `productsCount` is the store's total for the collection and may include unpublished or unsynced products, so it can exceed what `browse_products` returns.

list_collections

The 20 newest pieces of media the merchant has, mixing two sources: their own videos and images (uploaded or imported from Instagram and TikTok, marked `type: "vod"`) and unpublished AI-generated drafts from Studio (marked `type: "studio"`). Use it for "what media do we have", "what is new", "show the recent uploads", "what AI drafts are waiting", or "show the starred ones". It always returns the newest 20 and nothing else — no paging, no searching. To find a particular item by name, use `search_assets`. Filters. `type` restricts to one of the two sources. `favoritedOnly` keeps only starred items from within those 20. Output. Each item's name, which source it came from, when it was made, and a thumbnail. Studio drafts also carry their pixel dimensions. Keep the `id` and `type` pair — the other media tools need both. `mediaUrl` is the playable file — give it to the merchant to share, paste, or download. For a Studio draft it is the full-resolution original; for the merchant's own video it is the rendition their store serves, so do not call it a master. `thumbnailUrl` is a small compressed preview for display only; delivering it produces a blurry asset, so never substitute it for a missing `mediaUrl`. Studio drafts also report `width` and `height`, so check the dimensions before you reuse one outside chat. A video with no `mediaUrl` has no file that this tool can deliver. Do not say that it is still processing. Tell the merchant that the video is in their Tolstoy library.

list_assets

Lists the storefronts this merchant has connected. Most merchants have one, but some run several — a separate store per country or per brand. Every other tool works on this connection's store unless you tell it otherwise. Call this first when the merchant mentions more than one store, or when a product or widget you expect is missing — it may live on a different one. Output. Each store's domain, which platform it runs on, how many video experiences it has, and which one is this connection's default. Pass a domain as `appUrl` to another tool to work on that store instead.

list_stores

Marks which products appear in one of the merchant's videos, or removes those marks. This is what makes a video shoppable. A marked video gains a buyable product next to it, joins the automatic `product_tagged` playlist that most widgets are filled from, and becomes eligible to appear on that product's own page. An unmarked video will sit in the library doing nothing, so marking products is usually the step that makes a new video worth uploading. Input. The video id comes from `list_assets`, `search_assets`, or `get_widget`. Product ids come from `search_products` or `browse_products` — look them up rather than guessing. If the merchant has more than one store, pass the same store you looked the products up in. Output. Which products were marked and unmarked.

tag_video_product

Renames a Studio project or folder the merchant already has. A project is a top-level folder. A folder is one level inside a project. Only the name changes: the parent stays the same, the chats inside stay in place, and the brand background stays as it is. A project made through this connection carries no brand background: no uploaded documents, and no store to draw products from. The merchant adds these in Studio. A project or folder cannot be moved to a different parent through this connection. The merchant moves it in Studio. Output. The id, the new name, the previous name, whether it is a project or a folder, and a link to it in Studio.

rename_studio_folder

Renames a piece of media, stars it, or — for the merchant's own videos and images — records who made it and when it expires. Works on both the merchant's own media and AI-generated Studio drafts; a Studio draft takes `name` and `favorite` only. Input. The `assetId` and `type` together identify the item; both come from an earlier `list_assets`, `search_assets`, `get_asset`, or `finish_library_asset_upload` result. Send any combination of `name`, `favorite`, `creatorHandle` with `creatorPlatform`, and `expirationDate` in one call. Whatever you omit stays as it is — the name, the star, the products marked on the video, and every other saved field are untouched. `creatorHandle` and `creatorPlatform` travel together and describe the creator the video came from. The handle is stored without a leading @. `expirationDate` is not a label. Tolstoy hides an expired video: on the date you set, the video leaves the merchant's Library listings and every widget that draws media from a Library search, so a wrong date silently removes the video from the storefront. Only set it from a date you are sure of, and read it back with `get_asset` afterwards. A date already in the past hides the video immediately. Repeating the same call is safe and changes nothing further. Output. What changed. The merchant sees it immediately on their side. Confirm the saved values with `get_asset`.

update_asset

One call that reports everything the store already has set up. Start here — it saves piecing the picture together from half a dozen other tools, and it tells you what is missing before you try to build on it. It covers: the brand details Tolstoy holds (name, logo, colours, fonts) and whether the brand has been analysed yet; how many products are in the catalogue and whether an import is still running; which AI shopping experiences exist and which are switched on — the assistant that answers shopper questions, the virtual try-on, the suggested-questions block on product pages, the chat bubble; whether the AI assistant has been given a personality and background knowledge; which outside accounts are connected (Shopify, Instagram, TikTok and the rest); and the merchant's other storefronts. Check the integrations before blaming anything else. An account can be connected and still broken — an expired Instagram or TikTok login keeps working in the UI but silently fails any import. Those are flagged as needing attention, and reconnecting is the fix. Scope. `include` limits which of those areas to read. `appUrl` points at another of the merchant's stores; omit it for this connection's store. Pass `surface` to also get one experience's full settings — leave it out otherwise, those objects are large. Reading the answer. An area that could not be read comes back empty **and** is named in `unavailable`. That means unknown, not absent — do not tell the merchant something is missing when it merely failed to load.

get_setup_state

Uploads a library video or image to the merchant's Meta Ads media library — it appears in Meta Ads Manager ready for ad creation. No campaign or ad is created and no spend occurs. Input. `asset` is an `{ id, type }` pair from `list_assets`/`search_assets`. When the account has one connected ad account it is used automatically; with several, omit `adAccountId` once to get the list, then pass the chosen one. Output. The Meta media id (videoId or imageHash) confirming the upload.

publish_to_meta_ads_library

Turns one of the AI shopping experiences on or off for shoppers, creating it first if the store does not have it yet. The experiences, by what a shopper gets: - `see-it-on-you` — virtual try-on: the shopper uploads a photo and sees the garment on themselves. - `beauty-tryon` — the same idea for make-up. - `video-try-on` — try-on rendered as video rather than a still. - `ask-ai` — an assistant that answers questions about the catalogue. - `search-bar` — natural-language search in place of keyword search. - `chat-bubble` — a floating bubble that opens the assistant anywhere on the site. - `top-questions` — the common questions block on a product page, answered from the catalogue. - `choose-model` — the shopper picks which model the product is shown on. - `complete-the-look` — suggested items that go with the one being viewed. Read `get_setup_state` first to see which already exist and which are on. This tool only switches them; it does not change how they look, and it does not need to — colours, fonts and logo come from the brand profile Tolstoy builds when the store is connected. Switching one on makes it visible to real shoppers on a live store. Confirm the merchant wants that before turning things on, rather than enabling a set because they were asked about.

configure_shopper_surface

Takes a request in plain words about this merchant's Tolstoy workspace and returns the answer as text. It covers the work the specific tools do not: store and campaign analytics, saved creative templates, the product catalogue, publishing work, Shopify, Meta, and connecting or checking a connected service. It runs against the merchant's own data and permissions, so send the request instead of assembling the answer from other tools. A conversation runs one turn at a time. `new` starts a conversation and returns its `chatId`. Keep that `chatId` and pass it to `continue` to stay in the same conversation, where everything already said stays available. `read` returns the current result of a conversation and sends nothing. Every call waits up to about 50 seconds for the answer. `status` says what happened: `completed` means the text is the answer, and `platformTokensUsed` is the credit cost of that one turn. `running` means Studio is still working — call `read` with the same `chatId`. `busy` means the conversation already runs a turn, so your message was not sent — call `read` first, then `continue`. `failed` means the turn ended without an answer. `not_found` means this workspace has no such conversation. If Studio asks a question, its question comes back as the answer text. Give it to the person, then send their reply with `continue` on the same `chatId`. If Studio reports a service that is not connected, its answer holds the setup or authorization link when one exists; otherwise open `studioUrl` and finish the setup there. The answer is text. Images and videos stay in Studio: `studioUrl` opens the conversation, and get_studio_session reads the media of a conversation that made some. To make new images or videos, use generate_studio_content instead — it is built for that work.

run_studio_agent

Overwrites selected fields on a Studio template owned by the connected workspace. Global templates and templates owned by another account cannot be edited.

update_studio_template

Opens a Library upload for a local image or video file and hands you a signed plan to transfer it yourself. The file lands in the merchant's Library, available to playlists, widgets, later Library searches, and as a Studio reference. The file bytes never pass through the model. Supply the exact file name, MIME type, and byte size, transfer the file with the signed plan in the result, then call finish_library_asset_upload. The id is not usable until that finish succeeds — nothing finalizes the upload on your behalf. This transport needs a client that can run a command and reach the host the plan names. If the transfer is refused — HTTP 403, the host is not allowed, or any other network refusal — do not retry it, and do not ask the merchant to publish the file on the open web. Use upload_library_assets_from_panel instead: the Tolstoy panel transfers the same file types into the same Library and reports the ids back. Reading a local folder and reading meaning out of a file name are your work, not Tolstoy's. This server never sees the merchant's file system: it takes one file at a time, by the name, MIME type and size you give it. So a repeatable folder job — for each file, upload it and then save the creator, the expiry and the product from the file name — needs a client that can list the folder and run the transfer command. A panel-only host cannot list a folder, so there the merchant picks the files by hand through upload_library_assets_from_panel.

start_library_asset_upload

Opens a file picker in the Tolstoy panel and uploads what the merchant chooses into their Library. This is the transport for a client that cannot run a shell command, or whose command was refused: the panel performs the transfer itself, from the browser the merchant is already looking at. What lands is the same Library asset start_library_asset_upload produces, and it takes the same images and video — the merchant keeps it and can find it later. The merchant picks up to 10 files at once, and each is transferred on its own, so one failure does not lose the rest. The panel then posts a message naming every file that arrived with its mediaId and every file that failed. Those mediaIds are already finished and ready to use: to make one a reference, pass it verbatim in referenceImageMediaIds on generate_studio_content or iterate_studio_content, and wait for that message before generating. Do not alter an id and do not invent one. If no panel appears in your client and you cannot run a command either, say so plainly and let the merchant upload the file in Tolstoy Studio themselves — never ask them to publish it on the open web.

upload_library_assets_from_panel