Skip to main content
Glama

Valmera — agentic AI video editor

by io.valmera
OverviewDiscussionsAdmin

Add overlay

add_overlay

PROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Draw an image or video clip OVER the program picture for a window of PROGRAM time — picture-in-picture, a corner logo, or fit='cover' for a FULL-FRAME B-ROLL CUTAWAY. fit='picture' fills only frame.picture, preserving portrait bars and headline space. The picture switches to the asset while the program's audio (the speaker, the music) keeps playing — THE way to show what the speaker is talking about without touching the timing. asset_key from list_assets (kind='clip'/'image') or a generated/fetched/recorded asset. duration_s defaults: image 4s, video the clip's length (bounded by the program end); b-roll reads best at 2-6s. x/y = the overlay's CENTER as fractions of the frame (ignored with fit='cover') — pass a keyframe list [{t,v}] (t = seconds from the overlay's own start) for a slow drift/slide. scale = overlay width as a fraction of the frame width (0.05-1.0, default 0.4; ignored with fit='cover'). opacity 0.05-1.0 (omit = opaque). entrance/exit: fade, slide_left, slide_right, slide_up. source_start_s seeks into a video overlay. HONEST LIMITS: a video overlay's audio does NOT play (silent), overlays render above footage but BELOW captions (captions stay visible over b-roll), and they do NOT track objects in the footage. insert_media PAUSES the talk and adds time; fit='cover' does not — pick by whether the speech should continue. Assets may be reused whenever the edit benefits from repetition or a different source window.

Input Schema

NameRequiredDescriptionDefault
xNo
yNo
fitNo
exitNo
scaleNo
startYes
opacityNo
entranceNo
asset_keyYes
duration_sNo
project_idYesRequired immutable scope for this call. Copy the id from list_projects/open_project/project_state; the active-project pointer is never used to guess.
motion_motifNoActive Blueprint motion motif id this event executes; never 'hold'.
source_start_sNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / fit / enum
      Previous value: -[
-  "cover"
-]New value: +[
+  "cover",
+  "picture"
+]
  2. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only cover mutation/safety flags, and the description goes well beyond them with a dedicated 'HONEST LIMITS' block: video overlay audio is silent, overlays render above footage but BELOW captions, and they do not track objects. It also discloses project scoping and that the project identity is returned, plus asset reuse rules.

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-loads the scoping rule and core action, and each sentence carries distinct information (no filler). It is nonetheless a dense block of capped emphasis that an agent must parse carefully; slightly more structure would help, but nothing is wasted.

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

Completeness4/5

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

For a 13-parameter mutation tool with no output schema, the description covers behavior, limits, defaults, and most parameters, and notes the project identity comes back with the result. The main gap is motion_motif, which is unexplained despite being a non-trivial parameter.

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?

With only 15% schema description coverage across 13 parameters, the description carries the burden and delivers: fit semantics and frame.picture interaction, duration defaults per asset type, x/y as center fractions plus the [{t,v}] keyframe format, scale/opacity ranges and defaults, entrance/exit values, and source_start_s. Only motion_motif and the exact meaning of `start` are left unaddressed.

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 — 'Draw an image or video clip OVER the program picture for a window of PROGRAM time' — and immediately names concrete instantiations (picture-in-picture, corner logo, full-frame b-roll cutaway). An agent can distinguish it from add_screen_takeover or insert_media 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.

Usage Guidelines5/5

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

Explicitly names the alternative and the deciding condition: 'insert_media PAUSES the talk and adds time; fit=cover does not — pick by whether the speech should continue.' It also frames the tool's raison d'etre ('THE way to show what the speaker is talking about without touching the timing') and where asset_key comes from.

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

All Valmera — agentic AI video editor toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources