Skip to main content
Glama

Vidova

by ai.vidova
OverviewDiscussionsAdmin

Run Python code on the project's files

run_code

Run Python on the project's files and get files back as project assets. Use it for work the film's own tools do not do: data to a chart (a CSV to a rendered PNG and the JSON an animated chart component reads), a map from GeoJSON, measuring audio (onsets, beats, loudness, pitch) or images (colours, edges, faces), procedural assets (a GLB model for a 3D world, an SVG, a PNG texture, a pattern), file conversions (ffmpeg, a font, a table) and batch work over many files. Do not use it for motion, camera or timing: a follow, a frame, keys and cuts belong in the film. The sandbox has Python 3 with numpy, pandas, scipy, matplotlib (Inter is its font), pillow, opencv, librosa, soundfile, trimesh, pygltflib, shapely, svgpathtools, cairosvg, geopandas, pyproj, requests and the ffmpeg command, and internet access for pip install and public data. Put assets in with assetIds and the film, transcripts, beats and analysis with their fields; /input/manifest.json lists them. Every file the code writes under /output (or the ones outputs names) becomes a project asset: an image, a video, a sound, a 3D model (.glb), a data file (.json, .csv, .geojson, .svg, up to 2 MB) or a font. When the code writes no file there, a figure it shows becomes an image asset. The answer gives each new Asset ID with its line, the printed output and the last expression's value. A Python error comes back with its traceback: fix the code and run it again. Files in /work, imports and variables stay for the next run_code call in this project for 30 minutes. Uses about 0.84 credits a minute, billed by the second while the code runs and its files go in and out; a call that fails on Vidova's side costs nothing. A call that runs past about 45 seconds answers with a Job ID: wait_for_jobs gives its result. Read guide/run-code for worked examples.

Input Schema

NameRequiredDescriptionDefault
codeYesPython 3 to run. It runs in a Jupyter kernel with /work as the working folder: print what you want to read, and the last expression comes back too. Write every file that should become a project asset under /output.
filmYestrue puts the film's files (main.film and its modules) in /input/film. null leaves them out.
beatsYesAssets whose measured beats go in /input/beats/<assetId>.json: the tempo, beats and downbeats in source seconds. null puts none.
outputsYesPaths under /output to import, such as ["/output/chart.png"]. null imports every file the code wrote under /output in this call.
analysisYesAssets whose completed analysis rows (scenes, sound events, tracks and the rest) go in /input/analysis/<assetId>/<plugin>.json. null puts none.
assetIdsYesProject assets to put in /input, each at /input/<file name>: a video as its playable MP4, any other file as it was uploaded or made. /input/manifest.json lists every file with its asset id, kind, duration, size and path. null puts none.
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.
transcriptsYesAssets whose transcript goes in /input/transcripts/<assetId>.json: segments and words with their source seconds. null puts none.
timeoutSecondsYesThe most the code may run, 10 to 600 seconds. null is 120.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only say non-readonly/non-idempotent/non-destructive; the description supplies everything else that matters: the available libraries and internet access, the /output-to-asset mapping with a 2 MB file-size cap, the figure-to-image fallback, what the response contains (Asset ID + <use> line, stdout, last expression), traceback behavior on error, 30-minute persistence of /work and variables, cost of 0.84 credits/minute billed by the second with failures free, and the ~45 s cutoff that returns a Job ID. One nuance: openWorldHint=false sits slightly awkwardly with the stated pip/public-data internet access, but that is a sandbox detail rather than a contradiction of the tool's project-scoped behavior.

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?

Roughly 230 words for a nine-parameter sandboxed execution tool, front-loaded with purpose and exclusions, then environment, I/O contract, response shape and cost — nearly every sentence earns its place. It is delivered as one dense block and lightly restates the assetIds/outputs routing already present in the schema, which costs it the fifth point.

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?

With nine required parameters, no output schema and thin annotations, the description carries the full burden and does: filesystem layout (/input, /output, /work), manifest discovery, asset production rules, return payload, error path and async continuation are all covered. An agent has everything needed to invoke it correctly on the first attempt.

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

Parameters3/5

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 reinforces the binding model ('put assets in with assetIds and the film, transcripts, beats and analysis with their fields; /input/manifest.json lists them' and 'the ones outputs names'), but it does not add format or semantics beyond what the schema already documents for each parameter.

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?

Opens with a specific verb and resource ('Run Python on the project's files') plus the output contract ('get files back as project assets'). The boundary section ('Do not use it for motion, camera or timing') explicitly separates it from the timeline-editing siblings, so an agent can route 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.

Usage Guidelines5/5

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

Gives concrete positive triggers (chart from CSV, map from GeoJSON, audio/image measurement, procedural assets, ffmpeg conversions, batch work) and an explicit exclusion with the alternative destination named ('a follow, a frame, keys and cuts belong in the film'). It also routes to 'guide/run-code' for worked examples and to wait_for_jobs for long runs.

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