The video infra for agents. ClipKit turns a JSON timeline — the open ClipKit Protocol — into rendered video on the GPU. Describe a video as structured data; get an MP4. Built for AI agents and the developers shipping them.
clipkit.dev · Docs · Protocol · Agent quickstarts
https://github.com/user-attachments/assets/ff4b7e9b-2e0a-40f4-a6a1-042e981fc65f
npm install -g @clipkit/cli
clipkit new my-video.json # scaffold a Source
clipkit render my-video.json -o out.mp4 # render locally (headless Chrome)…or from code:
import { render } from '@clipkit/renderer';
import { writeFile } from 'node:fs/promises';
const { buffer } = await render({ source }); // source = a ClipKit Protocol document
await writeFile('out.mp4', buffer);Local rendering uses your installed Google Chrome (for WebCodecs). For GPU-accelerated
and pro-format (ProRes / AV1 / transparent) output, render on the hosted service with
clipkit render --cloud.
Related MCP server: fcpxml-mcp-server
A monorepo; each package publishes to npm under the @clipkit scope.
Package | What it is |
the ClipKit Protocol — schema, types, validation | |
the engine — WebGPU/WebGL2 compositor + WebCodecs encoder | |
render a Source to MP4 locally (headless Chrome) | |
a configurable, embeddable editor over the schema | |
the editor's UI-free data layer | |
browser playback engine | |
composable motion-graphics units | |
procedural sound-effects synthesis | |
beat / tempo analysis for authoring | |
transcription → captions | |
protocol-aware validation + plain-language summaries | |
an MCP server so agents can author + render video | |
the local-first CLI |
ClipKit ships an MCP server — point your agent at it and it can build, validate, preview, and render ClipKit videos:
npx -y @clipkit/cli mcp # stdio MCP serverSee the agent quickstarts for Claude, Cursor, and more.
Apache-2.0 — except @clipkit/runtime, which is under the
Business Source License 1.1 and converts to Apache-2.0 four years after
each release. In plain terms: use it, embed it, build your own product on it, and render
for your own customers — all free. The one thing you can't do is offer a competing
hosted ClipKit-rendering service. See LICENSING.md and
TRADEMARK.md.
Append a single element to an existing project — a TWEAK, e.g. dropping in one more caption or shape. By default it is added at the top level; pass parent_id to add it INTO a group (nested). The element is any valid schema element: video, image, text, shape, audio, group, caption, or particles. To create a composition or add several elements at once, build the JSON and use set_project instead. The new element is validated as part of the project as a whole before being added. Call get_schema(element_type) for the exact per-type fields; unrecognized keys are flagged.
| Name | Required | Description | Default |
|---|---|---|---|
| element | Yes | A Clipkit element object. Must include `type`. | |
| parent_id | No | Optional id of a group to add this element INTO (nested). Omit to add at the top level. | |
| project_id | No | Which project to act on — the id returned by create_project / set_project / create_promo / load_project. Omit when working on a single local project. |
| Name | Required | Description |
|---|---|---|
| parent_id | No | |
| element_type | No | |
| added_element_id | No | |
| top_level_element_count | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description explains key behavioral aspects: the element is validated as part of the whole project before being added, and unrecognized keys are flagged. This gives the agent insight into error handling and validation behavior, which is not evident from annotations alone.
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 concise yet information-dense. Each sentence serves a purpose: the first defines the core function, the second explains default vs nested behavior, the third lists supported element types, the fourth differentiates from set_project, the fifth describes validation, and the sixth directs to get_schema. 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?
Given the tool's complexity (nested element object, three parameters, an output schema exists), the description is comprehensive. It covers all essential aspects: purpose, placement behavior, supported element types, alternative tools, validation, and parameter semantics. The reference to get_schema handles per-type fields, and the output schema renders return-value documentation unnecessary. No significant gaps remain.
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 input schema already has 100% coverage with descriptions for all parameters, but the tool description adds meaningful value by explaining the semantics of parent_id (top level vs. nested) and project_id (omitted for single local project). It also clarifies that the element must include a type and is a valid schema element, enriching the structured data with context that aids correct parameter construction.
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 clearly states the tool's purpose: 'Append a single element to an existing project.' It specifies the resource (project) and action (add element), and distinguishes itself from set_project by noting that set_project is for creating compositions or adding multiple elements at once. This makes the purpose unambiguous and well-differentiated from siblings.
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 description provides explicit usage guidance: it notes that by default the element is added at the top level, and parent_id is used to nest it into a group. It also gives a clear alternative: 'To create a composition or add several elements at once, build the JSON and use set_project instead.' Furthermore, it advises calling get_schema(element_type) for exact fields, giving the agent actionable paths for correct usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new, blank Clipkit project with the given dimensions and duration, and return its project_id. Defaults: 1920×1080, 10 seconds, 30 fps, output_format "mp4". Call this first when starting a new video. Pass an existing project_id to reset that project to blank; omit it to start a fresh project (note the returned id for subsequent tools).
| Name | Required | Description | Default |
|---|---|---|---|
| width | No | Composition width in pixels. Default 1920. | |
| height | No | Composition height in pixels. Default 1080. | |
| duration | No | Composition duration in seconds. Default 10. | |
| frame_rate | No | Frame rate. Default 30. | |
| project_id | No | Which project to act on — the id returned by create_project / set_project / create_promo / load_project. Omit when working on a single local project. | |
| output_dither | No | Anti-banding output dither — DEFAULT ON, leave unset. Pass false for byte-exact undithered output, or { amplitude, pattern } to tune. Stops gradients / soft shadows / blur from showing 8-bit banding; deterministic. | |
| output_format | No | Output container/codec. Default "mp4". | |
| background_color | No | Hex color, e.g. "#000000". |
| Name | Required | Description |
|---|---|---|
| width | No | |
| height | No | |
| duration | No | |
| frame_rate | No | |
| project_id | Yes | Id of the created project — pass to subsequent tools. |
| output_format | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states that passing an existing project_id 'reset[s] that project to blank,' which is a destructive action, while annotations declare destructiveHint=false. This is a direct contradiction, so the description does not transparently disclose the destructive nature. Annotation Contradiction.
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 front-load the core purpose, then add defaults and usage guidance. Every sentence earns its place with no wasted words.
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 an output schema exists, the description need not detail return structure; it mentions project_id. It covers the main use case, defaults, and reset edge case. However, the contradiction with destructiveHint slightly undermines overall completeness, but the description itself is contextually sufficient.
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. The description adds value by listing defaults (1920×1080, 10s, 30fps, mp4) and explaining the reset behavior for project_id, which goes beyond the schema's description. It does not explain output_dither, but the schema does comprehensively.
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 clearly states the tool's purpose: 'Create a new, blank Clipkit project with the given dimensions and duration, and return its project_id.' It distinguishes itself from siblings by explicitly noting it should be 'first when starting a new video' and describes reset 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?
The description provides clear usage context: 'Call this first when starting a new video' and explains when to pass an existing project_id for reset. It does not explicitly name alternative tools or state when not to use, but the guidance is sufficient for a new project.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Assemble a designed-looking promo/intro/product/data video from the Clipkit pattern library: give an ordered list of SCENES and the words, and it bakes in the camera, glass, lighting, motion blur, timing, and layout, then returns an editor link. This is a FAST option when a conventional promo structure fits — it is NOT the only way to make a video and NOT a default; for anything specific or original, author the JSON yourself and call set_project (the full creative range). When you do use this, MIX scene types to fit the brief and vary the structure — a video can be a single kinetic headline, three title cards, a showcase montage, or a data explainer; you do NOT need a hero or a cta. Scene types: hero (glass-orb logo reveal: wordmark, tagline?), kinetic (letter-fly headline: text, subtitle?), showcase (a screenshot tilted in 3D: screenshot URL), title (full-frame title card: headline, kicker?, subtitle?), cta (closing card with a glass button: wordmark, tagline?, cta), stats (hero numbers: stats[{label,current,previous?}], title?), bars (bar chart: bars[{label,value,previous?}], title?), ranking (top-N list: items[{label,value}], title?), pie (pie cards: cards[{label,value,total,previous?}], title?). The data scenes (stats/bars/ranking/pie) look best with theme "mux".
| Name | Required | Description | Default |
|---|---|---|---|
| theme | No | Visual theme. Default "cinematic" (dark, serif, premium). | |
| width | No | Default 1920. | |
| height | No | Default 1080. | |
| scenes | Yes | Ordered scenes; mix types to fit the brief — you do NOT need hero/cta. e.g. a single [{type:"kinetic",text:"…"}], a sequence [{type:"title",headline:"…"},{type:"showcase",screenshot:"…"},{type:"title",headline:"…"}], or a data piece [{type:"ranking",title:"…",items:[…]}] | |
| project_id | No | Which project to act on — the id returned by create_project / set_project / create_promo / load_project. Omit when working on a single local project. | |
| motion_blur | No | Supersampled motion-blur samples (≥2 enables it — nicer but slower to render). Default off. |
| Name | Required | Description |
|---|---|---|
| width | No | |
| height | No | |
| duration | No | |
| editor_url | No | |
| project_id | Yes | |
| scene_count | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag readOnlyHint=false and destructiveHint=true; the description adds valuable context about baking in camera/glass/motion blur, returning an editor link, and being a fast constrained path. It doesn't detail destructive side effects, but annotations cover that. No contradiction.
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 long but every sentence is productive: it opens with the core function, contrasts with set_project, then gives a structured scene-type rundown. Despite length, it is well-organized and free of fluff.
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?
It covers purpose, when to use, when not to use, alternatives, scene types, theme recommendations, and output behavior. Given the tool's complexity and rich schema, this is a complete and sufficient description.
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. The description goes further by providing a per-scene-type cheat-sheet (e.g., hero requires wordmark, showcase requires screenshot URL) and notes the 'mux' theme for data scenes, adding design intent 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 clearly states the tool assembles designed promos/intros/data videos from Clipkit scenes, given an ordered list of scenes and words, and returns an editor link. It explicitly contrasts with set_project for original work, distinguishing it from siblings.
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 explicitly says this is a FAST option for conventional promo structures, NOT the default, and directs users to set_project for full creative range. It also provides concrete guidance to mix scene types, avoid forcing hero/cta, and gives example video structures.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete the element with the given id, anywhere in the tree (including one nested inside a group or its mask) — a tweak to an existing composition. (The project must keep at least one top-level element.)
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The id of the element to delete. | |
| project_id | No | Which project to act on — the id returned by create_project / set_project / create_promo / load_project. Omit when working on a single local project. |
| Name | Required | Description |
|---|---|---|
| deleted_element_id | Yes | |
| top_level_element_count | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as destructive (destructiveHint=true). The description adds valuable context: it works on nested elements and imposes a constraint that the project must keep at least one top-level element, going beyond the basic destructive hint.
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 two sentences with no wasted words. It front-loads the core action ('Delete the element with the given id') and packs scope and constraints efficiently.
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 scope, the nesting behavior, and a critical constraint. The presence of an output schema means return values need not be described. Slight gap: no mention of cascading deletion of child elements, but overall sufficient.
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% with clear descriptions for both id and project_id. The description does not add parameter-specific semantics beyond referencing 'the given id', 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 clearly states the tool deletes an element by id, specifies the scope (anywhere in the tree, including nested inside groups or masks), and distinguishes it from sibling tools like add_element and edit_element.
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?
Provides clear context that this is a deletion operation on an existing composition, but doesn't explicitly mention when not to use it or name alternatives; no exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a compact, human-readable summary of the current project — dimensions, fps, duration, an element breakdown by type, a per-track timeline (paint order low→high), and render-time warnings. Much cheaper to read than get_project's full JSON; use it to orient yourself or sanity-check structure without dumping the whole source.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | No | Which project to act on — the id returned by create_project / set_project / create_promo / load_project. Omit when working on a single local project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds meaningful behavioral context: it returns a compact summary (not full JSON), includes specific content like render-time warnings and paint order, and notes performance characteristics ('Much cheaper to read'). No contradiction with annotations; the description enriches understanding of the tool's behavior.
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 two sentences, with the first sentence stating purpose and content, the second providing comparison and use case. Every clause adds value, no redundancy, and it is front-loaded with the core function.
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 simple tool with one optional parameter and no output schema, the description is complete: it states what the tool returns, what it includes, when to use it, and how it compares to a sibling. The output is a human-readable summary, so a detailed return schema is not necessary, and the description covers all important contextual aspects.
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 the baseline is 3. The description does not add any parameter-specific semantics beyond what the schema already provides (e.g., project_id optional, omit for local project). It neither clarifies nor obscures parameter usage, so the baseline 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 ('Return') and resource ('a compact, human-readable summary of the current project'), and enumerates exactly what the summary includes (dimensions, fps, duration, element breakdown, per-track timeline, render-time warnings). It also distinguishes from sibling tool get_project by explicitly contrasting with 'get_project's full JSON', making the purpose unambiguous.
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 description gives explicit when-to-use guidance: 'Much cheaper to read than get_project's full JSON; use it to orient yourself or sanity-check structure without dumping the whole source.' It names the alternative (get_project) and explains the trade-off, which is clear usage guidance beyond a simple 'use this to get a summary.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change fields on the element with the given id by merging in a partial element — only the keys you include change. The id may be any element ANYWHERE in the tree, including one nested inside a group (or its mask). Pass a whole nested value (e.g. a new keyframe_animations array) to replace that key; set a key to null to remove it. This is for TWEAKING an existing composition. To create a composition or change many elements at once, edit the JSON and call set_project instead. The result is re-validated before being accepted.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The id of the element to edit. | |
| patch | Yes | Partial element: the fields to change. Omitted keys are left as-is; a key set to null is removed. | |
| project_id | No | Which project to act on — the id returned by create_project / set_project / create_promo / load_project. Omit when working on a single local project. |
| Name | Required | Description |
|---|---|---|
| element_id | Yes | |
| changed_keys | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behavioral traits: merge semantics (only provided keys change), null to remove a key, id can target any element anywhere in the tree (including nested in groups or masks), and the result is re-validated before acceptance. The annotations provide basic readOnly/destructive hints, but the description adds crucial operational detail without contradicting them.
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 four sentences with no unnecessary words. It front-loads the core action and then efficiently covers scope, removal semantics, an alternative usage, and validation, with every sentence earning 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?
Given the tool's complexity (3 params, nested object, output schema exists), the description is fully complete. It covers purpose, scope, parameter behavior, alternative tools, and validation, while the output schema handles return value details.
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 description significantly enriches parameter understanding beyond the schema. It explains that patch replaces whole nested values (e.g., keyframe_animations) and that null removes keys, and it clarifies that id can be any element anywhere in the tree. Even though schema coverage is 100%, the description adds critical usage nuances and an example.
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 clearly states the tool changes fields on an existing element by merging in a partial element, making it distinct from add_element, delete_element, and set_project. The title 'Tweak one existing element (merge changed fields)' reinforces this specific purpose.
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 explicitly states this is for tweaking an existing composition and directs to set_project for creating a composition or changing many elements at once, providing clear when-to-use guidance and an alternative. The context of editing an existing element vs. creating/deleting is also implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the full current Clipkit source as JSON. Use this to inspect the project, pass it to a render pipeline, or compose follow-up edits.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | No | Which project to act on — the id returned by create_project / set_project / create_promo / load_project. Omit when working on a single local project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already indicates no side effects, and the description aligns with that. It adds value by describing the output as JSON and mentioning the 'current' project, but it does not elaborate on how project selection works or any pagination or snapshot semantics. With annotation coverage, a score of 3 is appropriate — it provides some context but not deep behavioral 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?
The description is two concise sentences, front-loaded with the primary action and followed by immediate use cases. No redundant words, every sentence 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?
Given a simple read-only tool with one optional param and no output schema, the description adequately covers purpose, output format (JSON), and typical usage. It doesn't explicitly mention the project_id optionality (which is in the schema) or return structure details, but it is sufficiently complete for the tool's simplicity.
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 input schema has 100% coverage for the single optional project_id, including guidance on when to omit it. The description itself adds no additional parameter-level details, so it does not compensate beyond the schema. Baseline 3 for high schema coverage is correct.
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 clearly states the tool returns the full current Clipkit source as JSON, with a specific verb ('Return') and resource ('current Clipkit source'). It also distinguishes itself from sibling tools like describe_project (which likely summarizes) and get_schema (which retrieves schemas), making its purpose unambiguous.
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 description provides clear use cases: inspect the project, pass to a render pipeline, or compose follow-up edits. It does not explicitly exclude alternatives or name when not to use it, but the guidance is actionable and appropriate for a lightweight read tool, making the context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the authoritative JSON Schema for a Clipkit Source — exact field names, types, and enums, generated from the protocol. Call with no argument for the full Source schema, or with element_type (e.g. "text", "shape", "particles") for just that element's fields (much smaller). Use this when authoring with set_project / add_element so you never guess a field.
| Name | Required | Description | Default |
|---|---|---|---|
| element_type | No | Limit to one element type's fields (e.g. "text"). Omit for the full Source schema (large). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already declares this is a read-only operation. The description adds that the schema is 'generated from the protocol' and notes size differences ('much smaller'), but does not disclose other behavioral traits like return format or error conditions. Given the annotation coverage, the description adds enough context but not rich 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?
The description is two sentences: the first defines the tool, the second explains invocation options and use case. Every sentence earns its place, there is no redundancy, and the key verb 'Return' is front-loaded.
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 simple read-only tool with one optional parameter, the description covers purpose, invocation patterns, and use case. The lack of an output schema is acceptable since the tool returns a schema, which is self-descriptive. The description is complete for its complexity.
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 input schema already covers the sole parameter element_type with a description and all enum values. The tool description essentially repeats this with examples ('text', 'shape', 'particles') and the 'much smaller' note, adding minimal new meaning. Since schema coverage is 100%, baseline 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 clearly states the tool's function: 'Return the authoritative JSON Schema for a Clipkit Source — exact field names, types, and enums'. This is a specific verb+resource that distinguishes it from sibling tools like read_docs. The additional context 'so you never guess a field' reinforces its purpose.
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 description explicitly says 'Use this when authoring with set_project / add_element so you never guess a field', providing a clear use case. It also explains how to use the optional element_type parameter for smaller responses. However, it does not mention when not to use the tool or compare it to alternatives such as read_docs, so it misses the 'when-not' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Import a previously shared project as the current project, by its share id or its editor URL (e.g. https://clipkit.dev/editor?id=…), returning its project_id. Use this to continue working on a project the user opened in the editor or shared earlier — the round-trip for open_in_editor. Pass an existing project_id to load into that project; omit it to load into a new one.
| Name | Required | Description | Default |
|---|---|---|---|
| id_or_url | Yes | A share id, or a clipkit.dev/editor?id=… URL. | |
| project_id | No | Which project to act on — the id returned by create_project / set_project / create_promo / load_project. Omit when working on a single local project. |
| Name | Required | Description |
|---|---|---|
| width | No | |
| height | No | |
| duration | No | |
| project_id | Yes | |
| element_count | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and destructiveHint=true. The description adds that loading makes the project 'the current project' and returns project_id, which is useful context. No contradiction.
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, front-loaded with action and input format; the example URL and round-trip note are valuable and not redundant.
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 output schema and annotations, the description covers input formats, return value, and relationship to open_in_editor, making it fully contextual.
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 adds clarity by explaining that omitting project_id loads into a new one, a meaningful semantic beyond the schema's generic 'omit when working on a single local project.'
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 uses a specific verb 'Import' and resource 'previously shared project', states it returns project_id, and explicitly positions itself as the 'round-trip for open_in_editor,' distinguishing it from sibling tools.
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?
Provides an explicit use case: 'continue working on a project the user opened in the editor or shared earlier' and names the sibling counterpart open_in_editor as its inverse, giving an alternative. It also clarifies behavior with optional project_id.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate the current project and create a link that opens it in the Clipkit web editor, where the user can preview and refine it. This shares the PROJECT (nothing is rendered — that's render_video). Use after composing or editing. Returns a URL.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | No | Which project to act on — the id returned by create_project / set_project / create_promo / load_project. Omit when working on a single local project. |
| Name | Required | Description |
|---|---|---|
| editor_url | Yes | |
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and openWorldHint=true. The description adds context that the project is validated before creating the link, that it returns a URL, and that no rendering occurs, which goes beyond the annotation-provided safety 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?
The description is three short sentences with no filler. The main action comes first, the scope/alternative clarification is second, and the return value is last. Every sentence 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?
For a simple one-parameter tool with an output schema, the description covers usage timing, alternative tool, behavioral nuance (no render), and return value. It is complete enough for an agent to decide when and how to invoke.
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 input schema already provides a complete description for project_id, including allowed origins and guidance on omitting it for a single local project. The tool description adds no additional parameter semantics, so the baseline score 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 uses a specific verb ('create') and resource ('link that opens it in the Clipkit web editor') and explicitly distinguishes from render_video by stating 'nothing is rendered — that's render_video'. This clearly separates it from sibling tools.
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 states when to use the tool ('Use after composing or editing') and explicitly names render_video as the alternative for rendering, providing clear guidance on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render a single frame of the current project to a PNG and return it as an image you can look at. This is how you check your work — in chat there is no other way to see what a composition actually looks like. Use it liberally: after composing, after edits, and at different times to inspect motion. Stills are FREE (credits are only spent by render_video). Pass time (seconds) to choose the frame; defaults to 0.
| Name | Required | Description | Default |
|---|---|---|---|
| time | No | Composition time in seconds to capture. Default 0 (first frame). | |
| project_id | No | Which project to act on — the id returned by create_project / set_project / create_promo / load_project. Omit when working on a single local project. |
| Name | Required | Description |
|---|---|---|
| time | Yes | |
| width | No | |
| height | No | |
| mime_type | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds valuable context about cost (FREE vs. render_video credits), return format (PNG image), and the ability to sample different time points. This goes beyond the annotations without contradiction.
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 concise: four sentences that front-load the core action and include all essential information. Every sentence contributes practical guidance (output, reason, cost, parameter default) with no wasted words.
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?
The description covers purpose, usage frequency, cost, return format, and parameter behavior. Combined with rich annotations and a complete schema, it leaves no important gaps for an AI agent to make an informed 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?
Schema coverage is 100%, so the description adds marginal value. It reiterates that 'time' is in seconds and defaults to 0, which is already in the schema. It doesn't introduce new parameter semantics, but it does reinforce the usage context for time.
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 clearly states a specific verb and resource: 'Render a single frame of the current project to a PNG and return it as an image'. It distinguishes itself from render_video by emphasizing single-frame output and explicitly mentions return format. This makes the tool's purpose unambiguous.
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?
Provides explicit when-to-use guidance: 'This is how you check your work', 'Use it liberally', and specifies the appropriate moments (after composing/edits, at different times to inspect motion). It also contrasts with render_video by noting stills are free, clarifying when not to use the sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a canonical Clipkit doc as text. topic "card" = the ~8KB compact authoring card — the recommended context for authoring; "pattern-data-viz" / "pattern-cinematic-ui" / "pattern-ui-screencast" = ~4-5KB archetype pattern cards (proven idioms: count-ups and bar rows; product hero shots with camera rigs; faked app UI with typing/cursor/clicks) — load ONE alongside the card when the brief matches its archetype; "agents" = the full authoring guide (fetch only when the card doesn't cover a need); "protocol" = the formal field spec; "brand" = brand reference. (Same docs offered as MCP resources, exposed as a tool so you can read them directly — resources are not always model-readable.)
| Name | Required | Description | Default |
|---|---|---|---|
| topic | No | Which doc. Default "agents". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals a safe read operation; the description adds context beyond that—each topic's approximate size, the nature of the pattern cards, and the rationale for exposing docs as a tool. It doesn't cover errors or pagination, but for a single-parameter read-only doc fetcher, the added behavioral context is sufficient.
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 long but tightly packed with necessary distinctions for seven topics; it front-loads the core return behavior and uses semicolon-delimited sub-clauses to keep structure scannable. Slightly verbose but every clause earns its place given the many options.
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 simple read-only tool with one enum parameter and no output schema, the description covers the full set of topics, their relative sizes, recommended usage, and even the rationale for the tool's existence. It is complete for both selection and 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?
While the schema provides an enum and default, the description gives deep semantic meaning to every enum value: sizes, use cases, and distinctions (e.g., 'card' vs 'agents' vs 'protocol'). This far exceeds the schema's bare 'Which doc' description, making the parameter's effect crystal clear.
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 opens with a clear verb+resource: 'Return a canonical Clipkit doc as text.' It then enumerates distinct topics and their contents, distinguishing this read-only documentation tool from the sibling project/element tools. The purpose is unambiguous and specific.
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?
Provides explicit when-to-use guidance for each topic: the card is 'the recommended context for authoring', patterns are to 'load ONE alongside the card when the brief matches its archetype', and the full guide is 'fetch only when the card doesn't cover a need'. Also explains that resources may not be model-readable, positioning this tool as the preferred access path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate the current Clipkit project and render it to a finished MP4 on Clipkit's servers, returning a downloadable URL. This is the paid path — it consumes render credits and requires CLIPKIT_API_KEY to be configured. Use open_in_editor instead to just open the project in the editor for free. Rendering is synchronous and may take a while for long or high-resolution videos.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | No | Which project to act on — the id returned by create_project / set_project / create_promo / load_project. Omit when working on a single local project. | |
| resolution | No | Output resolution. Defaults to the source dimensions. Higher resolutions cost more credits. |
| Name | Required | Description |
|---|---|---|
| credits | Yes | |
| download_url | Yes | |
| duration_seconds | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only indicate non-read-only and non-destructive; the description adds crucial behavioral details: it validates the project, consumes render credits, requires an API key, runs synchronously, and returns a downloadable URL. These go well beyond the structured annotations.
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 sentences, front-loaded with the core action and outcome, followed by cost/alternative, then performance characteristics. Every sentence earns its place; no fluff.
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?
Even with an output schema present, the description covers validation, cost, auth, synchronous behavior, and an alternative tool. It gives the agent all necessary context to decide whether to use this tool and what to expect.
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 covers 100% of parameters with detailed descriptions (resolution enum, project_id omission rule). The description adds the 'validates' and 'current project' framing but doesn't materially extend parameter semantics beyond what the schema already provides. Baseline 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 clearly states the tool renders the current project to a download-ready MP4 on Clipkit's servers, distinguishing it from siblings like open_in_editor and preview_still. The verb 'render' and specific resource 'current project' make the purpose unambiguous.
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 says this is the paid path, mentions open_in_editor as a free alternative, and notes the need for CLIPKIT_API_KEY. It also warns about synchronous, potentially slow rendering, giving clear context on when to choose this over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace the entire project with the given source JSON, returning its project_id. This is the PRIMARY way to build: use it to create a composition or to add/change many elements at once. (To tweak a single element in an existing project, use edit_element / add_element / delete_element instead.) Pass an existing project_id to replace that project; omit it to create a new one (note the returned id). The input is validated against the @clipkit/protocol before being accepted; invalid inputs return an error. Shape: { width, height, duration, frame_rate, output_format, background_color?, fonts?, camera?, lights?, elements:[…] }; every element has a type plus base fields (id, x, y, width, height, time, duration, track, opacity, rotation, animations, keyframe_animations) and type-specific fields. For exact field names + types call get_schema (optionally with an element_type) — the runtime ignores unrecognized keys, and this tool flags any it does not recognize.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | A full Clipkit source object. | |
| project_id | No | Which project to act on — the id returned by create_project / set_project / create_promo / load_project. Omit when working on a single local project. |
| Name | Required | Description |
|---|---|---|
| width | No | |
| height | No | |
| duration | No | |
| project_id | Yes | |
| element_count | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description adds validation behavior ('validated against the @clipkit/protocol before being accepted'), error behavior ('invalid inputs return an error'), and unknown-key handling ('flags any it does not recognize'). These operational details give the agent expectations for side effects and 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?
The description is robust but every sentence earns its place: core action, primary usage, alternatives, id behavior, validation, shape summary, and schema pointer. It is front-loaded with the most important information and structured logically.
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 nested object structure and presence of an output schema, the description is exceptionally complete. It covers operation, when to use, parameter behavior, validation, and unknown-key handling. Return values are not described but that is covered by the output 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 100%, so baseline is 3. The description compensates by explaining the source shape ('{ width, height, duration, ... elements:[…] }') and project_id semantics ('Pass an existing project_id to replace that project; omit it to create a new one'). It also points to get_schema for exact fields, adding guidance without replacing 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?
Description opens with 'Replace the entire project with the given source JSON, returning its project_id,' a specific verb+resource statement. It distinguishes itself from sibling tools by declaring 'This is the PRIMARY way to build' and contrasting with edit_element/add_element/delete_element for single-element tweaks.
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 ('to create a composition or to add/change many elements at once') and when not to ('To tweak a single element in an existing project, use edit_element / add_element / delete_element instead'). Also clarifies project_id behavior: pass to replace, omit to create new.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Transcribe an audio or video file into a word-timestamped caption element (the protocol renders these). Captions need real per-word timings, which can only come from actual speech-to-text — this runs Whisper in the server process (no API key, no third-party upload). Provide a url (fetched server-side — use this in chat-mode, where there is no local file) OR a local path. Requires ffmpeg on the host. By default the caption is added to the current project; set add:false to only return it.
| Name | Required | Description | Default |
|---|---|---|---|
| add | No | Add the caption to the current project. Default true. | |
| url | No | Public URL of an audio/video file to fetch and transcribe. Use this OR path. | |
| path | No | Local path to an audio/video file (Claude Desktop / local servers). Use this OR url. | |
| layer | No | Layer for the caption element (higher = nearer front, the highest layer is on top). Default 999 so captions sit above scene content; if the project already stacks that high, the caption goes one above its top layer instead. | |
| model | No | Whisper model id. Default 'Xenova/whisper-base'. Use '…-tiny.en' for speed, '…-small' for accuracy. | |
| language | No | Force a language code (e.g. "en"); omit to auto-detect. | |
| project_id | No | Which project to act on — the id returned by create_project / set_project / create_promo / load_project. Omit when working on a single local project. |
| Name | Required | Description |
|---|---|---|
| text | Yes | |
| added | Yes | |
| word_count | Yes | |
| duration_seconds | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses behavior beyond annotations: runs Whisper in the server process without API key or third-party upload, requires ffmpeg, and by default adds to the current project unless add:false. It also explains the layer default behavior. These are valuable context traits not present in the sparse annotations. Minor gaps remain, such as expected runtime or return format, but output schema covers return shape.
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?
Five sentences, each with a distinct purpose: purpose, rationale, input modes, prerequisite, and default behavior. No redundant or filler content, and the most important information is front-loaded. The structure is crisp and scannable.
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 7-parameter tool with an output schema and minimal annotations, the description covers purpose, why this tool is needed, execution details, prerequisites, parameter flexibility, and side effects. It is complete enough for an agent to reliably select and invoke it without additional lookups.
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%, giving a baseline of 3. The description adds meaning beyond the schema by explaining the practical use cases for url vs path (chat-mode vs local), the layer stacking fallback, and model selection guidance ('tiny.en' for speed, 'small' for accuracy). This context is genuinely helpful for selecting parameters.
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 clearly states the action and resource: 'Transcribe an audio or video file into a word-timestamped caption element.' It uses a specific verb and resource, and distinguishes this tool from generic siblings (like add_element) by emphasizing that only this tool provides real per-word timings via speech-to-text.
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?
Provides explicit context for when to use URL vs local path ('use this in chat-mode, where there is no local file'), notes the ffmpeg prerequisite, and explains the add:false option to avoid modifying the project. However, it does not explicitly name alternatives like add_element for non-transcribed captions, so it misses a clear exclusion statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the @clipkit/protocol validator against the current project AND surface render-time warnings even when the JSON is valid — things that pass the schema but the runtime will silently drop or clip: emoji / non-ASCII text (the runtime font atlas is ASCII-only), elements that run past the composition end, a missing top-level duration. Run it before you share or render the project. For a fuller timeline read-back, use describe_project.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | No | Which project to act on — the id returned by create_project / set_project / create_promo / load_project. Omit when working on a single local project. |
| Name | Required | Description |
|---|---|---|
| valid | Yes | |
| width | No | |
| errors | No | |
| height | No | |
| duration | No | |
| warnings | No | |
| error_count | Yes | |
| unknown_keys | No | |
| element_count | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description details what warnings are surfaced (emoji/non-ASCII, elements past composition end, missing duration) and that they appear even when the JSON is valid. This is valuable behavioral context for an agent.
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 compact but information-dense, front-loading the primary action and then listing specific warning types and usage guidance. Every sentence contributes unique value.
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?
The description fully covers purpose, behavior, and usage context; an output schema exists to handle return values. It is complete given the tool's complexity and annotations.
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 input schema's description for project_id is thorough, including when to omit it, and coverage is 100%. The tool description adds no additional parameter semantics, so baseline 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 explicitly states the tool's function: running the @clipkit/protocol validator and surfacing render-time warnings even when the JSON is valid. It distinguishes itself from describe_project by noting that tool is for a fuller timeline read-back, so purpose is unambiguous.
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 temporal guidance ('Run it before you share or render the project') and names the alternative (describe_project) for different needs. This clearly answers when to use versus siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct action and object: project CRUD, element tweaks, validation, preview, transcription, promo assembly, editor sharing, and rendering. The descriptions explicitly contrast overlapping tools (set_project vs create_project, get_project vs describe_project), so an agent should never confuse them.
All 16 tools follow a strict verb_noun pattern with snake_case (create_project, edit_element, render_video). There are no mixed conventions or vague verb-only names, and the verb consistently reflects the operation (get, set, add, edit, delete, validate, preview, render, open, load, transcribe, create).
At 16 tools, this is just one over the typical 3-15 sweet spot, but the server's scope is a full video authoring and rendering pipeline, and every tool serves a distinct stage of that pipeline. It feels appropriately scoped rather than bloated.
The tool surface covers the full lifecycle: project creation and replacement, element CRUD, validation with render warnings, still preview, caption transcription, template-based assembly, editor round-tripping, and paid rendering. There are no obvious dead ends—any operation an agent needs is present.
Render animated motion-graphics overlays as MP4: lower thirds, titles, callouts
Turn long videos into short, captioned viral clips from your AI assistant. 28 tools, OAuth.
Render on-brand images, PDFs and videos from templates. 60+ tools: brand kit, folders, workflows.
Render video and run AI media tasks from a single declarative JSON request.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/clipkit-video/clipkit'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
