Turn long podcast episodes, video or audio, into captioned vertical clips and transcripts.
Scored across 22 tools
Most tools have clearly distinct purposes and the descriptions explicitly cross-reference each other (e.g. cut_words/set_trim/edit_captions/set_caption_style are framed as the no-render edits vs. restyle_clip which re-renders, and transcribe_audio vs. start_episode vs. transcription_status are separated by explicit 'do not use' notes). The weaker spot is the style cluster — get_visual_style, list_styles and suggest_visual_styles all deal with looks, and edit_captions vs. set_caption_style overlap conceptually, though the descriptions do resolve them. An agent can pick correctly with careful reading, but a few pairs would benefit from sharper boundaries.
Almost everything is consistent snake_case with a verb_noun shape: get_episode, get_job, get_clip_edit, make_clips, cut_words, edit_captions, restyle_clip, start_episode, set_trim, set_frame, undo_edit. The only real deviations are the bare-noun templates and the status-style transcription_status. Predictable enough that an agent can guess names from intent.
At 22 tools this is on the heavy side, but the surface spans genuinely different jobs: episode ingest, clip discovery, clip making, stepwise clip editing, styling/framing, templates, transcription, jobs and undo. Each tool earns a place in that workflow rather than being artificially split; a couple of style/template tools could in principle be consolidated to trim the set.
The lifecycle is well covered end to end: start_episode -> get_episode -> find_clips_about -> make_clips -> per-field edits (cut_words, set_trim, edit_captions, set_caption_style, set_frame, set_hook_title) -> restyle_clip/get_job -> undo_edit, plus transcription and template save/apply. Gaps are minor: no explicit delete/cleanup for clips or episodes, no share/publish tool despite the 'share the results page instead' advice in email_transcript, and no way to cancel an in-flight job.
Use this when the person wants to remove words, every filler, or long pauses from a made clip, the way the Slice editor's clean-up does: the sound and the captions both, with breathing room kept so it never sounds choppy. Pass words as a list of indexes from get_clip_edit, or {"fillers": true}, or {"pauses_over_seconds": 0.8}. restore: true puts those cuts back. Saves the clip only, no render: the person sees it in Slice at once and can undo. Export once at the end.
| Name | Required | Description | Default |
|---|---|---|---|
| words | Yes | Word indexes from get_clip_edit, or {"fillers": true}, or {"pauses_over_seconds": n}. | |
| clip_id | Yes | The clip's id (from get_episode, get_job or the Slice link). | |
| restore | No | Put these cuts back instead. |
| Name | Required | Description |
|---|---|---|
| clip_id | No | |
| open_in_slice | No | The clip in the Slice editor, where the person sees the change. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: it discloses that both sound and captions are cut, that padding is retained so the result isn't choppy, that only the clip is saved with no render, that the change is immediately undoable in Slice, and that export happens once at the end. That reconciles the mutation with destructiveHint=false and gives the agent a real picture of side effects and workflow.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the trigger condition and then the input forms, restore, and save-vs-render semantics in a tight sequence. A few phrases ("the way the Slice editor's clean-up does", "so it never sounds choppy") are colorful rather than load-bearing, and the parameter forms duplicate the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained; the description instead covers the things structure can't: what gets modified, reversibility, that no render occurs, and the export-at-the-end workflow. Nothing an agent needs to invoke this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description's three input forms (index list, {"fillers": true}, {"pauses_over_seconds": 0.8}) restate the schema's words description almost verbatim, as does restore: true. The only added nuance is the padding/breathing-room behavior around cuts. Baseline 3 is appropriate when the schema already carries the parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (cut words or pauses from a clip) and immediately narrows scope: it removes words, all fillers, or long pauses, affecting both audio and captions. That contrasts implicitly with caption-only or trim-only siblings, so an agent can tell what this tool does and does not touch.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Opens with an explicit trigger ("Use this when the person wants to remove words, every filler, or long pauses from a made clip") and covers the inverse operation via restore: true. It also routes the agent to get_clip_edit for word indexes. It does not explicitly exclude near neighbors like edit_captions or set_trim, which keeps it short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the person wants to change captions on a made clip, applied in order. Word indexes and seconds come from get_clip_edit. set_text {word, text} fixes a word; split {word} starts a new caption at it; join {word} joins its caption to the one before; line_break {word} breaks the line before it inside the caption; insert {at_seconds, text, duration_seconds?, lane?} adds a caption where none was heard; delete {word} removes the caption that word is in (the sound stays) and restore {word} brings it back; hide / show {from_word, to_word} over a stretch; retime {word, start_seconds?, end_seconds?} moves a caption's edges; shift {word, by_seconds} slides it; set_lane {word, lane: 1 or 2} puts it on the first or second line of captions; place {word, x?, y?} puts that caption at a spot (fractions of the frame, null puts it back in line); move {direction: up or down} moves all captions; words_per_caption {n: 1 to 7}; split_by_speaker puts the second voice on lane 2. Saves the clip only, no render.
| Name | Required | Description | Default |
|---|---|---|---|
| ops | Yes | ||
| clip_id | Yes | The clip's id (from get_episode, get_job or the Slice link). |
| Name | Required | Description |
|---|---|---|
| clip_id | No | |
| open_in_slice | No | The clip in the Slice editor, where the person sees the change. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, it discloses that edits save the clip without rendering, that operations apply in order, and that delete removes only the caption while restore brings it back. It does not cover error behavior or undo semantics, but the added context is substantial for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but free of filler, and the use case is front-loaded. However, the long run-on enumeration of sixteen operations is harder to scan than a structured list would be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex multi-op mutation tool with an output schema, the description covers the essential context: when to use it, where word/seconds indexes come from, what each operation does, and that it only saves the clip. Nothing critical for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has only 50% description coverage, and the description compensates extensively by explaining each op's arguments and meaning: word indexes from get_clip_edit, seconds, lane 1/2, fractional x/y placement, words_per_caption 1–7, and split_by_speaker behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource: changing captions on a made clip. It also clarifies that operations are applied in order, which distinguishes it from reading captions or changing caption style.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear when-to-use condition ('when the person wants to change captions on a made clip') and a prerequisite source for indexes ('get_clip_edit'). It does not explicitly name when-not-to-use or alternative sibling tools, so it falls short of the highest bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this only when the user explicitly asks for a finished transcript to be emailed to them. Needs a Slice sign-in, asked for on first use, and sends the .txt, .srt and .vtt files only to the confirmed email address on that Slice account, never to another address. Each transcript can be emailed one time, and only from the conversation or account that made it. Do not use to send a transcript to somebody else; share the results page instead.
| Name | Required | Description | Default |
|---|---|---|---|
| transcription_id | Yes | The transcription_id of a finished transcript. |
| Name | Required | Description |
|---|---|---|
| status | Yes | |
| message | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say readOnlyHint=false, destructiveHint=true, openWorldHint=true; the description goes well beyond that with the Slice sign-in requirement on first use, the hard-coded destination (only the confirmed email on that account, never another address), the one-time-per-transcript limit, and the requirement that it be sent from the originating conversation or account. These are exactly the operational constraints an agent cannot infer, and nothing contradicts the destructive/open-world hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, each carrying a distinct constraint (eligibility, auth, destination, lifetime) with the most important gating rule front-loaded. No filler or repetition of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one simple parameter, full schema coverage, and an output schema (so return values need no explanation), the description covers everything an agent needs: prerequisites, destination restriction, idempotency limit, and the negative case routing to sharing. Nothing material is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single parameter (transcription_id) is already documented in the schema as a finished transcript's ID. The description reinforces 'finished transcript' but adds no syntax, format, or sourcing detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb+resource ('email a transcript') and immediately scopes it to a finished transcript. It also implicitly separates itself from creation tools like transcribe_audio and transcription_status by requiring an already-finished transcript as input.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit trigger ('only when the user explicitly asks for a finished transcript to be emailed'), explicit exclusions ('Do not use to send a transcript to somebody else'), and a named alternative action ('share the results page instead'). It also states the per-transcript and per-account conditions that gate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants clips from an episode on a particular topic or for a particular audience, e.g. "clips about creativity for artists" or "moments for young entrepreneurs". Searches the episode again for moments that fit the focus, skipping clips already found, and adds what it finds to the episode's clips. It may find fewer than usual, or none, when little in the episode fits; say so plainly. Returns each new clip's number, ref, title and why it fits. Takes about a minute; if it is still searching, call it again with the same focus to wait for the result. Do not use before get_episode reports the episode ready.
| Name | Required | Description | Default |
|---|---|---|---|
| focus | No | What to look for, in the user's words: a topic or an audience. Optional when target_seconds is given. | |
| episode_id | Yes | The episode to search. | |
| target_seconds | No | Optional. How long each clip should be, in seconds (15 to 180), when the user asks for a length, e.g. "30 second clips". Every clip found then plays for at most this long and at most 10% less (at least 3 seconds less), cut at clean sentence or pause boundaries; fewer clips come back if few moments fit. Leave it out for clips of any length (30 to 150 seconds). Works with or without a focus. |
| Name | Required | Description |
|---|---|---|
| clips | No | |
| focus | No | |
| found | No | How many new clips fit the focus. |
| status | Yes | |
| message | Yes | |
| episode_id | Yes | |
| target_seconds | No | The clip length searched for; null for any length. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false with destructiveHint=false, and the description is consistent, explaining exactly what mutates (new clips are appended to the episode's clip set) and that already-found clips are skipped. It further discloses failure modes ('may find fewer than usual, or none... say so plainly') and latency ('takes about a minute; if still searching, call it again with the same focus') — context annotations cannot carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the use case, then behavior, return fields, latency, and the precondition in roughly that priority order. Every sentence carries operational information — no filler or restatement of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, yet the description still names the returned fields (number, ref, title, why it fits) at low cost, and covers preconditions, mutation semantics, latency, and the sparse-result case. Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description still adds value by clarifying the retry semantics tied to the focus parameter (call again with the same focus to wait) and framing focus as the user's own words. The target_seconds behavior is mostly documented in the schema itself, so this is additive rather than essential.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific action (searches the episode for moments matching a topic/audience and adds them as clips), a concrete resource (episode clips), and a scope constraint (skips clips already found). The example phrasings 'clips about creativity for artists' make it immediately distinguishable from make_clips and restyle_clip.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit trigger ('when the user wants clips from an episode on a particular topic or for a particular audience') and an explicit precondition/exclusion ('Do not use before get_episode reports the episode ready'). It also covers the retry case: call again with the same focus while searching.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when you are about to fix a made clip, first: returns every word with its index, text and times on the clip (seconds), whether it is a filler ("um"), whether a long pause follows it, and whether it is already cut; plus the hook title, the caption look, the trim, the frame (shape, layout, crop, moves, split, speaker follow, logo, end frame), a one-line summary ("14 ums, 3 pauses over 0.6 s") and any notes the person sent you from Slice. Changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| clip_id | Yes | The clip's id (from get_episode, get_job or the Slice link). |
| Name | Required | Description |
|---|---|---|
| clip_id | No | |
| open_in_slice | No | The clip in the Slice editor, where the person sees the change. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description reinforces this with "Changes nothing" and adds what data is returned, but does not disclose extra behavioral details such as permissions, rate limits, or limitations beyond the annotation-covered read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but front-loads the usage condition and then lists relevant returned data compactly. The parenthetical list is information-rich, though the single long sentence could be easier to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description does not need to enumerate return values, but it helpfully summarizes them. It covers the tool's role, read-only behavior, and enough context for an agent to call it correctly before editing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the single clip_id parameter is fully documented in the schema. The description does not add syntax or format details beyond what the schema provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: it returns word-level clip data plus hook, caption, trim, frame details and notes for a made clip. It clearly distinguishes this preparatory read from the many editing siblings by saying to use it when you are about to fix a clip.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear when-to-use context: before editing a made clip, and specifies that it changes nothing. It does not explicitly name alternatives or when-not-to-use, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user asks how an episode is going, whether it is ready, or what clips were found. Returns one status for the whole pipeline (waiting_for_upload, uploading, transcribing, finding_clips, ready or failed) and, once ready, the found clips with number, ref, title, opening line, length and whether each has been cut and captioned. With no episode_id it lists recent episodes. Read the live answer from here rather than guessing how long things take. Do not use for transcripts made with transcribe_audio.
| Name | Required | Description | Default |
|---|---|---|---|
| episode_id | No | From start_episode, or from this tool with no id. |
| Name | Required | Description |
|---|---|---|
| name | No | |
| clips | No | |
| status | Yes | |
| message | Yes | |
| duration | No | Episode length, mm:ss. |
| episodes | No | |
| episode_id | No | |
| upload_url | No | |
| progress_percent | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds real behavioral substance on top: the full status state machine, the fact that clip fields only appear once ready, and the fallback listing behavior. It stops short of stating pagination limits or how stale the status may be.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with the trigger and the return shape, then fallback and exclusion. The enumeration of clip fields is somewhat list-heavy but each item is load-bearing for deciding whether the tool answers the user's question. No filler or restatement of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be fully restated, and the annotations carry the safety profile. The description still covers triggers, exclusion, fallback behavior and the status vocabulary, leaving nothing an agent needs in order to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single optional episode_id, so the baseline is already 3. The description goes beyond the schema by explaining the consequence of omitting it ('With no episode_id it lists recent episodes'), which is behavior the parameter definition alone does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('get an episode') plus the exact artifact returned: one pipeline status from a closed set of six states, and the clip metadata once ready. It explicitly distinguishes itself from the siblings that could be confused with it, naming transcribe_audio as out of scope and pointing at get_job/transcription_status-adjacent behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Opens with the trigger conditions ('when the user asks how an episode is going, whether it is ready, or what clips were found'), supplies an exclusion ('Do not use for transcripts made with transcribe_audio'), and explains the no-argument fallback. It also tells the agent to prefer this live read over estimating timing, which is actionable routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants to know whether a clip is cut or rendered, or wants the finished file. Pass the job_id from make_clips or restyle_clip, or a clip_id for that clip's latest render. Returns the status, progress, a still from the clip and, when finished, a short download link. Pass wait: true to hold on up to about 40 seconds for it to finish. Do not use for transcribe_audio jobs.
| Name | Required | Description | Default |
|---|---|---|---|
| wait | No | Wait briefly for it to finish instead of reporting now. | |
| job_id | No | From make_clips or restyle_clip. | |
| clip_id | No | A cut clip, for its latest render. |
| Name | Required | Description |
|---|---|---|
| kind | Yes | |
| clips | No | For a cut: the clips it made, and the render that follows each. |
| stage | No | The step the job is on, as the worker reports it. |
| title | No | |
| job_id | Yes | |
| status | Yes | |
| clip_id | No | |
| message | Yes | |
| poster_url | No | |
| download_url | No | A short link that downloads the MP4. Good for 7 days. |
| file_size_mb | No | |
| progress_percent | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the description is free to add what they can't: the response payload (status, progress, still, download link) and the blocking behavior of wait: true ('hold on up to about 40 seconds'). The latency disclosure is exactly the kind of trait annotations cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the use case, then input sourcing, then return shape, then the wait flag, then the exclusion. Every sentence carries distinct information with no restatement of the name or title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return values are technically optional to describe, yet the description still previews them usefully. Combined with input sourcing, the exclusion, and the wait-time bound, nothing an agent needs to invoke this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description goes beyond it: it tells the agent where each ID comes from and quantifies wait as 'about 40 seconds' where the schema only says 'briefly'. Only the mutual exclusivity of job_id vs clip_id is left implicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('know whether a clip is cut or rendered, or wants the finished file') for a job-status tool. It names the siblings that produce a job_id (make_clips, restyle_clip) and explicitly rules out transcribe_audio jobs, so an agent can separate it from transcription_status without reading schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete triggering conditions, two alternative input paths (job_id from a creation tool, or clip_id for the latest render), and an explicit exclusion: 'Do not use for transcribe_audio jobs.' That is when/when-not/alternatives all in one place.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone gives a Slice style ref (like "sref-V4RYN2"), names a style from tryslicemedia.com/styles, or pastes a prompt that says to call get_visual_style. Returns the style's look and feel: palette, materials, motion and type rules, what it suits, how to use it in a clip, and the STORY FIRST rules. A style is a moodboard, never a template: keep its look and invent your own scenes for the clip. Accepts the code or the style's slug.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | The style ref ("sref-V4RYN2") or the style's slug ("torn-newsprint"). |
| Name | Required | Description |
|---|---|---|
| style | No | The full style record. |
| message | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is settled. The description adds genuinely useful semantics beyond that: a style is a moodboard rather than a template, and the look should be kept while scenes are invented. It does not mention lookup-failure behavior for an unknown code, which would be the next useful detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the trigger conditions, then the payload, then the usage philosophy — a sensible order with no filler sentences. The 'moodboard, never a template' line is slightly editorial but carries real invocation-relevant meaning, so it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description need not enumerate return fields, yet it summarizes them in a way that tells the agent how to apply the result to a clip. Combined with trigger conditions and input forms, an agent has enough to call it correctly; only error/not-found behavior is unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single parameter already documents both accepted forms (sref code or slug) with examples. The description's closing sentence repeats that fact rather than adding format rules, so it sits at the baseline where the schema does the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb and resource (get_visual_style → a Slice visual style) and enumerates exactly what comes back: palette, materials, motion and type rules, fit, clip usage, STORY FIRST rules. This clearly separates it from siblings like list_styles (enumerate) and restyle_clip (apply).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives three concrete trigger conditions (an sref-style code, a named style from tryslicemedia.com/styles, or an explicit prompt instruction), which is well above typical. It stops short of naming alternatives such as list_styles or suggest_visual_styles and when to prefer them, so it is not a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants to know which caption looks they can choose from. Returns each style's id, name, a one-line description and a link to a preview picture. Pass styles to look up particular ones. Do not use to change a clip (use restyle_clip or make_clips).
| Name | Required | Description | Default |
|---|---|---|---|
| styles | No | Ids or names to look up. Default all. |
| Name | Required | Description |
|---|---|---|
| notes | No | |
| styles | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds the lookup-by-id-or-name behavior, but its enumeration of return fields (id, name, description, preview link) duplicates what the existing output schema already provides. With annotations doing the heavy lifting, this is adequate but adds little beyond structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences: intent first, then behavior, then the negative routing. Every sentence earns its place, though the return-field enumeration partially duplicates the output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only lookup with an output schema, the description covers intent, filtering behavior and alternative tools. Return values need not be explained since the output schema exists, so nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and there is a single optional parameter already documented as 'Ids or names to look up. Default all.' The description's 'Pass styles to look up particular ones' restates the same filtering semantics without adding format, matching rules, or error behavior. Baseline 3 is correct when the schema carries the parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List caption styles') and immediately frames the user intent it serves ('which caption looks they can choose from'). It also names the siblings it is not (restyle_clip, make_clips), so an agent can separate it from nearby tools without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use it (user wants to know available caption looks) and when not to (changing a clip), routing to two named alternatives. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user picks found clips to make. Cuts each one from the episode and renders it with captions burned in, in one step. Pass the numbers or refs get_episode listed (refs in brackets are fine), or any stretch of the episode as {"start_seconds", "end_seconds", "title"}. Optional style, caption_size, position, hook_title, fit and background apply to these clips. aspect is the shape: 9:16 (Shorts, Reels, TikTok), 4:5 (feeds), 1:1, 16:9 (YouTube) or source. Ask the person which shape before calling; with no aspect the clips are 9:16. Returns a job per clip; follow with get_job for the files. Do not use before get_episode reports the episode ready, and do not use to change a clip that is already made (use restyle_clip).
| Name | Required | Description | Default |
|---|---|---|---|
| fit | No | How the picture sits in the frame. "fill" (the default) crops it to fill the frame. "whole" shows the whole video, nothing cropped, with space around it; use when the user does not want a wide video cropped. | |
| clips | Yes | Numbers or refs from get_episode, e.g. [2, 5] or ["a3f9"], or stretches {"start_seconds": 312, "end_seconds": 371, "title": "..."} on the episode. Up to 10. | |
| style | No | A caption style id or name from list_styles, e.g. bold-punch. | |
| aspect | No | The clip's shape. Ask the person first; 9:16 when left out. | |
| position | No | Where the captions sit. "up" and "down" move them from where they are now. | |
| background | No | What fills the space around a whole video: "black", or "blur" for a blurred copy of the video. Only matters with fit "whole". | |
| episode_id | Yes | The episode the clips were found in. | |
| hook_title | No | The title box at the top of the clip, on by default for new clips. false removes it, true puts the clip's title there, or give the words to show. | |
| caption_size | No | Caption size. "bigger" and "smaller" are relative to now. |
| Name | Required | Description |
|---|---|---|
| clips | Yes | |
| notes | No | |
| aspect | No | The shape the clips are made in. |
| message | Yes | |
| episode_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already declaring non-read-only and non-destructive, the description adds real context: captions are burned in, cutting and rendering happen in one step, a job is returned per clip and must be followed up with get_job. It omits anything about render time, cost, or whether partial failures leave clips behind, which keeps it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the action and one-step behavior, then parameter guidance, then guardrails. It is on the long side and repeats the aspect/default point already in the schema, but every sentence carries operational information rather than filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the full call-and-follow-up loop for a job-returning render tool (get_job), states the readiness precondition, names the escape hatch for edits, and answers the aspect question an agent would otherwise have to ask twice. With an output schema present, no return-value explanation is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description still adds value the schema cannot: aspects are mapped to real destinations (9:16 for Shorts/Reels/TikTok, 4:5 for feeds, 16:9 for YouTube), the 9:16 default is restated, and the optional style/caption_size/position/hook_title/fit/background group is framed as applying to these clips. It also clarifies that bracket refs from get_episode are acceptable input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb and resource ('Cuts each one from the episode and renders it with captions burned in, in one step') and clearly scopes it as the creation step distinct from restyle_clip and get_episode. An agent can tell exactly what this produces without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States the trigger ('use this when the user picks found clips to make'), the prerequisite ('do not use before get_episode reports the episode ready'), and the explicit alternative for later changes ('use restyle_clip'). It also adds a procedural rule the agent would otherwise miss: ask the person which aspect ratio before calling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user asks what a clip says, what is on screen at a particular moment, which caption contains a word or a typo, or who said something. It is also the only way to get a caption's id, so read it first whenever a later step needs to name one caption. Narrow with at_seconds, a from/to range, or contains. Do not use for a transcript made with transcribe_audio, or to find clips (use get_episode).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Up to 200. Default 40. | |
| clip_id | Yes | A made clip's clip_id, from get_episode or get_job. | |
| contains | No | Only captions containing this text. Case-insensitive. | |
| at_seconds | No | Only the caption(s) on screen at this moment, in seconds. | |
| to_seconds | No | End of a time range, in seconds. | |
| from_seconds | No | Start of a time range, in seconds. | |
| include_removed | No | Include captions the editor has removed. They are not in the video. Default false. |
| Name | Required | Description |
|---|---|---|
| name | No | |
| total | No | Captions matching, before the limit. |
| clip_id | Yes | |
| message | Yes | |
| captions | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful non-schema context: it is the only route to a caption id and should be called before any dependent step. It does not discuss result volume or pagination behavior beyond the schema's limit, hence not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the primary use case and efficiently packed; the sequencing rule and the exclusion clause each earn their place. It reads slightly list-like with multiple parallel question framings, but there is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With full schema coverage, a rich annotation set, and an output schema, the description only needs to cover selection and sequencing, which it does thoroughly. Nothing an agent needs to invoke this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter is already documented with type, default, and meaning. The description restates the three narrowing parameters (at_seconds, from/to range, contains) without adding semantics beyond the schema, which matches the baseline 3 when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (read) and resource (captions on a clip) and enumerates the question types it answers, making its scope concrete. It explicitly distinguishes itself from transcribe_audio output and from get_episode, so an agent can separate it from siblings without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use cases (what a clip says, on-screen moment, word/typo lookup, speaker attribution), an ordering rule (read first to obtain caption ids), narrowing strategies, and explicit when-not-to-use guidance naming the correct alternatives (transcribe_audio, get_episode).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants a made clip changed and rendered again: a different caption style, bigger or smaller captions, captions moved up or down, the hook title turned on, off or reworded, or the whole video shown instead of cropped (fit, background). The change is saved on the clip and a new render starts; follow with get_job. When the user wants the look kept for future clips, pass save_as_default (new clips then start from it). Do not use for clips that have not been made yet (use make_clips). When the person is watching in Slice and you are fixing a clip step by step, prefer the tools that change the saved clip without a render (cut_words, set_hook_title, edit_captions, set_trim, set_caption_style, set_frame) and export once at the end: export true with nothing else makes the video from the clip exactly as it stands.
| Name | Required | Description | Default |
|---|---|---|---|
| fit | No | How the picture sits in the frame. "fill" (the default) crops it to fill the frame. "whole" shows the whole video, nothing cropped, with space around it; use when the user does not want a wide video cropped. | |
| style | No | A caption style id or name from list_styles, e.g. bold-punch. | |
| export | No | True with nothing else to change: make the video from the clip as it stands now (after edits with the no-render tools). | |
| clip_id | Yes | The clip_id from get_episode or get_job (or the job_id of its render). With episode_id, the clip's number or ref also works. | |
| position | No | Where the captions sit. "up" and "down" move them from where they are now. | |
| background | No | What fills the space around a whole video: "black", or "blur" for a blurred copy of the video. Only matters with fit "whole". | |
| episode_id | No | Only needed when clip_id is a number or ref from get_episode. | |
| hook_title | No | The title box at the top of the clip, on by default for new clips. false removes it, true puts the clip's title there, or give the words to show. | |
| caption_size | No | Caption size. "bigger" and "smaller" are relative to now. | |
| save_as_default | No | True when the user wants this look kept for future clips ("use this from now on", "save this style"). Can be sent with no other change to keep the clip's current look. |
| Name | Required | Description |
|---|---|---|
| job_id | Yes | Pass to get_job. |
| status | Yes | |
| changes | Yes | |
| clip_id | Yes | |
| message | Yes | |
| saved_as_default | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations establish it is a non-read-only, non-destructive local action; the description adds the key side effects an annotation cannot cover: the change is saved on the clip and a new render starts, followed by get_job. It further explains that save_as_default persists the look to future clips, and clarifies the export-only path.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the trigger and the editable dimensions, then routing to alternatives, then the export path. It is dense and long but nearly every clause carries routing or behavioral information; only the parenthetical tool list is slightly bulky.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 10 parameters, 100% schema coverage, annotations, and an output schema, the description supplies the remaining context: render side effect, follow-up with get_job, persistence semantics, and the no-render alternative workflow. Nothing needed to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so the baseline is 3, but the description adds meaning about relative edits ('bigger or smaller captions', 'captions moved up or down'), the boolean-or-string form of hook_title, and the interaction between fit and background. It stops short of adding syntax beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb and resource ('restyle a clip') and enumerates the exact changes it can make: caption style, size, position, hook title, fit/background. It also explicitly separates itself from make_clips (unmade clips) and the no-render edit tools, so an agent can pick it correctly without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use ('user wants a made clip changed and rendered again'), when-not ('clips that have not been made yet (use make_clips)'), and named alternatives for step-by-step editing with a single export at the end. The save_as_default condition is also stated in user-language terms.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the person wants to change a made clip's captions, anything a person can change by hand, without a render: style (list_styles names), size (smaller, bigger, small, medium, large, extra_large), position (up, down, top, middle, lower, bottom) or an exact height (caption_y, e.g. to keep them clear of a scene's drawing), colour, highlight colour, font, case, outline, shadow, words per line, captions off, and stretches with no captions (hide: where a scene already writes the words on screen, so they are not shown twice); also weight, italic, size_fraction, appearance (how words appear: word by word, karaoke, typewriter...), card (a box behind the words), letter, word and line spacing, effect (glow, gradient, echo, depth, knockout), highlight_block and highlight_size for the highlighted word, blur in and out, arrangement (a stacked layout), colour_by_speaker and reset. scope {from_word, to_word} gives just those captions their own look; words [{word, color, size, weight, font, italic, case, highlight, big}] styles single words. list_styles kinds font, appearance, effect and arrangement list the choices. A clip with scenes from you follows the change. Use restyle_clip only when the person wants a new video made straight away.
| Name | Required | Description | Default |
|---|---|---|---|
| blur | No | Words blur in and out: false, true, or { "in", "out", "strength": "soft" | "full" }. | |
| card | No | A box behind the words: false, true, or { "color", "opacity" 0-1, "padding" 0-1.5, "radius" 0-1.5 }. | |
| case | No | ||
| font | No | One of Slice's caption fonts: Inter, Montserrat, Poppins, Sora, TeX Gyre Heros, DM Sans, IBM Plex Mono, JetBrains Mono, Courier Prime, Anton, Bebas Neue, Oswald, Nunito, DM Serif Display, Instrument Serif, Cormorant Garamond, Lora, Libre Baskerville, Merriweather, Playfair Display, Space Mono, Pacifico, Courgette, Satisfy, Dancing Script, Kaushan Script, Yellowtail, Grand Hotel, Parisienne, Caveat, Archivo Black, Barlow Condensed, Baloo 2, Anybody, Archivo, Bricolage Grotesque, Epilogue, Figtree, Manrope, Outfit, Plus Jakarta Sans, Space Grotesk, Urbanist, Bitter, Bodoni Moda, EB Garamond, Fraunces, Libre Bodoni, Newsreader, Spectral, Young Serif, Zilla Slab, Alfa Slab One, Big Shoulders Display, Black Ops One, Bungee, Fjalla One, Fugaz One, Lilita One, Passion One, Rubik Mono One, Staatliches, Teko, Titan One, Ultra, Abril Fatface, Bungee Inline, Lobster Two, Lobster, Monoton, Poiret One, Sacramento, Silkscreen, Yeseva One, Amatic SC, Bangers, Caveat Brush, Chewy, Fredoka, Gloria Hallelujah, Indie Flower, Luckiest Guy, Patrick Hand, Rock Salt, Shrikhand, Sriracha, Audiowide, Chakra Petch, Major Mono Display, Michroma, Orbitron, Rajdhani, Share Tech Mono, VT323, Heebo, Rubik, Assistant, Frank Ruhl Libre, Secular One, Suez One. | |
| hide | No | Stretches (seconds on the clip) with no captions, e.g. where a scene already writes the words on screen. Replaces the clip's hidden stretches; [] shows captions everywhere again. | |
| color | No | The caption words' colour, "#rrggbb". | |
| reset | No | "look" (back to the style's own look), "captions" (every caption back on the clip's look), "positions" (captions placed by hand back in line) or "all". | |
| scope | No | Give only the captions holding these words this look (colour, font, case, weight, size, outline, shadow, card, effect, appearance...). | |
| style | No | ||
| words | No | Looks for single words (index from get_clip_edit): colour, size (0.5 to 3 times), weight, font, italic, case, highlight, big (the one big word of a Big word caption). | |
| effect | No | none, glow, gradient, echo, depth or knockout, or { "type", "color", "color2" }. | |
| italic | No | ||
| shadow | No | false, true, or { "color": "#rrggbb", "blur": 0 to 0.5, "offset_y": 0 to 0.3 }. | |
| weight | No | 100 to 900; snapped to the weights the font has. | |
| clip_id | Yes | The clip's id (from get_episode, get_job or the Slice link). | |
| outline | No | false, true, or { "width": 0 to 0.3 (fraction of the font size), "color": "#rrggbb" }. | |
| captions | No | Captions on or off for the whole clip. | |
| position | No | ||
| caption_y | No | The caption block's centre: a fraction of the frame's height (0.7) or px of 1920 (1340). Kept inside Instagram's safe area. On a clip with scenes from you it holds on every scene. | |
| hide_also | No | Stretches to add to the hidden ones. | |
| appearance | No | How the words appear: phrase, fade, rise, pop (word by word), bounce, karaoke, word (one at a time), typewriter, punch, slide, sweep, around. | |
| arrangement | No | A stacked layout id (list_styles kind "arrangement"), or null to take it off. | |
| line_height | No | 0.7 to 2; null for the style's own. | |
| caption_size | No | ||
| word_spacing | No | em, -0.2 to 1; null for the style's own. | |
| size_fraction | No | Exact caption size: a fraction of the frame height, 0.015 to 0.15 (0.05 is large). | |
| highlight_size | No | The highlighted word's size, 0.5 to 3 times the others. | |
| letter_spacing | No | em, -0.1 to 0.5; null for the style's own. | |
| words_per_line | No | At most this many words a caption line, 1 to 7, or "auto". | |
| highlight_block | No | A block behind the highlighted word: false, true, or { "color", "opacity", "padding", "radius" }. | |
| highlight_color | No | The highlighted word's colour, "#rrggbb". | |
| colour_by_speaker | No | true gives each voice its own colour, false takes it off, or { "<voice>": "#rrggbb" }. |
| Name | Required | Description |
|---|---|---|
| clip_id | No | |
| open_in_slice | No | The clip in the Slice editor, where the person sees the change. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish that this is a non-read-only, non-destructive, closed-world mutation. The description adds significant behavioral context beyond annotations: changes happen without a render, scope limits the effect to selected words, hide replaces the clip's hidden stretches, reset has specific meanings, and clips with generated scenes follow the change. It stops short of covering permission needs or full reversibility, so it is strong but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The when-to-use guidance is front-loaded, and the length is partly justified by 32 parameters. However, nearly all parameter semantics are packed into one run-on paragraph with semicolons and parentheticals, making it hard for an agent to scan and parse the different option groups.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the description covers the essential decision context, the main parameter families, scoping behavior, hide semantics, reset semantics, and the key sibling alternative. An output schema exists, so the description does not need to explain return values, and the remaining details are handled by the rich input schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already high, but the description adds domain meaning: style names come from list_styles, size and position accept specific named values, caption_y can keep captions clear of a scene's drawing, hide is for stretches where a scene already shows words, scope applies styling to a word range, and words applies styling to individual words. It covers most parameter groups, though the single dense sentence is less precise than the schema for several nested options.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: change a made clip's captions look, including style, size, position, colour, effects, and per-word or per-range styling. It explicitly distinguishes itself from restyle_clip, so an agent can identify the correct tool without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear when-to-use condition: the person wants to change an already made clip's captions by hand without a render. It also names the alternative and its selecting condition: use restyle_clip only when a new video should be made straight away.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the person wants to change how a made clip's picture is framed, anything the Slice editor's Frame tab and Layouts do, with no render. aspect: 9:16, 4:5, 1:1, 16:9, 3:4, source (ask the person which shape first). layout: follow-speaker, follow-both, two-people, face-on-top, face-corner, speaker-slides, fill, whole-blur, whole-black (list_styles kind "layout" says what each is; split screens are 9:16 only). fit (fill or whole) and background (black or blur); crop {scale 1-5, x, y} moves and zooms the picture; frame_on {x, y?, scale?} frames ONE person of a wide shot (x: where their face is across the whole picture, 0 left to 1 right; look at a frame first): a fixed crop that never moves to whoever is talking, so use it, not follow, when the person names who to show. The storyboard (scenes, splits, boxes) uses the clip's frame too. moves [{at_seconds, scale, x, y}] reframe part-way through ([] removes them); split {share, swap, border, corner_size} adjusts a split screen; follow speaker, both or off (Slice finds who is talking, as the editor's Follow the speaker does); logo "brand", false or {path, x, y, width, opacity}; end_frame "brand", false or {path, kind, duration_seconds}. Saves the clip only: the person sees it in Slice and can undo.
| Name | Required | Description | Default |
|---|---|---|---|
| fit | No | ||
| crop | No | scale 1 fills the frame, up to 5; x and y -1 to 1 move the picture (0 is centred). | |
| logo | No | "brand" (the account's logo), false (none), or { "path" (a file in this account), "x", "y" (0-1, its centre), "width" (0.04-0.6), "opacity" (0-1) }. | |
| moves | No | Camera moves: from at_seconds on, the picture is framed like this. Replaces the clip's moves. | |
| split | No | ||
| aspect | No | ||
| follow | No | ||
| layout | No | ||
| clip_id | Yes | The clip's id (from get_episode, get_job or the Slice link). | |
| frame_on | No | Frame one person: x (and optionally y) is where their face is in the whole source picture, 0 to 1; scale 1 fills the frame. A fixed crop: speaker follow goes off. | |
| end_frame | No | "brand" (the account's end card), false (none on this clip), or { "path", "kind": "image" | "video", "duration_seconds" }. | |
| background | No |
| Name | Required | Description |
|---|---|---|
| clip_id | No | |
| open_in_slice | No | The clip in the Slice editor, where the person sees the change. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the write profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds real context beyond that: no render, it saves the clip only, effects are visible in Slice and undoable, and it discloses cross-cause effects (frame_on switches follow off; moves replaces existing moves; the storyboard inherits the clip's frame). It does not cover rate limits, auth, or failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the when-to-use clause and sized appropriately for a 12-parameter tool, with no filler sentences. It is one dense paragraph of semicolon-separated clauses, though, so an agent parsing specific parameters must scan long parentheticals rather than structured lines.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 12-parameter mutation tool with nested objects, it covers every top-level parameter, their interactions, and the persistence/undo story; an output schema exists, so return values need no explanation. Nothing essential to invoking it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 12 parameters and only 50% schema description coverage, the description does heavy lifting: it explains each layout name's intent, lists valid aspect shapes, defines fit/background, ties split screens to 9:16, explains moves as a replacing list where [] clears it, and clarifies where logo/end_frame accept "brand" vs false vs an object. That is substantially more than the schema alone, though some nested fields (split.share, split.border) remain only implicitly defined.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — change how a made clip's picture is framed, i.e. what the Slice editor's Frame tab and Layouts do — and notes 'with no render', which separates it from render-producing siblings like make_clips or restyle_clip. An agent can distinguish it from set_trim and set_caption_style without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit routing rules: ask the person which shape first for aspect, use frame_on rather than follow when the person names who to show, look at a frame first, and consult list_styles kind "layout" to learn what each layout is. It names the alternative behaviors and the conditions that select them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the person wants to reword, turn on or off, or restyle the title card at the top of a made clip. style is a box such as "white box", "black box" or "lime word" (or a title template id). Saves the clip only, no render.
| Name | Required | Description | Default |
|---|---|---|---|
| on | No | ||
| text | No | The words to show (up to 140 characters). | |
| style | No | ||
| clip_id | Yes | The clip's id (from get_episode, get_job or the Slice link). |
| Name | Required | Description |
|---|---|---|
| clip_id | No | |
| open_in_slice | No | The clip in the Slice editor, where the person sees the change. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false. The description adds real value beyond that by stating 'Saves the clip only, no render,' which tells the agent about persistence scope and the absence of a render step. It does not say whether the previous title is recoverable or point to undo_edit, which keeps it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, with the usage trigger front-loaded and the parameter format note following. Every clause carries information an agent needs; nothing restates the tool name or title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists and annotations cover the safety profile, so the description's job is mostly the persistence note and style format, both of which it supplies. It could be more complete about overwrite behavior and recoverability, but nothing essential for calling the tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50%, so the description carries partial burden. It compensates well for `style` by explaining the accepted formats ('white box', 'black box', 'lime word', or a title template id) and implies the meaning of `on` through 'turn on or off'. The `text` and `clip_id` semantics are already documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('reword, turn on or off, or restyle the title card at the top of a made clip'), which clearly separates it from caption-editing siblings like edit_captions and set_caption_style. It stops short of explicitly naming the sibling it could be confused with, so it lands at 4 rather than 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The opening clause ('Use this when the person wants to reword, turn on or off, or restyle...') gives concrete trigger conditions tied to the three user intents. There are no explicit exclusions or named alternatives, but the intent framing is strong enough for correct routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the person wants to change where a made clip starts or ends, or to cut out any stretch in the middle, in seconds on the clip (get_clip_edit gives the word times). remove [{start_seconds, end_seconds}] cuts stretches (sound, picture and their captions); restore [...] puts cut stretches back. Edges move to the nearest gap between words. A clip keeps at least 3 seconds. Saves the clip only, no render.
| Name | Required | Description | Default |
|---|---|---|---|
| remove | No | ||
| clip_id | Yes | The clip's id (from get_episode, get_job or the Slice link). | |
| restore | No | ||
| end_seconds | No | ||
| start_seconds | No |
| Name | Required | Description |
|---|---|---|
| clip_id | No | |
| open_in_slice | No | The clip in the Slice editor, where the person sees the change. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: it discloses that removal cuts sound, picture and captions together, that restore reverses it, that edges snap to the nearest inter-word gap, that a 3-second minimum is enforced, and that only the clip is saved with no render. The reversibility via restore is exactly the context that makes destructiveHint=false credible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the trigger, then the two array operations, then the constraints. The wording is dense but every clause carries a rule an agent needs (snapping, 3-second floor, no render).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Return values need not be explained since an output schema exists, and the mutation's safety profile is covered by annotations plus the restore explanation. The remaining gap is that the top-level start/end knobs are unexplained relative to remove/restore, leaving ambiguity about how to set the clip's boundaries.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema coverage at only 20%, the description carries the load and explains the remove/restore array shapes, their units (seconds), and their side effects on captions. The top-level start_seconds/end_seconds parameters are only implied by "change where a made clip starts or ends" and are never named or bounded explicitly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States the specific operation (changing a made clip's start/end, or cutting a middle stretch) on a specific resource (the clip), in seconds. It also distinguishes itself from get_clip_edit by naming that sibling as the source of word times rather than a trimmer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Use this when the person wants to change where a made clip starts or ends, or to cut out any stretch in the middle" gives a clear triggering condition, and the get_clip_edit parenthetical points at the prerequisite lookup. It stops short of explicit when-not guidance or naming edit_captions/undo_edit as alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants a podcast, interview, stream or other video turned into short clips. An audio-only episode (MP3, M4A, WAV, OGG or FLAC) works too: its clips come out as captioned vertical videos drawn with an audio template. With a video or audio file attached in the chat, pass it as file: it is copied into Slice, transcribed, and searched for the moments worth posting, with no further steps. With no file, it returns an upload_url for the user to open and drop the file in (up to three hours and 4.5GB). Follow with get_episode. If the user shared a video without saying what they want, ASK FIRST: "Find the best clips in it, or edit the whole video as one piece?". For the whole video pass purpose "whole": Slice only transcribes it (no clip search, no clips email), then make_clips with one stretch from 0 to its full length makes it one clip (10 minutes at most; a longer video must be split into parts or turned into clips). Do not use when the user only wants the words as text (use transcribe_audio), and do not use for links to YouTube or other web pages; those are not supported.
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | A video or audio file the user attached in the conversation. | |
| name | No | What to call the episode. Defaults to the file name. | |
| purpose | No | "clips" (default): Slice finds the best clips. "whole": edit the whole video as one piece, with no clip search; ask the user first when they have not said. | |
| content_type | No | What kind of video it is, which decides how clips are found: podcast (a podcast or interview), stream (a livestream or gaming video) or other (a vlog, challenge, talk or story). Pass it when the user's video is clearly one of these. Otherwise leave it out and Slice will guess. | |
| target_seconds | No | Optional. How long each clip should be, in seconds (15 to 180), when the user asks for a length, e.g. "30 second clips". Every clip found then plays for at most this long and at most 10% less (at least 3 seconds less), cut at clean sentence or pause boundaries; fewer clips come back if few moments fit. Leave it out for clips of any length (30 to 150 seconds). Works with or without a focus. |
| Name | Required | Description |
|---|---|---|
| name | No | |
| status | Yes | |
| message | Yes | |
| episode_id | Yes | |
| upload_url | No | Open this to upload the video or audio file. Works for two hours. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: states the file is copied into Slice, transcribed and searched, that no-file calls return an upload_url, the 3-hour/4.5GB limits, and that purpose "whole" only transcribes with no clip search. Minor gap: no mention of processing time or async job behavior beyond pointing to get_episode.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the primary use case and efficiently grouped by branch (file / no file / whole). It is dense and lengthy, with some downstream make_clips detail that could live in a sibling, but no sentence is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema and annotations covering safety, the description covers the remaining agent needs: when to call, what to do with an attached file, the upload fallback and its limits, the clarifying question, and which sibling to use next.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds real meaning: what passing file does (copied, transcribed), the no-file upload_url path, and the operational consequence of purpose "whole" (transcribe only, then make_clips with a 10-minute cap).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence states a specific verb and resource ('turned into short clips') and enumerates the source types (podcast, interview, stream, video, audio-only) it covers. It also differentiates itself from siblings by naming transcribe_audio and the get_episode follow-up.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use branches (file attached vs. no file), a prescribed clarifying question when intent is ambiguous, the purpose "whole" path, and explicit exclusions (transcribe_audio for text only, unsupported YouTube/web links). Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the person asks to see Slice's style library, and only then. When someone wants visuals or animation and has no style, design your own looks for the clip first (owner, 1 November 2026: the library is being reworked); never list library styles in the chat unasked. With a library request: Pass the words as text, or a clip_id, job_id or episode_id from Slice to use its transcript. Returns a few ranked styles from the Slice library with a short reason each, plus the whole catalogue so you can choose with your own judgement. Show the person 3 to 5 options with the reasons and let them choose. They can mix styles or use none: there is no need to use a Slice style at all.
| Name | Required | Description | Default |
|---|---|---|---|
| text | No | A transcript, a script or a description of the clip, up to 20,000 characters. | |
| count | No | How many suggestions, 1 to 12. Default 5. | |
| aspect | No | The frame shape, if known. Every style works in every shape; this only breaks ties. | |
| job_id | No | Instead of text: the job_id of a clip being made or rendered, to use its words. | |
| clip_id | No | Instead of text: a Slice clip's clip_id, to use its words. | |
| episode_id | No | Instead of text: a Slice episode_id, to use the episode's words. |
| Name | Required | Description |
|---|---|---|
| note | Yes | |
| message | Yes | |
| catalogue | Yes | |
| suggestions | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already establish a read-only, idempotent, non-destructive, closed-world operation. The description adds useful behavioral context: it returns a few ranked styles with reasons plus the whole catalogue, notes that the library is being reworked, and states that the person need not use a Slice style at all. It does not detail rate limits or permissions, but those are not central here.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the trigger and prohibition, then moves through input choices, return shape, and presentation guidance. Despite its length, each sentence carries operational value, including the rework note that explains why the agent should design its own looks first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a six-parameter, read-only tool with full schema coverage, annotations, and an output schema, the description covers when to call it, how to supply input, what it returns, and how to present results. The main remaining gap is that it does not clarify its relationship to the sibling list_styles tool, which also concerns the style library.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all six parameters. The description adds valuable cross-parameter meaning by explaining that the agent can pass words as text or use a clip_id, job_id, or episode_id to draw from a transcript. It does not add much for count or aspect, but the schema covers those.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: it suggests ranked styles from Slice's library based on text or a clip transcript, and returns the full catalogue. It is clear about scope, but it never names or explicitly contrasts with sibling tools such as list_styles, so an agent must infer the boundary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit triggering conditions ('when the person asks to see Slice's style library, and only then') and explicit exclusions ('never list library styles in the chat unasked'). It also says what to do instead when the person merely wants visuals with no style, and tells the agent to present 3-5 options and let the person choose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the person likes a look and wants to keep it, or wants their saved look on clips. The same saved templates as the Slice editor's Saved styles. kind: style (the caption look with logo, framing, stacking and caption rules; "setup" also keeps the clip's shape, layout, hook title look and B-roll look), title (a hook title style), audio_brand (the brand template every new audio episode opens in), layout (the starting layout for whole videos), broll_look (a saved Un-Stock look for B-roll) and visual_cut (a storyboard's saved style). save: from_clip (its current look) or settings (style: the set_caption_style fields, e.g. {"style":"bold-punch","color":"#ffffff","font":"Anton"}; title: {"template","colour","mark_colour","font_scale","align"}; broll_look: Un-Stock {"preset"?, "settings"}), with a name. list: every template with its id, kind and which is the default. get: one in full. apply: id to clip_id, clip_ids or an episode_id's clips: no render, one undoable change per clip (undo_edit). new_uploads true makes it the default for new uploads; only when the person asks for that. rename: id and name. delete: call once to get a confirm token and a question; ask the person, then call again with confirm.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | A template id as list gives it (e.g. "style:<uuid>", "title:<id>", "audio_brand"). | |
| kind | No | For save and list. Not needed with an id from list. | |
| name | No | Up to 60 characters (save, rename). | |
| action | Yes | ||
| clip_id | No | ||
| confirm | No | delete: the token the first delete call gave, once the person has said yes. | |
| replace | No | save: overwrite a template of the same name. | |
| clip_ids | No | apply: up to 30 clips. | |
| settings | No | save without a clip: the look itself (see the description). | |
| from_clip | No | save: the clip whose current look to keep (a clip id, or a storyboard's clip for visual_cut). | |
| episode_id | No | apply: every clip of this episode. | |
| from_video | No | save kind layout: the whole video whose layout to keep. | |
| new_uploads | No | apply or save: true makes it the default for new uploads (only when the person asks); false stops that. |
| Name | Required | Description |
|---|---|---|
| template | No | |
| templates | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by disclosing that apply performs "no render, one undoable change per clip (undo_edit)" — a critical reversibility fact for a destructiveHint=true tool. It also documents the two-phase delete protocol (first call returns a confirm token plus a question, second call with `confirm`) and the `replace` overwrite semantics, which are exactly the safety details annotations cannot convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the when-to-use sentence and then organized loosely by action, and nearly every clause carries new information (kind meanings, settings shapes, confirm flow). It is a single dense run-on block, though, which makes it harder to scan than a short per-action breakdown would be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 13-parameter, six-action tool with an output schema, the description covers each action's inputs, the kind taxonomy, and the delete confirmation loop. It omits error/failure behavior (e.g. applying a nonexistent id, or what happens if a `replace` is not set on a name collision), which would matter for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 85%, but the description adds real meaning: per-kind `settings` payload shapes with a concrete example ({"style":"bold-punch","color":"#ffffff","font":"Anton"}) and the title fields, plus the three alternative targets for apply (clip_id, clip_ids, episode_id). Only marginal gaps remain, such as clip_id vs clip_ids precedence.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (saved templates) and enumerates each verb the tool performs: save, list, get, apply, rename, delete. It also anchors the concept to user-facing vocabulary ("the same saved templates as the Slice editor's Saved styles") and breaks down every enum value of `kind`, so an agent can distinguish this from siblings like list_styles or get_visual_style.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Use this when the person likes a look and wants to keep it, or wants their saved look on clips" gives a clear triggering context, and the apply/save clauses add conditions (e.g. `new_uploads` only "when the person asks"). However, it never explicitly excludes the nearest siblings (list_styles, restyle_clip, get_visual_style), so the agent must infer when a one-off restyle is preferable to saving a template.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants the words: speech in an audio or video file turned into text, from a podcast, interview, lecture, meeting or voice note. Accepts a file the user attached (file) or a direct https link to a media file such as .mp3, .m4a, .wav or .mp4 (url). Returns the transcript with speaker turns, plus a page with the full text and .txt, .srt and .vtt downloads. Short files finish in this call; longer ones return status "processing" and a transcription_id for transcription_status. Up to 1 hour per file. The first transcript needs no account; after that it asks for a Slice sign-in, and a signed-in person gets 2 transcripts a month, shared with the Slice website. Do not use when the user wants short video clips made from a video (start_episode does that), for YouTube, Spotify, Apple Podcasts or other web pages (they are pages, not files), for text already in the conversation, or for live audio.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | A direct https link to an audio or video file, e.g. https://example.com/episode.mp3. Not a web page. | |
| file | No | An audio or video file the user attached in the conversation. | |
| wait | No | Default true: wait briefly so short files come back finished. False returns at once with a transcription_id. |
| Name | Required | Description |
|---|---|---|
| status | Yes | |
| message | Yes | |
| language | No | Detected language code, e.g. en. |
| downloads | No | |
| duplicate | No | True when this is the transcript already made of the same file earlier: nothing new was started or counted. Do not send the file again. |
| file_name | No | |
| transcript | No | The transcript in paragraphs, with speaker labels when there is more than one voice. |
| word_count | No | |
| results_url | Yes | Page with the full transcript and downloads. No sign-in; share it only with people who should see the transcript. |
| duration_minutes | No | |
| transcription_id | Yes | Pass to transcription_status or email_transcript. |
| transcript_truncated | No | True when only the first part is included here; the results page has all of it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=false, openWorldHint=true, destructiveHint=false), and the description goes well beyond them: it discloses the speaker-turn output, the derived page with .txt/.srt/.vtt downloads, the async 'processing' + transcription_id path, the 1-hour file cap, and the auth/rate-limit model (first transcript anonymous, then sign-in, 2/month). That is genuinely rich behavioral context for a non-read-only tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the trigger sentence, then inputs, then returns, then limits/auth, then exclusions — a sensible order. It is a single dense paragraph with some run-on stretches (the auth/quota sentence packs three facts), but almost every clause carries information an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with async processing, auth quota, and a nested file object, the description covers everything an agent must know: input forms, supported formats, duration limit, synchronous vs polling outcome, and sibling routing. An output schema exists, yet the description still summarizes the return shape concisely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all three parameters, which sets the baseline at 3. The description does add real value by framing file vs url as mutually exclusive input paths and listing supported container formats (.mp3, .m4a, .wav, .mp4), but it never mentions the 'wait' parameter, leaving a behaviorally significant toggle to the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('speech in an audio or video file turned into text') and scopes the input sources (podcast, interview, lecture, meeting, voice note). It also explicitly separates itself from siblings like start_episode and transcription_status, so an agent can pick it without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives both positive triggers ('when the user wants the words') and a full exclusion list: no clip-making (start_episode does that), no YouTube/Spotify/Apple Podcasts pages, no text already in the conversation, no live audio. The alternatives are named rather than implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when transcribe_audio returned status "processing", to check whether the transcript is finished and get its text. Pass the transcription_id it returned. Call it again after a short wait while the status is still "processing". Only answers in the conversation (or Slice account) that started the transcription. Do not use to start a transcription; use transcribe_audio.
| Name | Required | Description | Default |
|---|---|---|---|
| transcription_id | Yes | The transcription_id transcribe_audio returned. |
| Name | Required | Description |
|---|---|---|
| status | Yes | |
| message | Yes | |
| language | No | Detected language code, e.g. en. |
| downloads | No | |
| duplicate | No | True when this is the transcript already made of the same file earlier: nothing new was started or counted. Do not send the file again. |
| file_name | No | |
| transcript | No | The transcript in paragraphs, with speaker labels when there is more than one voice. |
| word_count | No | |
| results_url | Yes | Page with the full transcript and downloads. No sign-in; share it only with people who should see the transcript. |
| duration_minutes | No | |
| transcription_id | Yes | Pass to transcription_status or email_transcript. |
| transcript_truncated | No | True when only the first part is included here; the results page has all of it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish that this is a read-only, idempotent, non-destructive operation. The description adds useful behavior beyond that: polling semantics, access scoping to the conversation or Slice account that initiated the transcription, and the fact that the transcript text is returned once finished.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the primary usage condition, then polling guidance, then scope and exclusion. Every sentence carries actionable information, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With rich annotations, a complete single-parameter schema, and an output schema, the description supplies the remaining operational context an agent needs: when to call it, how to poll, what access scope applies, and which tool not to use. Nothing material is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one parameter and schema description coverage is 100%, so the schema already explains that transcription_id is the value returned by transcribe_audio. The description reinforces this but adds no syntax, format, or validation detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: check whether a transcription started by transcribe_audio has finished and retrieve its text. It explicitly distinguishes itself from transcribe_audio, so an agent can route between the two tools without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives the exact triggering condition (transcribe_audio returned status "processing"), explains how to poll (call again after a short wait while still processing), and explicitly says not to use it to start a transcription. The alternative, transcribe_audio, is named for the excluded case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the person wants to take back changes you (the person's AI) made to a clip with the edit tools, newest first, the same as Undo in the Slice editor. A storyboard moment taken off the clip (in the editor or by you) is undone here too: it comes back as it was (edit_id "moment:" from list true). With no edit_id or count it undoes the newest change; count undoes the newest n (up to 10); edit_id undoes back to and including that change. list true only lists the recent changes with their ids. Saves the clip only, no render.
| Name | Required | Description | Default |
|---|---|---|---|
| list | No | ||
| count | No | ||
| clip_id | Yes | The clip's id (from get_episode, get_job or the Slice link). | |
| edit_id | No |
| Name | Required | Description |
|---|---|---|
| clip_id | No | |
| open_in_slice | No | The clip in the Slice editor, where the person sees the change. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses that the tool saves the clip but performs no render, that moments return 'as it was' with the moment:<id> handle, and that list=true lists rather than mutates. These are real behavioral facts an agent could not infer from readOnlyHint=false / destructiveHint=false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is front-loaded with the when-to-use condition and the core undo semantics follow the dense parameter rules. It is slightly long and run-on with parentheticals, but nearly every clause carries operational meaning and nothing is padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter mutation tool, the description covers triggers, ordering, defaults, limits, the special moment case, and the save-vs-render side effect. With an output schema present, it does not need to explain return values, so an agent has everything required to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 25%, so the description carries the load: it defines the default behavior with no edit_id/count, the meaning of count (newest n, up to 10), the semantics of edit_id (undo back to and including), and list=true. That fully compensates for the undocumented parameters and even supplies the moment:<id> format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('take back changes you made to a clip with the edit tools') and pins down the ordering model ('newest first, the same as Undo in the Slice editor'). It also covers an edge case (restoring a removed storyboard moment), which is exactly what separates it from siblings like set_trim or set_frame.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit trigger ('Use this when the person wants to take back changes...') and clarifies that list=true is a read-only listing mode rather than an undo. It doesn't name a sibling to use when the intent is to redo or inspect history, but the positive guidance is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
set_frame1 field changedInput schema / properties / frame_onAdded value: +{
+ "description": "Frame one person: x (and optionally y) is where their face is in the whole source picture, 0 to 1; scale 1 fills the frame. A fixed crop: speaker follow goes off.",
+ "properties": {
+ "scale": {
+ "maximum": 5,
+ "minimum": 1,
+ "type": "number"
+ },
+ "x": {
+ "maximum": 1,
+ "minimum": 0,
+ "type": "number"
+ },
+ "y": {
+ "maximum": 1,
+ "minimum": 0,
+ "type": "number"
+ }
+ },
+ "required": [
+ "x"
+ ],
+ "type": "object"
+}templates1 field changedInput schema / properties / from_clip / descriptionPrevious value: -"save: the clip whose current look to keep (a clip id, or a visual cut's clip for visual_cut)."New value: +"save: the clip whose current look to keep (a clip id, or a storyboard's clip for visual_cut)."start_episode1 field changedInput schema / properties / purposeAdded value: +{
+ "description": "\"clips\" (default): Slice finds the best clips. \"whole\": edit the whole video as one piece, with no clip search; ask the user first when they have not said.",
+ "enum": [
+ "clips",
+ "whole"
+ ],
+ "type": "string"
+}templatescut_wordsedit_captionsget_clip_editmake_clips5 fields changedInput schema / properties / aspectAdded value: +{
+ "description": "The clip's shape. Ask the person first; 9:16 when left out.",
+ "enum": [
+ "9:16",
+ "4:5",
+ "1:1",
+ "16:9",
+ "3:4",
+ "source"
+ ],
+ "type": "string"
+}Input schema / properties / clips / descriptionPrevious value: -"Numbers or refs from get_episode, e.g. [2, 5] or [\"a3f9\"]. Up to 10."New value: +"Numbers or refs from get_episode, e.g. [2, 5] or [\"a3f9\"], or stretches {\"start_seconds\": 312, \"end_seconds\": 371, \"title\": \"...\"} on the episode. Up to 10."Input schema / properties / clips / items / oneOfAdded value: +[
+ {
+ "type": [
+ "integer",
+ "string"
+ ]
+ },
+ {
+ "properties": {
+ "end_seconds": {
+ "type": "number"
+ },
+ "start_seconds": {
+ "type": "number"
+ },
+ "title": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "start_seconds",
+ "end_seconds"
+ ],
+ "type": "object"
+ }
+]Input schema / properties / clips / items / typeRemoved value: -[
- "integer",
- "string"
-]Output schema / properties / aspectAdded value: +{
+ "description": "The shape the clips are made in.",
+ "type": "string"
+}restyle_clip1 field changedInput schema / properties / exportAdded value: +{
+ "description": "True with nothing else to change: make the video from the clip as it stands now (after edits with the no-render tools).",
+ "type": "boolean"
+}set_caption_styleset_frameset_hook_titleset_trimundo_editget_visual_stylesuggest_visual_stylesget_visual_stylesuggest_visual_stylesget_visual_stylesuggest_visual_stylesget_job1 field changedOutput schema / properties / stageAdded value: +{
+ "description": "The step the job is on, as the worker reports it.",
+ "type": "string"
+}transcribe_audio1 field changedOutput schema / properties / duplicateAdded value: +{
+ "description": "True when this is the transcript already made of the same file earlier: nothing new was started or counted. Do not send the file again.",
+ "type": "boolean"
+}transcription_status1 field changedOutput schema / properties / duplicateAdded value: +{
+ "description": "True when this is the transcript already made of the same file earlier: nothing new was started or counted. Do not send the file again.",
+ "type": "boolean"
+}email_transcriptfind_clips_aboutget_episodeget_joblist_stylesmake_clipsread_captionsrestyle_clipstart_episodetranscribe_audiotranscription_statusTurn long videos into captioned vertical clips for TikTok, Reels and Shorts.
Turns long videos into captioned vertical clips, cut at the moments that stand on their own.
Turn long videos into captioned short clips and schedule them to TikTok, YouTube Shorts and Reels.
Turn long videos into captioned, reframed short clips, thumbnails, and social posts.
Add one secure layer between your agents and this server.
