Reference
Tools
What an agent can call. SPREVA lists 49 tools, and the ones for the Studio and AI images need a plan that includes the Studio.
All tools
searchSearch the workspace
Finds posts, files, campaigns, accounts, queues, scripts, Studio projects and styles, by words or by what a picture or video shows. A name written loosely still finds it (capitals, accents, dashes, spaces, no extension), and when nothing matches it answers with the closest names.
- Risk
- Low
Reads onlyfetchRead one thing in full
Reads a post, file, campaign, queue, account or Studio project from its link or id, or a page of SPREVA's reference.
- Risk
- Low
Reads onlyoverviewWorkspace overview
The first call in a conversation: the time zone and clock, what needs attention, what goes out next, the accounts, queues and campaigns, and what the plan allows.
- Risk
- Low
Reads onlylist_workspacesYour workspaces
Lists the workspaces this connection can work in, with your role and time zone in each and which one calls are made in now.
- Risk
- Low
Reads onlyswitch_workspaceSwitch workspace
Moves the conversation to another of your workspaces, by name or link, when the connection was allowed in all of them. The calls that follow use that workspace's accounts, media and agent permissions.
- Risk
- Low
save_workspaceChange the workspace's settings
Renames the workspace or changes its time zone, the language media descriptions are written in, and whether new uploads are described automatically. Owners and Admins can. A new time zone does not move posts already scheduled.
- Risk
- Medium
list_membersThe workspace's people
Lists the members with their email and role, and the invitations still waiting, with when each link expires.
- Risk
- Low
Reads onlyinvite_memberInvite someone
Invites a person by email with a role, always after a preview to confirm, since it emails them and may take a seat of the plan. Someone who already has a SPREVA account at that address joins at once. Owners and Admins can; an Admin cannot invite an Owner.
- Risk
- High
save_postCreate or edit a post
Writes a post for one or more accounts, with what differs per account, and sets when it goes out: a time, a queue's next slot, or a draft. In a workspace that requires approval, a time or a queue sends it for review instead, and it goes out once a person approves it.
- Risk
- Medium, High when it goes out in less than an hour.
publish_postPublish a post now
Publishes a post on all its accounts, or again only where it failed. What already went out is never posted twice. In a workspace that requires approval, a post nobody approved is refused: send it for review with save_post and a time or a queue.
- Risk
- High
delete_postDelete a post
Removes a draft, a scheduled post or a published one from SPREVA. A published post stays live on the networks.
- Risk
- Medium, High for a published post.
import_mediaImport a file into the library
Brings an image or a video into the library from a public link, or from bytes the agent uploads.
- Risk
- Medium
update_mediaRename, tag, file or describe a library file
Changes a file's name, tags, folder or alt text, and can write the alt text from what the picture shows.
- Risk
- Medium, High when it writes the alt text with AI.
delete_mediaDelete library files
Deletes one or more files (images, videos, audio) from the library, after a preview and a confirmation that show where each is used and the space it frees. Files used by unpublished posts or Studio projects are refused unless the agent is told to force it.
- Risk
- High
save_campaignCreate or edit a campaign
Creates or changes a campaign, and adds posts to it or takes them out.
- Risk
- Medium
save_queueCreate or edit a queue
Creates or changes a posting schedule: its name, time zone and weekly slots.
- Risk
- Medium
analyticsHow posts performed
Totals against the period before, the top posts, the split by network and comparisons with their sample sizes, for the workspace, a campaign, an account or a post.
- Risk
- Low
Reads onlyrefresh_metricsRefresh the numbers
Reads a post's numbers, or an account's followers, from the networks right now instead of waiting for the usual schedule, and leaves that schedule alone. The same post or account can be refreshed again after five minutes.
- Risk
- Low
list_clippersYour clippers and their views
The accounts associated with your clippers program, ranked by views in a period, with each one's network, handle and link, and the ones waiting for your decision first.
- Risk
- Low
Reads onlyclipper_postsOne clipper account's posts
What an associated account published since it joined, newest first, with views, links and dates. Takes the account's name, @handle, link or id.
- Risk
- Low
Reads onlyclipper_calendarWhat your clippers have scheduled
The posts your clippers scheduled in SPREVA for the coming days, and the ones that went out that way, earliest first, with the account, the network and the link once they are out. Posts made on a network itself are not here.
- Risk
- Low
Reads onlycreate_videoCreate a Studio video
Starts an empty Studio project in a format, which the agent then builds. If a project with that name already exists it answers with that one instead of making a copy.
- Risk
- Medium
Needs a plan that includes the Studionarrate_videoNarrate a Studio video
Voices the script the agent wrote and places every word on the timeline. Uses AI credits, 1 per 100 characters.
- Risk
- High
Needs a plan that includes the Studiocompose_videoBuild a Studio video from a markdown script
Builds a whole explainer video from one markdown script: what is said, and what is on screen at which word. The narration is voiced, the look sets colours, entrances, transitions and sounds, the camera punches in on what enters, and captions and music are added. The result is a normal, editable Studio project. Uses AI credits, 1 per 100 characters of narration, and answers with a preview first. Rebuilding a project from a changed script voices it again only when the narration changed.
- Risk
- High
Needs a plan that includes the Studiomatch_mediaMatch library files to a script
For each line of a script, lists the library files that fit it best, by what they show, the words on them, what is said in them and their quality, with the moment of a clip that fits. Changes nothing and spends nothing.
- Risk
- Low
Needs a plan that includes the StudioReads onlyfind_sfxFind a sound effect by what it does
Lists the best three library sound effects for a moment of a video, by intent, emotion and energy rather than file name, with why each fits and the gentlest one first. When nothing fits well, or when asked, it makes a new sound with Spreva's own synthesiser, saves it in the library and lists it first. Spends no AI credits.
- Risk
- Low
Needs a plan that includes the Studiofind_musicFind music by feel, varied between videos
Lists the best three library music tracks for a video, by mood, genre, energy and how well they sit under a voice rather than file name, with why each fits. Tracks the workspace's recent videos used rank lower and tracks the project already has are held back, so videos do not share one bed. Tracks not classified yet are queued for classification. Changes nothing and spends nothing.
- Risk
- Low
Needs a plan that includes the StudioReads onlyfind_iconFind an icon by what it means
Lists the Lucide icons that best match a few words in English, such as phone, security or growth chart, with their tags and the best match first, and says how to place one in a motion graphic: the icon block, which draws itself on, or path nodes in a raw scene. Changes nothing and spends nothing.
- Risk
- Low
Needs a plan that includes the StudioReads onlycreate_sfxCreate a sound effect
Makes a new sound effect with Spreva's own synthesiser, from a few words in English or Portuguese or from a recipe the agent writes for full control. It is saved in the library, in the Generated sounds folder, and classified like any other sound, so it can be found and placed in a video. Spends no AI credits.
- Risk
- Medium
Needs a plan that includes the Studioscore_videoScore a Studio video with music
Composes instrumental music made to the video: a quiet intro, a build, the drop exactly on the reveal and a resolution. It joins the library as music and goes under the project as the bed, lowered under the voice. Uses AI credits, 30 per started 30 seconds of video, and answers with a preview first.
- Risk
- High
Needs a plan that includes the Studioplan_editPlan the edit of a Studio video
Reads a Studio video (what is said, the shots and cuts, what is already there) and the library's classified sounds, picks the recipe for its kind of video (theory, list, news, tutorial, promo, podcast, vlog, story, highlights) and applies a complete edit in one step, as one saved version: every cut hard or with a transition and its sound, the look, captions, a hook, music that ducks under the voice, punch-ins, text and B-roll. Cutting a picture out of its background uses AI credits, so it is offered, never applied. Without apply it changes nothing and only describes the plan.
- Risk
- Low
Needs a plan that includes the Studiofind_momentsFind moments in a long video
Shows what a long video says, sentence by sentence with its times, where it gets loud, what the picture shows, and the clips it would suggest, so the agent can choose the parts worth cutting. Changes nothing and spends nothing.
- Risk
- Low
Needs a plan that includes the Studioread_transcriptRead a file word by word
Reads the transcript of a video or audio file the way an editor does: phrases with their times and speakers, hesitations (um, uh) kept and marked, and the silences listed. Several files can be read together to compare takes, and a range can be listed word by word with each word's start and end. Changes nothing and spends nothing.
- Risk
- Low
Needs a plan that includes the StudioReads onlymake_clipsMake short clips from a long video
Cuts the parts you chose from a long video into short vertical Studio projects, one per part, with captions from what is said. Each one is a project to edit and export.
- Risk
- Medium
Needs a plan that includes the Studioclips_from_linkMake short clips from a link to a long video
Takes the link to a long video (YouTube, Twitch, Kick, Vimeo, X, TikTok or any public page), asks for the person's confirmation that they may use it, and starts a batch that downloads it, reads what is said, finds the best moments and makes one vertical Studio project of each. It answers at once with the batch's link; fetch shows the progress and then every clip with its score and reason. Uses transcription minutes and may use AI credits.
- Risk
- High
Needs a plan that includes the Studioedit_videoChange a Studio video
Edits text, timing, cuts, pictures, clips, effects and sound, and adds new elements, with the Studio's own editing operations.
- Risk
- Medium
Needs a plan that includes the Studiosave_videoRename or file a Studio project
Renames a project and/or files it in a Studio folder, or takes it out of its folder; several projects can be filed at once. Renaming needs the project's revision; filing alone does not change the video. It can also copy a project to another of your workspaces: its files are shared with that workspace read-only and its brand fonts are added there.
- Risk
- Medium
Needs a plan that includes the Studiodelete_videoDelete Studio projects
Deletes one or more Studio projects, after a preview and a confirmation. Files exported from them stay in the library.
- Risk
- High
Needs a plan that includes the Studiopreview_videoSee a Studio video's frames
Draws the frames at the moments the agent names, exactly as the export will, so it can check what covers what before exporting. Changes nothing and spends nothing.
- Risk
- Low
Needs a plan that includes the StudioReads onlyinspect_mediaLook at a stretch of a source file
Draws one picture of a range of an uploaded video or audio file: frames spread evenly over it, the waveform of its sound with the pauses shaded, and the words said where they are said. Changes nothing and spends nothing.
- Risk
- Low
Needs a plan that includes the StudioReads onlycompare_videoCompare two versions of a Studio video
Lists what changed between two versions of a project: each element added, removed or changed, and what changed in it. It can also show both versions at the same moment. Changes nothing.
- Risk
- Low
Needs a plan that includes the StudioReads onlyrestore_videoRestore a version of a Studio video
Takes a project back to one of its versions. The result is kept as a new version, so the restore can be undone too.
- Risk
- Medium
Needs a plan that includes the Studioreview_videoReview a Studio video
Checks a project the way the Studio's own AI editor checks its work, and lists what to fix, worst first. It marks what the export will fix by itself.
- Risk
- Low
Needs a plan that includes the StudioReads onlyrender_videoExport a Studio video
Exports a project to an MP4 or a PNG in the library, ready to go in a post. First it brings the project to the quality floor by itself (captions, a hook, music under the voice, transitions inside their caps) and keeps that as a version called Quality pass; it never touches what you made by hand.
- Risk
- High
Needs a plan that includes the Studiogenerate_imageGenerate an image
Makes a new image from a description, in one of the workspace's styles if asked. Uses 10 AI credits. If the request is about pictures the library already has, it lists them first and spends nothing.
- Risk
- High
Needs a plan that includes the StudiomascotChoose the mascot
Reads or sets the workspace's mascot: an animated SVG host that speaks, blinks and takes poses in a video. Free, no AI credits. Pick a built-in one, tint it with the brand colours or use your own drawing.
- Risk
- Medium
Needs a plan that includes the Studiouse_skillRead the workspace's editing skills
Lists the workspace's editing skills (a creator's playbooks: a look, a pacing, a recipe) or reads one in full, so the agent follows it when it makes or edits a video.
- Risk
- Low
Needs a plan that includes the StudioReads onlysave_skillKeep an editing skill
Creates, changes, imports from a SKILL.md or deletes an editing skill of the workspace. Its description decides when it is used.
- Risk
- Medium
Needs a plan that includes the Studio
The usual path
An agent starts with overview for the time zone, the clock and the accounts, finds things with search, reads one in full with fetch, and changes it with save_post or another tool. Every answer says what can be done next.
Names, not ids
Tools take what a person would say: an exact file name, an @handle, a campaign's name, or a link to anything in SPREVA, pasted from the browser or from an earlier answer. Searching is forgiving and changing is not: a name that matches several things comes back as a choice, and nothing is saved until one is chosen.
Reference for agents
An agent reads SPREVA's reference with fetch when it needs it, rather than carrying it in every call:
spreva://docs/platforms/tiktok, and one page per network: what it accepts, lengths and options.spreva://docs/queues: times, time zones and queues.spreva://docs/agent-permissions: risk levels, confirmations, revisions and request ids.spreva://docs/studio/makingandspreva://docs/studio/editing: building a video, on SPREVA only.