Skip to main content
Glama
KyaniteLabs

kinocut

by KyaniteLabs
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

video_add_texts

Overlay multiple text elements or captions on a video in one FFmpeg pass, with optional position, size, color, timing, and automatic layout for stacked texts.

Instructions

Overlay multiple text elements on a video in a single FFmpeg pass.

Returns JSON {success, output_path}. Use when one video needs several captions at once. Pass input_path as the source video and texts as a list of overlay dicts (text plus optional position/size/color/timing).

Args: input_path: Absolute path to the input video. texts: List of text overlay dicts. Each dict may contain: - text (str, required) - position (str|dict, default "center") - font (str, optional) - size (int, default 48) - color (str, default "white") - shadow (bool, default True) - start_time (float, optional) - duration (float, optional) output_path: Where to save the output. Auto-generated if omitted. crf: Override CRF value (0-51, lower = better quality). Default 23. preset: Override FFmpeg encoding preset (ultrafast, fast, medium, slow, veryslow). auto_layout: Automatically distribute vertically stacked texts at the same named position. Default True.

Input Schema

NameRequiredDescriptionDefault
crfNo
textsYes
presetNo
overwriteNoExplicitly allow replacing existing media. Existing non-media files are protected.
input_pathYes
auto_layoutNo
output_pathNo

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.16.4
    • addedInput schema / properties / overwrite
      Added value: +{
+  "default": false,
+  "description": "Explicitly allow replacing existing media. Existing non-media files are protected.",
+  "title": "Overwrite",
+  "type": "boolean"
+}
  2. Changed1 schema field changedv1.16.0
    • addedInput schema / additionalProperties
      Added value: +false
  3. Addedv1.5.1

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses the single-pass FFmpeg behavior, the return shape {success, output_path}, auto-generated output path, and the auto_layout default that distributes stacked texts. It does not mention overwrite semantics or permissions, though overwrite is covered in the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and return shape, then a well-organized Args block. The nested texts documentation is necessarily verbose but every line earns its place; minor redundancy in restating defaults already in the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite 7 parameters and a nested texts list, the description covers all inputs, their defaults, sub-field structure, and the return format. An agent has everything needed to invoke it correctly; the output schema being present makes the return note a bonus rather than a gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 14%, so the description must compensate, and it does: every parameter is documented with defaults (crf 0-51 lower=better default 23, preset enum values, auto_layout default True) and the texts dict sub-fields are fully enumerated with types and defaults.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Overlay multiple text elements on a video in a single FFmpeg pass') and the plural/plural-batch scope distinguishes it from the singular sibling video_add_text. An agent can tell them apart 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.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Use when one video needs several captions at once,' which implies the alternative (single-text tool) for other cases. It stops short of naming video_add_text as the fallback, but the routing condition is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools