Skip to main content
Glama
Sign In

FilmLab

by com.thefilmradar
OverviewDiscussionsAdmin

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. Every prompt goes through the Dreamer first: run it through lab_prompt_transform before proposing (lab_generate/lab_animate enforce this; proposals and batches do not yet). 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

NameRequiredDescriptionDefault
kindYesWhich kind of generation to propose
toolNoModel 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_secNoVideo: start of the excerpt cut out of the reference clip, in seconds. Only together with out_sec and source_video_id.
intentNoVideo intent from the routing rules. Used to choose a model when tool is omitted and retained for Plan B; an explicit tool wins.
promptYesWhat to generate. The user can edit it on the card; lab_run_proposal takes the edited text as prompt_override without a new proposal. Video only: For a clip of 4 s or longer, write the action as timed beats, one per line under a '// Action Timing' header: '[0-2s] [CAM 01] <framing> -> [ACT] <action> -> [DIAL] <who>: "<line>" -> [AUDIO] <sound>'. The spans start at 0 and cover duration_seconds; keep the same CAM number while the camera does not cut. lab_prompt_transform (medium video) writes exactly this form. Murnau's SceneFlow lights each beat while the clip plays, and the crew judges it there.
familieNoVideo: 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_secNoVideo: end of the excerpt in the reference clip, in seconds. Must lie behind in_sec.
variantsNoImage: how many variants (default 1). Multiplies the price — the card shows the multiplication.
audio_urlNoVideo: URL of an existing audio track to lay under the clip. Independent of generate_audio.
scene_refNoScene label (e.g. 'SZ 04'). Stored on the row, so the result can be matched back to a shot list.
project_idYesProject id (from lab_list_projects)
referenzenNoVideo, 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.
resolutionNoResolution tier, exactly as listed for the model in lab_list_models. Omit for the model's default.
location_idNoLocation board id (from lab_list_locations) — anchors the shot in the same place.
aspect_ratioNoImage: aspect ratio as W:H, from the model's aspect_ratios in lab_list_models.
costume_refsNoThe 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_idNoVideo: the completed image to land the clip on (last frame). Only where lab_list_models says supports_end_frame.
camera_motionNoVideo: 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_refsNoCharacter 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_audioNoVideo: ask for the model's native audio. Only meaningful where lab_list_models says audio: schaltbar.
seed_image_urlNoImage: run img-to-img guided by this existing image URL. Shown on the card as the 'before'.
source_image_idNoVideo: the completed image to animate (positive integer as string). Required for a video proposal — unless source_video_id proposes a clip instead.
source_video_idNoVideo: 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).
dreamer_signaturNoDreamer proof (lab_prompt_transform) for THIS prompt. Without it the proposal runs the Dreamer itself and the card shows its version — that card is what the person confirms.
duration_secondsNoVideo: 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.

  1. Changed1 schema field changed
    • addedInput schema / properties / dreamer_signatur
      Added value: +{
+  "description": "Dreamer proof (lab_prompt_transform) for THIS prompt. Without it the proposal runs the Dreamer itself and the card shows its version — that card is what the person confirms.",
+  "type": "string"
+}
  2. Changed1 schema field changed
    • changedInput schema / properties / prompt / description
      Previous value: -"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."New value: +"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. Video only: For a clip of 4 s or longer, write the action as timed beats, one per line under a '// Action Timing' header: '[0-2s] [CAM 01] <framing> -> [ACT] <action> -> [DIAL] <who>: \"<line>\" -> [AUDIO] <sound>'. The spans start at 0 and cover duration_seconds; keep the same CAM number while the camera does not cut. lab_prompt_transform (medium video) writes exactly this form. Murnau's SceneFlow lights each beat while the clip plays, and the crew judges it there."
  3. Changed1 schema field changed
    • addedInput schema / additionalProperties
      Added value: +false
  4. Changed1 schema field changed
    • 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"
+}
  5. Changed1 schema field changed
    • 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"
+}
  6. Changed1 schema field changed
    • 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"
+}
  7. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the readOnlyHint annotation, the description discloses critical behavior: nothing runs until lab_run_proposal is called, the tool is free, and without a measured price there is no vorschlag_id and no button. It also explains the card-versus-text response path and the Dreamer pre-processing requirement.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core action and pricing/card behavior, then layers in the Dreamer prerequisite and run-gating rule. Every sentence adds distinct operational guidance without repetition.

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 25-parameter proposal tool with no output schema, the description covers the essential mechanics: pricing validation, widget versus text response, Dreamer prerequisite, and the vorschlag_id handoff. It does not fully describe the returned object's structure beyond mentioning vorschlag_id and text fallback, which is a minor gap.

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 all 25 parameters are already documented in the schema. The description adds workflow context around the proposal and vorschlag_id but does not add parameter-specific meaning beyond what the schema provides.

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?

The description states a specific verb and resource: propose a generation for the user to confirm, validating parameters, computing price, and showing a card or returning the same object as text. It clearly distinguishes this from lab_run_proposal, which actually executes, and from lab_prompt_transform, which is the required Dreamer step.

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?

It explicitly names when to use this tool versus alternatives: run lab_prompt_transform first, then use lab_run_proposal with the returned vorschlag_id after the user confirms. It also notes that lab_generate and lab_animate enforce the Dreamer step while proposals and batches do not yet.

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

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