Kestroll MCP tools

Look up what Kestroll knows about one asset by its absolute path: metadata, summary, people, timeline segments with transcript excerpts, document pages, face appearances, tracked people, audio levels, and cached visual Q&A. Use it once you know the asset; use search to find assets. Request only the fields you need — a full timeline on an asset over ~5 minutes overflows, so window it with start_time/end_time. frame_at and view_image return actual frames or images inline. Every timestamp is source-asset time, not composition time. For who is speaking or on screen, use inspect_speakers rather than question. Read-only.

Find assets and moments in the library. Use query for visual content, transcript text, or filenames, and the filters (people, collections, folder, asset_type) to narrow it; or leave query empty and pass glob_pattern or size/duration filters to browse by path. Use it to discover assets; use get_asset_data to read one you already have. Returns the top 20 moments or assets (limit up to 50) with paths and timestamps; filename_matches are counted apart from moments_total, so moments_total: 0 beside filename matches means those files are the answer. When a named file can't be found the result says why, including deleted files — relay that rather than searching again. Read-only.

Look up or delete the people Kestroll has identified in the organization from face recognition and transcripts. find fuzzy-matches a name, list returns people (filter by asset_paths, folder or unnamed), show returns one person's headshot inline, and delete permanently removes people. Use it to get a person_slug or confirm who someone is; to find footage of a person use search with the people filter, and to see when they appear in one video use get_asset_data face_appearances.

List the organization's Collections — named, shareable groupings of assets and moments — with each one's slug and name. To find assets inside a collection, use search with the collections filter; to view or edit a collection's clips, pass its slug to composition. Read-only.

Create, view and edit compositions (video edits) and collections (clip sets). create takes a full JSON document: read docs editing/composition_schema.md first. apply_patch is the default edit; other actions are specialized (captions, framing, splits, markers, concatenation), documented at editing/composition_commands.md#<action>. Edits save a new version at once; revert undoes. For dialogue cuts quote the transcript with the *_by_transcript actions.

Save a finished deliverable into the user's library — only when the user asks to export, render, download or save. mode: composition renders compositions (by slug) to MP4 assets in the background: start it, tell the user it's rendering, and move on; the finished MP4 lands in the library and action: status checks progress. The other modes synchronously save one still image: a composition frame, a raw video frame, or a document page. Exports the composition's current version and creates new library assets. Never use it to inspect — composition view_frame and get_asset_data frame_at show frames without creating anything. Details in docs editing/export.md.

Find out who is talking and who is on screen across a span — to pick the person and window for composition track_person, or to check that a shot frames the right speaker. Use it instead of get_asset_data question for any who-is-speaking or who-is-on-screen question. Pass asset_path with source-time from/to (pooling every synced angle), or artifact_slug with composition-time from/to (one window per shot). Returns time-resolved measurements per visual window from independent sources — diarized audio turns, transcript, lip-motion readings and on-screen faces — each with its own status, never one verdict: a window can hold several speakers in turn, so you decide the framing. Read-only.

Change data stored on a source asset — only when the user explicitly asks. edit_transcript replaces a verbatim phrase in the asset's transcript (copy it from get_asset_data); the new wording flows into search and into the captions of every composition drawing on that asset. link_local_file records the path of the asset's original file on the user's computer; nothing is uploaded. To fix one composition's captions use composition; to cut a composition by transcript use its *_by_transcript actions.

Browse and reorganize the library's files and folders: list_folders lists folders (optionally narrowed by glob_pattern) with their absolute paths and asset counts, move_assets moves assets into a folder, create_folder creates folders, and delete_assets permanently deletes assets and/or whole folders with everything inside — there is no undo, so only on a clear request from the user. Takes absolute paths from search or list_folders. NAS-synced assets can't be moved and come back in skipped; unresolved paths come back in not_found; title collisions are renamed automatically. Project bins are managed with project, not here.

Manage Projects, Projects-page folders, and their Media Library. Read product/projects.md with docs before using this tool for operations, parameters, and deletion behavior.

Read Kestroll's reference docs before non-trivial work with the other tools: composition schema and commands, captions, framing, sync, export, asset processing, socials, and product surfaces. list returns every doc's path, title and description — start there when you don't know the path. search ranks docs by keyword, read returns one doc (or one section with path#anchor, the form review findings carry), and outline lists a doc's anchors. Examples in the docs are authoritative. Read-only.

Find curated example edits — Kestroll's and the organization's own — to use as a reference when the user wants a style or format you haven't built before. search by description, then view one by its key: summary, file metadata, timeline segments with transcript excerpts, audio levels, songs, frames and visual questions. view works like get_asset_data, except nothing is added to the library, so the template has no path for other tools. Request only the fields you need and window long timelines with start_time/end_time. Every timestamp is the template's own time. Read-only.

Organization-wide memory shared by every member and conversation, for durable facts such as brand guidelines, preferences and standing instructions. list shows every memory's name and description, save adds a memory, read loads its full body, edit revises or renames it, and delete removes it; those four address a memory by its kebab-case name. Writes are visible to the whole organization and to every future conversation.

Report friction to the Kestroll team: a missing/awkward tool, confusing or wrong data, a feature you wish you had, your own frustration, or a problem the user is causing. Logged for the team — does not affect or block the current task.

Organization and user settings, custom fonts, and plan usage. Read product/settings.md before editing settings and product/custom_fonts.md before adding a font.

