Tolstoy Library

Connects an outside account to this merchant: their Shopify store, their Instagram, or their TikTok ad account. Only the merchant can do this. Granting access means signing in and approving permissions in a browser, so this tool returns a link for you to give them — nothing here can click it for them, and there is no way around that. Connecting the Shopify store is usually the first thing worth doing: it brings in the whole catalogue and starts Tolstoy analysing the brand on its own, with no further call from you. Shopify takes two calls, both naming the store in `shop`. The first gives you the link. Once the merchant says they have finished, call again exactly the same way and it completes the connection. Always name the store — it is what makes sure the install being finished is the one you asked for. Instagram and TikTok take one call; their sign-in finishes the job by itself, so just confirm afterwards with `get_setup_state`. Watch for two answers that are not success: the store may already belong to a different Tolstoy account, or it may need a Shopify billing issue resolved first. Both come back plainly and neither is something you can retry past.

connect_integration

Creates a named playlist and, if you pass videos, fills it in the same call. A playlist is how you decide what a storefront video experience shows. Hand its id to `update_widget` as a `custom` entry in `sourcesIn` and the widget plays exactly that set. Use it to curate deliberately — a launch, a category, one creator's videos — instead of relying on the automatic playlists like every-video-with-a-product-tagged. Input. Video ids come from `list_assets` or `search_assets`. Pass the videos in this call: calling again with the same name creates a second playlist rather than adding to the first. Output. The playlist id to pass to `update_widget`, and per-video confirmation. Adding a video can fail on its own without failing the playlist, so check the result rather than assuming every video landed. Teams. A connection that works in a team creates a team playlist. It holds only the team's own videos, it is not a Library playlist, and widgets cannot show it because widgets are only supported in Main. A request with a video that did not come from the team's own Studio assets is refused, and nothing is created.

create_playlist

Panel step. Discards a Library upload whose bytes never arrived, so the Library keeps no row that looks like it is still uploading. The panel calls this; nothing else does.

fail_library_asset_upload

Panel step. Finalizes a Library upload once its bytes have transferred, and returns the finished asset id. The panel calls this; nothing else does.

finish_library_asset_upload

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. Output. For each item: name, whether it is a video or an image, whether it is starred, a thumbnail, and its date. 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. 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`. 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. `originalUrl` is the stored source file — the exact bytes that were uploaded, imported, or generated, at full detail — and is the URL to hand to a generation or editing tool. It is present only when `originalStatus` is `ready`; `processing` means the file is still being ingested, and `unavailable` means no source is stored (`originalUnavailableReason` says why, for example `external_source` for a Shopify-hosted video). An uploaded original is served through a signed link that stays valid for 7 days.

get_asset

Returns the merchant's 20 most recent media library assets — a mixed feed of imported library content (videos, images, uploads, social imports) and AI Studio drafts (unpublished AI-generated content), each tagged with a `type` discriminator (`vod` or `studio`) so callers can distinguish them. Use this for: "what's in my library", "what's new", "show my recent uploads", "what AI drafts do I have", "show my favorites". This tool always returns the most recent 20 (no pagination, no search) — a recency feed, not a search interface. Filters. `type` narrows to one source. `favoritedOnly` returns only starred assets within the recent 20. Omit filters for the latest 20 across all sources. Output. Markdown list with each asset's name, type, creation date, and thumbnail URL. `structuredContent.items` carries `{ id, type }` for each asset.

list_assets

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

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. Teams. Product tagging is only supported in Main. A connection that works in a team cannot mark products, and the tool changes nothing.

tag_video_product

Find specific assets in the merchant's imported library (videos and images they uploaded or imported from social platforms) by display name or UGC creator handle. Returns up to 20 matches. Matching is OpenSearch `match_phrase` against the asset `name` AND the `ugcUsername` field. Phrase order matters; tokens are analyzed but must appear in sequence. No fuzzy matching, no typo correction. Use this when the user asks to find a specific asset by name: "find my beach reel", "show me videos from @cooluser", "do I have anything called summer dress?". Targeted lookup only — not for enumeration. Scope. Searches imported VOD library only (uploads, social imports, UGC). Does NOT search AI Studio drafts — Studio assets have no text-search backend. Output. Markdown list of matches with name, type, date, thumbnail. `structuredContent.items` carries `{ id, type: "vod" }` for each match.

search_assets