FilmLab

Propose Generation

lab_propose

Read-only

Propose a generation for the user to confirm: validates the parameters against the catalog, computes the price, and shows a card (widget hosts) or returns the same object as text. NOTHING runs until lab_run_proposal is called with the returned vorschlag_id — by the card's button, or by you after the user said yes. Without a measured price there is no vorschlag_id and no button: the answer then says so instead of offering an estimate as if it were a quote. Free.

Input Schema

TableJSON Schema

Name	Required	Description
`kind`	Yes	Which kind of generation to propose
`tool`	No	Model id, copied verbatim from lab_list_models. Omit to use the default for this kind — the card names it and prices it either way.
`in_sec`	No	Video: start of the excerpt cut out of the reference clip, in seconds. Only together with out_sec and source_video_id.
`intent`	No	Video intent from the routing rules. Used to choose a model when tool is omitted and retained for Plan B; an explicit tool wins.
`prompt`	Yes	What to generate. The user can edit it on the card; lab_run_proposal takes the edited text as prompt_override without a new proposal.
`familie`	No	Video: pick the model ('seedance-2.0', 'seedance-2.5') instead of a route — the card then names and prices the route the server takes for this account, and the run is PINNED to it (a card promises one price, so no silent fallback). Mutually exclusive with tool and intent.
`out_sec`	No	Video: end of the excerpt in the reference clip, in seconds. Must lie behind in_sec.
`variants`	No	Image: how many variants (default 1). Multiplies the price — the card shows the multiplication.
`audio_url`	No	Video: URL of an existing audio track to lay under the clip. Independent of generate_audio.
`scene_ref`	No	Scene label (e.g. 'SZ 04'). Stored on the row, so the result can be matched back to a shot list.
`project_id`	Yes	Project id (from lab_list_projects)
`referenzen`	No	Video, clip path (source_video_id): typed references. The position IS the address — first image @Image1, first extra clip @Video2, first sound @Audio1. Image references are measured before sending and scaled up to the model's minimum rather than rejected.
`resolution`	No	Resolution tier, exactly as listed for the model in lab_list_models. Omit for the model's default.
`location_id`	No	Location board id (from lab_list_locations) — anchors the shot in the same place.
`aspect_ratio`	No	Image: aspect ratio as W:H, from the model's aspect_ratios in lab_list_models.
`costume_refs`	No	The costume plate of these characters goes along as an extra reference image — the outfit on an invisible mannequin, NO person. Every id must also be in character_refs. Needs a model whose max_references covers characters + plates. Each plate is one more reference and may cost credits.
`end_image_id`	No	Video: the completed image to land the clip on (last frame). Only where lab_list_models says supports_end_frame.
`camera_motion`	No	Video: Structured camera move sent to the model itself — only models whose lab_list_models entry lists camera_motions. Prefer this over prose when a keyframe chain must MOVE rather than cross-fade.
`character_refs`	No	Character ids (from lab_list_characters) whose reference image locks the cast's identity. Counted against the model's max_references and shown on the card by name.
`generate_audio`	No	Video: ask for the model's native audio. Only meaningful where lab_list_models says audio: schaltbar.
`seed_image_url`	No	Image: run img-to-img guided by this existing image URL. Shown on the card as the 'before'.
`source_image_id`	No	Video: the completed image to animate (positive integer as string). Required for a video proposal — unless source_video_id proposes a clip instead.
`source_video_id`	No	Video: propose a run FROM A CLIP instead of a still — a generated video id (lab_animate/lab_job_status) or an asset key (lab_list_assets). Mutually exclusive with source_image_id; only for models that take a video reference (lab_list_models says v2v).
`duration_seconds`	No	Video: clip length in seconds, inside the model's duration grid from lab_list_models. The card shows the DELIVERED seconds and says so when the provider snaps.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 11, 2026
- addedInput schema / additionalProperties
```
Added value: +false
```

Changed1 schema field changedOct 5, 2026

addedInput schema / properties / costume_refs

Added value: +{
+  "description": "The costume plate of these characters goes along as an extra reference image — the outfit on an invisible mannequin, NO person. Every id must also be in character_refs. Needs a model whose max_references covers characters + plates. Each plate is one more reference and may cost credits.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Changed1 schema field changedOct 4, 2026

addedInput schema / properties / familie

Added value: +{
+  "description": "Video: pick the model ('seedance-2.0', 'seedance-2.5') instead of a route — the card then names and prices the route the server takes for this account, and the run is PINNED to it (a card promises one price, so no silent fallback). Mutually exclusive with tool and intent.",
+  "enum": [
+    "seedance-2.0",
+    "seedance-2.5"
+  ],
+  "type": "string"
+}

Changed1 schema field changedOct 4, 2026

addedInput schema / properties / intent

Added value: +{
+  "description": "Video intent from the routing rules. Used to choose a model when tool is omitted and retained for Plan B; an explicit tool wins.",
+  "type": "string"
+}

First observedOct 3, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Annotations only carry readOnlyHint=true, but the description adds substantial behavior: validation against the catalog, price computation, dual output (widget card or text object), a hard non-execution guarantee, and the fact that the call is free. It also warns that the answer refuses to present an estimate as a quote, which prevents a real misuse.

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?

Four sentences, front-loaded with the core action and the execution gate, with the terse 'Free.' closing that earns its place. Slightly dense with em-dash asides, but nothing is padding.

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 24-parameter, no-output-schema tool with minimal annotations, the description covers the lifecycle (propose → confirm → run), the success and refusal cases, and the cost signal. It leaves the returned object's full shape to be discovered, but names the key field (vorschlag_id), which is enough.

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% across all 24 parameters, so the schema already carries the semantics (kind, tool, referenzen channels, cost multipliers, mutual exclusions). The description adds no per-parameter meaning beyond introducing the returned vorschlag_id, so the baseline of 3 applies.

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 ('Propose a generation for the user to confirm') and enumerates the concrete work it does: validates parameters against the catalog, computes the price, and renders a card or text object. This clearly separates it from execution siblings like lab_run_proposal and lab_generate.

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?

Names the follow-up tool and the condition that triggers it: 'NOTHING runs until lab_run_proposal is called with the returned vorschlag_id — by the card's button, or by you after the user said yes.' It also states the failure path (no measured price means no vorschlag_id and no button), which is exactly the decision an agent needs.

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

All FilmLab tools Inspect

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

Need Help?