Read and manage the organization's workflows: named procedures invoked as /slash_commands. When the user types a /slash_command, or a request matches a workflow's description, read it (omit workflow_command to list them all) and follow its instructions. create_new, edit (a full rewrite), patch (change part of one field) and delete change workflows for the whole organization — only when the user asks, and always read before writing. Kestroll-team workflows are read-only. YAML fields and patch rules are in docs agent_capabilities/workflows.md.

Manage the organization's Scheduled Work: saved prompts that start a new Kestroll chat on a cron schedule. list and view read schedules and their recent runs. create, update and run (start a chat right now) act as the current user — only when the user asks. update replaces the whole prompt, so view first and send it back complete.

List, summarize, rename, and delete the user's chats.

Put recordings of one shoot on a shared timeline. inspect (free, read-only, always first): each asset's capabilities and timeline membership, and which alignment methods can run on each pair. probe: measure how far apart recordings started — every method you name runs on every pair and reports its own verdict; never average offsets that disagree, decide which to trust. validate: check a plan is possible (never that it is right) and get a validation_id. apply_plan: write a validated or inline plan. edit: write an offset a person supplied, with a reason. delete: take assets off their timeline. Writes return the final placements, normalized so the earliest member starts at 0 — report those, not what you submitted. See docs editing/timeline_sync.md.

Diagnose and rebuild an asset's analysis (transcript, speakers, faces, object tracks, scene layouts, segments, moments) when get_asset_data shows it missing or wrong. Always inspect first: it reports each step's last success, failure and in-flight state, plus prerequisites and skip reasons. run rebuilds a preset, overwriting existing analysis over several minutes — only with the user's confirmation; kill stops in-flight work; await (or run with await) watches for the data you need instead of you polling. Read docs asset_processing/pipeline.md before the first run.

Search the web. Returns results, not content. action: images finds images to bring into the library — pass a candidate's image_url to web_fetch with a file_name to save it. action: videos finds YouTube, TikTok, or Instagram videos to bring into the library — pass a candidate's url to web_fetch with a file_name to save it.

Fetch a URL. A web page or PDF comes back as markdown text. A public YouTube, TikTok or Instagram post, or a direct image/video/audio file URL, is instead imported into the library as a new asset (several at once with imports): it returns right away with the new asset_path while the download and analysis run in the background. Find media URLs with web_search; call asset_processing await if the next step needs the import ready. Private, removed or bot-blocked posts fail during the background download.

Make an edited copy of an existing library asset. edit_image_with_ai applies a prompt to an image; edit_video_with_ai applies a prompt to 3-15 seconds of a video (e.g. removing an object), keeping its audio; remove_image_background cuts an image's subject out into a transparent PNG (use it, not an edit prompt, for transparency); remove_video_background cuts the people out of up to 5 minutes of video into a transparent video that keeps the audio. Always creates a new asset and never modifies the original. Returns the new asset_path at once; the AI edits and the video cutout finish in the background. To generate an image from scratch, use create_asset. See docs agent_capabilities/image_generation.md.

Create a brand-new library asset. ai_generate_image generates an image from a prompt; ai_generate_video generates a short video clip with audio from a prompt; create_motion_graphic renders self-contained Remotion/React code (lower-thirds, title cards, charts, callouts) into a transparent video; generate_speech speaks text as an mp3, optionally in the voice from a sample clip. Returns the new asset_path at once and finishes in the background; place the result in a composition as an ordinary image, video, or audio element. Assets never change — to revise one, create it again. To edit an existing image, use asset_editor. Read docs editing/motion_graphics.md before writing motion-graphic code.

Kestroll's built-in sound-effects library, for adding sound effects to an edit. action: search finds sounds by description (whooshes, impacts, pops, clicks, dings, risers, room tone, ambience…); import the picks with action: import. action: import copies sounds (sound_ids from search) into the library and returns their asset_paths. Place imported sounds as audio elements with composition; see docs editing/sound_effects.md.

Move files in and out of the organization's Kestroll library, and check on what's coming in. list returns recent transfers of every kind — uploads, cloud storage imports, NAS syncs, and web and video imports — newest first. inspect (with a file_transfer_id from list) adds per-file rows and errors. To send files from where you're running, upload returns per file either put_url + headers (curl -T <file> -H ...) or parts: PUT each part_size_bytes piece (split -b) to its part_number's url. Then complete the upload_file_ids; anything missing comes back with fresh URLs. download gives one asset's url, or a zip download_id for folders or several paths — call again with it until it has a url. For connected cloud storage, connections says what's connected; an organization owner connects an account in Agent → Connectors. browse lists a folder. search finds files and folders by name. import brings files or whole folders into the library, where they download and process in the background. Importing a file twice makes a second copy.

Work with the organization's connected social accounts (TikTok, YouTube, Instagram, Facebook Pages, X).list_channels returns each account with its status and engagement totals; list_posts returns posts with engagement stats as of the account's last sync; refresh_channels re-syncs every account, or one channel, from its platform now. make_post publishes a library video or a text post to one account now, schedules it, or saves a draft. list_publications returns the posts made through Kestroll, including drafts and scheduled ones; update_post, unschedule_post, and delete_post change one until it starts publishing. Posting is public — only post what the user asked for, and read docs agent_capabilities/socials.md first for each platform's options.