Skip to main content
Glama

Vidova

by ai.vidova
OverviewDiscussionsAdmin

Put an effect over a clip

apply_effect

Put one effect from search_effects into the film. It writes the effect on a new track in front of the clip it goes over, adds what the effect draws to the project, and makes what the effect needs. An effect on a person reuses a person mask of the clip's footage, or runs cutout_person on the part of the footage the effect covers. An effect on a face reuses a face track of that footage, or runs track_faces there and takes the first face. Those runs use credits as those tools do. at is the timeline second the effect starts. duration null uses the effect's own length. clipId is the video clip the effect goes over: an effect on a person or a face needs it, and every effect sits in front of it when it is given. values is JSON text of the settings that differ from the effect's defaults, such as {"emoji": "😭"} or {"face": "track_face_2"}; photos go in by Asset ID, such as {"top": "img_a", "bottom": "img_b"}. region is the part of the frame an overlay effect covers, as [x0, y0, x1, y1] fractions of the frame; null uses the effect's own box, most often the whole frame. Use one effect per moment, on a real beat or impact: an effect on every cut reads as noise. It writes the current version. The effect is in the film at once, and the editor shows it waiting while its mask or face is made; if that cannot be made, the effect is taken out again and the answer says why. A long cutout answers with a Job ID: wait for it with wait_for_jobs, and the effect plays when the cutout ends. Check the result with preview_frame.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
atYesTimeline second the effect starts.
clipIdYesId of the video clip the effect goes over, from read_film. Needed for an effect on a person or a face. null places the effect in front of every track.
regionYesThe part of the frame an overlay effect covers, as [x0, y0, x1, y1]: its top left and bottom right corners as fractions of the frame. null (or leaving it out) uses the effect's own box, most often the whole frame. An effect drawn on a person or a face ignores it.
valuesYesJSON text of the effect's settings that differ from its defaults, as search_effects lists them, such as {"emoji": "😭"}. Photos go in by Asset ID. null keeps every default.
durationYesHow long the effect runs on the timeline, in seconds. null uses the effect's own length.
effectIdYesEffect id from search_effects.
projectIdYesThe project this call runs on without changing the open project. null (or leaving it out) uses the open project. wait_for_jobs takes the projectId of the calls that started the jobs.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only mark this as a non-readonly, non-idempotent mutation; the description goes far beyond by disclosing that it writes on a new track, reuses masks/face tracks or runs cutout_person/track_faces (consuming credits), writes the current version, and rolls the effect back with an explanatory answer if the mask can't be made. It also explains the Job ID path for long cutouts.

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?

The purpose is front-loaded and most sentences carry weight for a complex 7-parameter tool, but the prose is dense and slightly rambling in places, with a minor typo ('at is the timeline second'). It is adequately sized rather than tight.

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?

For a complex mutation with 7 required params and no output schema, the description is complete: it covers side effects, credit costs, mask/face prerequisites, error rollback, and the async Job ID plus preview_frame verification path. 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.

Parameters4/5

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 concrete value with worked examples ('{"emoji": "😭"}', '{"face": "track_face_2"}', photos by Asset ID like '{"top": "img_a"}') and restates the key null-semantics for duration, region and clipId in prose. It adds useful grounding beyond the schema field docs.

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 ('Put one effect from search_effects into the film') and clearly routes from discovery (search_effects) to application. An agent can distinguish it from siblings like prepare_effect or apply_template 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.

Usage Guidelines4/5

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

Gives real usage guidance ('Use one effect per moment, on a real beat or impact: an effect on every cut reads as noise') and names follow-ups (wait_for_jobs for long cutouts, preview_frame to check). It doesn't explicitly differentiate from the closely related prepare_effect sibling, so it stops 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.

All Vidova 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