Tool reference

Every tool acts on the account the credential belongs to. None of them takes a user id, so none of them can be pointed at somebody else's video.

Reading

pitvi_list_videos

No arguments. Returns every video on the account, newest edit first, with its id, title, duration, frame rate, clip count and updatedAt.

pitvi_get_video

{ videoId }

Returns the full timeline: settings, every clip in every bucket, and the updatedAt to quote back on writes. Read this before editing anything, both to find clip ids and to preserve what is already there.

pitvi_review_visual_quality

{ videoId }

Run this after a generated first cut or a material visual edit and before calling the result ready. It reports data-level signs of an interchangeable generated design: wide shadows, shadows on thin accents, elevation on most surfaces, glass/glow everywhere, repeated equal card triptychs, common purple/blue gradient fingerprints, generic marketing copy and decorative idle motion.

One signal is not a failure and does not prove who authored the design. Three or more independent signals set needsDesignPass, which means the composition needs a deliberate pass against its brand, reference, hierarchy and story.

Catalogs and media

pitvi_find_icons

{ query?, limit? }

Searches the icon catalog and returns names accepted by icon elements. Call it without a query to see the curated groups. Use a returned name instead of guessing: an unknown name cannot render a valid icon.

pitvi_describe_elements

{ type? }

Returns the available UI element types, the data each renderer reads and its default dimensions. Pass one type for a focused description, or omit it for the whole catalog. Read this before creating a specialized UI element.

pitvi_describe_ui_patterns

{ patterns? }

Returns proven image-container + TEXT + ICON composition grammars and the visual-quality guardrails that accompany them. Patterns are starting structures, not templates: adapt their geometry, density, palette, copy, radius, depth and timing to the brief instead of copying the sample treatment.

pitvi_search_photos

{ query, page? }

Searches stock photography. Use a returned url as the src of an image clip.

pitvi_search_music

{ query }

Searches royalty-free music by mood or genre and returns candidates with their title, artist and playable URL.

pitvi_list_uploads

No arguments. Returns the images, videos and audio uploaded to the account, newest first. Check this before stock search when a request refers to the user's logo, recording, image or song.

Creating

pitvi_create_video

{ title?, aspectRatio?, fps? }

Creates an editable project with one five-second background clip. aspectRatio can be 16:9, 9:16, 1:1, 4:5 or 21:9, and defaults to 16:9.

Editing

Every tool that changes an existing video accepts an optional expectedUpdatedAt. See staying out of the editor's way.

pitvi_add_track

{ videoId, track, expectedUpdatedAt? }

Adds a clip and returns its generated id. track is one of these seven shapes, selected by kind:

Text, image, video and UI clips also accept width, height, layoutSide, layer, an exact position, preset animations and property keyframes. Keyframe times are relative to the clip's own start; from is always absolute on the video timeline.

{
  "videoId": "abc123",
  "track": {
    "kind": "text",
    "content": "Cohorts. Without the wait.",
    "role": "TITLE",
    "from": 2.5,
    "duration": 3,
    "layoutSide": "CENTER"
  }
}

Use either an empty div surface or a known image/https://placehold.co/... image as the container for a UI simulation, then layer separate text, real image/logo assets and specialized elements from pitvi_describe_elements above it. A div accepts only paint in style—background, border, radius, shadow, opacity and backdrop blur. It rejects text, typography and children.

pitvi_compose_ui

{ videoId, elements, expectedUpdatedAt? }

Adds a complete product-UI beat atomically from an empty DIV or a known image/https://placehold.co/... container, plus separate TEXT, real IMAGE/LOGO assets and specialized UI elements such as ICON. Put labels and icons above the container and give related elements matching timing. IMAGE containers remain fully supported. Scene backgrounds stay in native BACKGROUND tracks and are not part of the UI simulation.

Avoid using the tool as a card generator. Cards are grouping devices, not the default container for every idea.

A camera move is not a scale

kind: "camera" moves the whole frame: every clip and the background travel together. Scaling a clip changes only that clip. The camera's x and y are the composition-space point it settles on, and scale must be between 1 and 4.

pitvi_update_track

{ videoId, trackId, patch, expectedUpdatedAt? }

Merges patch into one clip. Anything left out is kept, and element merges one level deep, so changing a colour does not require resending the content and box.

pitvi_move_track

{ videoId, trackId, from?, duration?, layer?, expectedUpdatedAt? }

Changes when a clip starts, how long it lasts or what it stacks over. from is absolute seconds on the video's timeline.

pitvi_delete_track

{ videoId, trackId, expectedUpdatedAt? }

Removes one clip. The video's duration is recalculated from what remains.

Video-wide

pitvi_set_background

{ videoId, layers, expectedUpdatedAt? }

Replaces the background layers. Each layer is timed like a clip; leave its timing out to cover the whole video.

{
  "videoId": "abc123",
  "layers": [{ "background": { "type": "color", "value": "#0a0a0a" } }]
}

Background types are lowercase. Alongside flat colors and gradients, Pitvi supports image, video, patterns and animated shader backgrounds. The tool schema lists the accepted names and fields.

pitvi_set_settings

{ videoId, fps?, width?, height?, aspectRatio?, expectedUpdatedAt? }

Changes frame rate and frame size. Duration is deliberately absent: a video is as long as its furthest clip reaches.

Visual-quality rules

Visual quality is part of correctness. A valid timeline can still be a weak one-shot draft when several unchosen defaults accumulate.

• Do not default to a purple/blue gradient, centered hero, three equal rounded cards, giant icon badges, glass panels, glow blobs or pills everywhere.
• Use an effect when the supplied brand/reference, information hierarchy or interaction state gives it a reason to exist.
• Thin lines, connectors, accent strips, progress tracks and background blobs normally have no shadow. Resting panels use short, neutral elevation; reserve deeper or colored shadows for one genuinely floating focal surface.
• Prefer whitespace, alignment, typography, dividers, tables, timelines and shared shells before nesting more cards.
• Motion must explain entrance, causality, focus or state. Keep supporting UI stable long enough to read and avoid perpetual idle animation by default.
• Use specific product copy and believable states instead of interchangeable slogans or decorative analytics.

The key distinction is intent: gradients and rounded forms can be strong brand language, and glass can clarify a real overlap. The failure is inheriting them as median polish without connection to the product.

A reliable one-shot MCP workflow is:

pitvi_get_video
-> pitvi_describe_ui_patterns (when composing product UI)
-> editing calls
-> pitvi_get_video
-> pitvi_review_visual_quality
-> correct material signals
-> pitvi_get_video for the final audit/version

Staying out of the editor's way

The editor auto-saves the timeline. If a tab is open on the same video, a stale browser save can conflict with an agent edit. Read first, then quote what you read:

pitvi_get_video -> { ..., "updatedAt": "2026-08-03T21:14:02.113Z" }
pitvi_add_track { "expectedUpdatedAt": "2026-08-03T21:14:02.113Z", ... }

If the video changed in between, the write is rejected. Read the video again and apply the edit against its current timeline. expectedUpdatedAt is optional, but any workflow with more than one call should pass it.