AI film lab for filmmakers: generate and review images/clips with input provenance, cost preflight
Scored across 150 tools
Most tools are individually distinguishable because the descriptions are unusually explicit, but the 150-tool surface still creates real set-level ambiguity: many status/polling tools, several generation/planning paths, and multiple lifecycle tools overlap by domain. An agent can often recover by reading the long descriptions, but choosing the right tool is not reliably obvious from the names alone.
All tools use the lab_ prefix and snake_case, which is consistent at the surface level, but the semantic pattern is mixed: English verbs, German nouns, noun-only names, and different verb conventions appear throughout. It is readable, but not a predictable verb_noun convention across the set.
150 tools is far beyond an appropriate scoped surface, even for a complex film-production pipeline. The count creates discoverability and selection problems; many capabilities could be consolidated into fewer, more coherent tools.
The surface covers an unusually broad lifecycle: projects, characters, locations, props, sequences, timelines, generation, audio, VFX, export, review, licensing, and workflow orchestration. Some CRUD gaps remain (e.g. limited deletion/update coverage outside locations), but the domain is mostly well covered.
Prompt check of ONE generated image or clip: does the result show what its prompt asked for? The backend first DESCRIBES the result without seeing the prompt, then splits the prompt into checkable claims (counts as digits, quoted text, identity, place, framing, style; for clips the motion) and scores each. verdict: pass | mismatch | unverified, plus checks, issues and the neutral beschreibung. Runs automatically after every generation (lab_job_status shows it as abgleich); call this to read it, or with neu=true to check again. On mismatch: offer at most ONE retry per original, lead the new prompt with the failed claim; never re-run a video on your own. Free for the account (FilmLab carries the cost).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Asset id (positive integer as string) | |
| neu | No | Discard an existing result and check again (ignored within 60 s of the last check) | |
| reference_type | Yes | What kind of asset |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses substantial behavior beyond annotations: the two-stage backend (describe-then-claim-split), the verdict enum and returned fields, that neu discards an existing result and is ignored within 60 s, and that the call is free to the account. readOnlyHint=false is consistent with the neu re-check path; no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Dense but front-loaded: purpose first, then backend mechanics, verdicts, workflow policy, and cost. Nearly every sentence carries information, though the numbering of claim types and the long retry clause make it heavier than strictly minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by naming the return fields (verdict, checks, issues, beschreibung) and the pass/mismatch/unverified values. For a three-parameter check tool it tells the agent everything needed to invoke it and act on the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds context the schema lacks: neu is framed as 'check again' within the automatic-after-generation workflow, and id/reference_type are situated in the read-vs-recheck loop. It stops short of explaining field-level formats already covered by the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource+scope: 'Prompt check of ONE generated image or clip: does the result show what its prompt asked for?' It further distinguishes itself from siblings by noting it runs automatically after every generation and is surfaced by lab_job_status. An agent can identify it 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance: it runs automatically after every generation, so calling it reads the result; call with neu=true to re-check. It states when-not and the follow-up policy on mismatch (offer at most ONE retry, lead the new prompt with the failed claim, never re-run a video autonomously).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Append a shot to a sequence's timeline. Call it once per shot, in cutting order — start_time is computed from the clips already there, so appending in order is enough. The continuity pass reads exactly this timeline: a shot missing here is a shot nobody checks. Returns the new clip's index and the sequence's total duration.
| Name | Required | Description | Default |
|---|---|---|---|
| text | No | Text content for type 'title', 'credits' or 'lower_third' | |
| type | Yes | What this clip is. 'image' references a generated image via source_id; 'title', 'credits' and 'lower_third' carry `text` instead. 'lower_third' is an OVERLAY: appended without start_time it is laid over the clip before it (track V2), takes no time of its own and never runs past that clip's end; metadata.versatz_s delays it inside that clip. As the very first clip it is a card on black. 'video' is where it gets sharp — read the source_id note before using it | |
| seq_id | Yes | Sequence id (from lab_create_sequence/lab_list_sequences) — positive integer as string | |
| metadata | No | JSON stored alongside the clip. The continuity pass reads video_id (a generated video's id — it checks the start image), image_url (a frame URL), location_id and scene_num from here; for a 'lower_third', versatz_s (seconds into the clip it sits on) sets when it appears; other keys are stored as-is | |
| source_id | No | For type 'image': the id of a generated image (from lab_generate). For type 'video': source_id is IGNORED by the continuity pass (a video id used to be misread as an unrelated image, see vault/followups/2026-08-04-continuity-loest-source-id-blind-auf.md). Give a video clip its frame via metadata instead: metadata.video_id = the generated video's id (the pass checks the video's start image), or metadata.image_url = a frame URL. Without either, the shot is counted as 'not checked' (summary.ohne_frame). | |
| start_time | No | Absolute start on the timeline. Omit to append after the last clip (the normal case); set it only to place a clip deliberately | |
| duration_seconds | No | Clip duration in seconds. Backend default is 5.0 — pass the clip's REAL length, otherwise the sequence duration and the render drift apart |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false and destructiveHint=false, which is minimal. Description adds important context: start_time is computed from existing clips, continuity pass reads this timeline, returns index and duration. Doesn't elaborate on failure modes or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, all earning their place. Front-loaded with purpose, then usage, then consequence, then return value. No waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no annotations, description covers purpose, usage, behavioral consequence (continuity pass), and return value. Complete for a mutation tool whose schema is fully documented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. Description adds nuance about start_time computation and ordering expectations, which informs how to use parameters correctly beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource: 'Append a shot to a sequence's timeline.' Clearly distinguishes from siblings like lab_create_sequence, lab_shots_setzen, and lab_timeline_apply by focusing on single-shot append.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clear when-to-use: 'Call it once per shot, in cutting order.' Explains how to append in order. But doesn't mention when NOT to use or name alternatives for bulk operations, though it's fairly implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bring your own video, audio or image into a project — not generated, yours. Two ways: media_url (a public http(s) address; the server fetches it, max 100 MB) or file_name + content_type (you get a signed upload_url and the header that are part of its signature: PUT the file's raw bytes there within the hour with EXACTLY those headers — the answer's anleitung has the ready curl line; a missing header is a 403). Either way the answer is the asset_key — use it in lab_timeline_apply as clips[].asset_key (video) or bett.asset_key (audio). A URL import also returns url, a signed address (24 h) for tools that want an address; an uploaded file shows up as the newest row of lab_list_assets with its url once the PUT is done. lab_reference_motion also takes the asset_key as reference_video_url. Exception: in projects that check images, an uploaded image is not in the project after the PUT — the answer then carries abschluss_noetig and an abschluss_key; after the PUT call lab_add_media again with the same project_id, art, herkunft and abschluss_key only. That call checks the image and returns the asset_key, or says why it was refused. Free. Internal addresses are refused.
| Name | Required | Description | Default |
|---|---|---|---|
| art | Yes | What the file is | |
| herkunft | Yes | Required, no default: 'eigen' = shot, recorded or made by people (no AI generation); 'ki' = generated or altered with AI. Decides the EU AI Act Art. 50 disclosure of every export that uses this file. If the file itself carries an AI mark (C2PA or IPTC source type), it stays AI material whatever you declare, and the answer says so. | |
| file_name | No | Name of a local file to upload, with extension. Give this OR media_url | |
| media_url | No | Public http(s) URL of the file. Give this OR file_name | |
| project_id | Yes | Project id (from lab_list_projects) — positive integer as string | |
| content_type | No | Media type of the upload, e.g. video/mp4, audio/mpeg — required with file_name | |
| abschluss_key | No | Only after an upload whose answer said `abschluss_noetig`: the `abschluss_key` from that answer, given AFTER the PUT returned 200. Give it instead of media_url and file_name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnly=false / destructive=false; the description adds the substance: 100 MB cap, server-side fetch, signed upload_url with an exact-header signature and a one-hour window, 403 on missing headers, 24 h signed URL, refusal of internal addresses, and that the operation is free. The `abschluss_noetig` / `abschluss_key` re-call exception is disclosed rather than discovered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and the two paths; every sentence carries operational content. It is dense, however, with heavy parenthetical nesting and mixed German field names (`anleitung`, `abschluss_noetig`), which slows scanning of the exception paragraph.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description carries the return burden — and it does: `asset_key`, `url`, `upload_url` + `header`, `anleitung`, and the `abschluss_noetig`/`abschluss_key` refusal variant. Combined with the async-upload protocol and the post-PUT visibility in lab_list_assets, nothing an agent needs to complete the round trip is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 goes further: it explains the mutual exclusivity of media_url vs file_name+content_type, the size limit on the URL path, and — critically — the exact protocol for `abschluss_key` (same project_id, art, herkunft; only the key; after PUT returns 200). Only the enums are left entirely to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (bring your own video/audio/image into a project) and immediately disambiguates against the generation tools with 'not generated, yours'. The two intake paths are named concretely, so an agent can distinguish this from lab_generate 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit branching: use `media_url` for a public address, or `file_name` + `content_type` for a local upload — mutually exclusive and stated as such. It also gives the downstream routing (asset_key into lab_timeline_apply clips[]/bett, lab_reference_motion as reference_video_url) and the conditional second-call flow for image-checking projects.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a photo and extract location fields from it (Gemini Vision, costs credits — exact price via get_cost: true). Returns the fields — it does NOT create a board; feed the result into lab_create_location yourself. Note the payload: the image travels as base64 inside the call, so keep it small (a downscaled JPEG, not a full-resolution capture).
| Name | Required | Description | Default |
|---|---|---|---|
| get_cost | No | Free: the exact price of this operation; nothing is rendered or charged. Name it to the person before the real run. | |
| mime_type | No | Defaults to 'image/jpeg' | |
| image_base64 | No | The image as base64. A data-URL prefix ('data:image/jpeg;base64,…') is stripped by the backend |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say readOnlyHint=false/destructiveHint=false; the description adds real behavioral facts — it consumes credits via Gemini Vision, it deliberately does not persist a board, and the image travels inline as base64 so payload size matters. These are exactly the non-obvious traits an agent needs before invoking.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action, then cost, then the non-persistence caveat, then payload advice. Dense use of em-dashes but every clause carries information; nothing is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description must cover returns — it says 'Returns the fields' and clarifies the downstream step (feed into lab_create_location), but does not enumerate what the extracted fields look like. Flow and cost are complete; the return shape is only loosely characterized.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is already 100% (get_cost, mime_type, image_base64 all documented), so baseline is 3. The description adds practical value on top: price via get_cost, name the cost to the user, and keep the base64 payload downscaled rather than a full-resolution capture.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Read a photo and extract location fields from it.' It goes further by naming the sibling it is not — explicitly 'it does NOT create a board' — and routes the agent to lab_create_location, so it is unmistakable against the many lab_* siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear operating context: run with get_cost: true first to price the credits, then feed the result into lab_create_location yourself. It stops short of naming an alternative analyzer or a when-not condition, but the workflow it belongs to is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Animate a completed image into a clip with a video model. Pick the model from lab_list_models; check the price with get_cost or let the user confirm a card via lab_propose. Costs credits when called without get_cost.
| Name | Required | Description | Default |
|---|---|---|---|
| seed | No | Seed for a repeatable run. Omit it and the project's stored seed applies (POST /api/lab/projects/{id}/einstellungen), and without that the provider picks one. The seed that actually rendered comes back in lab_job_status as `seed` with `seed_quelle` ('provider' = read from the provider's answer, 'gesetzt' = the one sent, null = the model tells no seed). Models whose endpoint has no seed field do not drop a given seed silently: the run proceeds and the row carries `seed_hinweis: seed_nicht_unterstuetzt` — some models tell their seed but take none, others take one but tell none. | |
| tool | No | Video model id — copy it verbatim from lab_list_models (kind: video). Omit to let the intent router choose. Every model has its own resolutions, duration grid, audio behaviour and price; the catalog is the only place those live, this text deliberately names none. | |
| shots | No | Multi-shot: a sequence of shots rendered as ONE output, holding character, place and voice across the cuts. This is NOT the same as several clips stitched together — those you pay for individually and they do not hold the cast. PRICE: the billed length is the SUM of the shot durations, not duration_seconds. Three 5s shots cost the same as one 15s clip (140 credits at the reference resolution), not the same as one 5s clip (47). The sum must fit the provider's 3-15s window — each shot may be legal on its own and the sum still too long. Only kling_3_pro. Requesting it elsewhere is rejected before quota is spent. | |
| in_sec | No | Cut the reference clip server-side before it reaches the provider: start of the excerpt, in seconds from the clip's beginning. Only together with out_sec, and only with source_video_id. | |
| intent | No | Say WHAT the shot is instead of picking a model — the router chooses by priority and a cost cap. 'draft' and 'ambient' route to the cheapest provider, 'dialog' to the one with the steadiest faces, 'hero' to the most expensive on purpose, 'atmo' for atmosphere. Prefer intent over tool: it also gives you an automatic fallback to the next provider if the first one hard-fails. An explicitly set `tool` always wins over intent. | |
| prompt | Yes | Motion/camera instruction for the animation. 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. | |
| familie | No | Pick the MODEL, not the access route: 'seedance-2.0' or 'seedance-2.5'. The server takes the cheapest route that this account may use and that can do the job (OpenRouter only with the user's consent; references, 1080p for 2.5, or audio switched off go to fal) and falls back to fal if a cheaper route fails — the fallback can cost more than the preflight price. Mutually exclusive with tool and intent. | |
| out_sec | No | End of the excerpt in the reference clip, in seconds. Must lie behind in_sec; both are set together or neither. Only with source_video_id. | |
| get_cost | No | Preflight: return the price in credits and your balance WITHOUT generating, reading the same catalog as lab_list_models. Do this before a batch or when the user wants to see the cost. For a card the user confirms, use lab_propose instead. | |
| metadata | No | Free-form JSON stored alongside the video. Not interpreted by the pipeline. | |
| prop_ids | No | Prop ids from lab_list_props, belonging to this project (an @prop_ tag in the prompt does the same). Animating an image: the descriptions go into the prompt as text, no prop image is sent. From a clip (source_video_id): the front views join the reference images on free slots, as in lab_reference_motion. | |
| audio_url | No | URL of an existing audio track to lay under the clip. Independent of generate_audio, which asks the PROVIDER to synthesise its own. | |
| scene_ref | No | Scene label (e.g. 'SZ 04'). Stored on the row, so clips can be matched back to a shot list and reviewed per scene with lab_review_queue. | |
| shot_type | No | How to cut a multi-shot clip. 'customize' (default) renders exactly the shots you gave. 'intelligent' lets the model decide the cutting — your shot prompts become a suggestion, not a spec. Belongs to `shots`; alone it is rejected. | |
| apply_lens | No | Defaults to TRUE on the backend: the project's lens_state UrPrompt is appended to the prompt. Pass false only to deliberately opt out for this one call. | |
| kamerapfad | No | The camera move as INPUT instead of prose: an object following shared/kamerapfad/schema.json — poses over time (position, look-at or quaternion, metres, Y up) from the Kadrage terrain flight or drawn by hand, or motion phases as lab_kamerafahrt reads them from a clip (its answer carries a ready `kamerapfad`). The backend validates it, derives phases, and then writes the move into the prompt IN THE FORM THIS MODEL UNDERSTANDS: prose at the camera slot for most families, bracketed director commands inside the prompt string for the MiniMax/Hailuo family, which parses them. NO MODEL RECEIVES THE POSES TODAY — the answer says which form went out (kamerapfad.angewandt = als_text or als_regiebefehle), names the family rule and the source it rests on (kamerapfad.sprache), and lists what that form could not carry (kamerapfad.nicht_gesendet, kamerapfad.befehle_weggefallen next to kamerapfad.befehle_gesamt). IF YOUR OWN PROMPT ALREADY CARRIES BRACKETED COMMANDS and the model parses them, the path is NOT sent on top of them — two chains would contradict each other at the same parser; the answer then says angewandt = eigene_regie and names what it found in kamerapfad.eigene_regiebefehle, and your prompt goes out unchanged. A `zusammenfassung` inside the path is display only and is NEVER sent — the move is always rebuilt from the phases; if nothing can be built (phases without tempo/verlauf), the answer says angewandt = nicht_ableitbar with the reason, and nothing of the path is in the prompt. Mutually exclusive with kamerapfad_url. | |
| project_id | Yes | Project id (from lab_list_projects) | |
| referenzen | No | Typed references for the clip path (source_video_id). The position IS the address: the first image is @Image1, the first extra clip is @Video2 (the reference clip itself is @Video1), the first sound is @Audio1. Write @bild1/@video1/@ton1 in the prompt and they are resolved to exactly these positions HERE, before anything is sent — no detour through lab_prompt_transform needed (it resolves them too when it rewrites a prompt). Every image reference is MEASURED before it is sent and scaled up to the model's minimum if it is below it; nothing is ever rejected for being small. | |
| resolution | No | Resolution tier, exactly as listed for the model in lab_list_models. Omit for the model's default. Some models have no resolution field at all — then leave it out. | |
| location_id | No | Location board id (from lab_list_locations). The board's `prompt_prefix_en` is appended to your prompt as 'Location: …', so a clip stays in the same place as the images shot there. A board WITHOUT a prefix anchors nothing and fails silently — check with lab_list_locations. | |
| stil_kit_id | No | Style kit id from lab_list_stil_kits (an @stil_ tag in the prompt does the same). Omit it and the project's default kit applies (lab_stil_kit_standard); its rules and palette go into the prompt as text, and its reference images join only where the call already sends reference images (characters or props) and the model has a free slot after them. The answer says which way it went (stil_kit.weg). | |
| end_image_id | No | id of a completed image to land the clip on (last frame). REQUIRES a start frame (source_image_id or character_refs) — an end frame alone is rejected before quota is spent. Only kling_3_pro. | |
| camera_motion | No | 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. | |
| ohne_keyframe | No | Skip the keyframe checkpoint on purpose. By default a paid clip only starts from a start image the user has approved (lab_review_asset verdict: accepted) — look at the frame first, then spend on the clip. Set true only when the user explicitly asked to skip the frame check. | |
| ohne_stil_kit | No | true switches the project's default style kit off for this one call. | |
| apply_grundton | No | Defaults to TRUE on the backend: the project's ground tone (the filmmaker's own creative signature, set in the Composer's prompt stage) goes right after the prompt. Pass false only to deliberately opt out for this one call. | |
| character_refs | No | Character ids (positive integer strings) whose reference image locks the cast's identity for this clip. On most providers only the FIRST character's image is used, as the start frame — with two characters in frame the second is unbound. On kling_3_pro each character additionally becomes its own reference element (frontal view plus up to 3 further angles from its sheet), so all of them are bound. The response reports `elements_bound` and `characters_without_reference`. | |
| generate_audio | No | Ask for the model's native audio track. Only meaningful where lab_list_models says audio: schaltbar — models with audio: immer always have it, audio: nie never. | |
| kamerapfad_url | No | Address of a kamerapfad JSON instead of the object — the url of a file in THIS project (lab_list_assets), e.g. the kamerapfad JSON that Kadrage writes next to its flight video. Fetched by the backend under the same ownership rule as every reference: a file of another project is a named rejection before anything is charged. Mutually exclusive with kamerapfad. | |
| source_image_id | No | id of a completed image (from lab_generate/lab_job_status) to animate — positive integer as string. Required unless get_cost is true. Imported Midjourney images work directly: use an image_id from lab_umzug. | |
| source_video_id | No | Animate FROM A CLIP instead of a still: the id of a generated video (from lab_animate/lab_job_status) or the asset key of an uploaded one (from lab_list_assets, asset_type 'video'). The run then goes to the reference-motion path — your clip leads, the model restyles it. Mutually exclusive with source_image_id, and only for models that take a video reference (lab_list_models says v2v); The picture-side fields (end frame, shots, audio, location) do not travel this path and are rejected rather than dropped; character references exist here under a different name (ready image URLs instead of sheet ids) and are rejected too, with that reason. An intent IS resolved before the run and travels as the chosen model. | |
| character_states | No | Which STATE each character is in for this clip, as { characterId: stateKey } — e.g. { "12": "wet" }. A state is its own asset with its own full descriptor (clean / soaked / bloodied are three assets, not one with a note), and it is the ONLY way that descriptor reaches a generation: the reference image always carries the BASE state, so without this field you get dry Cal in a scene where he just came out of the Thames — and the clip looks correct. Get the keys from lab_get_character_sheet. Every id here must also appear in character_refs (who is not in the frame is not described), and an unknown key is rejected before any quota is spent. | |
| character_voices | No | Bind a voice per character: character id -> fal voice id. Voice ids come from fal-ai/kling-video/create-voice — FilmLab keeps no voice registry of its own, the id is passed through unverified. Every character named here must also be in character_refs AND must have a generated reference image (no image → no element → nothing to bind the voice to; rejected before quota is spent). Only kling_3_pro. | |
| dreamer_signatur | No | Proof from the Dreamer (lab_prompt_transform, or the dreamer_fassung of a previous call) that THIS prompt went through it. Without a valid one the tool does not generate: it runs the Dreamer and returns its version first. | |
| duration_seconds | No | Clip length in seconds. Must lie inside the model's duration grid from lab_list_models; inside the grid the provider may snap to its nearest step. IGNORED when `shots` is given — then the rendered length is the sum of the shot durations. | |
| nur_eigene_daten | No | Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only. | |
| abdruck_startframe | No | Generate frame one WITH the character's trained Figurenabdruck (LoRA) instead of taking the flat studio portrait from the character sheet — the clip then starts IN the scene rather than in a photo studio. Opt-in: it costs one extra image (3 credits). Needs EXACTLY ONE character_ref that has a finished Abdruck, and is rejected together with source_image_id (that one PICKS frame one, this one MAKES it). Refused before any quota is spent. | |
| veraltete_figur_ok | No | Only with source_video_id (the clip path); animating an image rejects it. Exception for a reference clip made with an OLDER version of a character: such a clip is refused (figur_veraltet, nothing charged). Set it to true ONLY after the human has seen that warning and said yes to going on with the old version — ask first, name the price, wait for the yes; never set it on your own. Default off. The alternative is to re-create the clip with the current version of the figure. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark the tool as non-read-only and non-destructive, and the description adds the key behavioral point that it costs credits unless get_cost is used, plus the lab_propose confirmation route. However, for a complex paid generation call it omits job lifecycle, validation/fallback behavior, and return shape, leaving clear gaps beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three efficient sentences with the purpose front-loaded, followed by model-selection and cost-preflight guidance. There is no filler, and every sentence contributes to correct invocation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema is extremely rich, but the description does not orient the agent to major modes such as source_video_id reference-motion, multi-shot generation, or batch alternatives, nor does it mention job/output behavior. For a 38-parameter paid generation tool, it is minimally sufficient but relies almost entirely on the schema for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 38 parameters, including nested shots and references, are already documented in the schema. The description adds little parameter-level meaning beyond naming get_cost and the model catalog; therefore the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: animate a completed image into a clip with a video model. It also points to lab_list_models for model choice. It does not distinguish itself from siblings like lab_animate_batch or lab_reference_motion, and it omits the schema-supported clip-reference path via source_video_id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells the agent to pick a model from lab_list_models and either check price with get_cost or confirm a card via lab_propose. That gives clear preflight context. It does not explain when to use this tool instead of batch or reference-motion alternatives, nor when to use the image path versus the clip path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Animate MANY images into videos in ONE call (max 25 jobs). Prefer this over looping lab_animate: it validates every job BEFORE spending any quota, so an invalid job 12 of 15 does not leave 11 paid-for generations running. Quota is spent once, collectively (one ledger row); refunds stay per-clip, so a partial failure refunds only that clip. Returns a batch_id — poll lab_batch_status with it instead of polling each id separately. Every job's prompt goes through the Dreamer first: without valid dreamer_signatur on ALL jobs, nothing is generated or charged; the batch returns each dreamer_fassung and signature for human approval (at most four Dreamer calls at once). Repeat with the approved versions and signatures. get_cost: true preflights the whole batch without generating anything.
| Name | Required | Description | Default |
|---|---|---|---|
| jobs | Yes | One entry per clip, max 25. All jobs are validated before any quota is spent | |
| get_cost | No | Preflight: return the summed price in credits for the WHOLE batch and your balance WITHOUT generating, reading the same catalog as lab_list_models. For a card the user confirms, use lab_propose instead. | |
| project_id | Yes | Project id (from lab_list_projects) | |
| ohne_keyframe | No | Skip the keyframe checkpoint on purpose. By default a paid clip only starts from a start image the user has approved (lab_review_asset verdict: accepted) — look at the frame first, then spend on the clip. Set true only when the user explicitly asked to skip the frame check. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say readOnlyHint=false and destructiveHint=false; the description adds genuine behavioral context beyond that: quota is charged once collectively with per-clip refunds on partial failure, all jobs are validated before any charge, a batch_id is returned for polling, and the Dreamer gate blocks all generation until signatures are valid on every job. It also discloses the concurrency limit (at most four Dreamer calls at once) and the approval round-trip before spending.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is front-loaded with the action and scope, then layers cost model, polling, and the Dreamer approval loop in a logical order; every sentence carries operational information. It is dense and long, but the length is justified by the amount of non-obvious cost/approval behavior being disclosed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a nested-array batch tool with no output schema, the description covers the essential unknowns: return value (batch_id), billing semantics, failure/refund behavior, and the mandatory Dreamer approval cycle. The only soft spot is the retry step after approval ('Repeat with the approved versions and signatures'), which is stated but not spelled out in detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents each parameter and the description rightfully avoids repetition. It still adds cross-parameter semantics the schema cannot express: the collective vs per-clip billing model, the all-or-nothing dreamer_signatur requirement, and that get_cost preflights the whole batch rather than one job. It adds value without duplicating field-level text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence names a specific verb, resource, and scope ('Animate MANY images into videos in ONE call (max 25 jobs)'), and the second immediately contrasts it with the sibling it replaces: looping lab_animate. An agent can select this over lab_animate without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states the primary selection rule ('Prefer this over looping lab_animate') with the reason (validation before quota spend), plus the alternative paths: use lab_batch_status for polling and get_cost:true for a no-generation preflight, and lab_propose for a card the user confirms. When-to-use and when-to-use-something-else are both explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compute the sequence's clip durations from the project's cutting preset and — when the tempo allows it — pull the cut points onto the measured beat grid. WRITES the timeline; costs nothing. The old duration of every changed clip is kept in clip.metadata.dauer_vorher, so one undo step exists (a second differing run overwrites it — there is no history). Clip count is never changed: no clip is added or removed. SNAPPING IS NOT GUARANTEED, AND A REFUSAL TO SNAP IS A RESULT, NOT A FAILURE — read gerastet and raster.grund before you repeat anything: 'tempo_unverlaesslich' = measured below the confidence threshold (deliberate; pass trotz_unsicherem_tempo to override), 'nicht_gemessen' = run lab_beatgrid first, 'keine_musikspur'/'musikspur_nicht_aufgeloest' = run lab_bind_audio first, 'rhythmus_ohne_raster' = the preset's rhythm is 'frei' or 'atmend', which means not snapping IS the promise ('auf den Beat', 'auf die Songstruktur' and 'gegen den Takt' are the three that snap), 'toleranz_null' = you passed toleranz_s 0. In every one of those cases the durations are still recomputed from the preset and written — that alone is the difference between 40 and 6 cuts over 30 seconds. Also read raster.getroffen of raster.von: gerastet: true only says snapping ran; this pair says whether it landed. And geklemmt lists clips the renderer's own duration clamp moved back OFF the grid.
| Name | Required | Description | Default |
|---|---|---|---|
| seq_id | Yes | Sequence id (from lab_create_sequence/lab_list_sequences) — positive integer as string | |
| toleranz_s | No | How far a cut point may travel to land on a beat, in seconds (default 0.12 — three frames at 25 fps). 0 disables snapping entirely and only recomputes the durations | |
| trotz_unsicherem_tempo | No | Snap onto a grid whose own measurement reports `verlaesslich: false`. Default false, and that default is the honest one: below the threshold the detector has not confirmed it found the pulse. Set it only as a deliberate decision — the answer then carries raster.unsicheres_tempo_uebergangen: true |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations give readOnlyHint=false, idempotentHint=true, destructiveHint=false, and the description adds substantial context beyond that: the write is free, the prior duration is stashed in clip.metadata.dauer_vorher giving a single undo step that a second differing run overwrites, and there is no history. It also discloses that a refusal to snap is a valid result, not an error, and clarifies that 'gerastet: true' only proves snapping ran while raster.getroffen shows whether it landed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core action is front-loaded and no sentence is filler — the dense error-code list and the dauer_vorher/undo caveat are all decision-relevant. It is nevertheless a long, single-block description; a short bulleted split of the refusal codes would have improved scanability without losing content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return contract itself: it names the fields to inspect (gerastet, raster.grund, raster.getroffen of raster.von, and geklemmt) and explains what each implies. Prerequisite ordering and the non-error semantics of a failed snap are fully covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 real value by tying parameters to outcomes: passing toleranz_s 0 yields 'toleranz_null' and disables snapping, while trotz_unsicherem_tempo overrides the 'tempo_unverlaesslich' refusal and sets raster.unsicheres_tempo_uebergangen. This gives the agent a reason to set each optional parameter rather than just their formats.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a precise verb and resource — recomputes clip durations from the cutting preset and snaps cut points to the measured beat grid — and explicitly scopes what it does not do (clip count never changes). It is clearly separable from siblings like lab_beatgrid and lab_bind_audio, which it names as prerequisites.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use, when-not-to-use, and prerequisite routing: 'nicht_gemessen' → run lab_beatgrid first, 'keine_musikspur'/'musikspur_nicht_aufgeloest' → run lab_bind_audio first, and 'rhythmus_ohne_raster' → the preset is 'frei'/'atmend' so not snapping is intended. The trotz_unsicherem_tempo override is also explained as a deliberate choice rather than a default.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Break one scene down into a STRUCTURED shot list of 2, 4 or 6 shots — each with shot size, camera angle, purpose and its own ready prompt, plus one shared floor plan (anchor, axis, light) so the shots cut together. Two families: an 'aufloesung' shows ONE moment from several angles (coverage, dialog, orbit, pov, zwischenschnitte for cutaways …); a 'montage' lets time pass between shots (ursache_wirkung, zeitverlauf, kleiner_bogen …). An unknown art is rejected with the list of known ones. Costs no credits: it is one text-model call and renders nothing; generate the shots afterwards with lab_generate / lab_animate, one prompt each. This is NOT lab_shots_ableiten — that one groups clips that already exist on a timeline; this one plans shots that do not exist yet. By default nothing is written. uebernehmen=true appends the shots as scenes to the project's shot list (mod_shotlist), which the image and video steps read — ask before you set it.
| Name | Required | Description | Default |
|---|---|---|---|
| art | No | Which breakdown. Default coverage. Known: coverage, dialog, winkel, hoehen, orbit, pov, naehe, gesicht, haende, reaktionen, zwischenschnitte (aufloesung); ursache_wirkung, entdeckung, zeitverlauf, gefuehlswende, kleiner_bogen (montage). | |
| laenge | No | Number of shots: 2, 4 or 6. Default 4. Never odd — a breakdown runs in pairs. | |
| prompt | Yes | The scene or the master prompt to break down | |
| scene_ref | No | Optional scene reference the shots are filed under when uebernehmen=true | |
| project_id | Yes | The project the scene belongs to | |
| uebernehmen | No | Default false. true appends the shots to the project's shot list — ask first. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false, idempotentHint=false, destructiveHint=false; the description adds substantial context beyond them — zero credit cost, one text-model call, nothing rendered, no writes by default, and that uebernehmen=true appends scenes to mod_shotlist which downstream image/video steps read. It also flags that unknown art values are rejected with the known list, and instructs the agent to ask before writing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose and output shape, then alternatives, cost, and the write side effect. Every sentence carries information, though the single dense paragraph is longer than strictly necessary and the art-family enumeration could be tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and a write-capable parameter, the description compensates fully: it describes what the returned shot list contains, the credit/render cost, the default no-write behavior, the opt-in write and its downstream consumers, and the follow-up tools. 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.
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 real semantics the schema does not: the two art families (aufloesung = one moment from several angles; montage = time passing) and what each named art means, plus the 'never odd — runs in pairs' rule for laenge. The uebernehmen side effect is also clarified beyond the schema's short note.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — break one scene into a structured shot list — and immediately names what each shot contains (size, angle, purpose, prompt) plus the shared floor plan. It explicitly contrasts itself with the sibling lab_shots_ableiten, so an agent can distinguish the two 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use context ('plans shots that do not exist yet'), an explicit when-not with the alternative named ('NOT lab_shots_ableiten — that one groups clips that already exist'), and the downstream path ('generate the shots afterwards with lab_generate / lab_animate, one prompt each').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Auto run with a hard spending cap: the person approves ONE run with an upper limit in credits; inside it you may generate without asking per item, but never above the cap. aktion: anlegen (project_id + deckel_credits → status 'angelegt', nothing can be spent yet) · freigeben (ONLY after the person explicitly approved the cap) · stand (cap, reserved, free, items) · beenden. While a run is active, EVERY paid call in that project reserves its price against the cap — whichever tool makes it; reservations are never refunded (a failed item keeps its share, a retry reserves again), upscales and exports count too. The cap counts credits: runs on the person's OWN provider key (BYOK, 0 credits) are not counted. Other projects are not affected. When the cap would be crossed the backend answers budget_exceeded: stop, report what finished, what is open and the minimum budget still needed. Under budget pressure lower the resolution first, never cut runtime, never drop character or location variants.
| Name | Required | Description | Default |
|---|---|---|---|
| aktion | Yes | What to do | |
| lauf_id | No | freigeben / stand / beenden: the id from anlegen | |
| project_id | Yes | Project id (from lab_list_projects) | |
| deckel_credits | No | anlegen only: the cap in credits. Name it to the person in credits AND in the price list's terms before freigeben |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say it is a non-idempotent, non-destructive write; the description adds far more: every paid call reserves against the cap regardless of which tool makes it, reservations are never refunded, failed items keep their share, retries re-reserve, upscales/exports count, BYOK runs are excluded, and other projects are unaffected. This is exactly the beyond-annotations behavioral context an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core concept, then the action list, then the reservation rules; the separator-based layout is scannable. It is dense and long, but nearly every clause carries operational meaning, with only mild redundancy in the budget-pressure advice.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, yet the description covers what stand returns (cap, reserved, free, items) and what budget_exceeded signals, and it documents the full mutation lifecycle. Nothing needed 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.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds real semantic depth: it explains what each aktion value does and when it is permitted, and that deckel_credits must be named to the person in both credits and the price list's terms before freigeben. Only lauf_id semantics are left entirely to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific mechanism (auto run bounded by a hard spending cap in credits) and enumerates the four actions with their state transitions ('anlegen → status angelegt, nothing can be spent yet'). No sibling covers this concept, so it is trivially distinguishable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit sequencing: approve one run with a cap, generate freely inside it, 'freigeben ONLY after the person explicitly approved the cap', then stand/beenden. It also prescribes the exact recovery path on budget_exceeded (stop, report finished/open/minimum needed) and under budget pressure (lower resolution first).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Auto-generate a storyboard from either script OR situationen (mutually exclusive). An LLM splits script into scenes; situationen bypasses that LLM entirely and generates exactly one frame per entry, ignoring max_scenes. situationen requires figur_id of an existing character sheet with a reference image: every frame uses that character on seedream_5_pro, without creating a new sheet. format selects 16:9 (default) or 9:16 for every model. bewegung_en is saved in each frame’s metadata for later animation. COSTS CREDITS — every scene is one generated image, charged up front for the number of scenes the script is split into (at most max_scenes). Ask the human before running it. CHARACTERS ARE NOT GUESSED: every character who appears in more than one frame first gets a reference image (an existing project character with a reference is reused for free; a new one is created and its reference sheet is charged separately as character_sheet_generate), and every frame showing such a character is generated WITH those references on seedream_5_pro instead of model. Frames without a recurring character use model. The answer lists figuren (name, status, scenes), figuren_kosten_geschaetzt and kosten_je_bild; prices per model come from lab_list_models. If a reference cannot be made, the frames that need it fail and are refunded — they are never generated without it. The scene split is SYNCHRONOUS and can take up to ~55s and then time out (504) for long scripts; run it in the app if so. The answer lists the new image ids; the frames themselves render in the background as pending images — poll them with lab_job_status (type 'image').
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | Image model for the frames. Default krea_2_medium. Prices per model: lab_list_models. | |
| format | No | Frame aspect ratio for every model, default 16:9 | |
| script | No | Screenplay or scene description; provide either script or situationen. The backend splits script into scenes; each scene becomes one image. | |
| figur_id | No | Existing character-sheet id with a reference image; required for situationen, only used with situationen | |
| creativity | No | Krea 2 creativity setting; ignored by flux_pro. Default medium. | |
| max_scenes | No | Upper limit for the number of scenes, and therefore images charged. Backend default when omitted. | |
| project_id | Yes | Project id | |
| situationen | No | Independent situations, each exactly one frame. Requires figur_id; excludes script and figuren_raten. | |
| figuren_raten | No | Opt-out, off by default: true skips the character references and lets the image model invent every character from the text — a different face in every frame. Only set it when the human explicitly asks for that; it is recorded on every frame (figuren_geraten). | |
| nur_eigene_daten | No | Same rule as lab_animate: set it only after the human has said this material shows or contains no real person other than them, for this step. Needed for figures from photos or a style reference on a model without a documented transfer basis. | |
| style_reference_url | No | Shared moodboard image applied to ALL frames for one consistent look. Used by Krea 2 and by the Seedream character-reference path (one additional reference, included in pricing). Must be an asset of this project or an absolute URL — anything else is refused before credits are spent. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only give readOnlyHint=false and destructiveHint=false, so the description carries the real burden and does it well: credits are charged up front per split scene, failed reference frames are refunded rather than generated without a reference, and the split is synchronous with a ~55s/504 timeout. Frames render in the background as pending images to be polled via lab_job_status. Minor gap: it never states which project roles or permissions are required to run it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core modes and cost warning, and nearly every sentence carries operational weight (mutual exclusivity, refunds, timeout, polling). It is still one dense block of prose that would scan faster as bullets, and the costs/characters passage is long-winded relative to the rest.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter, credit-consuming tool with no output schema, the description still explains the response shape (figuren, figuren_kosten_geschaetzt, kosten_je_bild, new image ids as pending frames) and the follow-up call needed. Nothing an agent needs in order to invoke it safely or handle the result is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 genuine cross-parameter meaning the schema cannot: situationen bypasses the scene split and ignores max_scenes, format applies to every model, bewegung_en is persisted into frame metadata for later animation, and style_reference_url applies to ALL frames and is validated before credits are spent. The model enum's interaction with the character-reference path (seedream_5_pro replaces `model` for recurring characters) is also explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Auto-generate a storyboard") and immediately defines the two mutually exclusive input modes, script vs situationen. An agent can tell exactly what this produces and how it differs from siblings like lab_generate or lab_situationen 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says script and situationen are mutually exclusive, when situationen is appropriate (one frame per entry, bypasses the LLM, ignores max_scenes), that figur_id is mandatory in that mode, and that figuren_raten should only be set when the human explicitly asks for it. It also names the alternative path when the synchronous split times out ("run it in the app") and the downstream polling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Aggregated progress of a video batch started by lab_animate_batch. Returns {total, completed, failed, pending, done, items[]} — poll this ONCE per batch instead of calling lab_job_status per clip. done: true means nothing is pending any more (some items may still have failed). Each item carries retry_count (an automatic second attempt happened) and fallback_from (the provider was swapped after a content-policy rejection).
| Name | Required | Description | Default |
|---|---|---|---|
| batch_id | Yes | The batch_id returned by lab_animate_batch (format: vb_<hex>) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint only tells the agent this is a safe read; the description goes well beyond that by decoding lifecycle edge cases — `done: true` with still-failed items, `retry_count` meaning an automatic second attempt, and `fallback_from` meaning a provider swap after a content-policy rejection. This is behavior an agent could not infer from annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded, followed by the return shape, the polling rule, and then field semantics — a logical order with no filler. Every clause (done semantics, retry_count, fallback_from) carries distinct information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description takes on the return-value burden and does so thoroughly: it enumerates the JSON keys, explains `done`, and interprets the per-item fields. Nothing needed to call or interpret this tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter with 100% schema description coverage, including the vb_<hex> format, so the schema already carries the burden. The description implies batch_id filtering but adds no syntax beyond what the schema states, making the baseline 3 correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb+resource ('aggregated progress of a video batch') and ties it to its producer (lab_animate_batch), while explicitly distinguishing it from lab_job_status. An agent can tell exactly what this returns 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'poll this ONCE per batch instead of calling lab_job_status per clip' gives an explicit alternative plus the condition that selects this tool over it. It also states the prerequisite (a batch started by lab_animate_batch).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Turn the still-image clips of a sequence into video clips that exactly fill their beat-snapped slots. Free — this tool itself generates nothing. aktion plan: one job per image clip, ready for lab_animate_batch — start image, the frame's motion (bewegung_en), and the SMALLEST duration the model can deliver that still covers the clip's timeline duration (a shorter video would end early and shift every later cut off the beat). Refuses with 409 if a start image is not accepted yet. Pass the returned jobs unchanged to lab_animate_batch (get_cost first, then run). aktion einsetzen: once the videos are done, each finished video replaces its image clip — same duration, source in-point 0. Repeatable; reports what is still open and any video shorter than its slot (left as still). Run lab_beatgrid and lab_apply_rhythm on the sequence BEFORE plan, so the durations are the beat durations.
| Name | Required | Description | Default |
|---|---|---|---|
| tool | No | plan only: video model id from lab_list_models — default vidu_q3_turbo (1-second grid) | |
| aktion | Yes | plan: build the animate jobs; einsetzen: put finished videos into the timeline | |
| seq_id | Yes | Sequence id (from lab_create_sequence/lab_list_sequences) — positive integer as string | |
| resolution | No | plan only: resolution tier from lab_list_models — default 720p |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the thin annotations: discloses that the tool is free and generates nothing, that it refuses with 409 if a start image is not yet accepted, that it is repeatable, and that it reports what remains open plus any video shorter than its slot (left as a still). What it does not state is what exactly happens to the original image clip on einsetzen beyond 'replaces' — e.g. whether that replacement is recoverable — which is the one behavioral detail an agent would still want.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core purpose in one sentence and then organizes the two modes with explicit 'aktion plan'/'aktion einsetzen' markers, so it is scannable despite its density. Some phrasing is clunky — mixed German jargon and a few run-on clauses in the plan paragraph — but almost every sentence carries operational information rather than filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description compensates by telling the agent that `jobs` is the return value from plan, that it must be passed unchanged to lab_animate_batch, and that einsetzen reports open items and undersized videos. The workflow is complete end to end; only the exact shape of the plan/report payload is left implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description earns above that by giving each aktion mode real semantics ('build the animate jobs' vs 'put finished videos into the timeline') and by explaining the tool/model parameters' defaults and their 1-second grid implication. The critical constraint on duration ('the SMALLEST duration the model can deliver that still covers the clip's timeline duration') is stated, though the resolution tier is left entirely to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb and resource: 'Turn the still-image clips of a sequence into video clips that exactly fill their beat-snapped slots', then clarifies it generates nothing itself. The two modes (plan builds jobs, einsetzen installs finished videos) are each stated in a single clause, and the tool is clearly separable from lab_animate_batch, lab_beatgrid and lab_apply_rhythm in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit ordering: run lab_beatgrid and lab_apply_rhythm BEFORE plan; pass the returned jobs unchanged to lab_animate_batch after get_cost; then switch to aktion=einsetzen once videos exist. It also states the repeatability and the 409 refusal case, so the agent knows when the tool cannot be used at all.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Measure the TEMPO of the sequence's bound music track and store the beat grid — opens the real file with ffmpeg and analyses it, no guessing and no provider, so it costs nothing but a few seconds. Writes bpm and metadata.beat_grid on the audio row; it does NOT touch the timeline (timeline_geaendert: false). Deterministic and cached: a second call returns the same numbers without downloading again (pass neu_messen to force). READ confidence AND verlaesslich BEFORE YOU CUT. Below the threshold (0.35) lab_apply_rhythm computes durations but deliberately does NOT snap them to the grid — that is a decision, not a failure. Soft material measures badly: a real swing track came out at 0.164, an ordered hard pulse (techno, 128 bpm) at 0.621. Half and double tempo are the classic misreads, so bpm_alternativen is part of the answer. frame_konflikt reports the collision between beat grid and frame grid, for BOTH renderers: export (24 fps, the delivered MP4) and murnau (25 fps, the editor timeline). Read frames_pro_schlag as a DEVIATION, not a count: it is how far one beat sits from a whole frame, between 0 and 0.5. 0 means beat and frame coincide (100, 125 and 150 bpm at 25 fps do); anything above means beat-accurate and frame-accurate cannot both hold, and the rounding error accumulates across clips — measured on a finished MP4 at 128 bpm: up to 64.7 ms off the audible beat although every cut point had snapped. Shown here, not fixed: that decision belongs to a human. Refusals that name their own remedy: 409 without a bound music track (run lab_bind_audio), 409 when the track is pending (poll lab_list_audio), 502/504 when the audio host is unreachable or slow, 422 when the file carries no usable audio, 503 when ffmpeg is missing.
| Name | Required | Description | Default |
|---|---|---|---|
| takt | No | Beats per bar (default 4). INPUT, not detection — time-signature detection is explicitly out of scope. It only affects where the downbeats fall, which is what the rhythm 'auf die Songstruktur' snaps to | |
| seq_id | Yes | Sequence id (from lab_create_sequence/lab_list_sequences) — positive integer as string | |
| neu_messen | No | Measure again even though a result for this exact file already exists. Default false. The measurement is deterministic — the same file gives the same number, so this only helps after the track behind the url was swapped |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial context beyond the annotations: writes `bpm`/`metadata.beat_grid`, does not touch the timeline, is deterministic and cached, costs only seconds, opens the real file via ffmpeg with no provider, and enumerates refusal codes (409/502/504/422/503) with remedies. This is rich disclosure; only the exact return-field semantics of every key are left implicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and outcome, and most sentences carry genuine behavioral information. It is long and dense with parenthetical asides and example measurements, some of which could be trimmed, but little is pure filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, yet the description explains the return fields an agent must interpret (confidence, verlaesslich, bpm_alternativen, frame_konflikt, frames_pro_schlag) and their meaning, including the 0–0.5 deviation semantics. Nothing needed to call and interpret it is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents `takt`, `seq_id` and `neu_messen`. The description reinforces `neu_messen` ('pass neu_messen to force') but adds no format or constraint information beyond what the schema already states. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: 'Measure the TEMPO of the sequence's bound music track and store the beat grid'. It immediately distinguishes itself from siblings like lab_apply_rhythm (which consumes the grid) and lab_bind_audio (which supplies the track), so an agent can route correctly 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs 'READ confidence AND verlaesslich BEFORE YOU CUT', explains what lab_apply_rhythm does below the 0.35 threshold, and names the remediation tools for each refusal (lab_bind_audio, lab_list_audio). When-to-use, downstream dependency, and alternatives are all covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
See a clip at EXACT seconds: up to 12 frames, in the order you list them, tiled into one image and shown. Use it to check what is on screen where you plan a cut, whether a motion has ended, or whether a face drifted between two moments — lab_contact_sheet spreads frames evenly and cannot answer 'what is at 3.2 s'. A second past the clip's end is rejected by name, not clamped. Works on generated clips (video_id) AND on your own uploaded footage (project_id + asset_key from lab_add_media) — look at it before you cut it. Free (no credits).
| Name | Required | Description | Default |
|---|---|---|---|
| preview | No | Show the image inline (default true) | |
| sekunden | Yes | Seconds into the clip, e.g. [0.5, 3.2, 3.24]. Order is kept: left to right, then the next row (4 per row) | |
| video_id | No | Generated video id (from lab_animate/lab_job_status) — positive integer as string. Give this OR asset_key | |
| asset_key | No | Storage key of uploaded footage (from lab_add_media / lab_list_assets). Needs project_id | |
| project_id | No | Project the asset_key belongs to — required with asset_key | |
| kachel_breite | No | Width of one frame in px (default 480) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover idempotency and non-destructiveness, but the description adds real behavior the annotations cannot: out-of-range seconds are rejected by name rather than clamped, the call is free (no credits), and it accepts two different source modes (generated video_id vs uploaded project_id+asset_key). The readOnlyHint=false is not contradicted by the text, since the tool does produce a new tiled image artifact, though the description never explains that distinction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and capped at a handful of dense sentences that each carry information. Slightly bloated by the em-dash asides and the marketing-flavored closer ('look at it before you cut it'), but nothing is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description fully specifies the return shape (one tiled image shown inline), plus error behavior and cost. For a six-parameter, dual-source frame-extraction tool this is complete enough to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 schema already documents ordering, row layout, the 12-item cap, and the source-id pairs. The description mostly restates these ('up to 12 frames, in the order you list them') and only adds the provenance pointer for asset_key/video_id, which is marginal over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('See a clip at EXACT seconds'), the output form (up to 12 frames tiled into one image), and the exact scope that separates it from the nearest sibling by name. An agent can tell this apart from lab_contact_sheet without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete when-to-use triggers (checking what is on screen before a cut, whether motion has ended, whether a face drifted) and an explicit when-not with the named alternative: lab_contact_sheet spreads frames evenly and cannot answer 'what is at 3.2 s'. It also states the workflow ordering ('look at it before you cut it').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bind the project's generated audio to a sequence's tracks — ONE call that does both halves of the job, because doing only the first half silently produces a silent film. Half one (POST …/soundmix) creates the four empty tracks (dialog, music, sfx, atmo); half two (POST …/soundmix/resolve-stems) is what actually attaches the audio rows to them. On 2026-08-28 that split cost a complete silent export: the mix looked configured, and every track was empty. From here it is one tool, and it is idempotent — an existing mix is NOT re-initialised (that would throw away volumes, effects and the other tracks' bindings), only re-resolved. Per track it takes the audio row marked selected, otherwise the newest one with a url. Rows still pending have no url and stay unbound. That choice is re-made on every call: generate a second music track and run this again, and the music track follows the NEWER row — unless one row is pinned with selected, which is set in the web UI. With audio_ids the named rows are bound and PINNED, and every track you do NOT name is pinned EMPTY (so an old narrator or sfx row of the project cannot slip into the mix); later automatic resolves, e.g. before a render, keep all of that. A call WITHOUT audio_ids releases every pin and resolves as described above. Changes state, costs nothing. Next: lab_beatgrid.
| Name | Required | Description | Default |
|---|---|---|---|
| seq_id | Yes | Sequence id (from lab_create_sequence/lab_list_sequences) — positive integer as string | |
| audio_ids | No | Bind EXACTLY these rows instead of the newest/selected one per track, as { music: '12', dialog: '13' }. Named tracks are pinned to these rows, tracks you leave out are pinned empty. Each row must belong to this project, match the track's audio type and have a file. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only give readOnly=false, idempotent=true, destructive=false; the description goes well beyond them by spelling out that an existing mix is NOT re-initialised (protecting volumes/effects/bindings), that rows without a url stay unbound, that pin choices persist across later automatic resolves, and that state changes but costs nothing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose, then ordered purpose → two halves → idempotency → selection rule → audio_ids → no-audio_ids → next tool. It is long, and the 2026-08-28 incident sentence is narrative justification rather than call-time information, though it does explain the design.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter mutation tool with no output schema, everything an agent needs is present: required id source, the two operating modes, idempotency guarantees, row-selection rules, and the natural next step.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 semantics the schema does not carry: unnamed tracks are pinned EMPTY so stale rows cannot slip in, pins survive later automatic resolves, and omitting audio_ids releases every pin. Only the seq_id parameter gets no extra color.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Bind the project's generated audio to a sequence's tracks') and immediately scopes it against the failure mode of doing only half the job, which cleanly separates it from siblings like lab_list_audio, lab_sfx and lab_mix.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to call it, what the two internal halves are, when the pinning mode (audio_ids present) vs the resolve mode (audio_ids absent) applies, and names the follow-up tool ('Next: lab_beatgrid'). An agent has no routing ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
See the CUT at exact seconds of the finished film: up to 12 frames, tiled into one image and shown. Each second is mapped like the export maps it — which clip is on screen, where in its source (src_in_s counts), the export's framing (scaled and letterboxed), title cards drawn. A video whose source is shorter than its clip duration ends early in the export, and everything after it moves forward; this tool follows that, so you see the film that will be rendered. The answer names per frame the clip (position, clip_id), clip start and offset; a clip that would render black says so ('schwarz'). NOT in the image: lens/grade, lower thirds, the AI badge — that needs lab_start_export. Use it after lab_timeline_apply to check cut points before exporting. Free (no credits).
| Name | Required | Description | Default |
|---|---|---|---|
| seq_id | Yes | Sequence id — positive integer as string | |
| preview | No | Show the image inline (default true) | |
| profile | No | Export profile key (default 'web'); a 9:16 profile gives portrait frames — see lab_export_profiles | |
| sekunden | Yes | Seconds into the finished film, e.g. [0.5, 4.9, 5.1]. Order is kept: left to right, then the next row (4 per row) | |
| kachel_breite | No | Width of one frame in px (default 480) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare safety hints (readOnlyHint=false, idempotentHint=true, destructiveHint=false); the description goes well beyond by describing export-fidelity semantics (source shorter than clip duration ends early and subsequent material shifts forward), black-frame handling ('a clip that would render black says so (\'schwarz\')'), the per-frame answer contents, and cost ('Free (no credits)'). With no output schema, this disclosure of return content and quirks is exactly the added value the description should carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded and every sentence carries weight: the export-fidelity sentence is dense but necessary for interpreting results, and the exclusion clause routes to the right sibling. It is on the long side and slightly packed with jargon (src_in_s, 'schwarz'), which keeps it just short of a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a five-parameter tool with no output schema, the description covers return shape (per-frame clip position, clip_id, clip start and offset; black frames flagged), workflow placement, cost, and rendering caveats. Nothing an agent needs to call and interpret this tool correctly appears missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five parameters (seq_id, sekunden, preview, profile, kachel_breite) are already documented with defaults and bounds. The description adds interpretive context about what sekunden map to ('Each second is mapped like the export maps it') and the 12-frame limit, but no syntax or format detail beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise verb and resource ('See the CUT at exact seconds of the finished film: up to 12 frames, tiled into one image and shown') and explicitly demarcates scope against siblings: 'NOT in the image: lens/grade, lower thirds, the AI badge — that needs lab_start_export.' An agent can separate it from lab_render_frames, lab_contact_sheet, or lab_letzter_frame without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit workflow position ('Use it after lab_timeline_apply to check cut points before exporting') and names the alternative for the excluded content ('that needs lab_start_export'). Both the when and the when-to-use-something-else are stated, not inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create character sheets for the people found in a project's material — the writing counterpart to lab_cast_gaps. Creates at most 6 per call and binds each to the project. Costs an LLM run per call. Run lab_cast_gaps first if you want to see what it would create. The sheets it creates have NO reference image: each one still needs lab_generate_character_reference before lab_generate accepts it as character_refs. Fail-open: no script or no AI key returns an EMPTY created list with a note, not an error. Each created sheet carries a casting note (world, the one deviation from the obvious face, why). herkunft: true additionally lets the casting propose the person's ORIGIN as that one deviation (skin, hair and eye tone only) — off by default, because it changes who a named character is; the note names it.
| Name | Required | Description | Default |
|---|---|---|---|
| herkunft | No | Allow the origin as the casting deviation (default false). Only turn it on when the person asked for casting against type by origin. | |
| project_id | Yes | Project id (from lab_list_projects) — positive integer as string |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare write/non-destructive; the description adds the operationally critical traits: a hard cap of 6 per call, per-call LLM cost, projection onto the project, missing reference images, and fail-open semantics (empty `created` plus `note` instead of an error). It also explains the side effect of `herkunft` on named characters, which no structured field conveys.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and sibling distinction are front-loaded, and each clause carries operational content. The final herkunft sentence is dense and partially overlaps the schema description, which keeps it from being maximally tight.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description compensates by naming the returned fields (`created`, `note`, and the per-sheet `casting` note with world/deviation/why) plus the fail-open return shape. For a paid, mutating, batch-limited tool, everything an agent needs before calling is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 meaning beyond the schema: why `herkunft` is off by default (it changes who a named character is), that it is limited to skin/hair/eye tone, and that the casting note names it. That rationale is genuinely additive rather than a restatement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Create character sheets for the people found in a project's material") and immediately distinguishes itself from the sibling lab_cast_gaps as "the writing counterpart". An agent can tell the two apart without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit ordering guidance ("Run lab_cast_gaps first if you want to see what it would create"), a downstream prerequisite chain (sheets have no reference image, so lab_generate_character_reference is required before lab_generate will accept them as `character_refs`), and a when-not rule for herkunft. Nothing about selection is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find people who appear in a project's material (script / cast module) but have NO character sheet yet. Returns up to 6 missing entries, each with a name and a short hint from the text. It creates nothing — lab_cast_autopopulate does that. Costs an LLM run, so it is credit-gated. Fail-open by design: no script, no AI key, or an unparseable answer all come back as an EMPTY list (with a note saying which) — an empty list is the correct answer, not an error.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project id (from lab_list_projects) — positive integer as string |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, idempotentHint=true, destructiveHint=false; the description explains why the read-looking tool is not read-only (it consumes an LLM run and is credit-gated) and adds the return cardinality (up to 6 entries) plus the full fail-open contract with a 'note' field. That is substantive context beyond the annotations rather than repetition.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tight sentences, front-loaded with what it does, followed by return shape, the sibling contrast, the cost gate, and the failure semantics. No filler and no repetition of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return contract (up to 6 'missing' entries with name and hint) and the failure behavior, which is exactly what an agent needs. Nothing material for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter with 100% schema description coverage ('Project id (from lab_list_projects) — positive integer as string'), so the schema already does the work. The description adds no syntax or format detail beyond it; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise verb+resource and scope: finds people present in a project's material but lacking a character sheet. It explicitly distinguishes itself from lab_cast_autopopulate ('It creates nothing — lab_cast_autopopulate does that'), so an agent can route without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Names the alternative sibling and the division of labor (this finds gaps, the other creates), and flags the cost gate ('costs an LLM run, so it is credit-gated'), which tells the agent to call it deliberately rather than speculatively. The fail-open note also tells the agent not to treat an empty list as a failure.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Propose THREE candidates for ONE role, the way a street-casting director does: the obvious face, the one you would walk past, and the one nobody would think of. Casting is choosing — this gives you something to choose from. It creates nothing: pick one and create it with lab_create_character, passing that candidate's anlegen fields (they include project_id). Costs an LLM run per call, so it is credit-gated, and every call draws NEW candidates (it is not cached on purpose). What the project material fixes (age, gender, …) is the same in all three; the answer's spektrum says whether they really differ (ok, maengel). Fail-open: no material, no AI key or an unusable answer comes back as an EMPTY list with a note, not an error — fewer than three candidates carry note: unvollstaendig.
| Name | Required | Description | Default |
|---|---|---|---|
| notiz | No | What to know about the role that the material does not say, e.g. 'retired judge, buys the same roll every morning'. Without material, a note alone is enough. | |
| rolle | Yes | The role to cast, usually the character's name, e.g. 'Ottmar'. It becomes the sheet name of every candidate. | |
| project_id | Yes | Project id (from lab_list_projects) — positive integer as string. Its script and cast module are the material. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: discloses the credit gate, the deliberate non-caching, the fail-open contract (empty list + `note` instead of an error when material, AI key or answer is missing), and the `note: unvollstaendig` case for short lists. It does not describe latency or how partial failure interacts with billing, but the destructive/no-op profile is fully covered by annotations, so what remains is genuinely additive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and the 'creates nothing' boundary before the cost and error semantics. It is information-dense rather than padded, though the em-dash-chained sentences and the mid-paragraph fail-open detail make it slightly harder to scan than a shorter version would be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description still tells the agent what comes back (`anlegen` fields including project_id, `spektrum` with `ok`/`maengel`, `note`) and how to read a degenerate response. For a 3-parameter, credit-charged generation tool this covers everything needed to call and interpret it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so `rolle`, `notiz` and `project_id` are already documented in full. The description adds only a little on top (that `rolle` becomes every candidate's sheet name, and that `notiz` alone suffices with no material), and it spends more words on output fields (`anlegen`, `spektrum`) than on inputs. Baseline 3 is right when the schema carries the parameter burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise verb and resource (propose three candidates for one role) and immediately scopes it against the sibling that actually persists data: 'It creates nothing: pick one and create it with lab_create_character'. The 'street-casting director' framing adds the selection logic (obvious / overlooked / unexpected) without obscuring what the call returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use and the follow-up path: call this to get options, then pass a candidate's `anlegen` fields to lab_create_character. It also names the cost condition (credit-gated, an LLM run per call) and warns that repeat calls are intentionally not cached, which directly shapes an agent's decision to re-invoke.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build a contact sheet for a generated clip — N frames spread evenly over its runtime, tiled into ONE image — and show it. This is how a clip gets judged at all: MCP has no video content type, so without a sheet a clip is just a URL and a promise. It is also the fastest way to SEE camera drift: measured 2026-08-04, the wander in one clip was a PSNR number until frames sat side by side. The sheet is cached on the video row — a second call returns the same URL without re-rendering (pass force to redo it). Rendering downloads the clip and runs ffmpeg, so the first call takes a few seconds.
| Name | Required | Description | Default |
|---|---|---|---|
| cols | No | Grid columns (default 3) | |
| rows | No | Grid rows (default 3). cols x rows = number of frames | |
| force | No | Re-render even if a sheet already exists | |
| width | No | Total sheet width in px (default 1280) | |
| preview | No | Attach the sheet itself, downscaled to 512px, instead of only its URL. Default true — showing it is the whole point; pass false to get just the URL. | |
| video_id | Yes | Generated video id (from lab_animate/lab_job_status) — positive integer as string |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: it discloses caching on the video row with same-URL reuse, the force escape hatch, and the cost model ('downloads the clip and runs ffmpeg, so the first call takes a few seconds'). The readOnlyHint=false/idempotentHint=true pair is consistent with the described render-and-cache behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the purpose, then rationale, cache behavior, and latency in a logical order. It is slightly long due to rhetorical asides ('just a URL and a promise', the PSNR anecdote), but each sentence still carries usable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description still explains what comes back (a tiled image and/or its URL), the caching semantics, and the latency to expect. An agent has everything needed to call it and set expectations for the first vs. subsequent calls.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so cols/rows/width/preview are already fully documented in the schema. The description adds only a framing detail ('N frames spread evenly') and restates force's re-render purpose, which the schema already covers, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Build a contact sheet for a generated clip') plus the exact composition rule ('N frames spread evenly over its runtime, tiled into ONE image'). This clearly separates it from siblings like lab_render_frames or lab_letzter_frame, which produce different frame artifacts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives strong when-to-use motivation ('MCP has no video content type, so without a sheet a clip is just a URL and a promise') and a second use case (spotting camera drift). It does not name the sibling tools an agent might otherwise pick, so routing is by inference rather than explicit exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start the continuity pass over a sequence — every shot is compared against its PREDECESSOR and, with check_references, against the character and location reference boards. This is the pass that catches drift (the flat that changed between two shots, the cardigan that turned into a coat), which is the actual enemy in AI film, not the cut. Runs in the BACKGROUND: returns a job_id with HTTP 202 — poll it with lab_get_job until status is done|failed, the findings sit in the job result. Two refusals worth knowing before you spend time: an empty timeline is rejected with 400 (add shots with lab_add_clip first), and the backend answers 503 if GEMINI_API_KEY is not configured.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | Vision model for the comparison. Omit it — the backend resolves its default through the model catalogue, so it follows a model retirement on its own. A literal passed here does not, and that is how a dead model id stays wired in | |
| seq_id | Yes | Sequence id (from lab_create_sequence/lab_list_sequences) — positive integer as string | |
| check_references | No | Also check every shot against the character and location reference boards, not just against its predecessor. Backend default is true; pass false for a cheaper neighbour-only pass |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover readOnlyHint=false and destructiveHint=false, so the description carries the load and does so well: it discloses BACKGROUND execution, an HTTP 202 + job_id return, the polling contract via lab_get_job, and two failure modes (400 on empty timeline, 503 when GEMINI_API_KEY is missing). This is exactly the operational context annotations cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and drift rationale before the job/refusal details. It is dense but each sentence (background behavior, polling, refusals) earns its place; slightly long but not padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description steps in to explain the return value (job_id, findings in the job result) and the polling path, and it pre-empts the two refusals an agent would otherwise waste time on. Nothing needed 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.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema already documents each parameter in depth, so the baseline is 3. The description echoes check_references and implies model can be omitted, but adds little meaning beyond what the schema strings already provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action ('start the continuity pass over a sequence') and precisely scopes what it does: 'every shot is compared against its PREDECESSOR and, with check_references, against the character and location reference boards.' The drift-catching framing ('the flat that changed between two shots') makes its distinct purpose legible against siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear when-to-use context ('the pass that catches drift ... the actual enemy in AI film, not the cut') and prerequisites ('add shots with lab_add_clip first'), plus the check_references cheaper-pass alternative. It routes the agent to lab_get_job for polling but does not explicitly contrast against sibling review/analysis tools, so it stops short of full when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a character sheet for a human, animal or creature in the cast register. The backend derives an English prompt_prefix_en from the fields you give — that prefix is what later describes this character in every image, so the richer the description, the more stable the identity. This is step 1 of 2: a fresh sheet has NO reference image and is therefore not yet usable as character_refs. Run lab_generate_character_reference on the returned id to finish it. Free — it writes a row, it burns no credits.
| Name | Required | Description | Default |
|---|---|---|---|
| age | No | Age in years, as a number | |
| eyes | No | Eye colour and expression | |
| hair | No | Hair colour, length, cut | |
| name | Yes | Character name, e.g. 'Maren' — the only required field | |
| skin | No | Skin tone and texture | |
| build | No | Body build and posture | |
| gender | No | e.g. 'female', 'male', 'non-binary' | |
| gattung | No | Character kind: human, animal or creature. Omitted or empty means mensch. For tier/kreatur, begin the description with the species and its distinctive features. | |
| clothing | No | Default costume the character is seen in | |
| demeanor | No | How the character moves and behaves, in prose | |
| project_id | No | Bind the sheet to this project (from lab_list_projects) — positive integer as string. PASS THIS whenever the character belongs to a project. Without it the sheet stays an orphan: lab_cast_gaps will not count it as created, and image generation will not find it as a char_ref. | |
| project_name | No | Free-text project label shown in listings (does NOT bind the sheet — that is project_id) | |
| facial_features | No | Face shape, nose, mouth, jaw — what makes this face recognisable | |
| distinctive_features | No | Scars, tattoos, glasses, anything that must appear in every image |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations, which only declare readOnlyHint=false and destructiveHint=false. It discloses a real side effect (the backend derives an English prompt_prefix_en that drives later image identity), the cost profile ('Free ... burns no credits'), and an important state limitation (a fresh sheet has no reference image and is not yet usable as character_refs).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each carrying distinct information (what it creates, the derived prefix, the 2-step workflow, the cost/credit facts), front-loaded with the core purpose. No restatement of the title or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 14-parameter creation tool with no output schema and only a readOnly/destructive annotation pair, the description covers purpose, cost, side effects, workflow ordering, project binding, and even a lightweight statement of the return value (the id). Nothing an agent needs to call this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all 14 fields, setting a baseline of 3. The description still adds cross-parameter guidance the schema lacks: 'the richer the description, the more stable the identity' tells the agent the descriptive fields are load-bearing rather than cosmetic.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Create a character sheet ... in the cast register') and explicitly positions itself as 'step 1 of 2', which separates it cleanly from lab_generate_character_reference, lab_create_location and lab_get_character in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit sequencing ('Run lab_generate_character_reference on the returned id to finish it') and a conditional instruction with a named consequence ('PASS THIS whenever the character belongs to a project. Without it the sheet stays an orphan: lab_cast_gaps will not count it as created'). An agent knows both when to call it and what to call next.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a location board. The backend derives an English prompt_prefix_en from the fields you give — that prefix is what later anchors every image and clip shot there, so the richer the description, the more consistent the place. Pass project_id to bind the board to a project (recommended: unbound boards are invisible to lab_list_project_locations).
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Board name, e.g. 'Wohnung Hanna — Balkon' | |
| props | No | Objects that must be present | |
| colors | No | Dominant palette | |
| atmosphere | No | Mood, weather, sound of the place | |
| project_id | No | Bind the board to this project (from lab_list_projects) — positive integer as string | |
| description | No | What the place is, in prose | |
| time_of_day | No | e.g. 'morning', 'blue hour', 'night' | |
| architecture | No | Building style, era, materials | |
| project_name | No | Free-text project label shown in listings | |
| location_type | No | e.g. 'interior', 'exterior', 'apartment', 'street' | |
| lighting_notes | No | Light direction, quality, sources |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover the safety profile (readOnlyHint=false, destructiveHint=false), so credit goes to the description for disclosing behavior beyond them: the backend derives an English prompt_prefix_en, and richer field input yields more consistent downstream images/clips. It stops short of stating duplicate-name behavior, whether the call is idempotent, or what is returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, zero waste, front-loaded with the action and then the two pieces of non-obvious context (derived prefix, project binding). Every sentence carries information not present in the structured fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter create tool with no output schema, the description explains input semantics and downstream effects well, but says nothing about what the call returns (e.g. the new location id that later tools need), which is the remaining gap for a caller to chain correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning on top: project_id is recommended and its omission has the concrete consequence of invisibility to lab_list_project_locations, and the free-text fields are framed as driving prompt_prefix_en quality.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource ('Create a location board'), and it distinguishes itself from siblings by naming lab_list_project_locations and its visibility rule. An agent can tell it apart from lab_get_location, lab_delete_location, and lab_create_project 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives concrete when-to guidance: pass project_id to bind the board, with an explicit exclusion ('unbound boards are invisible to lab_list_project_locations'). It does not route against other creation tools (e.g. lab_create_character / lab_create_project), so it stops short of full alternative handling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new FilmLab project. Returns the new project id and its datenmodus. Optionally set a title and the data mode: 'eu' keeps the project on models whose data path is proven inside the EU (lab_list_models eu: true lists them; other models are refused with alternatives), 'frei' allows every model. Omit to get the account default.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Project title (optional) | |
| datenmodus | No | Data mode of the project: 'eu' (only EU-allowed models) or 'frei' (all models). Omit for the default |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose the safety profile (readOnlyHint=false, destructiveHint=false), and the description adds real behavioral context: it describes the effect of the 'eu' mode (models refused with alternatives) and points to lab_list_models eu: true as the way to see permitted models. It stops short of covering anything like auth needs or limits, but it adds substantive context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose and return value, then the optional parameters, with no filler sentences. The 'eu' clause is dense but every clause carries information; slightly tighter phrasing would reach a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description compensates by stating the returned id and datenmodus. Both optional parameters and the default behavior are documented, and annotations cover the mutation safety profile, so an agent has everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description genuinely enriches the enum semantics — 'eu' is explained as restricting to models whose data path is proven inside the EU, and 'frei' as allowing every model — plus the omit-for-default rule. That is more than the terse schema strings provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Create a new FilmLab project') and immediately names what it returns (project id and datenmodus). This distinguishes it cleanly from sibling creation tools such as lab_create_sequence, lab_create_character, or lab_get_project without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is largely implied by the resource name — create a project — and the description explains that title and datenmodus are optional with a sensible default when omitted. However, it never states when to use this versus alternatives or any prerequisite (e.g., must a project exist before adding sequences), leaving routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a named prop (Requisite) in this project. Free, no model call: its prompt prefix is built deterministically from the fields. Returns its @prop_ tag for shot prompts. To generate views use lab_prop_ansichten separately (costs credits).
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| epoche | No | ||
| farben | No | ||
| groesse | No | ||
| zustand | No | ||
| material | No | ||
| project_id | Yes | ||
| beschreibung | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare it is a non-readonly, non-destructive write. The description adds substantial context: it is free, performs no model call, builds its prompt prefix deterministically from fields, and returns a @prop_ tag. This goes well beyond what the annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the core action, followed by cost/behavioral details and an alternative. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, cost model, return value, and a key alternative, which is helpful. However, for an 8-parameter tool with zero schema descriptions and no output schema, the complete lack of parameter meaning leaves a significant gap for an agent trying to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for 8 parameters, so the description carries the full burden. It only vaguely refers to 'fields' and implies 'name' through 'named prop', but gives no meaning for epoche, farben, groesse, zustand, material, or beschreibung. This leaves most parameters undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Create') and resource ('named prop (Requisite)') within the project. It also explicitly distinguishes itself from lab_prop_ansichten by naming that sibling and its separate cost, so an agent can tell the two apart without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly directs the agent to use lab_prop_ansichten for generating views, noting that it costs credits. This provides a clear alternative for a related task, though it does not discuss other possible alternatives like lab_list_props or lab_create_character.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a sequence (Stage 9 timeline) inside a project — START HERE to turn generated shots into something the continuity pass can read. The new sequence is EMPTY: add shots with lab_add_clip before anything else works. lab_continuity_check rejects an empty timeline with 400. Returns the sequence record including its id.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Sequence title. Defaults to 'Main Sequence' on the backend | |
| project_id | Yes | Project id (from lab_list_projects) — positive integer as string |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false / destructiveHint=false, and the description correctly aligns by framing this as a creation. Beyond that it adds real behavioral context: the created sequence is EMPTY, it is a prerequisite for lab_add_clip, and lab_continuity_check will 400 on an empty timeline. It omits auth/permission needs and any failure mode for a bad project_id, so it stops short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, action front-loaded, and every sentence carries distinct weight (what it creates, the empty-state prerequisite, the downstream 400 and return value). No filler or restatement of the name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description appropriately closes the loop by stating it returns the sequence record including its id. Combined with the empty-state and ordering warnings, an agent has everything needed to call it and use the result correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema already documents both parameters, including the 'Main Sequence' default for title and the project_id source. The description adds no format or constraint detail for either parameter, so the schema baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Create) and resource (sequence / Stage 9 timeline) with explicit scope ('inside a project'). The parenthetical naming of the timeline concept and the 'START HERE' framing let an agent distinguish it from lab_get_sequence, lab_list_sequences, and lab_add_clip without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use ('START HERE to turn generated shots into something the continuity pass can read') and a concrete ordering constraint ('add shots with lab_add_clip before anything else works'). It also names the downstream sibling (lab_continuity_check) and the failure condition (400 on an empty timeline), so alternatives and prerequisites are unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a style kit in this project: rules (English text), palette (#RRGGBB) and up to three reference images taken from this project's own images (image ids). Free, no model call. Set als_standard to make it the project default, which then runs in every image and clip of the project (switch it off per call with ohne_stil_kit).
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| regeln | No | Style rules in English, e.g. 'cold moonlight, deep blue shadows, film grain' | |
| palette | No | Up to 8 colours as #RRGGBB | |
| bild_ids | No | Up to 3 image ids of THIS project | |
| project_id | Yes | ||
| als_standard | No | Make this kit the project default |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say non-read-only and non-destructive; the description adds real behavioral context the schema lacks: no model call/cost, and that setting als_standard makes the kit apply to every image and clip in the project. The dangling reference to 'ohne_stil_kit' (not a parameter in this schema) is slightly confusing but conveys the per-call override story.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the content model and then the important side-effect. The parenthetical about ohne_stil_kit, a parameter that does not exist in this schema, is the one piece of noise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and six parameters, yet the description covers the important semantics, cost profile and the global consequence of the default flag — enough to call it correctly. It is silent on what is returned (e.g. a kit id) and on name-collision behavior, which would have closed the gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% and already documents regeln, palette, bild_ids and als_standard, so several description phrases are redundant. Where it does add value is the als_standard explanation — the schema only says 'Make this kit the project default' while the description explains the project-wide downstream effect.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb and resource ('Create a style kit in this project') and enumerates the content dimensions, so an agent immediately knows what is produced. It does not explicitly contrast itself with lab_list_stil_kits or lab_stil_kit_standard, so sibling differentiation is only implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied ('Free, no model call' suggests preferring this over generation) and the als_standard flag is explained, but there is no explicit when-not-to-use statement or named alternative. The agent must infer whether to call lab_stil_kit_standard instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
DELETE a location board permanently. There is no undo and no soft-archive — the row is removed. Images and clips that were generated with this location_id keep their already-rendered prompt, but the board they point at is gone: nothing can be re-anchored to it, and lab_get_location will 404. Confirm with the user before calling this. Use lab_restyle_location if you only want the place to look different.
| Name | Required | Description | Default |
|---|---|---|---|
| loc_id | Yes | Location board id to delete permanently (from lab_list_locations) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, so the safety profile is partly given, but the description adds real value beyond that: no soft-archive, the row is removed, rendered prompts survive while the board becomes unanchorable, and lab_get_location will 404. These cascade consequences are exactly what an agent needs and could not get from annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, all load-bearing: the verb, the irreversibility, the cascade effect, and the routing/precondition. The destructive nature and no-undo warning are front-loaded where they matter most.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-param destructive tool with no output schema, the description covers purpose, irreversibility, downstream effects, routing, and a user-confirmation precondition. Nothing material is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one required parameter and schema coverage is 100%, so the schema fully documents loc_id and its provenance (lab_list_locations). The description actually references `location_id`, a slight naming mismatch with the schema's `loc_id`, so it adds no useful syntax guidance over the structured data. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('DELETE a location board permanently') and distinguishes itself from the sibling lab_restyle_location, which also touches locations. An agent can pick this tool apart from its neighbors on the strength of the first sentence alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names the alternative ('Use lab_restyle_location if you only want the place to look different') and adds a procedural precondition ('Confirm with the user before calling this'). Both when-to-use and when-not are covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or read a depth map for a project video in FilmLab: use it for fog, depth of field, relighting or occlusion. Near is white, like Resolve's Depth Map. Free on our own CPU, no credits; processing takes minutes. modell: v2 (default) is Depth Anything V2, sharpest edges. vda is Video Depth Anything: steadier over time (no brightness pumping across the shot, slightly less flicker), softer edges, about 2x slower than v2 (on our server ~0.5 s per frame for v2, ~1.1 s for vda), only for 16:9 landscape or 9:16 portrait videos (16:10 and 1.85:1 are fine, 4:3 and 2.39:1 are not). Each modell keeps its own map; always pass the same modell when reading again (engine in the answer says which one). Reuses the existing map or running job by default; neu: true starts a new job. Returns status and job_id; when done, tiefe_url is FFV1 gray16 and vorschau_url is a playable H.264 grayscale preview, both signed for download without a browser session. wait_s waits at most 15 seconds (default 0). If still running, call this tool again with the same project_id, video_id and modell, neu: false. Once done, use resolve_ergebnis_an_timeline with vorschau_url to put the preview as a matte above the original clip in Resolve.
| Name | Required | Description | Default |
|---|---|---|---|
| neu | No | Start a new depth job instead of reusing the existing map or running job (default false) | |
| modell | No | Depth engine: v2 (default, sharpest) or vda (steady over time, 16:9 or 9:16 only) | |
| wait_s | No | Wait up to this many seconds for completion (default 0, maximum 15) | |
| video_id | Yes | Completed video id belonging to this project | |
| nur_lesen | No | Only read: never create a job. Without an existing job the answer is status 'keine' (default false) | |
| project_id | Yes | Project id (from lab_list_projects) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, destructiveHint=false), it discloses cost ('free on our own CPU, no credits'), latency ('processing takes minutes', per-frame timings), the reuse-vs-new-job default via neu, and the format/signing of the returned URLs. This is unusually rich behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded and almost every sentence carries distinct information (cost, timing, engine tradeoffs, read-back instructions). It is dense and slightly long, with mild repetition around passing the same modell when reading again, which keeps it from a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, but the description covers the return values in detail (status, job_id, tiefe_url as FFV1 gray16, vorschau_url as signed H.264 grayscale preview). Combined with the usage and behavioral detail, an agent has everything needed to call and follow up correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 goes further by expanding modell (engine identity, edge quality, temporal stability, 2x slowdown, aspect-ratio limits) and explaining neu and wait_s semantics. It adds real meaning over the schema rather than repeating it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource ('Create or read a depth map for a project video in FilmLab') and immediately names the concrete uses (fog, depth of field, relighting, occlusion). It also names the downstream sibling resolve_ergebnis_an_timeline, so an agent can place it in a workflow without opening other schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use cases, selection guidance between the v2 and vda engines (with aspect-ratio constraints and speed tradeoffs), the default reuse behavior, and the exact re-call pattern ('call this tool again with the same project_id, video_id and modell, neu: false') when a job is still running.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Is everything wired? Backend reachability and latency, identity, credit check, catalog age, last error of this account, host widget support. Traffic light plus one sentence per point. Read-only, free.
| Name | Required | Description | Default |
|---|---|---|---|
| problem_report | No | Return the same findings as one block of text to paste into a bug report. This covers the MCP side only — server version, backend health, last failed job of this account. The Resolve bridge log lives on the user's machine and cannot be read from here: have them press ‚Problem-Report kopieren‘ in the bridge panel for bridge version, Resolve build, Python and the last 200 log lines. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description reinforces this with 'Read-only, free' while adding cost information (free) that annotations do not carry. It also discloses the output shape ('traffic light plus one sentence per point'), which is meaningful behavioral context for a tool with no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Telegraphic but efficient: the scope question is front-loaded, the check list is dense, and the output format plus safety/cost note close it out. No filler sentences, though the fragment list is slightly terse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only diagnostic tool with no output schema, the description covers what is checked, what the response looks like, and that it is read-only and free. Only the routing relative to sibling identity/state tools is left implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the single problem_report parameter is documented in rich detail within the schema itself. The description adds nothing about the parameter, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description enumerates the exact checks performed (backend reachability and latency, identity, credit, catalog age, last error, widget support), which is far more specific than the title 'Diagnose'. It does not explicitly distinguish itself from sibling identity tools like lab_whoami or lab_identitaet_pruefen, but the breadth of the check list makes the scope clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The opening question 'Is everything wired?' implies a troubleshooting/setup-verification use case, but no when-to-use condition or alternative tool is named. With a crowded sibling set containing other identity and state tools, an agent gets only implied routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build a dossier of a project's takes: one ZIP with an offline index.html (no external resources) plus the media files, named Project_SceneNN_YYYYMMDD-Tnn.ext. modus 'kunde' is for a client and NEVER shows seed or costs, whatever the switches say; 'intern' shows everything that helps to rebuild a take. Both modes carry the AI disclosure (EU AI Act Art. 50) on the page and in the image files. Free (no credits). Runs as a job — poll lab_get_dossier.
| Name | Required | Description | Default |
|---|---|---|---|
| modus | No | kunde (default) or intern | |
| auswahl | No | gewaehlt (default): the selected take per scene, plus every take without a scene (e.g. a series) that is not rejected; alle: every take that is not rejected. Stars/favourites do not count as a selection. | |
| bild_ids | No | Exactly these image ids (overrides auswahl) | |
| schalter | No | Switches: prompt, referenzen, aufloesung_dauer, datum, modell, seed, kosten, audio, mini_proxies (480p video proxies). Unknown keys are ignored. | |
| video_ids | No | Exactly these video ids (overrides auswahl) | |
| project_id | Yes | Project id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial behavior beyond the annotations: the operation is a non-destructive job whose cost is zero, 'kunde' never exposes seed or costs regardless of the schalter flags, both modes embed an EU AI Act Art. 50 disclosure in page and image files, and completion requires polling lab_get_dossier. This is exactly the context the readOnlyHint/destructiveHint pair cannot convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the artifact and output format, then layers mode rules, cost, and async behavior with no filler sentences. The filename specification and semicolon-chained clauses make it denser than ideal, but every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of describing the return artifact and does so (ZIP, offline index.html, media naming). It also covers async job handling and the disclosure requirement, leaving no material gap for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 goes further by explaining modus semantics (what 'kunde' hides) and clarifying that switches cannot override the client-mode filtering. It adds nothing for auswahl, bild_ids, video_ids or schalter keys, which remain schema-only.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and artifact: build a dossier ZIP containing an offline index.html plus media, with an explicit naming scheme. It is clearly distinguishable from generic export siblings like lab_get_export or lab_schnitt_export.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear operational context: 'kunde' vs 'intern' select audience, the call is free (no credits), and it runs asynchronously so the agent must poll lab_get_dossier. It does not compare itself against other export tools, so it stops short of full when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dub a sequence into another language: either a ready audio track (en_audio_url — e.g. the one lab_dub_tts just produced) OR a cloned voice reading a line of text (voice_id + dub_text), then a controlled visual lipsync runs over the sequence's own footage (ROI-crop + composite for a long static talking-head shot, or the full-frame veed_v2 path for multi-shot sequences and shots where the mouth is partly hidden). ASYNCHRONOUS: returns a job_id immediately: poll lab_job_status until it completes. Needs a cloned voice first — lab_voice_clone makes one, lab_list_voices shows what a project already has.
| Name | Required | Description | Default |
|---|---|---|---|
| seq_id | Yes | Sequence id (from lab_create_sequence/lab_list_sequences) — positive integer as string | |
| backend | No | Lipsync engine. Omit to use the backend default (replicate — ROI-crop, best for one long static talking-head shot). veed_v2 renders the full frame instead and is the pick for multi-shot sequences or a partly hidden mouth. 'inhouse' shares replicate's ROI-crop path. | |
| dub_text | No | The line(s) this cloned voice should read, in the target `language`. Required together with voice_id. | |
| get_cost | No | `true` reports the price and your balance WITHOUT starting a dub and without spending quota. The number is computed by the same function that later charges you, from THIS sequence: a sound rate per video clip, plus the chosen lipsync engine's own rate over the sequence's running time, plus a surcharge for the cloned-voice reading. `preisbasis` in the answer breaks it into those parts, so you can see which switch moves which share — turning the lipsync pass off removes its whole item. Not drawn from the lab_list_models catalog (that covers image and video models only; the lipsync engine is chosen with `backend` here, and dub has no catalog entry). | |
| language | Yes | Target language for the dub, e.g. 'de', 'fr', 'es' — drives the cloned voice's TTS. Required: there is no silent default here. | |
| voice_id | No | A cloned voice's id (lab_cloned_voices.id, from lab_voice_clone or lab_list_voices) — positive integer as string. Required together with dub_text, and mutually exclusive with en_audio_url. | |
| einwilligung | No | Consent of the person whose mouth this dub re-syncs. Only valid together with eigene_person:true and einwilligung_notiz when there is no likeness_ref — a dub always alters a real person's mouth in existing footage, so a likeness_ref or the own-person form is mandatory, checked before anything is spent. This is a caller attestation, not a registry check like likeness_ref — logged, not verified against likeness.thefilmradar.com, and it covers only YOUR OWN person. Do not set it to be rid of the error — set it because the consent exists. | |
| en_audio_url | No | URL of a READY dub track to lay under the sequence — typically the audio_url lab_dub_tts just returned. Mutually exclusive with voice_id+dub_text: a dub has exactly one audio source, and picking one silently would throw away the other after it was paid for. | |
| likeness_ref | No | A Likeness Register consent id (likeness.thefilmradar.com) for the person whose mouth this dub re-syncs. Checked live against the register before anything is spent; a revoked or unknown id refuses the call. REQUIRED for every person other than yourself — a plain confirmation no longer stands in for it (DSFA E3, 2026-11-06). Mutually exclusive with eigene_person+einwilligung+einwilligung_notiz — one form of consent is required, not both. | |
| eigene_person | No | Set true ONLY if the person whose mouth this dub re-syncs is you, the user ("the person shown and speaking is me"). It is the only way to dub without a likeness_ref and must come with einwilligung:true and einwilligung_notiz. For anyone else, a valid likeness_ref is mandatory: without one the call is refused with dub_fremde_person_braucht_kennung (403) before anything is spent. A declaration, not a proof — logged, not verified. Do not set it for somebody else. Unrelated to nur_eigene_daten, which concerns the third-country data flow. | |
| enable_lipsync | No | Whether to run the visual lipsync pass at all. Omit to use the backend default (on). Off only swaps the audio track and skips the mouth-sync render entirely. | |
| nur_eigene_daten | No | Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only. | |
| einwilligung_notiz | No | Free text: who consented, when, and for what — required together with einwilligung. Goes on record with the generated clip. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds the crucial behavioral facts the agent cannot get elsewhere: the call is asynchronous and returns a job_id that must be polled, a consent gate is evaluated before any spend, and get_cost reports price without consuming quota. It also discloses that the operation alters a real person's mouth in existing footage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the verb and resource, then the two modes, then the async/polling contract, then prerequisites — a sensible order. It is dense but nearly every clause carries operational information; the only waste is minor duplication of the backend trade-off that the schema already explains.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 13-parameter, asynchronous, gated mutation with no output schema, the description covers the call lifecycle, cost preview, and mode selection well. It does not surface the consent/likeness refusal paths (likeness_ref, eigene_person, nur_eigene_daten) or the drittland_dritte_gesperrt gate, leaving those discoverable only inside the schema — a notable omission for a tool this gated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description still earns an extra point by bundling the mode-selection logic in one place (en_audio_url XOR voice_id+dub_text, backend choice tied to shot composition) rather than leaving the agent to reconcile thirteen separate field descriptions. Much of it does restate what the schema already says about backend and ROI-crop.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Dub a sequence into another language") and immediately enumerates the two audio-source modes plus the visual lipsync pass over the sequence's own footage. It distinguishes itself from lab_dub_tts (which produces the ready track it consumes) and from lab_voice_clone/lab_list_voices, so an agent can place it in the workflow without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete routing: use the replicate/inhouse ROI-crop path for one long static talking-head shot, veed_v2 for multi-shot sequences or a partly hidden mouth. It also states the prerequisite chain (a cloned voice exists first, via lab_voice_clone or lab_list_voices) and the follow-up procedure (poll lab_job_status).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate the EN-dub audio track for a sequence via ElevenLabs TTS — SYNCHRONOUS, returns a ready audio_url immediately, no job_id and nothing to poll. Optionally pads the track with silence up to the sequence's own length so a shorter reading doesn't shorten the final cut. Feed the resulting audio_url into lab_dub's en_audio_url to lipsync the sequence to this track.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | The line(s) to speak. Kept short — very long text is rejected by the backend before anything is spent. | |
| seq_id | Yes | Sequence id (from lab_create_sequence/lab_list_sequences) — positive integer as string | |
| get_cost | No | `true` reports the price and your balance WITHOUT generating anything and without spending quota. This one is billed flat, one sound rate per run — the length of your text does not change it. Not drawn from the lab_list_models catalog (that covers image and video models only): the TTS voice is picked with `voice_id`, and the price does not follow the voice. | |
| voice_id | No | An ElevenLabs voice id, from lab_dub_voices. Omit to use the backend's configured default voice — NOT a lab_cloned_voices id. | |
| pad_to_video | No | Pad the generated track with silence up to the sequence's own duration if the reading comes out shorter. Omit to use the backend default (on). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only mark it non-read-only and non-destructive. The description adds the critical trait that it is SYNCHRONOUS, returns a ready audio_url with no job_id and nothing to poll, and explains the padding behavior — genuinely useful context the structured fields do not carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tightly written sentences with the synchronous/no-poll fact front-loaded, followed by the optional padding and the downstream wiring. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema, the description discloses the return shape (immediate audio_url), the cost model context, and the downstream handoff, so an agent has everything needed to call and chain it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five parameters are already documented in the schema. The description restates the padding concept but adds no syntax or format detail beyond what the schema provides; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Generate) and resource (the EN-dub audio track for a sequence via ElevenLabs TTS), and its synchronous nature immediately distinguishes it from polling-based generation siblings. An agent can identify it apart from lab_dub and lab_voice_tts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly positions the tool within the dub pipeline by naming the downstream consumer (lab_dub's en_audio_url for lipsync). However, it does not explicitly contrast with the sibling lab_voice_tts, so an agent still has to infer which TTS entry point to pick.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the ElevenLabs TTS voices available for lab_dub_tts's voice_id — this is the EN-dub-track text-to-speech voice list, NOT a project's cloned voices (those are lab_list_voices). Reads only — no state changes, no credits. If ELEVENLABS_API_KEY isn't configured on the backend the list comes back empty and configured is false.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=true; the description goes further by confirming no credits are consumed and, more importantly, disclosing the failure mode — an unconfigured ELEVENLABS_API_KEY yields an empty list plus a `configured: false` signal. That tells the agent how to distinguish "no voices exist" from "backend not configured," which the annotations cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with what the tool returns and the sibling it is not, followed by the read-only/cost note and the API-key caveat. Every clause carries distinct information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema list tool, the description covers purpose, sibling routing, safety/cost, and the one return-value nuance that matters (`configured`). An agent has everything needed to call it and to interpret an empty response correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing to document and the baseline is 4. The mention of `voice_id` refers to a consuming sibling's parameter rather than this tool's input, which is helpful context but not parameter semantics for this schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("List the ElevenLabs TTS voices") and immediately scopes it to the consumer (lab_dub_tts's `voice_id`). It explicitly excludes the look-alike sibling by name ("NOT a project's cloned voices (those are lab_list_voices)"), so an agent can disambiguate from lab_list_voices without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Names both the condition for using it (populating lab_dub_tts's `voice_id`) and the alternative for the other case (lab_list_voices for cloned voices). It also gives a prerequisite-style caveat about ELEVENLABS_API_KEY, which is exactly the routing/eligibility information an agent needs before calling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Append context to a board's prompt_prefix_en (plain string concatenation server-side — no AI call, no quota). Idempotent: context already present in the prefix is not duplicated. This does NOT rewrite or regenerate the prefix — for a board whose prefix is empty, too thin or a raw field dump, use lab_restyle_location (it rewrites prompt_prefix_en with an AI call, costs credits — exact price via get_cost: true) instead of recreating the board.
| Name | Required | Description | Default |
|---|---|---|---|
| loc_id | Yes | Location board id (from lab_list_locations) | |
| context | Yes | What to add or sharpen, e.g. 'late 1970s West Berlin, nicotine-stained walls' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say readOnlyHint=false and destructiveHint=false, so the description carries the real behavioral load and does so: plain server-side string concatenation, no AI call, no quota consumed, idempotent (no duplicate context). It also states what it will NOT do (rewrite/regenerate the prefix), which is the key risk an agent could otherwise get wrong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, all load-bearing, with the core behavior front-loaded before the alternative-tool routing. The nested parentheticals (cost note, get_cost reference) make it dense to parse, but nothing is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter mutation tool with no output schema, the description covers what it does, what it costs, its idempotency guarantee, what it does not do, and which sibling to use instead. An agent has everything needed to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters already carry descriptions and constraints (maxLength 500, minLength 3), so the baseline is 3. The description adds meaning beyond the schema by explaining the idempotency semantics of the `context` argument — already-present content is not duplicated — which affects how an agent should call it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and target ('Append context to a board's prompt_prefix_en') and explicitly contrasts itself with lab_restyle_location, which is the nearest sibling. An agent can distinguish the two without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives both the when-not and the alternative: for prefixes that are 'empty, too thin or a raw field dump' the agent is routed to lab_restyle_location, and it explicitly warns against 'recreating the board'. That is an explicit decision rule, not an implied one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the available export delivery profiles (web, social_vertical, social_youtube, streaming_hdr, cinema, master, alpha_prores4444, alpha_png_sequence) and quality presets (draft, standard, high). Call this before lab_start_export to pick a valid profile/quality. The two alpha profiles keep transparency (ProRes 4444, or one RGBA PNG per frame delivered as a zip) and are REFUSED unless the sequence actually carries an alpha source — a cut-out layer element, or a Switch X transform whose alpha track was kept.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say readOnlyHint=true; the description adds real behavioral context not in structured data — the two alpha profiles preserve transparency and are REFUSED unless the sequence carries an alpha source (cut-out layer element or kept Switch X alpha track). That refusal rule is exactly the kind of precondition an agent needs. It does not describe the response shape, but that is a minor gap for a read-only listing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose and the routing instruction, then the alpha caveat. The parenthetical detail about ProRes 4444 / RGBA PNG zip is slightly heavy but each clause carries actionable meaning, so waste is minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only listing with no output schema, the definition supplies everything needed: the full valid value sets, the sequencing relative to lab_start_export, and the alpha-source precondition. No material omission remains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, which sets the baseline at 4. The description still adds meaning by enumerating the two value families (7 profiles, 3 quality presets) the caller will choose from, information the empty schema cannot supply.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List the available export delivery profiles ... and quality presets') and enumerates the exact valid values. It is clearly distinguishable from siblings such as lab_list_exports/lab_get_export (existing exports) and lab_start_export (performing the export).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs 'Call this before lab_start_export to pick a valid profile/quality', naming the sibling and the condition that selects it. It lacks any when-not guidance (e.g., that it is unnecessary once a profile is already known), so it stops short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Face fix, step 1 of 2 — FREE. Finds one person in a clip FilmLab generated and plans which stretches of their face a redraw would improve (small or drifting faces). Give the generated clip (video_id) and a reference photo of that person (foto_url — an image FilmLab generated, e.g. a character sheet view from lab_get_character_sheet). Uploaded clips or photos are refused with face_fix_nur_generiert before anything happens: for now only material created in FilmLab is accepted. ASYNCHRONOUS: returns a job_id; poll it with lab_get_job until done. Then call lab_face_fix_freigeben with get_cost to see the price per stretch and let the human confirm. Nothing is charged by this tool.
| Name | Required | Description | Default |
|---|---|---|---|
| foto_url | Yes | Reference photo of the person, an image generated in FilmLab (address from lab_get_character_sheet or lab_list_assets). It must show the face clearly. | |
| video_id | Yes | Id of the finished generated video row to improve (from lab_job_status or lab_review_queue) — positive integer as string. | |
| project_id | Yes | Project id (from lab_list_projects) — positive integer as string. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say readOnlyHint=false and destructiveHint=false. The description adds substantial behavior: the tool is free, asynchronous, returns a job_id, refuses non-FilmLab material before doing anything, charges nothing, and requires human confirmation before pricing. These are meaningful operational details beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with step number and cost status, then purpose, inputs, refusal behavior, async flow, and next step. Despite its length, every sentence carries actionable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an asynchronous two-step planning tool with no output schema, the description covers the full workflow: inputs, validation failure, job polling, next tool, pricing step, and cost safety. Nothing essential is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameter definitions are already strong. The description still adds useful provenance and constraints, notably that foto_url should be a FilmLab-generated reference such as a character sheet view and that uploaded clips or photos are refused.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: it finds a person in a generated clip and plans which face stretches to redraw. It also distinguishes itself as step 1 of 2 and names the follow-up sibling lab_face_fix_freigeben, so an agent can separate it from related tools immediately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use it, what inputs to provide, what is refused with face_fix_nur_generiert, and what to do next (poll lab_get_job, then call lab_face_fix_freigeben with get_cost). Alternatives and sequence are fully covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Face fix, step 2 of 2 — PAID: redraw the faces of the stretches that lab_face_fix found, with Kling, and put them back into the clip. Call with get_cost first: the answer lists every stretch with its seconds and price. Charged per stretch; a stretch whose redraw does not pass the check (identity not better, too much flicker) is refunded on its own and stays as the original. A NEW video row comes back; the original stays. The backend refuses with a named reason (face_fix_analyse_nicht_fertig, face_fix_nichts_zu_tun, face_fix_bereits_freigegeben, face_fix_analyse_veraltet, face_fix_analyse_abgelaufen) before anything is charged. An analysis can be approved once and only within 24 hours (the face crops are deleted after that): for another try, run lab_face_fix again (free). Costs credits when called without get_cost.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | Job id of the finished lab_face_fix analysis — positive integer as string. | |
| get_cost | No | Preflight: return the stretches and the price per stretch WITHOUT starting anything and without spending. Do this first and let the human confirm. | |
| project_id | Yes | Project id (from lab_list_projects) — positive integer as string. | |
| nur_eigene_daten | No | Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial behavior beyond the annotations: charged per stretch, automatic refund for failed redraw checks, a new video row while the original stays, one approval only within 24 hours, named refusal reasons before charging, and credit consumption when get_cost is omitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the critical facts: step 2 of 2 and PAID. It is dense and mostly earns its length, but the long parenthetical error-code list and some repetition around the 24-hour window keep it from being maximally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description still explains the preflight return (stretches and price), the final result (a new video row, original preserved), refunds, refusal reasons, and the approval window. It is complete for a complex, paid, gated mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all four parameters already have detailed descriptions. The description adds useful meaning for get_cost by stating it must be called first and that omitting it costs credits, though it adds little new information for project_id and nur_eigene_daten beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States the exact step (step 2 of 2) and the specific action: redraw the faces of stretches found by lab_face_fix and put them back into the clip. It clearly distinguishes this paid approval/redraw tool from the free lab_face_fix analysis step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit sequencing: call with get_cost first and let the human confirm. It also explains the fallback when an analysis is approved or expired: run lab_face_fix again, and use a non-gated model if the gated-material refusal occurs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when the person asks about earlier states of a cut, wants to go back to a previous version, compare versions, name a version, or create a second cut (e.g. a short version next to the long one). The history and the versions of ONE cut (sequence). Every timeline write (lab_timeline_apply, the editor, the Resolve bridge) first saves the state it replaces; this tool reads those saved states and works with them. Costs nothing. aktion 'liste' (default): the saved states, newest first, with marke (a name a person gave a state), plus where this sequence was branched from (ursprung, with what changed since the branch point) and which versions were branched from it (abgezweigt). 'markieren': give a state a name (marke); a named state is never cleaned up — states without a name are capped per sequence. Empty marke removes the name. 'vergleichen': what changed since a state — against the current cut, or against another state (gegen), clip by clip. 'zurueckholen': write a state back as the current cut; the cut it replaces is saved first, so this is undoable. 'abzweigen': make a NEW sequence (a version — e.g. a broadcast cut next to the festival cut) from a state, or from the current cut without checkpoint_id. The new sequence keeps the clip ids and the shot layer, knows its origin, and the branch point gets a name so it stays. There is no merging back: a version is its own cut from then on. Edit it with lab_timeline_apply on the returned sequence id.
| Name | Required | Description | Default |
|---|---|---|---|
| gegen | No | vergleichen: a second state instead of the current cut | |
| marke | No | markieren: the name. Empty removes it | |
| titel | No | abzweigen: the name of the new version | |
| aktion | No | What to do. Default 'liste' | |
| seq_id | Yes | Sequence id (from lab_list_sequences) — positive integer as string | |
| checkpoint_id | No | The state (id from 'liste'). Needed for markieren, vergleichen, zurueckholen; optional for abzweigen (without: the current cut) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true and idempotentHint=false; the description goes beyond them by explaining that 'zurueckholen' saves the cut it replaces (so it is undoable), that named states are never cleaned up while unnamed ones are capped, and that branching creates a standalone sequence with no merge-back. It does not, however, explain return formats or failure/permission conditions, so it is strong but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The triggering condition is front-loaded, but the rest is a dense run-on paragraph that interleaves purpose, five action behaviors, and cross-tool notes into one block. Most sentences carry information, yet the wall-of-text format and mixed German/English make it harder to scan than it needs to be for a multi-action tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description must describe returns, and it does: 'liste' returns saved states newest-first with marke, ursprung and abgezweigt, and 'vergleichen' returns clip-by-clip differences. Combined with per-action guidance and mutation semantics, it is complete for a 6-parameter, 5-mode tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the prose adds meaning beyond the schema: it maps each aktion to the parameters it needs (checkpoint_id required for markieren/vergleichen/zurueckholen, optional for abzweigen), explains that empty marke removes a name, and clarifies the gegen target. This goes past the schema's own field notes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific resource (the saved states / versions of ONE cut) and covers every action it performs, while explicitly distinguishing itself from lab_timeline_apply and the editor/Resolve bridge that generate the states it reads. An agent can tell it apart from timeline-editing siblings 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It opens with an explicit 'Use when' clause listing the triggering intents (recall earlier states, revert, compare, name, branch a second cut), and names the alternative editing path (lab_timeline_apply). When-to-use and the routing to the sibling are both stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tell the FilmLab team about a bug or a missing feature — it reaches the people who can fix it, the chat does not. Use art 'fehler' when a tool returned something wrong, failed without a clear reason, or contradicted its own description; 'wunsch' when a step you needed does not exist. Write what you called, what you expected and what came back; put ids, arguments and the error text into kontext (no secrets, no personal data of third parties). One report per problem. Do not report a refused request that was correct (e.g. 'Project not found' for someone else's project). Needs an account. Free.
| Name | Required | Description | Default |
|---|---|---|---|
| art | Yes | fehler = something is broken; wunsch = something is missing | |
| text | Yes | What you called, what you expected, what happened — in a few sentences | |
| titel | Yes | One line, e.g. 'lab_capture: black frame for an image clip' | |
| kontext | No | Machine-readable details: ids, arguments, error text. Max ~8000 characters as JSON | |
| werkzeug | No | The tool it is about, e.g. 'lab_timeline_apply' | |
| project_id | No | Your project it happened in (only your own projects are accepted) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark this as a non-read-only but non-destructive, idempotent write, and the description adds real context beyond that: it requires an account, it is free, it forbids secrets/third-party personal data, and 'one report per problem' is consistent with the idempotentHint. It does not say what happens after submission (confirmation, ticket reference), which is the only remaining gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the purpose, then ordered operational instructions; nearly every clause carries a rule the agent needs. Slight overlap with the schema ('what you called, what you expected and what came back' restates the 'text' description), which keeps it from being perfectly tight.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-shot report tool with no output schema, the description covers the account prerequisite, privacy constraints, deduplication rule and anti-misuse exclusion. Only the post-submission outcome (whether a ticket id or receipt is returned) is left unstated, which is minor given there is no output schema to document it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline would be 3, but the description adds genuine semantics: which 'art' value maps to which real-world situation, that 'kontext' should carry ids, arguments and error text, that 'text' should say what was called/expected/returned, and that only the caller's own project_id is accepted. That is meaningfully more than the enum labels alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Tell the FilmLab team about a bug or a missing feature', and immediately distinguishes itself from the in-chat alternative ('the chat does not'). An agent can identify this as the out-of-band escalation channel 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit selection logic between the two enum modes ('fehler' when a tool returned something wrong/failed/contradicted its description; 'wunsch' when a needed step does not exist), plus an explicit exclusion ('Do not report a refused request that was correct') and volume guidance ('one report per problem'). Both when-to-use and when-not-to-use are covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finish an accepted DRAFT (a lab_reference_motion run with draft: true) in 1080p — same motion, same seed, same sound, sharper picture. A NEW video row comes back; the draft stays. Works only while the draft is valid and only through the account that ordered it; otherwise the backend refuses with a named reason (entwurf_abgelaufen, entwurf_anderes_konto, entwurf_fehlt, bereits_fertiggestellt) before anything is charged. Never download and re-upload a draft to get here: that is a new run, not this draft. Costs credits when called without get_cost.
| Name | Required | Description | Default |
|---|---|---|---|
| get_cost | No | Preflight: return the price in credits and the draft's expiry WITHOUT finishing it and without spending anything. Do this first and let the human confirm. | |
| video_id | Yes | Id of the DRAFT video row (from lab_reference_motion's answer or lab_job_status) — positive integer as string. | |
| project_id | Yes | Project id (from lab_list_projects) — positive integer as string. | |
| nur_eigene_daten | No | Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false and destructiveHint=false; the description goes well beyond them by confirming the draft is preserved, enumerating the four named refusal reasons (entwurf_abgelaufen, entwurf_anderes_konto, entwurf_fehlt, bereits_fertiggestellt), and stating that refusals occur before any charge. It also warns that download-and-re-upload produces a different run, and ties credit spend to omitting get_cost.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and outcome, then layered preconditions, error codes and cost. Every sentence carries information, though the 'Never download and re-upload' warning and the error-code list make it denser than ideal for a single operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema, the description covers what is returned (a new video row), what survives (the draft), what can fail and why, and when money is spent. An agent has everything needed to call it safely without opening anything else.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 cross-parameter meaning the schema does not: calling without get_cost costs credits, whereas the preflight returns price and expiry for free. That linkage is genuinely useful to an agent deciding call order.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (finish an accepted DRAFT in 1080p) and immediately defines what a DRAFT is — a lab_reference_motion run with draft: true — so the term is unambiguous. It also states the output ('A NEW video row comes back; the draft stays'), letting an agent distinguish this from a fresh generation or a re-upload.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit preconditions (draft still valid, same account that ordered it) and a routing rule for the gated-input case ('use a non-gated model or text only'). It also instructs the get_cost preflight. It does not name a concrete sibling for the non-draft upscale path (e.g. lab_upscale), so the alternative routing is only partially spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when the person wants a saved flow, pipeline or multi-step workflow priced, costed, calculated or checked against the balance BEFORE anything runs. Price a whole Flow (Pipeline) before running it: one quote over every node, checked against the credit balance and the project's cost cap. workflow is a FilmOS workflow in schema v1 (vault/workflows/_schema.md): nodes of type lab.tool call FilmLab tools by name, {{node_id.field}} passes one node's result into the next, parallel and condition are supported, foreach and workflow.invoke not yet. Every node whose tool costs money is priced with that tool's own get_cost preflight; a paid tool without a preflight, or a price that cannot be determined, rejects the whole quote by name — nothing is estimated. Nothing is generated and nothing is charged. Returns angebot_id (valid 24 h, for exactly this workflow, these inputs and this project), the total, one line per node, the balance and what the cap still allows. A node whose price only exists once its input exists (lab_upscale fed by a clip from another node) is listed with preis_folgt: true and is NOT in the total: the run stops before it, names the exact price and continues only after lab_flow_fortsetzen — tell the person so when you name the total.
| Name | Required | Description | Default |
|---|---|---|---|
| inputs | No | Values for the workflow's `inputs`, referenced as {{name}} | |
| workflow | Yes | The Flow (Pipeline) as a FilmOS workflow object, schema_version "1" | |
| project_id | Yes | Project id (from lab_list_projects) — every node runs in this project |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well past the annotations: discloses that nothing is generated or charged, that a paid tool lacking a preflight or an undeterminable price rejects the entire quote by name, that nothing is ever estimated, and that angebot_id is valid 24h and bound to this exact workflow/inputs/project. readOnlyHint=false is consistent with creating a persisted quote record, so there is no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the usage trigger and the core promise, and almost every sentence carries substantive constraints. The final sentence about `preis_folgt` is a long run-on that buries the operator instruction, costing some readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description fully covers the return contract: angebot_id, the total, one line per node, the balance and remaining cap allowance. It also covers the tricky partial case (`preis_folgt: true`, excluded from the total) and what to tell the user, so an agent can call it and report results without further sources.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, yet the description adds real meaning for the nested `workflow` object: schema v1 semantics, `lab.tool` nodes calling FilmLab tools by name, `{{node_id.field}}` data passing, supported `parallel`/`condition`, and unsupported `foreach`/`workflow.invoke`. That is exactly the information needed to build a valid workflow argument, which the schema does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise verb+resource: price/quote a whole Flow (Pipeline) before it runs, with an explicit scope (every node, checked against balance and cost cap). It is clearly distinguishable from siblings like lab_flow_starten, lab_flow_fortsetzen and lab_flow_status, and it explicitly declares the negative (nothing generated, nothing charged).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Opens with an explicit trigger ('Use when the person wants a saved flow... priced... BEFORE anything runs'), which cleanly separates it from the execution tools. It also names the hand-off for the deferred-price case (lab_flow_fortsetzen), but never explicitly contrasts with lab_flow_starten as the 'actually run it' alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when a flow/pipeline run is waiting for approval or a price confirmation and the person gives the go-ahead to continue. Resume a Flow (Pipeline) run that stopped and waits (status 'wartet' with a reason like 'Wartet auf Freigabe'). A run stops when a clip node needs a start image the person has not approved yet — approve the image first (lab_review_asset, verdict accepted), then resume. A run also stops before a node whose price only exists once its input exists (lab_upscale after a clip — the quote listed it as preis_folgt): the reason starts with 'Wartet auf Preisbestätigung' and names the exact credits. Resuming IS the confirmation of that price — ask the person first. The confirmed amount travels as max_credits; if the price rises before the run, nothing is charged and the run stops again with the new price. The waiting nodes are tried again; nothing that already ran is repeated.
| Name | Required | Description | Default |
|---|---|---|---|
| lauf_id | Yes | From lab_flow_starten |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well past the annotations (readOnlyHint=false, destructiveHint=false) by disclosing that resuming IS the price confirmation, that the confirmed amount travels as max_credits, that a price increase results in nothing being charged and another stop with the new price, and that only the waiting nodes are retried while completed work is not repeated. These are exactly the side effects an agent must know before acting.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the 'Use when' clause and organized around the two stop scenarios, which is good structure. It is on the long side for a one-parameter tool and repeats the status wording, but nearly every sentence carries actionable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter mutation with no output schema and no nested objects, it covers prerequisites, both stop causes, side effects and the retry scope, which is close to complete. Gaps are the unresolved max_credits reference and no guidance on what to do if the run is not actually in a waiting state.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and lauf_id is documented as coming from lab_flow_starten, so the baseline is 3. However, the description introduces 'max_credits' as something the confirmed amount 'travels as' while the input schema has only lauf_id and additionalProperties=false — an agent could plausibly try to pass a parameter that the schema will reject.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (resume) and resource (Flow/Pipeline run) and pins the exact precondition that separates it from lab_flow_starten/lab_flow_status: a run stopped with status 'wartet'. The two named stop reasons ('Wartet auf Freigabe' vs 'Wartet auf Preisbestätigung') let an agent identify the correct call without opening any sibling schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Opens with an explicit trigger ('Use when a flow run is waiting for approval or a price confirmation and the person gives the go-ahead'), and gives prerequisites plus a named alternative path: approve the image first via lab_review_asset with verdict accepted, then resume. It also states the when-not / ask-first condition for price confirmation, so routing is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when the person has seen the quote for a flow/pipeline and says to run, start or execute it. Run a Flow (Pipeline) that was quoted with lab_flow_angebot. Pass the SAME workflow and inputs plus the angebot_id — a changed workflow, an expired quote (24 h) or a quote that was already used is refused; get a new quote then. Only after the person confirmed the price. Returns right away with lauf_id; the run continues on the server without anyone watching. Follow it with lab_flow_status. Each node calls its FilmLab tool under your account; every tool's own gates still apply (approved keyframe before a paid clip, cost cap of the project). If the cost cap is hit, the whole run stops and nothing after it starts. The quoted price is also the run's own hard cap (auto_lauf_id): every node reserves against it, failed nodes keep their share, and a run whose retries would cost more than the quote stops with budget_exceeded instead of spending more.
| Name | Required | Description | Default |
|---|---|---|---|
| inputs | No | Exactly the inputs that were quoted | |
| workflow | Yes | Exactly the workflow that was quoted | |
| angebot_id | Yes | From lab_flow_angebot |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false and destructiveHint=false, so the description carries the real burden and does so well: it discloses the async contract ('Returns right away with `lauf_id`; the run continues on the server'), the refusal conditions, the per-node gating (approved keyframe, project cost cap), the stop-on-cap behavior, and the reservation/budget_exceeded semantics of auto_lauf_id. This is materially more than the annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the trigger condition and the alternative, then the return contract, then the budget rules. It is long, and the final sentence about auto_lauf_id reservations is dense, but nearly every clause conveys a behavior the caller must know, so little is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a nested-object, async, budget-governed tool with no output schema, the description supplies everything needed: the immediate return value, the follow-up tool, the failure modes, and the cost semantics. Nothing an agent needs to call this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 a genuine constraint the schema does not encode: workflow and inputs must be the SAME ones that were quoted, and angebot_id must come from lab_flow_angebot. That match-or-refuse rule is the key invocation detail and it lives only in the prose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Run a Flow (Pipeline) that was quoted with lab_flow_angebot') and explicitly distinguishes itself from the quote tool (lab_flow_angebot) and the follow-up tool (lab_flow_status). An agent can place this tool in the quote→run→status chain without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit preconditions ('Use when the person has seen the quote ... and says to run, start or execute it', 'Only after the person confirmed the price') and names the alternative path ('a changed workflow, an expired quote (24 h) or a quote that was already used is refused; get a new quote then'). When-to-use, when-not-to-use and the alternative are all present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when the person asks how far a flow/pipeline run is, whether it finished, why it stopped or hangs, or what a step returned. State of a Flow (Pipeline) run started with lab_flow_starten: the run's status (wartet, laeuft, fertig, fehlgeschlagen, abgebrochen) and, per node, its status, attempts, result and error. A node's result is exactly what its tool returned — ids from there go into the next tools. fehler is the run's stored message as written by the executor; when fehler_text is present it is the same message in the person's language — quote that one to the person. With angebot_id instead of lauf_id it finds the run started from that offer — gefunden: false means no run was created from it, so nothing was charged for it.
| Name | Required | Description | Default |
|---|---|---|---|
| lauf_id | No | From lab_flow_starten | |
| angebot_id | No | From lab_flow_angebot — finds the run started from this offer (when lab_flow_starten's answer was lost) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true is consistent, and the description goes well beyond it: it enumerates the five status values, describes per-node attempts/result/error, explains that `fehler` is the executor's stored message while `fehler_text` is the localized version to quote, and defines `gefunden: false` as 'no run was created from this offer, so nothing was charged'. With no output schema, this is the only place that behavior could be disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with a 'Use when...' trigger sentence, then the return shape, then two edge-case notes. Dense and largely earning its place, though the localized-error and billing implications are packed into a single long final sentence that could be split for scanability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description must carry the return-value burden, and it does: status vocabulary, per-node fields, error message duality, and the not-found case. Combined with 100% parameter coverage and a declared read-only annotation, an agent has everything needed to call and interpret this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds real semantics the schema lacks: lauf_id vs angebot_id are mutually alternative lookups, and the angebot_id branch is described as the recovery path when the start response was lost. It does not state what happens if both are supplied, which keeps it below 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb and resource ('State of a Flow (Pipeline) run started with lab_flow_starten') and enumerates exactly what comes back: run status values plus per-node status, attempts, result and error. It is clearly separable from siblings like lab_flow_starten, lab_flow_fortsetzen, lab_batch_status and lab_job_status because it scopes itself to a flow run.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Openers give explicit trigger conditions: the person asks how far a run is, whether it finished, why it stopped or hangs, or what a step returned. It also explains the angebot_id path for when lab_flow_starten's answer was lost. It never explicitly excludes alternatives (e.g. lab_batch_status or lab_job_status), so it stops short of a full when/when-not routing rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Release a paused PERSON-reference run (lab_reference_motion with use_depth: 'personen' or 'mannequin') after the human has looked at its mask preview: this starts the paid model run. Until now only the mask was charged. Show the preview (metadata.personen_referenz_url of the paused clip) first — holes in hair or hands cost a full run if released. A NEW video row comes back; the paused row stays as the record of the mask. The backend refuses with a named reason (nicht_wartend, bereits_freigegeben) before anything is charged. Costs credits when called without get_cost.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | No | Alternatively the job id from lab_reference_motion's answer — resolved to its video row. Give this or video_id. | |
| get_cost | No | Preflight: return the price of the run WITHOUT starting it and without spending anything. Do this first and let the human confirm. | |
| video_id | No | Id of the PAUSED video row (from lab_reference_motion's answer or lab_job_status) — positive integer as string. Give this or job_id. | |
| project_id | Yes | Project id (from lab_list_projects) — positive integer as string. | |
| nur_eigene_daten | No | Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: it discloses that the call starts a paid run and consumes credits, that only the mask was charged until now, and that a NEW video row is returned while the paused row remains. It also surfaces two named backend refusals (nicht_wartend, bereits_freigegeben) that fire before any charge, which is exactly the kind of pre-call context an agent needs. Minor gap: no detail on how long the run takes or how to follow it up.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The critical info is front-loaded: what it releases, the preview precondition, and the cost warning all land in the first three sentences. Some sentences are dense and clause-heavy, but no sentence is pure filler given the stakes of a paid, gated operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a paid mutation tool with no output schema, the description covers the outcome (a new video row, paused row preserved), the cost model, the error contract, and the compliance gate. An agent has everything needed to decide whether and how to call it safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all five parameters are already documented, including get_cost and nur_eigene_daten. The description adds only the cost consequence of omitting get_cost ("Costs credits when called without get_cost"); the rest of the parameter meaning is carried by the schema, which justifies the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action ("Release a paused PERSON-reference run") scoped to a named sibling (lab_reference_motion) with the exact use_depth values that produce such a run. An agent can tell immediately that this is the approval step following a mask preview, not a generation or status call.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit ordering and preconditions are given: show the mask preview first, call with get_cost before spending, let the human confirm. It also names the alternative path when the drittland gate blocks ("use a non-gated model or text only"), so both the when-to-use and the fallback are covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate an image on the production pipeline (fal.ai, quota-tracked, persisted to the project's gallery). Waits up to wait_s seconds (default 45) for the image and then answers with the finished rows — image_url set, inline previews attached, so the picture is in the answer like lab_job_status with preview. Pass wait_s: 0 to return right away with rows in status 'pending' (poll lab_job_status with id + project_id then). If the budget runs out, the rows come back as they are and fertig: false says so. Default tool is 'flux_pro'; use 'nano_banana_pro' (Gemini 3 Pro Image) for the Papercut-style look. Pass seed_image_url to run img-to-img guided by an existing image URL. get_cost: true preflights credits — it returns the price without generating anything. FOR A PERSON WHO MUST LOOK THE SAME across several images, do not re-describe them per prompt: get an id from lab_list_characters (or build one with lab_create_character + lab_generate_character_reference) and pass it as character_refs.
| Name | Required | Description | Default |
|---|---|---|---|
| seed | No | Seed for a repeatable run. Omit it and the project's stored seed applies (POST /api/lab/projects/{id}/einstellungen), and without that the provider picks one. The seed that actually rendered comes back in lab_job_status as `seed` with `seed_quelle` ('provider' = read from the provider's answer, 'gesetzt' = the one sent, null = the model tells no seed). Models whose endpoint has no seed field do not drop a given seed silently: the run proceeds and the row carries `seed_hinweis: seed_nicht_unterstuetzt` — some models tell their seed but take none, others take one but tell none. | |
| tool | No | Image model id — copy it verbatim from lab_list_models (kind: image). Omit to use the default. Every model has its own resolutions, aspect handling and price; the catalog is the only place those live, this text deliberately names none. | |
| aspect | No | Frame as [width, height], e.g. [9, 16]. Overrides the project's pose_state — pass it when the Pose-Director's blockout is set but not yet saved. Measured 2026-07-31: without it a 9:16 blockout came back as 16:9, because pose_state was still NULL. | |
| prompt | Yes | What to generate (required) | |
| wait_s | No | Seconds to wait for the finished image before answering (default 45, max 80). 0 = answer immediately with pending rows. | |
| anker_id | No | Look anchor id (positive integer string) whose CHOSEN image guides this generation as img-to-img. An anchor is a look imported from Midjourney: a handful of images plus the grammar of the old `--profile` code, stored per project. It resolves to exactly ONE image — the one the anchor's `gewaehlt` points at — because the provider payload carries one reference, not a set. So this is MUTUALLY EXCLUSIVE with seed_image_url (two sources for one field), and character_refs still wins over both: identity beats look. Build one from imported images with lab_umzug {anker}; list anchors with GET /api/lab/projects/<id>/umzug/anker. | |
| get_cost | No | Preflight: return the price in credits and your balance WITHOUT generating, reading the same catalog as lab_list_models. Do this before a batch or when the user wants to see the cost. For a card the user confirms, use lab_propose instead. | |
| metadata | No | Free-form JSON stored alongside the image (e.g. { parent_id, note }). Not interpreted by the pipeline. | |
| prop_ids | No | Prop ids from lab_list_props, belonging to this project (an @prop_ tag in the prompt does the same). Their descriptions go into the prompt, and each prop's FRONT view goes along as a reference image — after the characters, before the style kit; a prop alone may switch a text-to-image call to image-to-image (not on the abdruck path). The answer says which way it went (props.weg, props.grund). | |
| variants | No | How many variants to generate (default 1, max 5) | |
| scene_ref | No | Scene label (e.g. 'SZ 04'). Stored on the row, so results can be matched back to a shot list and reviewed per scene with lab_review_queue. Omit it and the image is an orphan. | |
| apply_lens | No | Defaults to TRUE on the backend: the project's lens_state UrPrompt is appended to the prompt. Pass false only to deliberately opt out for this one call. | |
| project_id | Yes | Project id (from lab_list_projects) — generation is always project-scoped | |
| resolution | No | Resolution tier, exactly as listed for the model in lab_list_models. Omit for the model's default; the aspect ratio still comes from the project's pose_state — this only sets the area. Some models have no resolution field at all — then leave it out. | |
| location_id | No | Location board id (from lab_list_locations). Anchors the shot: the board's `prompt_prefix_en` is appended to your prompt as 'Location: …' before generation, so every image of the same place stays in the same place. Check the prefix with lab_list_locations first — a board WITHOUT a prefix anchors nothing and fails silently. | |
| stil_kit_id | No | Style kit id from lab_list_stil_kits (an @stil_ tag in the prompt does the same). Omit it and the project's default kit applies (lab_stil_kit_standard); its rules and palette go into the prompt as text, and its reference images join only where the call already sends reference images (characters or props) and the model has a free slot after them. The answer says which way it went (stil_kit.weg). | |
| aspect_ratio | No | Aspect ratio as W:H (e.g. 16:9, 9:16). Must be one of the model's aspect_ratios where the model has an enum; models without an enum accept any W:H. Omit to use the project's camera aspect. | |
| costume_refs | No | The costume plate of these characters goes along as an extra reference image — the outfit on an invisible mannequin, NO person, so it carries the costume, never the face. Every id must also be in character_refs. Needs a model whose max_references covers characters + plates (lab_list_models); otherwise rejected before any quota is spent. Each plate is one more reference and may cost credits; get_cost prices it. | |
| ohne_stil_kit | No | true switches the project's default style kit off for this one call. | |
| apply_grundton | No | Defaults to TRUE on the backend: the project's ground tone (the filmmaker's own creative signature, set in the Composer's prompt stage) goes right after the prompt. Pass false only to deliberately opt out for this one call. | |
| character_refs | No | Character ids (positive integer strings) whose reference images lock the cast's identity. Routes the call to img-to-img and sends EVERY listed character's reference image, in the order given, up to the max_references (lab_list_models) of the model that actually runs. WITH A CHARACTER, flux_pro — the default — RUNS AS flux_2_pro (FLUX.2 [pro] edit), which takes up to 9 references: the answer names the switch in `umgeschaltet` (von/nach), and get_cost prices flux_2_pro. flux_pro's own img-to-img variant (redux) only varies its source image and dropped the scene in every measured case; it is still used for seed_image_url without characters, where the source's composition is wanted. A model that takes fewer references than you name: naming more with that tool explicitly is rejected before any quota is spent; without an explicit tool the image is made with the first max_references and the answer names the rest in `referenz_warnung` and `referenzen.nicht_gesendet` — nothing is dropped silently. Each additional reference may cost credits; get_cost with character_refs prices exactly that. This OVERRIDES seed_image_url: the characters fill the reference slots, and identity wins over composition. A character without a generated reference image is rejected before any quota is spent. GET IDS FROM lab_list_characters, or create one with lab_create_character followed by lab_generate_character_reference. Prefer character_refs over seed_image_url whenever a person must stay the same across images: seed_image_url holds identity only for the single call that passes it, character_refs is a register entry that every later call can name. SCENE AND LIGHT FOLLOW THE PROMPT: the reference holds the person, not the shot — harbour at night, stairwell under a top light, neon in the rain all came out as asked with the face kept (measured 2026-10-05 on flux_2_pro). What the reference does NOT change is the character's condition: it always shows the BASE state. For a wet, injured or otherwise changed character pass character_states instead of describing it in the prompt (lab_get_character_sheet returns the state keys and the descriptors behind them); to hold the outfit itself, add its costume plate with costume_refs. | |
| seed_image_url | No | Optional: run img-to-img guided by this existing image URL (e.g. a prior generation's url). For a PERSON who must look the same across several images, use character_refs instead — this URL binds one call, a register entry binds all of them. | |
| character_states | No | Which STATE each character is in for this image, as { characterId: stateKey } — e.g. { "12": "wet" }. A state is its own asset with its own full descriptor (clean / soaked / bloodied are three assets, not one with a note), and it is the ONLY way that descriptor reaches a generation: the reference image always carries the BASE state, so without this field you get dry Cal in a scene where he just came out of the Thames — and the image looks correct. Get the keys from lab_get_character_sheet; create one with the character state endpoint. Every id here must also appear in character_refs (who is not in the frame is not described), and an unknown key is rejected before any quota is spent. | |
| dreamer_signatur | No | Proof from the Dreamer (lab_prompt_transform, or the dreamer_fassung of a previous call) that THIS prompt went through it. Without a valid one the tool does not generate: it runs the Dreamer and returns its version first. | |
| nur_eigene_daten | No | Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial behavior beyond the annotations: quota tracking, persistence to the project gallery, wait semantics, pending rows, budget exhaustion returning fertig: false, and inline previews. The annotations only say non-read-only and non-destructive, so this description carries real operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded and dense with useful details, appropriate for a 25-parameter generation tool. It crams several distinct concerns into one paragraph, but there is little wasted wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the key operational behavior an agent needs for generation: synchronous wait versus pending polling, cost preflight, model default, image-to-image guidance, and character consistency routing. Rich schema descriptions cover the remaining parameters, and the description adequately explains return behavior despite no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 useful meaning: the default tool is flux_pro, nano_banana_pro is for Papercut style, get_cost is a no-generation preflight, and character_refs should be used instead of re-describing people. It does not explain every parameter, but the schema already does.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: generate an image on the production pipeline, with quota tracking and gallery persistence. It also distinguishes the immediate-return path from polling lab_job_status for pending rows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use guidance for wait_s: 0, get_cost preflight, default flux_pro versus nano_banana_pro, seed_image_url, and character_refs for consistent people. It names the relevant sibling tools for polling and character IDs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate the reference sheet for a character — six core views rendered from the sheet's prompt_prefix_en: detail (three-quarter close-up, the identity anchor), frontal (frontal close-up), profile, fullbody (front), fullbody_back (back view: hair and the back of the costume) and costume (the outfit on an invisible mannequin, NO person — use it where the costume is meant, never as a face reference). Back view and costume are derived from fullbody, everything else from detail. The poses pose_sitting, pose_walking, pose_action are optional extras for blocking — not part of the default run and not used as references for image or video models. A seventh view, 'detail_smile', is NOT in the default set and must be asked for: the same close-up with the mouth open and the teeth visible. Render it for every character who SPEAKS — otherwise the model invents the teeth and the jaw the first time they laugh, and the smile arrives as somebody else's mouth. It is an extra view for the mouth, never an identity anchor: a smiling reference carries its smile into every shot, funerals included. MEASURED 2026-09-15 (n=10, criterion fixed beforehand): the teeth land 10/10, but the PERSON only holds in about 4 of 10 even with the anchor active — two runs were plainly a different man. Generate it, then LOOK before you rely on it; the failure is obvious to the eye (a stranger's mouth on your character), not silent. THIS IS WHAT MAKES A SHEET USABLE: until it has run, lab_generate rejects the id as character_refs. Step 2 of 2 after lab_create_character. COSTS CREDITS — one provider call per view; the default run is six for humans, five for tier/kreatur (no costume). Pass views to render fewer, and get the exact price first with get_cost: true (free). Takes about 25 s PER VIEW (the tool requests them one by one, anchor first), so a full run is 2–3 minutes. If a single request times out, the answer says noch_in_arbeit instead of failing: that view is still rendering and already paid for — check it with lab_get_character_sheet, do NOT re-run it. The sheet needs a prompt_prefix_en; the backend regenerates one on demand but only best-effort, and answers 400 if that fails too. Views whose image could not be mirrored to R2 are deliberately NOT saved and come back in nicht_gespiegelt — those views are missing, not broken, and a re-run renders only what you ask for.
| Name | Required | Description | Default |
|---|---|---|---|
| views | No | Which views to render. Omit for the core views (six for humans, five without costume for tier/kreatur). Allowed: detail, frontal, profile, fullbody, fullbody_back, costume, pose_sitting, pose_walking, pose_action. Fewer views = fewer credits; `detail` and `fullbody` alone are usually enough to lock an identity. | |
| get_cost | No | Free: the exact price of this run (per view and total, anchor and edit rate included) — nothing is rendered or charged. Name it to the person before the real run. | |
| character_id | Yes | Character sheet id (from lab_list_characters or lab_create_character) — positive integer as string |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds far more: credit cost per view, ~25 s per view, timeout behavior returning `noch_in_arbeit`, R2 mirroring failures surfacing as `nicht_gespiegelt`, backend 400 on missing prompt_prefix_en, and measured identity-hold rates (4/10). This is exactly the behavioral context annotations cannot carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The content is valuable but poorly structured: three dense paragraphs with multiple embedded warnings, measurements, and caveats. It is front-loaded on purpose but the mid-section (detail_smile guidance and the n=10 measurement) disrupts scannability for an agent trying to extract the invocation parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a costly, multi-view generation tool with no output schema, this description covers everything an agent needs: cost, timing, failure modes, prerequisites, default behavior, and how to verify results. Nothing material is left to inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all three parameters. The description adds value beyond the schema by explaining the default view set (six for humans, five for tier/kreatur), the derived-view relationships, and the semantic warning that costume is not a face reference.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Generate the reference sheet for a character') and enumerates the six core views with their precise rendering semantics. This distinguishes it clearly from siblings like lab_create_character (creation) and lab_get_character_sheet (read).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly positions itself as 'Step 2 of 2 after lab_create_character' and states that lab_generate rejects the id as `character_refs` until this runs. It names the alternative for cost checking (get_cost: true) and tells the agent to use lab_get_character_sheet on timeout rather than re-running.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate time-of-day reference images for a location board (costs credits per variant — check the price with get_cost first). Without variants the backend renders all four. The images are what makes a board usable as a visual reference.
| Name | Required | Description | Default |
|---|---|---|---|
| loc_id | Yes | Location board id (from lab_list_locations) | |
| get_cost | No | Free: the exact price of this run (per variant and total) — nothing is rendered or charged. Name it to the person before the real run. | |
| variants | No | Which time-of-day variants to render. Allowed: day, night, golden_hour, rain. Omit for all of them. Fewer variants = fewer credits. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only tell the agent this is a non-read-only, non-destructive operation; the description goes further by disclosing that it consumes credits per variant and that omitting `variants` triggers a default render of all four. That cost/default behavior is exactly the kind of context annotations cannot carry. It stops short of explaining what happens to existing images or how results are retrieved.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the action and cost warning. The closing line ('The images are what makes a board usable as a visual reference') is mild editorializing, but it is the only sentence that does not carry operational information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a credit-consuming generation tool with no output schema, the description covers the essentials: what it produces, what it costs, and the default expansion behavior. It leaves minor gaps around where generated images land and whether re-runs overwrite, but nothing that would cause a bad call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the allowed variant values and the omit-for-all behavior are already documented in the schema itself. The description largely restates that ('Without `variants` the backend renders all four') rather than adding syntax or format detail beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Generate time-of-day reference images for a location board.' An agent knows what is produced and against which artifact. It does not, however, distinguish itself from near neighbors like lab_restyle_location or lab_location_panorama, so the sibling differentiation is only implied by 'time-of-day variants.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description prescribes a workflow step in 'check the price with get_cost first,' which is genuine usage guidance for the cost-check parameter. But it never states when to prefer this tool over alternatives such as lab_restyle_location or lab_create_location, nor does it note prerequisites like an existing board. Usage is implied rather than argued.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a MUSIC track for a project — the first step of the rhythm chain, and the only one that costs credits. Default engine: ElevenLabs Music v2.5 (produced, contemporary instrumental beds, 3-300 s, priced per second). Stable Audio stays selectable with tool 'stable_audio' (flat per run, up to 190 s, noticeably dated sound). ElevenLabs refuses prompts that name artists, bands or song lyrics; the failed row then carries its suggested rewording in metadata.error. ASYNCHRONOUS: the call returns immediately with a row whose audio_url is null and metadata.status is 'pending'. Nothing is playable and nothing can be bound yet. Poll lab_list_audio (audio_type 'music') until that row's status is 'completed' and audio_url is set — usually under a minute, and the backend gives up after five (status turns 'failed', metadata.error carries the reason, and the credits are refunded). PUT THE TEMPO IN THE PROMPT if you intend to cut on the beat. This is measured, not assumed: a soft swing track measured at confidence 0.164 (unusable), an ordered hard pulse ('techno, 128 bpm, four-on-the-floor') at 0.621. The tempo detector is autocorrelation over an onset envelope — it finds a hard pulse and shrugs at drone, ambient and rubato. Then: lab_bind_audio, lab_beatgrid, lab_apply_rhythm.
| Name | Required | Description | Default |
|---|---|---|---|
| tool | No | Music engine. Default 'elevenlabs_music' (ElevenLabs Music v2.5, per second, 3-300 s). 'stable_audio' is the older flat-priced engine (1-190 s) | |
| prompt | Yes | What the music should be. Name genre, instrumentation, mood AND the tempo in bpm if the cut is supposed to sit on the beat — e.g. 'driving techno, four-on-the-floor kick, 128 bpm, no vocals'. A prompt without a stated pulse is the usual reason lab_beatgrid comes back unreliable | |
| get_cost | No | `true` preflights the credit price and your balance WITHOUT generating anything and without spending quota. | |
| scene_ref | No | Optional scene label, stored on the row. Useful to tell several tracks of one project apart | |
| project_id | Yes | Project id (from lab_list_projects) — positive integer as string | |
| duration_seconds | No | Track length in seconds (default 30). ElevenLabs takes 3-300 s (shorter is raised to 3), Stable Audio up to 190 s. Make it at least as long as the sequence you want to cut — lab_apply_rhythm computes durations for the clips that exist and neither adds nor deletes any, so a short track under a long timeline stays a short track |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare only readOnlyHint=false and destructiveHint=false; the description adds substantial context beyond that: credit costs and per-second pricing, asynchronous call behavior (immediate row with null audio_url and status 'pending'), the polling contract, the five-minute backend timeout with failure reason and credit refund, and content refusal rules (no artist/band/lyric names, suggested rewording in metadata.error). This is a genuine behavioral disclosure of exactly the traits an agent cannot infer from the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the purpose and chain position, and every section (engine choice, refusal behavior, async/polling, tempo) earns its place. It is nonetheless long and the tempo discussion is carried across several sentences that could be tighter, which keeps it short of a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter mutation tool with no output schema, the description supplies everything an agent needs: the async return shape (audio_url null, metadata.status 'pending'), how and how long to poll, the failure/refund path, and the prerequisites (project_id from lab_list_projects). No gap remains that would cause an incorrect invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning beyond the schema: the engine tradeoff (produced contemporary beds vs. noticeably dated sound, per-second vs. flat pricing, differing duration caps) and a nuanced warning that duration_seconds must cover the target sequence because lab_apply_rhythm neither adds nor deletes clips. The tempo guidance is also reinforced with measured evidence rather than just restated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Generate a MUSIC track for a project') and immediately positions it within the rhythm chain, explicitly contrasting it with the sibling engine tool 'stable_audio'. An agent can distinguish it from lab_bind_audio, lab_beatgrid and lab_apply_rhythm without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says this is the first step of the rhythm chain and the only one that costs credits, names the downstream tools (lab_bind_audio, lab_beatgrid, lab_apply_rhythm), states the polling alternative lab_list_audio with the audio_type filter, and gives the when-to-use conditions for switching to stable_audio. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get ONE character sheet in full — every descriptive field plus the three that decide what you can do with it. prompt_prefix_en is the text block describing this person; it is what the backend prepends wherever the sheet is used. reference_images decides whether the sheet is usable at all: lab_generate REJECTS a character_refs entry without one, before any quota is spent — if it is empty, run lab_generate_character_reference first. states carries the state sheets against character drift (costume, light, physical condition); lab_get_character_sheet renders them agent-readable.
| Name | Required | Description | Default |
|---|---|---|---|
| preview | No | Attach the reference images themselves, downscaled to 512px. `reference_images` decides whether the sheet is usable at all — seeing them is the check, counting them is not: a sheet can carry a URL to a picture of the wrong person. | |
| character_id | Yes | Character sheet id (from lab_list_characters) — positive integer as string |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint only covers the safety profile, yet the description discloses the downstream gating behavior (reference_images must be non-empty or lab_generate rejects before spending quota) and the quarantine purpose of states. This is exactly the kind of cross-tool behavioral context annotations cannot carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the scope statement, then spends each sentence on a distinct high-value field. It is dense and slightly long, but no sentence is filler and the dependency ordering is clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description names the three load-bearing return fields (prompt_prefix_en, reference_images, states) and their roles, which is strong for a read tool. 'Every descriptive field' remains hand-wavy about the remaining payload, so it is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description reinforces the semantics of reference_images as a usability gate and preview as a verification aid ('seeing them is the check, counting them is not'). It adds interpretive meaning beyond the raw field docs, though character_id is left entirely to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Get ONE character sheet in full') and the word 'ONE' plus the field inventory distinguishes it from lab_list_characters and lab_get_character_sheet. An agent knows exactly what single resource this returns without opening a sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit conditional guidance: if reference_images is empty, run lab_generate_character_reference first, and explains why lab_generate rejects such sheets before quota is spent. It stops short of an explicit when-to-use branch versus lab_get_character_sheet, implying the division only through the states note.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The character sheet PREPARED FOR PROMPTING: base prefix, the state sheets by name, which reference views exist, and the ready-made sentence to paste into a lab_generate prompt. Same source as lab_get_character, different shape — use this one when you are about to generate, and lab_get_character when you want the raw record. State sheets exist against character drift: one sheet per costume, light or physical-condition change, so a person stays the same person when the situation changes. THIS IS THE ANSWER to 'same person, different light': character_refs alone routes to i2i and drags the reference's lighting along, so a drastically different light fights the reference. A state sheet puts the change into the TEXT, where the prompt can win. Free.
| Name | Required | Description | Default |
|---|---|---|---|
| state | No | Render the snippet for THIS state key (from `states[].key`) instead of the base state | |
| preview | No | Attach the reference views themselves, downscaled to 512px. `usable_as_character_ref` only says a URL exists — the picture says whether it is the right person, in the right view. That check is the whole point of a character sheet. | |
| character_id | Yes | Character sheet id (from lab_list_characters) — positive integer as string |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so safety is covered; the description adds value beyond that by disclosing the return payload shape, stating the call is 'Free', and explaining the behavioral mechanism (a state sheet puts the change into the text so the prompt can win rather than dragging the reference's lighting). It stops short of describing pagination or error behavior, but for a read-only lookup this is solidly above the bar.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the return contents before rationale and alternative, which is the right order. It is longer than strictly needed — the character-drift rationale and the 'THIS IS THE ANSWER' framing run a bit long — but each sentence carries usable routing or conceptual information rather than filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the full burden of explaining returns and does so completely (base prefix, named state sheets, reference views, paste-ready sentence). Combined with the explicit sibling routing and cost note, an agent has everything needed to select and call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters are already documented in the schema, including the `states[].key` origin of `state` and the downscale/verification purpose of `preview`. The description reinforces the concept of a state but adds no syntax or format detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (retrieve the character sheet prepared for prompting) and enumerates exactly what it returns: base prefix, state sheets by name, reference views, and a ready-to-paste sentence. It explicitly names and contrasts with the sibling lab_get_character, so an agent can distinguish the two without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit routing rule: 'use this one when you are about to generate, and lab_get_character when you want the raw record.' It further explains the scenario it is designed for ('same person, different light') and why character_refs alone fails there, which is a concrete when-to-use condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the accumulated context/output for one pipeline module of a project (e.g. the IDEE, STORYBOARD or SHOTS stage). Needs project_id and module name.
| Name | Required | Description | Default |
|---|---|---|---|
| module | Yes | Pipeline module/stage id, e.g. 'idee', 'storyboard', 'shots' | |
| project_id | Yes | The FilmLab project id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes this is a safe read, so the description only needs to add context. It adds that the read is scoped to one module of a project, which is useful, but says nothing about what 'context/output' contains, whether it errors when no output exists yet, or any size/format behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, front-loaded with the action and resource. The trailing prerequisite sentence is slightly redundant with the schema's required fields but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-param read tool with full schema coverage and a readOnly annotation, this is close to sufficient, but it omits what the returned context is and how it relates to sibling read tools like lab_get_state, leaving a gap in choosing between them.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters are documented in the schema with examples, so the description need not carry this dimension. The description restates the requirement of project_id and module without adding format or value guidance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (read) and resource (accumulated context/output for a pipeline module) with a concrete example set of module names. It is clear on its own, but it does not differentiate from closely adjacent siblings like lab_get_state, lab_get_dossier, or lab_run_module, which also read pipeline state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by 'read the accumulated context/output for one module', but there is no explicit when-to-use guidance, no statement of when to prefer lab_get_state or lab_get_dossier, and no prerequisites. Adequate but leaves alternative selection to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Poll a dossier job by job_id (from lab_dossier). status is queued|processing|done|failed. When done, result.archiv_url is a signed https link to the ZIP that loads WITHOUT a login and expires after 24 h — call again for a fresh one. result.fehlend lists takes that could not be loaded.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | The dossier job id returned by lab_dossier |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, it discloses non-obvious behavior: the archiv_url is a signed https link that loads without a login, expires after 24 hours, and can be refreshed by calling again, plus what result.fehlend contains. These are exactly the traits an agent could not derive from the schema or annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences: purpose and input first, status lifecycle second, return-value semantics last. No filler, and the most important operational facts are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of explaining return values and does so (archiv_url semantics, expiry, refresh, fehlend). Status values and input provenance are also covered, leaving nothing an agent needs missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single parameter is already documented there; the description only adds the provenance of job_id (returned by lab_dossier). Baseline 3 is appropriate when the schema carries the parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: polling a dossier job by job_id, with the originating tool (lab_dossier) named. It does not, however, differentiate itself from the many sibling job/status tools (lab_get_job, lab_job_status, lab_batch_status), so an agent must infer which poller applies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clear context for use: it is the poller for a job started by lab_dossier, and the enumerated status values tell the agent when to keep polling versus stop. It stops short of naming alternatives or stating exclusions, so it is context-rich but not fully routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Poll an export render job by job_id (from lab_start_export). status is queued|processing|done|failed; when done, the result (output url) is included. Call repeatedly until done|failed. NB: this is the EXPORT poll — different from lab_get_generation. Where the address sits depends on the profile: a rendered film is in video_url, but profile alpha_png_sequence delivers a ZIP of RGBA PNGs and therefore leaves video_url null and puts the address in archiv_url — a .zip under a key called video_url would read as something playable to every client. download_url carries the address in both cases and is the safe one to hand to a user. All result addresses — video_url, download_url, archiv_url and the provenance record herkunft.pdf_url / herkunft.json_url — are signed https links that load WITHOUT a login and expire after 24 h; call lab_get_export again for fresh ones. view_url is the short session-bound form for the web app only. A finished result also carries zielmarkt_checkliste: per target market of the project (see lab_zielgruppe) what the customer must observe when delivering there — empty without markets. Pass it on to the person with the download; it is not legal advice.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | The export job id returned by lab_start_export |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint already covering safety, the description adds substantial behavioral context beyond annotations: the queued|processing|done|failed state machine, that result links are signed https URLs that load without login and expire after 24h, and that re-polling is the refresh path. It also explains why video_url may be null for the alpha_png_sequence profile, which is non-obvious behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose and polling contract before the dense field-name caveat, and nearly every sentence carries operational value. It is long and packs several distinct topics (polling, URL fields, expiry, market checklist) into one block, which costs some scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description carries the full burden of describing return values, and it does: status values, which address fields are populated per profile, link expiry, and the zielmarkt_checkliste payload. Nothing needed to call or interpret the result is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single parameter's description already says it comes from lab_start_export, so the description's mention of the same origin adds no meaning beyond the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Poll an export render job by job_id') and explicitly disambiguates from the sibling lab_get_generation, so an agent can select it without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives the origin of the id ('from lab_start_export'), the loop contract ('Call repeatedly until done|failed'), and the explicit sibling it is not ('different from lab_get_generation'). Usage is fully determined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the status of a background job by job_id (status is queued|processing|done|failed). Poll this after starting a long-running generate/export. Returns the job record; its payload and result are objects (for a clip chain: result.zusammenfassung, result.ketten, result.clips). For an Umzug import (lab_umzug): result.bildzeilen (image_id, datei), result.gesperrt (datei, grund), result.ungeprueft. Pass wait_s (up to 80) to wait inside the call until the job is done or failed instead of polling in quick succession. Rights class is returned as rechte_klasse (klasse + regelstand) on result rows: mitgebracht, generiert, abgeleitet or lizenziert; nicht_festgehalten means the old row has no recorded class. This is separate from eigen/ki (AI Act).
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | The job id returned by a generate/export tool | |
| wait_s | No | Wait up to this many seconds (max 80) for done/failed; the answer says gewartet_s |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint already covering the safety profile, the description still adds substantial behavior: the four status values, the blocking semantics of wait_s (up to 80 seconds, then gewartet_s in the answer), and the meaning of rechte_klasse values including the nicht_festgehalten edge case. It also flags a non-obvious distinction from eigen/ki under the AI Act, which an agent could easily conflate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The lead sentence and polling guidance are correctly front-loaded, but a large share of the text is deep domain detail: clip-chain result fields (result.zusammenfassung, result.ketten, result.clips), Umzug import fields, and a multi-line rights-class taxonomy. Much of this is only relevant to specific job types, and none of it reads as wasted, but the density makes the core call pattern harder to extract.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description carries the return-value burden and does so for two concrete job types plus the generic job record with payload/result objects. It leaves the shape of a failed job's record and any error fields unstated, which is the one thing an agent polling on errors would still want.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, and the description earns above that by supplying the status enum values that the schema omits (job_id has no enum) and by explaining the blocking/waiting behavior of wait_s. It does not add syntax or format detail for job_id beyond the schema's own text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb and resource: 'Get the status of a background job by job_id', plus the status vocabulary (queued|processing|done|failed). It does not distinguish itself from the close siblings lab_job_status, lab_batch_status, and lab_jobs_inflight, which is the main remaining gap for an agent selecting among job-lookup tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Poll this after starting a long-running generate/export' gives a clear triggering condition, and 'Pass wait_s (up to 80) to wait inside the call... instead of polling in quick succession' gives explicit alternative behavior. It stops short of naming when to prefer lab_job_status or lab_jobs_inflight, so a routing ambiguity against those siblings remains.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get ONE location board in full — all descriptive fields plus its reference images and prompt_prefix_en. Use it to check what a board actually anchors before generating with it.
| Name | Required | Description | Default |
|---|---|---|---|
| loc_id | Yes | Location board id (from lab_list_locations) — positive integer as string | |
| preview | No | Attach the board's reference images themselves, downscaled to 512px — the fastest way to check whether a board anchors the place you mean before spending quota on it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only supply readOnlyHint=true; the description goes further by enumerating the returned payload (descriptive fields, reference images, prompt_prefix_en) and tying the preview flag to quota cost. It does not mention pagination or failure modes, but for a single-resource read the added return-format context is meaningful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, front-loaded with the resource and payload, then the usage rationale. No filler or restated name/title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description compensates by naming the key returned artifacts, and the read-only safety profile is covered by annotations. What's missing is only marginal detail (e.g., what happens on an invalid id), which is low-stakes for a single getter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both loc_id and preview are already fully documented, including the 512px downscale and quota rationale. The description adds no parameter syntax beyond what the schema states, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Get ONE location board in full'), and lists what comes back (descriptive fields, reference images, prompt_prefix_en). The emphasized 'ONE' cleanly distinguishes it from the sibling lab_list_locations, which enumerates boards.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly frames when to use it: 'to check what a board actually anchors before generating with it.' The schema also points at lab_list_locations for id discovery. It lacks an explicit when-not or a named alternative tool, which keeps it 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.
Use when the person asks where a project stands: its current stage, what is finished, what comes next, or wants the project's state before continuing. Get a single FilmLab project with its full stage state, including its datenmodus ('eu' or 'frei'). Needs the project_id (from lab_list_projects).
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The FilmLab project id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so safety is covered. The description adds real behavioral context beyond that: the response is a single project's full stage state and includes the `datenmodus` field with its two possible values ('eu' or 'frei'), which the annotations and schema do not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences: the first front-loads the invocation triggers, the second states what is returned and the ID source. No restatement of the name or title, and no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one required param, full schema coverage, a readOnly annotation, and no output schema, the description covers what an agent needs: when to call it, where the ID comes from, and the shape of the returned state including `datenmodus`. Only the disambiguation from other `lab_get_*` reads is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single parameter is documented as 'The FilmLab project id', so the baseline is 3. The description goes beyond that by telling the agent where the value comes from (`lab_list_projects`), which prevents guessed or fabricated IDs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Get a single FilmLab project') plus the payload scope: full stage state including `datenmodus`. It also positions itself against `lab_list_projects` by naming it as the ID source, so an agent can separate fetch-one from list-many 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The opening clause gives concrete triggers — asking where a project stands, what is finished, what comes next, or needing state before continuing. It also routes ID lookup to `lab_list_projects`. It does not disambiguate against other read siblings like `lab_get_state` or `lab_get_context`, which is the only missing piece.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get ONE sequence in full — timeline (the shots in order), audio_tracks, transitions, duration_seconds and render status. Check timeline here before starting a continuity pass: an empty one is the single most common reason the pass refuses.
| Name | Required | Description | Default |
|---|---|---|---|
| seq_id | Yes | Sequence id (from lab_create_sequence/lab_list_sequences) — positive integer as string |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already tells the agent this is a safe read. The description adds value beyond that by disclosing the return contents and a real workflow gotcha (empty timeline causes downstream continuity passes to fail), which is genuinely useful behavioral context. It does not cover error behavior for a non-existent seq_id.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both earning their place: the first defines the payload, the second front-loads the actionable check. No filler or restatement of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly enumerates the returned fields and ties the tool into the continuity workflow, which is sufficient for a 1-parameter read tool. Minor gap: it does not say what happens when the seq_id is unknown or how a missing/empty timeline is represented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and there is a single parameter, so the schema already documents seq_id including its provenance (lab_create_sequence/lab_list_sequences). The description adds nothing further about the parameter, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (get) and resource (sequence) with explicit scope ('ONE sequence in full') and enumerates the returned payload: timeline, audio_tracks, transitions, duration_seconds, render status. The 'ONE' framing distinguishes it from the sibling lab_list_sequences, which returns many.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a concrete pre-flight condition: check `timeline` here before starting a continuity pass, and explains why (an empty timeline is the most common cause of the pass refusing). It does not explicitly name sibling alternatives such as lab_list_sequences, so it stops short of full when/when-not routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One call, the whole picture: account (tier, credits, reset), default models with price, jobs in flight, catalog freshness, project count. Pass project_id for that project's sequences, assets and review-queue length. Read-only, free.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | No | Add a project view |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered; the description's "Read-only" restates it, while "free" adds a genuine cost signal not present in structured data. It discloses what data is returned but says nothing about freshness guarantees, pagination, or failure behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences, front-loaded with the aggregate scope followed by the optional parameter's effect. Every clause carries distinct information; nothing is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return-value burden and does it well by enumerating the state fields returned. Minor gaps remain around output format/shape and whether the project view is additive to the base payload.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% but the schema text is thin ("Add a project view"); the description expands it meaningfully by specifying that project_id yields that project's sequences, assets, and review-queue length, telling the agent what the parameter actually changes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete verb+resource (fetch whole account state) and enumerates the payload: account tier/credits/reset, default models with price, jobs in flight, catalog freshness, project count. That specificity distinguishes it from narrower siblings like lab_get_project or lab_jobs_inflight, though no sibling is named directly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"One call, the whole picture" implies using this for an overview instead of many targeted calls, and "Pass project_id for that project's sequences, assets and review-queue length" gives conditional guidance for the optional parameter. There is no explicit when-not or named alternative, so usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply a deterministic colour grade to an image already in the project gallery — no re-generation, no provider, no credits. The look is computed pixel-exact (exposure, saturation, hue, lightness, contrast, film grain) and lands as a new gallery image the sequencer and export pick up. For full control the recipe fields are open too: levels and curves per channel (rgb, r, g, b — values 0..255), a gradient map (luminance → colour ramp), exposure offset/gamma and grain seed/colour. Fixed order, like a node stack: exposure → levels → curves → hue/saturation → look (LUT) → gradient map → grain. The same recipe on the same image always yields the same result (grain is fixed-seed), so a look is reproducible across every still. Set from_colorist to start from the project's colorist crew brief (look, contrast, grain) and tune with the sliders on top. At least one adjustment OR from_colorist is required. Synchronous — the graded image_url comes straight back, no polling.
| Name | Required | Description | Default |
|---|---|---|---|
| hue | No | Hue rotation in degrees; zero neutral | |
| look | No | Named look from the bundle catalogue (e.g. filmlab-neutral, filmlab-warm, filmlab-cool, filmlab-soft, filmlab-punch) — a hand-authored LUT, applied on top of the sliders. The server resolves the name; a path is never accepted. | |
| grain | No | Film grain amount; zero is none, monochrome | |
| curves | No | Curves per channel as [x, y] points 0..255, x strictly increasing (smooth monotone curve through them). Example warm highlights: {"r": [[0,0],[192,205],[255,255]], "b": [[0,0],[192,180],[255,255]]}. Not together with contrast on the rgb channel | |
| levels | No | Levels per channel (rgb = all three, r/g/b single), values 0..255: input black/white point, gamma (above 1 brightens midtones), output black/white. Example: {"rgb": {"black": 12, "white": 240, "gamma": 1.1}} | |
| contrast | No | Contrast curve: high is an S-curve, low flattens it | |
| exposure | No | Exposure in stops; positive brightens, zero is neutral | |
| image_id | Yes | Id of the source image in the project gallery (from lab_list_assets / lab_generate) | |
| lightness | No | Lightness; negative darkens, zero neutral | |
| grain_mono | No | Grain in black and white (default true); false gives colour grain | |
| grain_seed | No | Seed of the grain pattern (default 0) — same seed, same grain | |
| project_id | Yes | Project id (from lab_list_projects) | |
| saturation | No | Colour saturation; minimum is greyscale, zero neutral | |
| gradient_map | No | Gradient map: luminance 0..1 → colour ramp, blended with opacity (default 1). Example teal-orange: {"stops": [[0, "#0b2a33"], [0.5, "#7a7a72"], [1, "#ffd9a8"]], "opacity": 0.3} | |
| look_opacity | No | Blend of the named look, 0..1 (default 1) | |
| from_colorist | No | Start from the project's colorist crew brief (look/contrast/grain), then apply the sliders on top | |
| exposure_gamma | No | Exposure gamma; 1 neutral, above 1 brightens midtones | |
| exposure_offset | No | Exposure offset added after the stops (lifts or crushes blacks); zero neutral |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description richly explains behavior beyond the annotations: deterministic/reproducible output ('same recipe on the same image always yields the same result'), non-destructive write to gallery ('lands as a new gallery image'), fixed processing order ('like a node stack: exposure → levels → curves → hue/saturation → look (LUT) → gradient map → grain'), synchronous/no-polling contract ('the graded image_url comes straight back'), and the requirement 'At least one adjustment OR from_colorist'. Annotations only say readOnlyHint=false, destructiveHint=false; the description's extra disclosure is substantial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The content is front-loaded with purpose, then gets long with lists of fields and pipeline order that are already documented by the schema. Some sentences are dense but informative; the description is about 3-4 sentences compressed, with several details that restate schema. It's not bloated, but not sufficiently concise given schema coverage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 18-param mutation tool with no output schema, the description covers behavior (deterministic, sync return, gallery write), ordering, the from_colorist branch and the minimum-adjustment requirement. It doesn't cover edge cases like error conditions, or what happens to existing recipe state beyond 'new gallery image'. Given schema describes parameters fully, the contextual gaps are minor, but still not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all 18 parameters with types, ranges and descriptions. The description echoes field names ('exposure, saturation, hue, lightness, contrast, film grain') and clarifies the order they apply in, plus the mutual exclusion 'Not together with contrast on the rgb channel' (present in schema). The description adds the fixed-order semantics and the from_colorist behavior ('apply the sliders on top'), which is useful, but mostly repeats the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Apply a deterministic colour grade to an image already in the project gallery') and immediately distinguishes itself from generation siblings with 'no re-generation, no provider, no credits'. The pipeline names (exposure, saturation, hue, lightness, contrast, film grain) make it distinguishable from lab_grade_clip and lab_grade_from_resolve.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a clear context ('image already in the project gallery') and an entry condition ('At least one adjustment OR from_colorist is required'), plus a routing hint for from_colorist. It doesn't explicitly name alternate tools like lab_grade_clip or lab_grade_suggest, so it lacks sibling exclusion, but the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the colour grade of ONE clip in the edit (Murnau), or of the whole programme with programm: true. It is the same grade a colourist sets in Murnau's colour workspace, and the export uses it: Murnau bakes the export LUTs when you set it. Only the fields you send change (zuruecksetzen: true starts from neutral). Fields and ranges, as the sliders: exposure in stops (−5..5); contrast, saturation, temperature, tint −100..100; hue −180..180; lift/gamma/gain/offset as {x, y, master}, each −1..1 (x/y move the colour wheel); log as {shadow|midtone|highlight: {x, y, master}} — the Log wheels in ACEScct, each acting only on its range of brightness (shadows below ~4 % linear, highlights above ~50 %), master ±1 ≈ ±2 stops there; schritte as a list (≤ 8) of further grades with the same fields (plus name), applied in series after this grade — serial nodes; creative and sek stay on the grade itself; hdr as {dark|shadow|light|highlight: {x, y, master}} — HDR zone wheels centred −3/−1/+1/+3 stops around 18 % grey, master ±1 ≈ ±1.5 stops; curves as {master|r|g|b: [[x,y],…]} 0..1; boost, shadows, highlights −100..100; intensity 0..100 (0 = original). Per clip also sek — a secondary correction: {qualifier: {hueCenter, hueWidth, satLow, satHigh, lumLow, lumHigh, softness, invert}, fenster: [{form: kreis|rechteck|verlauf|polygon|bezier, cx, cy, rx, ry, winkel, weich, invert, modus: add|sub, punkte (polygon/bezier only: 3–16 resp. 3–12 [x, y] in the window's own unit space, scaled by rx/ry and turned by winkel — bezier draws a smooth closed curve through them)}], grade: {saturation, exposure, temperature, tint, hue, schutz}} — schutz 0..100 takes the clip's and the programme's grade back inside the selection (100 = ungraded there, e.g. to protect skin); sek: null removes it. Any level also takes warper — the Color Warper: {huesat|chromalum: {res: 6|12|24, punkte: [[i, j, dx, dy], …]}}; node (row i, column j) sits at (j/res, i/res) and is moved by (dx, dy) in −1..1. huesat plane: x = 0.5 + 0.5·sat·cos(hue), y = 0.5 + 0.5·sat·sin(hue) (lightness kept); chromalum plane: x = sat, y = 1 − lightness (hue kept). Only moved nodes; warper: null removes it. Call WITHOUT grade to list the clips (clip_id, start/end, current grade, input profile) and the programme grade. Measure first and after with lab_scopes — its vorschlag.grade is a computed correction you can pass here as grade. Writes state, costs nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| grade | No | Fields to set — see description; omit to list clips and grades | |
| preset | No | Soft highlight shoulder (master curve only, saturation untouched) for AI-generated video; fields in `grade` override it; pair with Mid Detail −10 in the editor for a softer look (measured: −19 % fine-detail energy). | |
| seq_id | Yes | Sequence id — positive integer as string (lab_list_sequences) | |
| clip_id | No | The clip to grade (from the listing); omit with programm:true | |
| programm | No | Grade the whole programme instead of one clip | |
| zuruecksetzen | No | Start from a neutral grade before applying `grade` |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well past the annotations by disclosing a real side effect — Murnau bakes the export LUTs on set — plus partial-update semantics ('Only the fields you send change'), neutral-reset behavior, and clip-vs-programme propagation via `schutz`. Consistent with destructiveHint=false and idempotentHint=true, though no auth/permission or failure behavior is covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded correctly and nearly every clause carries real information, but the body is a single dense run-on paragraph mixing scope, ranges, warper geometry, and qualifier windows, making it hard to scan. Some framing ('the same grade a colourist sets in Murnau's colour workspace', the measured −19% detail plug) could be trimmed without loss.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter tool with deeply nested payloads and no output schema, the description covers the listing return shape (clip_id, start/end, grade, input profile), preset interaction with `grade`, and every nested sub-structure. Nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema exposes `grade` as an opaque open object, so the description carries semantics the schema cannot: numeric ranges for exposure/contrast/hue, wheel structures for lift/gamma/gain/offset, log-wheel behavior per brightness range, HDR zone centres, curve domains, and the serial `schritte` limit of 8. The Color Warper coordinate math (node at (j/res, i/res), plane formulas) is genuinely beyond anything structured.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence names a specific verb and resource ('Set the colour grade of ONE clip in the edit'), and draws the clip-vs-programme scope boundary with `programm: true`. It does not differentiate itself from near-name siblings such as lab_grade, lab_grade_suggest, or lab_grade_from_resolve, so an agent must still infer which grading tool to pick.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Strong when-to-use cues: call without `grade` to list clips first, use `programm: true` for the whole programme, run lab_scopes before and after and pass its `vorschlag.grade` back in, and `sek: null` / `warper: null` to remove. The gap is that no alternative grading tools are named or excluded, so sibling selection is left unguided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Suggest a FilmLab grade look from a Resolve LUT name or path — read-only, no cost. First call resolve_node_graph_lesen on the local FilmLab bridge (filmlab_bruecke_mcp.py), a SEPARATE MCP server, and pass its lut field here. The agent connects these two calls: this Cloudflare Worker cannot reach the bridge at 127.0.0.1 on the user's computer or fetch the name itself. Only the name is matched; the Resolve LUT file is neither read nor imported, and its exact grade is not reproduced. Returns look, reason, alternatives and sicher (false means the name was not confidently recognised). Apply with lab_grade(look: …) only once the user agrees.
| Name | Required | Description | Default |
|---|---|---|---|
| lut | Yes | LUT name or path from the lut field returned by resolve_node_graph_lesen on the local FilmLab bridge |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation it discloses that the call is free, that the bridge is a separate server the Worker cannot reach, that only the name is matched and the LUT file is never read/imported, that the exact grade is not reproduced, and it enumerates the return fields including the 'sicher' confidence flag. This is far more than the annotation carries.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The key purpose and read-only nature are front-loaded, and most sentences carry distinct facts. There is mild redundancy in the explanation of why the Worker cannot reach the bridge, but it is dense and information-bearing rather than padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description fully compensates by listing the returned fields (look, reason, alternatives, sicher) and explaining the confidence semantics, plus the cross-server dependency and the apply step. An agent has everything needed to chain and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single documented parameter, so the baseline is 3. The description adds real meaning beyond the schema by clarifying that the lut value is only matched as a name (not read as a file), which changes how an agent should source and treat it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise verb+resource: 'Suggest a FilmLab grade look from a Resolve LUT name or path.' It clearly distinguishes itself from near-siblings (lab_grade, lab_grade_suggest, lab_look_match) by being the Resolve-LUT-name-driven suggester, and scopes exactly what input it consumes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit ordering: call resolve_node_graph_lesen first on the separate bridge, pass its lut field here, and only apply via lab_grade once the user agrees. It names the prerequisite tool, the alternative/next step, and the user-consent gate — nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Suggest a grade look for a project — read-only, no cost. With image_id, includes the image prompt; without it, uses only the colorist crew brief. Returns a recommended look name with a reason and alternatives; apply it with lab_grade(look: …) once the user agrees.
| Name | Required | Description | Default |
|---|---|---|---|
| image_id | No | Generated image id belonging to the project; includes its prompt in the suggestion | |
| project_id | Yes | Project id (from lab_list_projects) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes beyond the readOnlyHint annotation by declaring 'no cost' and describing the exact return payload (a recommended look name with a reason and alternatives). It also discloses the input-dependent behavioral difference (image prompt included only when image_id is passed), which the annotations do not cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact sentences, front-loaded with what the tool does and its cost profile, followed by the parameter conditional and the next-step handoff. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return-format burden and does so ('look name with a reason and alternatives'), and it covers cost, the parameter conditional, and the follow-up action. 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.
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 real semantic value: it explains that image_id pulls the image prompt into the suggestion, while omitting it falls back to the colorist crew brief. That is a behavioral consequence of the parameter, not just a restatement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('suggest a grade look for a project') and immediately distinguishes itself from the sibling that performs the mutation by naming lab_grade. An agent can tell this is the advisory/read step rather than the apply step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly frames the workflow: use this to get a recommendation, then 'apply it with lab_grade(look: …) once the user agrees.' It also states the branching condition (with image_id vs. without) that selects different behavior, leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Declare or list where a project's material comes from: 'eigen' (made by people) or 'ki' (AI-generated or AI-altered). Exports decide the EU AI Act Art. 50 disclosure per clip from this — undeclared material counts as AI. With asset_key + herkunft: declare (the file is checked for an AI mark; one found keeps it AI and the answer says why). With project_id only: list every declaration with its effect (wirksam). Rights class is returned as rechte_klasse (klasse + regelstand) on result rows: mitgebracht, generiert, abgeleitet or lizenziert; nicht_festgehalten means the old row has no recorded class. This is separate from eigen/ki (AI Act).
| Name | Required | Description | Default |
|---|---|---|---|
| herkunft | No | Required together with asset_key | |
| asset_key | No | Storage key of the file (from lab_add_media or lab_list_assets). Omit to list | |
| project_id | Yes | Project id — positive integer as string |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say the tool is not read-only and not destructive. The description adds substantial behavioral context: declaration checks the file for an AI mark, a found mark keeps the material classified as AI and returns the reason, and listing returns each declaration with its effect (`wirksam`). It also explains returned rights-class values and the `nicht_festgehalten` fallback.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but front-loaded: purpose first, mode behavior second, return semantics third. Each sentence carries operational information, including the AI-mark check and the rights-class return fields. There is no filler and the length is justified by the dual-mode behavior and lack of output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by explaining the return semantics: listing includes each declaration's effect and rights class details. It covers the declaration behavior, listing behavior, AI Act consequence, and the distinction from rights class. Nothing an agent needs in order to choose the correct mode is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description still adds meaning beyond the schema by explaining the combined semantics of `asset_key` + `herkunft` versus `project_id` only, and by describing what the declaration check does. The enum values are defined conceptually as human-made versus AI-generated or AI-altered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific resource and verb pair: declare or list where a project's material comes from. It clearly distinguishes the two operating modes (`asset_key` + `herkunft` for declaration, `project_id` only for listing) and explains the EU AI Act Art. 50 consequence. An agent can tell what the tool does 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit mode-selection rules: use `asset_key` + `herkunft` to declare, use `project_id` only to list. It also states the downstream effect that exports decide AI Act disclosure from this data and that undeclared material counts as AI. The distinction from rights class (`rechte_klasse`) is explicitly called out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether still images of a project show the SAME character as its character sheet — before paid clips are made from them. Each image is compared against the sheet's detail and fullbody views. It judges identity (species, build, colouring, head shape, large markings), NOT style, light, pose, place or props — and deliberately NOT micro details like an ear notch or the number of fingers, which no image model holds reliably. Free. Runs in the BACKGROUND: returns a job_id with HTTP 202 — poll it with lab_get_job until status is done|failed; the result lists per image passt, sicherheit, abweichungen, begruendung (or error). Up to 16 images and frames together per call. Images must be completed images of this project (imported images are refused). To check frames of a GENERATED CLIP (an orbit turnaround, a lab_animate clip) pass clip_frames: the clip's video_id and the seconds to cut out — the frames are taken from the clip itself and compared the same way; a second beyond the clip's end fails only that frame. The sheet needs a reference image (lab_generate_character_reference).
| Name | Required | Description | Default |
|---|---|---|---|
| image_ids | No | Completed image ids of this project (from lab_generate/lab_auto_storyboard) — positive integer strings, no duplicates. Give this and/or clip_frames. | |
| project_id | Yes | Project id (from lab_list_projects) — positive integer as string | |
| clip_frames | No | Frames cut out of generated clips; images and frames together at most 16. | |
| character_id | Yes | Character sheet id the images should show — positive integer as string |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
It goes far beyond simple input/output definition by disclosing critical operational behaviors. It informs the AI agent that this is a background process, requiring it to return a `job_id` with HTTP 202 status and that it must poll using `lab_get_job`.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but exceptionally efficient. Every sentence conveys a specific operational constraint, scope definition, or technical requirement, making maximum use of the space without unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complex workflow (asynchronous job creation, specific polling requirements, and conditional logic for static images vs. clip frames), the description provides all necessary context for an AI agent to use the tool correctly and handle its resulting lifecycle.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While the schema is 100% covered, the description adds crucial constraints not present in the schema. It specifies input requirements such as 'completed images of this project' and 'imported images are refused,' which are vital for correct parameter selection.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly defines the tool's purpose: checking if still images match the character sheet's identity. It distinguishes itself by specifically stating what it judges (identity: species, build, coloring) and, critically, what it deliberately ignores (style, light, micro details).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidelines for usage based on input type. It distinguishes between using `image_ids` for static images and using `clip_frames` (requiring `video_id` and `sekunden`) for generated clips, covering all invocation scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Are any FilmLab generations running RIGHT NOW, across ALL projects? Use this before anything that restarts the backend (a deploy recreates the container and kills running jobs, losing paid credits), or to answer 'is the lab busy?'. Unlike lab_job_status/lab_batch_status this needs no id — it lists every job in queued/processing PLUS every direct image/video/audio/vfx generation currently within its own grace window (lab_generate/lab_animate write straight to their result tables, never to the job queue — omitting job_type covers both; naming one job_type narrows to the job queue only, since a direct generation's type vocabulary differs). Returns {busy, warm[], stale_count, stale[]}: warm are jobs that actually progressed within stale_after_seconds and are the ones a restart would destroy; stale are queue jobs stuck longer than that (a crashed worker leaves rows in 'processing' forever) — they are reported but do NOT make busy true, otherwise one zombie would block every future deploy. A direct generation is never 'stale' here — past its own grace window it stops being reported by the backend entirely and becomes the orphan sweep's job, not this check's. Carries no prompts or payloads: this view crosses project boundaries, so it returns only type, state and age.
| Name | Required | Description | Default |
|---|---|---|---|
| job_type | No | Only this job type, e.g. 'video_generate', from the JOB QUEUE. Omit to see everything, including direct generations — for a pre-deploy check, omitting is usually right. | |
| stale_after_seconds | No | How long without progress before a job counts as a zombie rather than running. Default 1800, same threshold as the deploy guard in scripts/deploy_backend.sh. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=true, so the description carries most of the burden and does so well: it discloses that a restart destroys 'warm' jobs and loses paid credits, that 'stale' rows never flip busy to true (guarding against zombie-blocked deploys), and that direct generations are never stale. It omits only refresh/caching or rate-limit behavior, which is minor here.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core question and the deploy guidance are front-loaded, and each clause adds operational value. It is dense and long for a 0-required-param check tool, with the parenthetical about direct generations and grace windows slightly taxing to parse in one pass.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even without an output schema, the description enumerates the return shape ({busy, warm[], stale_count, stale[]}) and explains the semantics of each field, plus why no prompts/payloads are returned due to cross-project visibility. An agent has everything needed to call and interpret it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 real meaning beyond the schema: why naming a job_type filters to the queue only (direct-generation type vocabulary differs) and what omitting it yields. The stale_after_seconds semantics are largely mirrored from the schema, so it is not a full 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific, answerable question ('Are any FilmLab generations running RIGHT NOW, across ALL projects?') that names the resource, the scope, and the temporal condition. It explicitly distinguishes itself from lab_job_status/lab_batch_status by noting it needs no id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use ('before anything that restarts the backend', 'to answer is the lab busy?') and names the alternatives it supersedes. Also states the job_type narrowing condition and when omitting is the right call, so invocation intent is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Poll the status of an image or video generation started by lab_generate/lab_animate. There is no single-item status endpoint on the backend — this fetches the project's full image/video list and filters by id, so it needs BOTH project_id and id (the id alone is not enough). status inside the returned item's metadata is 'pending'|'completed'|'failed'; when completed, image_url/video_url is populated. While a run is not done, the answer carries naechste_abfrage_s — wait that long before the next call instead of polling in quick succession; spaetestens_s (video) is the point after which the backend gives up and refunds. When the run is done, the answer may additionally carry schritte (the step trail of this run) and review (a machine check against the confirmed brief, present once for a run that went through lab_propose/lab_run_proposal — absent for a still-pending run, a run started outside a proposal, or a repeat poll after the one-time check already ran): abweichung lists every field that came back different from what was confirmed, possibly empty; tool means the provider fallback chain degraded the run; bild means a vision check found the result contradicting an explicit statement of the brief (free for the user, once per run; bild_review says why it was skipped). A failed or degraded proposal run may also carry plan_b: alternatives with checked prices and proposal IDs, offered once. Present them to the human; never start them yourself. Call lab_run_proposal only after the human confirms an alternative.For a run that carried a kamerapfad, metadata.kamerapfad says what arrived and, as angewandt, WHICH form of it was actually sent — als_text (prose), als_regiebefehle (bracketed director commands, MiniMax/Hailuo), eigene_regie (the prompt already carried bracketed commands, so the path was deliberately NOT added next to them — eigene_regiebefehle lists them) or nicht_ableitbar (nothing of the path reached the prompt, with the reason). sprache next to it names the family rule and the source it rests on. For a reference-motion run, metadata.referenz_masse is the reference trail: one row per reference with what it measured (original_px) and, if the backend had to scale it to the model's limits, what it became (angepasst_px) and the address that was actually sent. Look there when a result ignores a reference or looks softer than the source — a silently rescaled reference looks like a badly generated one. Rights class is returned as rechte_klasse (klasse + regelstand) on result rows: mitgebracht, generiert, abgeleitet or lizenziert; nicht_festgehalten means the old row has no recorded class. This is separate from eigen/ki (AI Act).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The id returned by lab_generate (image) or lab_animate (video) | |
| type | Yes | Whether the id refers to a generated image or a generated video | |
| wait_s | No | Wait up to this many seconds (max 80) until the result is rendered AND its prompt check (abgleich) is in, or it failed — instead of polling in quick succession. The answer says gewartet_s. tool_id is the catalog id even after tool_used switched to the display label. | |
| preview | No | Attach the image itself, downscaled to 512px, so it can be LOOKED at instead of described. Costs one extra fetch and adds roughly 15-25 KB to the answer. Videos carry no still and return no picture — that needs a contact sheet, which is not built yet. Without this flag the answer is unchanged. | |
| project_id | Yes | Project id — required, since there is no global id lookup |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations only declare readOnlyHint=true, but the description adds substantial behavioral context beyond that: why both project_id and id are required, how status values behave, the meaning of naechste_abfrage_s and spaetestens_s, the one-time nature of review, plan_b human-confirmation rules, and metadata details for kamerapfad, references, and rights class. No behavior contradicts the read-only annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and polling mechanics, but it becomes very long and dense, with multiple run-on clauses covering review, plan_b, kamerapfad, reference measurements, and rights class. Most details are useful, but the structure could be tighter and easier to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and only a readOnlyHint annotation, the description carries the return-value burden and does so extensively. It explains status values, completion URLs, polling delays, review fields, plan_b behavior, kamerapfad metadata, reference scaling, and rights class, which is enough for an agent to interpret the likely response without a formal output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, so the schema carries most parameter detail. The description still adds meaningful semantics by explaining that the backend has no single-item status endpoint and therefore both project_id and id are required, with id alone insufficient. It does not add much about type, wait_s, or preview beyond what the schema already says.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource: polling the status of an image or video generation started by lab_generate/lab_animate. It also explains the backend limitation that forces filtering the project list. It does not explicitly distinguish this from sibling status tools such as lab_get_job, lab_batch_status, or lab_vfx_status, so it falls short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is clear: call this after starting a generation via lab_generate or lab_animate, and use the returned next-poll delay rather than polling quickly. It also gives a strong rule for plan_b alternatives: present them to the human and never start them yourself, then call lab_run_proposal only after confirmation. It does not explicitly say when to prefer another status-like sibling tool, 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.
Produce ONE element on a transparent background: generated, then cut out and stored as an alpha PNG in the project's gallery. This is the counter-move to the one-shot lottery — cast, props and foreground pieces are made SEPARATELY, arranged as a set afterwards and only then unified, so a wrong hand or a wrong lamp is re-made alone instead of re-rolling the whole frame. The element is deliberately optics-neutral: no lens or camera suffix travels with it, because the look is decided later on the finished comp and every layer is meant to inherit the same focal length and bokeh. ASYNCHRONOUS: the row comes back with status pending and image_url null; poll lab_job_status (type 'image') with its id until the url is populated — that url IS the cut-out. Costs credits when called without get_cost.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | What the element shows — the OBJECT or the PERSON, not the scene around them. The backend appends an isolation clause (single subject, plain seamless background, even light) so the cut-out has a clean edge; describing a set as well fights that clause and produces an element that cannot be freed. | |
| get_cost | No | Preflight: return the price in credits and your balance WITHOUT generating and without spending anything. There is no model to pick on this path — the cut-out runs on the house image model and is billed at the plain image rate, so lab_list_models has no entry that would change this number; it comes from the same cost endpoint as everywhere else. | |
| metadata | No | Free-form JSON stored alongside the element (e.g. { note, parent_id }). Merged into the row's metadata next to the fields the pipeline sets itself (kind, layer_type, status) — not interpreted. | |
| scene_ref | No | Scene label (e.g. 'SZ 04'). Stored on the row, so the element can be matched back to a shot list and reviewed per scene with lab_review_queue. Omit it and the element is an orphan in the gallery. | |
| layer_type | No | Which kind of element this is — it picks the isolation clause: 'cast' full-body person, 'prop' single object, 'foreground' a foreground piece, 'background' a wide backdrop plate WITHOUT people, 'crowd' one background performer head to feet. 'stage' is accepted by the backend but has no clause of its own and falls back to the generic one. Omit for the backend default ('prop'). | |
| project_id | Yes | Project id (from lab_list_projects) — positive integer as string. Travels in the URL; the element is filed in this project's gallery. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say it is a non-read-only, non-destructive tool. The description goes far beyond that: it reveals the async behavior (row returns status pending and image_url null), the credit cost when called without get_cost, the deliberate optics-neutrality (no lens/camera suffix), and the isolation clause appended to the prompt. That is rich context the annotations do not carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core operation, then the rationale for separate layers, then the async contract, then cost. Every sentence adds a distinct behavioral fact (transparency background, per-element re-make, optics-neutral, pending/null, poll url, credit cost). No padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description fully covers the return contract (pending row, null image_url, populated url is the cut-out), the cost behavior, the async polling path, and the purpose of scene_ref/layer_type in routing to isola clauses. Nothing an agent needs to invoke and follow through is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, so the schema documents every parameter in detail. The description does emphasize the key constraint (prompt is the object/person, not the scene; describing a set fights the isolation clause) and mentions layer_type selection, but most parameter details are already in the schema — baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the exact artifact (ONE element on a transparent background, generated, cut out, stored as an alpha PNG in the project gallery) and distinguishes the counter-move from the one-shot lottery — cast, props and foreground pieces are made separately. It also clarifies that this is the per-element generator, not the whole-frame generator like lab_generate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells the agent when to use this vs. the alternative (re-rolling the whole frame), and gives operational routing for the async path: poll lab_job_status (type 'image') with its id until the url is populated. It also notes that get_cost must be set to avoid spending credits.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract the LAST frame of a finished clip as a new image (returns image_id, image_url, zu_dunkel). Use it as source_image_id to continue one unbroken take, or as a still. A frame that is too dark (zu_dunkel: true) makes a bad start image — say so instead of animating from black. Free (no credits). Chains (lab_verkettung) do this themselves for uebergang=durchgehend.
| Name | Required | Description | Default |
|---|---|---|---|
| video_id | Yes | A finished clip (positive integer as string) | |
| scene_ref | No | Scene for the new image; default: the clip's |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds real context beyond annotations: it is free (no credits) and returns image_id, image_url, and zu_dunkel. The zu_dunkel warning tells the agent to avoid animating from a black frame, which is behavioral guidance not present in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, front-loaded with purpose, then usage, then a caveat, then the free-cost note. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, return fields, cost, and a key failure mode (too dark). With only 2 params and 100% schema coverage, this is nearly complete; a brief note on whether the source clip must be finished/exported might help, but it is strongly implied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents video_id and scene_ref. The description adds no syntax or format detail for the parameters beyond what the schema provides. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Extract the LAST frame of a finished clip as a new image') and names the output fields. Distinguishes itself from siblings like lab_render_frames by emphasizing the last frame specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use it ('continue one unbroken take, or as a still') and names the alternative path (lab_verkettung) that handles this automatically for uebergang=durchgehend, so the agent knows when NOT to call it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a project's media assets (image/video/audio) with their URLs. Optionally filter by asset_type. Returns up to 20 with a total count. Each row carries its address as url (with type and key). Project assets come back as SIGNED addresses on https://thefilmradar.com/api/lab/assets/abruf/… — valid for 24 h, loadable without a session and with any User-Agent. Only older rows may still point at media.andresmarder.com, whose CDN WAF answers some non-browser User-Agents (e.g. curl's default) with 403 — prefer a browser UA there, or hand the URL to the user.
| Name | Required | Description | Default |
|---|---|---|---|
| preview | No | Attach the pictures themselves, downscaled to 512px, so you can look at them without fetching anything (older media.andresmarder.com addresses answer a non-browser User-Agent with 403). The worker fetches with a browser UA. At most 4 per call; audio and video rows carry no picture and are named in preview.notes. | |
| asset_type | No | Filter by asset type (optional) | |
| project_id | Yes | Project id (from lab_list_projects) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=true, so the description carries the rest and does so richly: a 20-row cap with total count, rows carrying url/type/key, signed addresses valid for 24 h that load without a session and with any User-Agent, and a documented 403 WAF behavior on legacy media.andresmarder.com for non-browser UAs. This is exactly the operational context an agent needs before calling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose and return shape before the URL/WAF caveats, and each sentence carries real information rather than filler. It is slightly dense and the URL-signing detail spreads across several clauses, but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by specifying the return shape (up to 20 rows, total count, url/type/key fields) and the lifetime and loadability of returned addresses. Combined with the schema's preview documentation, an agent has everything needed to call and consume the result correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema itself covers project_id, asset_type's enum, and preview's 512px/4-per-call behavior in detail. The description only restates the optional asset_type filter, adding nothing beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List a project's media assets (image/video/audio) with their URLs') and scopes it to a single project, which is more precise than the title alone. It does not, however, set itself apart from nearby siblings such as lab_list_audio or lab_bilder, which an agent may confuse with this one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It tells the agent the asset_type filter is optional and gives practical routing advice (fetch with a browser UA, or hand the URL to the user) for older rows. What is missing is any statement of when to reach for this tool versus lab_list_audio/lab_bilder or when not to use it, so usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a project's generated audio rows, newest first — this is the POLL for lab_generate_music. Read two fields: metadata.status ('pending' | 'completed' | 'failed') and audio_url. A pending row has no url, and nothing downstream works with it: lab_bind_audio silently leaves the track empty (resolve-stems only takes rows that carry a url) and lab_beatgrid has no file to open. A failed row carries metadata.error and its credits were refunded. Reads only — no state changes, no credits.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many rows to FETCH from the backend (default 50). At most 20 are SHOWN; `total` is what the fetch found, so a total of exactly `limit` means there may be more | |
| scene_ref | No | Filter by the scene label passed at generation time | |
| audio_type | No | Filter by kind. Pass 'music' when polling a lab_generate_music call — that is the kind the music track binds. The repair kinds (denoise, split, isolation) come from lab_sfx and hold cleaned-up versions of recordings you already had; a 'split' run leaves one row per stem, each naming its part | |
| project_id | Yes | Project id (from lab_list_projects) — positive integer as string |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation it discloses the exact fields to read (metadata.status, audio_url), the meaning of each status, that failed rows carry metadata.error and had credits refunded, and that reads cost no credits. This is rich operational context an agent cannot get from the annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and the polling role are front-loaded, and every sentence carries distinct information (status semantics, downstream impact, no-credit behavior). The downstream tool chain detail is useful but makes it longer than strictly necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description steps in to name the return fields and their states, and annotations cover the safety profile. An agent has everything needed to call and interpret the result correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all four parameters are already documented in the schema, including the fetch-vs-shown limit nuance and the audio_type guidance. The description focuses on output fields rather than adding parameter meaning, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (List) and resource (a project's generated audio rows) plus ordering (newest first). It further distinguishes itself by declaring it is 'the POLL for lab_generate_music,' so an agent can identify its role among the many lab_list_* siblings without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly frames the tool as the polling step for lab_generate_music and explains the consequences of pending/failed rows, which tells the agent when to call it. It does not spell out a when-not or a competing alternative list tool, so it stops short of the top tier.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the character sheets in the FilmLab cast register (id, name, age, gender, project_name, prompt_prefix_en). Call this BEFORE lab_generate whenever a person must look the same across several images: pass the id you find here as character_refs instead of re-describing the person in every prompt. Optional search matches name or project name (substring, case-insensitive). It shows YOUR OWN characters plus the public catalog (sheets explicitly made public and bound to no project). Characters of other accounts' projects never appear — projects can be confidential. New characters are private. The register returns at most 50 sheets, newest first, and offers NO paging — 20 are shown here. total therefore counts at most 50: with more than 50 sheets it understates, and search is the only way to reach the older ones. Nobody there yet? Create a sheet with lab_create_character.
| Name | Required | Description | Default |
|---|---|---|---|
| search | No | Substring of the character name or project name (case-insensitive) | |
| preview | No | Attach each sheet's reference portrait, downscaled to 512px. A cast list read as text is a list of names; seen as faces it is a cast. At most 4 per call. A sheet WITHOUT a reference image shows none — and that is the same emptiness lab_generate rejects, so an absent picture here is a finding, not a glitch. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint already covering safety, the description adds substantial non-obvious behavior: visibility scope (own characters plus public catalog; other accounts' projects never appear, projects can be confidential; new characters are private), result limits (max 50, newest first, no paging, 20 shown, total understates), and that search is the only route to older sheets.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with what the tool does and when to call it, then layers limits, privacy scope, and the fallback alternative. Dense but every sentence carries information; slightly long for a two-parameter read tool, keeping it just below the top mark.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must carry the return contract, and it does: it lists returned fields, the 50-sheet ceiling, newest-first ordering, no paging, and why total can understate. Nothing needed to call or interpret the result is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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; both the search semantics (substring, case-insensitive) and the preview constraints are already documented in the schema. The description restates that search is optional and is the only way to reach older sheets, which is context rather than new parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (list character sheets in the FilmLab cast register) and enumerates the returned fields (id, name, age, gender, project_name, prompt_prefix_en). This is easily distinguished from siblings like lab_get_character, lab_get_character_sheet, and lab_create_character.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit trigger: 'Call this BEFORE lab_generate whenever a person must look the same across several images', and explains the mechanism (pass the id as character_refs instead of re-describing). It also names the alternative for the empty case ('Nobody there yet? Create a sheet with lab_create_character').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List past export jobs for a project (each with job_id, status, profile). Returns up to 20 with a total count. Finished rows carry the same signed, login-free result addresses as lab_get_export (download_url, herkunft.pdf_url, …; valid 24 h).
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project id (from lab_list_projects) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already establishes the safe-read profile, so the description adds real value beyond annotations: a 20-row cap with a total count, the field shape of each row, and the fact that result URLs are signed, login-free, and expire after 24 h. It stops short of describing pagination/offset mechanics for retrieving beyond 20 rows.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the core action and scope before the detail about counts and URL validity. Dense but every clause carries information; the parenthetical ellipsis '(download_url, herkunft.pdf_url, …)' is slightly loose but harmless.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return-value burden and does so well: it enumerates row fields, states the result cap and total count, and explains URL validity and auth-free access. Nothing an agent needs to call or interpret this tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single project_id parameter is fully documented in the schema itself (including 'from lab_list_projects'), so the description's 'for a project' adds no syntax or format detail. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List past export jobs for a project') plus the scope of the returned rows (job_id, status, profile). It also names the sibling lab_get_export, so an agent can separate the list operation from the single-export fetch 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (listing historical export jobs for a project) and contrasts implicitly with lab_get_export by saying rows carry 'the same' addresses, but it never states when to prefer this over lab_get_export or lab_export_profiles, nor any exclusions. Usage is inferable rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List location boards, newest first — START HERE to find a location_id for lab_generate / lab_animate. Each entry carries its prompt_prefix_en: that is the exact text appended to your prompt as 'Location: …', so you can judge whether the board fits BEFORE spending quota. A board with an EMPTY prefix anchors nothing — it will silently do nothing. Fix it with lab_enrich_location_prefix or pick another board. Only public boards are returned, max 50 from the backend and 20 shown here; if your place is not listed that is a limit, not a failure — create it with lab_create_location.
| Name | Required | Description | Default |
|---|---|---|---|
| search | No | Filter by board name or project name (substring, case-insensitive) | |
| preview | No | Attach each board's reference picture, downscaled to 512px. A location board is a PLACE — its prefix text says what was written down, the picture says what the board actually anchors, and those two disagree more often than the text admits. At most 4 per call; narrow with `search` rather than expecting more. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=true, but the description adds substantial non-obvious behavior: only public boards are returned, a backend cap of 50 with 20 shown, that an empty prompt_prefix_en is a silent no-op, and that previewing avoids spending quota. These are exactly the traits annotations cannot carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the essential 'START HERE' routing before the caveats, and every sentence carries actionable information. It is dense and slightly long, but no sentence is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description fills the gap by describing what an entry contains (location_id, prompt_prefix_en), the result limits, and the two remediation paths. Nothing needed to call or interpret the tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters are already documented. The description nonetheless adds meaning beyond the schema by explaining why prompt_prefix_en matters (the exact 'Location: …' text appended) and why the preview picture can contradict the prefix text, motivating the `preview` flag.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('List location boards') plus ordering ('newest first') and immediately positions itself as the entry point for obtaining a location_id used by lab_generate/lab_animate. It is clearly distinguishable from siblings like lab_get_location, lab_list_project_locations, and lab_create_location.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'START HERE', explains the downstream use (feeding lab_generate/lab_animate), and names concrete alternatives for the two failure paths: lab_enrich_location_prefix for an empty prefix and lab_create_location when a place is missing. The agent is told what to do in each branch.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a project's location scans with their reconstruction state — this is the POLL for lab_location_recon and the place the scan ids come from. Read status: 'pending' (clip uploaded, nothing reconstructed yet), 'reconstructing', 'done' (splat_url/glb_url/board_url are filled), 'failed' (error says why). Listing is what ADVANCES a running reconstruction from the outside world into the row, so calling this is how the state moves at all. Reads only — no credits.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project id (from lab_list_projects) — positive integer as string |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered; the description goes further by disclosing the non-obvious trait that listing ADVANCES a running reconstruction, plus the credit cost and the meaning of each status value. It stops short of describing pagination or ordering behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core purpose and poll role, then enumerates status values compactly. Slightly dense with parentheticals, but every sentence carries distinct information and none is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully covers the return surface: status values, the URLs that get filled on 'done', and where failure reasons appear. It leaves the row's remaining fields and ordering unpinned, but is sufficient to call and interpret the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single project_id parameter is fully documented in the schema itself. The description implies project scoping but adds no format or sourcing detail beyond the schema's 'positive integer as string' note.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (List) and resource (a project's location scans) and immediately frames the tool's role — the poll for lab_location_recon and the source of scan ids — which distinguishes it from siblings like lab_list_locations or lab_get_location.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names the alternative relationship ('this is the POLL for lab_location_recon and the place the scan ids come from'), so an agent knows both when to call it and where the ids it needs originate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The model catalog: what every video or image model can do — resolutions, durations, aspect ratios, audio, reference limits, price per second or per image — grouped by capability class with a one-line explanation per group. Read this before choosing a tool for lab_generate/lab_animate/lab_propose; copy ids verbatim. Cached briefly; stand says how fresh. Without klasse the answer is COMPACT (one line per model, cheapest first, plus klassen with every valid class name): fields that are null, false or empty are left out, and a model that also belongs to another class shows there only as a short stub whose wie_in names the class holding its full entry. form: knapp means the catalog was too large for one answer — set klasse for the details. With klasse or voll: true every field. Filter to answer the usual question directly: aufloesung, dauer_s, ton (ohne = models that can run silent, including switchable audio). A model with switchable audio is listed under the class with AND without sound (i2v_ton and i2v).
| Name | Required | Description | Default |
|---|---|---|---|
| eu | No | Only models allowed in EU mode projects (data stays inside the EU data path). Every model carries `eu_modus` and, where false, `eu_grund` — the first missing proof (`form: knapp` carries only `eu_modus`) | |
| ton | No | ohne = can run without sound (audio nie or schaltbar); mit = can make sound | |
| kind | Yes | Which catalog | |
| voll | No | Every field of every model even without klasse — large, use a filter with it | |
| klasse | No | Only one capability class — the valid names are listed under `klassen` in every answer | |
| dauer_s | No | Only models that can render this duration in seconds | |
| aufloesung | No | Only models offering this resolution, e.g. 540p |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint, and the description adds substantial behavioral context: brief caching with `stand` freshness, compact default output, omission of null/false/empty fields, truncation via `form: knapp`, and stub entries for models belonging to multiple classes. It also explains that switchable-audio models appear under the class both with and without sound. This is rich disclosure beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and usage, and every part carries useful information for a complex catalog tool. However, it is a dense paragraph with nested clauses and German field names, making it harder to scan than ideal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the full burden of explaining return shape and behavior, and it does so thoroughly: compact vs full output, `klassen`, `stand`, truncation, stubs, null omission, and filter behavior. It is complete enough for an agent to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents parameters, but the description adds important semantics beyond it: omitting `klasse` returns a compact catalog, `voll: true` returns every field, `ton: ohne` includes silent and switchable-audio models, and switchable-audio models are listed in two class views. It meaningfully supplements the schema rather than repeating it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific resource and verb: it is the model catalog describing what video/image models can do, including capabilities and pricing. It clearly distinguishes itself as the catalog to read before choosing generation tools, so an agent can tell it apart from siblings like lab_generate or lab_search_catalog.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says to read this before choosing a `tool` for lab_generate/lab_animate/lab_propose and to copy ids verbatim, which is strong usage guidance. It also explains how filters answer common questions directly, but it does not name an explicit alternative or when-not-to-use condition, so it falls 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.
Location boards bound to ONE project. Narrower and more correct than lab_list_locations when you already know the project: it cannot leak boards from a different project with the same title. Boards created before the project binding existed (project_id NULL) deliberately do NOT appear here — use lab_list_locations for those.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project id (from lab_list_projects) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond that: it explains the project-scoped filtering guarantee and, crucially, that pre-binding boards (project_id NULL) are deliberately excluded. No contradiction; it enriches the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tightly packed sentences, zero filler. The scoping guarantee is front-loaded, followed by the fallback guidance. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-param, read-only list tool with no output schema, the description covers the scope guarantee, the exclusion edge case, and the alternative. 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.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the project_id parameter including its source tool. The description's mention of the binding adds behavioral meaning but doesn't expand on parameter syntax. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Location boards bound to ONE project') and explicitly differentiates from sibling lab_list_locations by naming the alternative and its use case. An agent can immediately tell which tool to pick.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'when to use' is given: use this when you already know the project. The fallback case (NULL project_id / pre-binding boards) is also routed to lab_list_locations, leaving nothing ambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List FilmLab projects (id, title, current pipeline stage). Call this first to find a project_id for the other tools. Shows up to 20 items; total counts your active projects (up to 200) and truncated: true means the list is cut off — sorted by last change, so older projects drop out of the shown window first.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond readOnlyHint=true, the description discloses concrete behavioral traits: a 20-item display window, a `total` that counts up to 200 active projects, a `truncated: true` signal, and the sort order (last change) with the consequence that older projects drop out first. This is exactly the kind of pagination/truncation context annotations cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A compact three-sentence block that front-loads purpose, then routing advice, then the pagination caveat. Every clause carries information; nothing restates the name or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates fully by naming the returned fields, the truncation flag, the item cap, and the ordering rule. An agent knows what it will get back and how to interpret a cut-off list.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing to disambiguate and the baseline for a no-param tool is 4. The description correctly focuses entirely on output semantics rather than inventing parameter guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List FilmLab projects') and names the fields returned (id, title, current pipeline stage). This clearly distinguishes it from the single-project sibling lab_get_project and the other lab_list_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit workflow guidance: 'Call this first to find a project_id for the other tools,' which tells the agent both when to invoke it and what it feeds into. No exclusions are stated, but the routing intent is unambiguous, so an agent can place it correctly in a sequence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the props (Requisiten) of this project, including @prop_ tags, descriptions and generated views. Free. Use the tags in image and video prompts: the description always goes into the prompt, the front view goes along as a reference image in lab_generate and lab_reference_motion.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project id, positive integer as string |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already covers the safety profile, but the description adds that the call is free and specifies the returned contents including generated views. It does not discuss pagination or response formatting, but the added cost and content disclosure is meaningful beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded: it states what is listed, notes that it is free, then explains the practical use of the returned tags. Every sentence contributes useful information without repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with one fully documented parameter, no output schema, and readOnlyHint annotations, the description is complete enough. It covers what is returned and how the output is intended to be used downstream.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one parameter, project_id, and the schema description coverage is 100%, so the schema already documents its meaning and format. The description implies project scoping but adds no syntax or format details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: list the props of this project. It also names the included fields (@prop_ tags, descriptions, generated views), which distinguishes it from sibling list tools such as lab_list_characters or lab_list_locations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains how the returned tags are used in image and video prompts, including lab_generate and lab_reference_motion, which gives useful downstream context. However, it does not explicitly say when to choose this tool versus related tools like lab_prop_ansichten or lab_create_prop.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a project's sequences: the main sequence (the film, ist_haupt: true, also in haupt_sequenz_id) first, then newest first. Trailers, opening titles and blocks are sequences too — edit the main sequence unless the person names another. Use it to find a seq_id instead of creating a second sequence for the same cut.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project id (from lab_list_projects) — positive integer as string |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true), yet the description adds real behavioral detail: return ordering (main sequence first, then newest-first) and the field names that encode that ordering (ist_haupt, haupt_sequenz_id). It also warns that trailers, titles and blocks are sequences too, which prevents a false assumption about what appears in the list.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences: purpose plus ordering first, then the 'what counts as a sequence' caveat, then the usage rule. No filler, though the density of domain terms (ist_haupt, haupt_sequenz_id) makes it slightly dense on first read.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully describes the return shape's ordering and key fields and clarifies the non-obvious inclusion of trailers/titles/blocks. Nothing critical is missing for a single-parameter read tool, though it could hint at whether the list is paginated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one parameter, project_id, and schema description coverage is 100% including its origin (lab_list_projects) and type. The description adds no extra semantics about that parameter, so the schema is doing all the work and baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List a project's sequences') and immediately qualifies the scope by enumerating what counts as a sequence (main sequence, trailers, opening titles, blocks). It separates itself from lab_create_sequence by explicitly framing the call as a way to obtain a seq_id rather than mint a duplicate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states a positive use case ('find a seq_id instead of creating a second sequence for the same cut') and names the alternative it replaces. It also gives a decision rule for downstream editing: work on the main sequence unless the person names another.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the style kits of this project (rules, palette, up to three reference images, @stil_ tag) and which one is the project default (standard_id). Free. Write the tag into an image or video prompt to use that kit for this one call instead of the default.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project id, positive integer as string |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes the safety profile, and the description adds useful behavioral context: the call is free, the result includes kit contents and the default standard_id, and the tag can be used in a prompt to override the default. It does not discuss pagination or error behavior, but it adds meaningful context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main action and scope, then adds the kit contents, default behavior, and tag usage in compact form. Every sentence contributes useful information without unnecessary repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with one fully documented parameter and annotations covering safety, this description is complete enough. It explains what is returned and how the returned tag can be used, compensating for the absence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single project_id parameter, so the schema already provides the necessary parameter semantics. The description only indirectly reinforces this by saying 'of this project,' without adding format or constraint details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource: list the style kits of this project. It also explains what a style kit contains and which one is the project default, though it does not explicitly distinguish itself from siblings such as lab_create_stil_kit or lab_stil_kit_standard.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies usage by saying to write the returned @stil_ tag into an image or video prompt to override the default for one call, and notes that the operation is free. However, it does not explicitly say when to choose this tool over lab_create_stil_kit or lab_stil_kit_standard.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a project's cloned voices (lab_voice_clone results) — id, label, voice house, sample and preview URLs. This is where a voice_id for lab_voice_tts or lab_dub comes from, and where you look up which house a voice belongs to before pricing it. Both houses are listed unless you narrow it. Reads only — no state changes, no credits.
| Name | Required | Description | Default |
|---|---|---|---|
| provider | No | Narrow the list to one voice house. Omit it and both come back, which is the normal case — a project can hold voices from either. An unknown value is refused rather than answered with an empty list: 'none found' and 'no such house' are different answers. What the houses can do: lab_list_models. | |
| project_id | Yes | Project id (from lab_list_projects) — positive integer as string |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover readOnlyHint=true, and the description corroborates and extends it with 'Reads only — no state changes, no credits,' which adds the credit-cost signal annotations cannot express. It does not mention pagination or result caps, which for a list tool is the main remaining unknown.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the verb and resource, and the return fields, routing hint, and safety note each carry distinct information in roughly three sentences. The one redundant clause is 'Both houses are listed unless you narrow it,' which largely restates the provider schema description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return shape (id, label, voice house, sample and preview URLs), the default filtering behavior, and the read-only/credit posture — everything an agent needs to call and consume this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the enum is fully documented, so the baseline is 3. The description still adds value by framing provider as 'voice house' with a business purpose ('before pricing it') and by restating the default both-houses behavior, which ties the parameter to the workflow rather than just its type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List a project's cloned voices') and immediately scopes it by naming the producing tool (lab_voice_clone results), which cleanly separates it from the sibling lab_dub_voices. It also enumerates the returned fields, so the agent knows exactly what this list yields 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to reach for it ('This is where a voice_id for lab_voice_tts or lab_dub comes from') and the pre-pricing house lookup use case, which is real routing guidance. It does not distinguish itself from the closely-named lab_dub_voices sibling, so the alternative selection is not fully closed out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Decline an offered license addressed to your account. Free.
| Name | Required | Description | Default |
|---|---|---|---|
| lizenz_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a non-read-only, non-destructive mutation. The description adds the useful precondition that the license must be offered to your account and notes that the action is free, but it does not explain reversibility, whether the license can be re-offered, or what errors may occur.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences with the action and scope front-loaded. The pricing note is brief and potentially useful, and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter mutation without an output schema, the description covers the basic action and precondition. However, it leaves out the post-decline state and does not compensate for the undocumented parameter, so it is only minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is one required parameter, lizenz_id, whose schema gives only type and UUID format with 0% description coverage. The description does not identify the parameter or explain that it must refer to an offered license, so it does not compensate for the missing schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: decline an offered license. It also scopes the action to licenses addressed to the caller's account, which helps distinguish it from generic license operations, but it does not explicitly point to the sibling accept/offer tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended context is implied: use this when an offered license has been addressed to your account and should be declined. There is no explicit guidance on when not to use it, nor is a specific alternative such as lab_lizenz_annehmen named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Offer a license for your own asset or an asset of a studio you can edit. The recipient must be an existing account. No charge until the recipient accepts. On acceptance, the owner receives floor(80% of the price) as non-expiring, spend-only credits; the platform retains the remainder (20% commission). Revocation refunds remaining inclusive days for fixed terms, or the full price through day 14 after acceptance for unlimited terms, then zero. No marketplace or catalog.
| Name | Required | Description | Default |
|---|---|---|---|
| gebiet | Yes | ||
| endet_am | No | ||
| local_id | Yes | ||
| beginnt_am | Yes | ||
| nutzungsart | Yes | ||
| plattformen | No | ||
| preis_credits | Yes | ||
| lokale_tabelle | Yes | ||
| lizenznehmer_email | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the full financial and lifecycle behavior beyond the sparse annotations: no charge until acceptance, 80/20 split paid as non-expiring spend-only credits, and a detailed revocation refund schedule (remaining inclusive days for fixed terms, full price through day 14 for unlimited terms, then zero). For a mutation tool with minimal annotations, this is exactly the kind of consequence disclosure the description must carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads what is being offered, then preconditions, then payment, then revocation, then exclusion – no filler sentences and each clause adds a distinct fact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The behavioral side is unusually complete for a write tool with no output schema, but with 9 undocumented parameters and zero schema description coverage, an agent still lacks the field-level guidance (formats, enum meanings, allowed date ranges) needed to construct a valid call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% across 9 parameters, so the description must compensate – and largely does not. It only indirectly touches preis_credits, endet_am (fixed vs unlimited terms), and lizenznehmer_email; nothing explains lokale_tabelle's enum values, local_id, nutzungsart, gebiet, beginnt_am, or plattformen.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Offer a license for your own asset or an asset of a studio you can edit') and distinguishes it from the sibling lifecycle tools (annehmen, ablehnen, widerrufen). An agent can tell immediately this creates an offer, not accepts or revokes one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete preconditions ('recipient must be an existing account', asset must be yours or a studio you can edit) and an explicit exclusion ('No marketplace or catalog'), which routes agents away from catalog-style paths. It stops short of naming when to use this versus lab_lizenz_annehmen or lab_lizenz_ablehnen, but the offer/accept split is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Accept a license addressed to your own account (studio: owner account). First call get_cost:true, show the exact credits, and obtain confirmation before accepting. Acceptance spends credits through the platform and creates a private PDF certificate. The owner receives floor(80%); the platform retains the remainder. Credits cannot be withdrawn. Show the refund rule before confirmation: fixed term refunds remaining inclusive days, unlimited term refunds fully through day 14 after acceptance, then zero. A zero-price license is free.
| Name | Required | Description | Default |
|---|---|---|---|
| get_cost | No | Return price without accepting or charging | |
| lizenz_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: discloses that credits are spent, that a private PDF certificate is created, the 80/20 revenue split, that credits cannot be withdrawn, and the full term-dependent refund schedule. One tension: destructiveHint=false while acceptance irreversibly consumes credits after day 14, though this is a financial rather than data-destructive operation, so it is not a contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the purpose, then ordered as workflow, then economics, then refund policy. Dense but nearly every sentence carries decision-relevant information; the prescriptive 'show X before confirming' phrasing is user-interface policy rather than tool behavior, which is slightly off-purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description still explains what happens after a successful call (credits spent, certificate created) and what the caller must verify first. Missing only failure modes, idempotency (calling twice), and explicit permission requirements beyond the 'studio: owner account' hint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50%, and lizenz_id has no description in the schema; the description partially compensates by telling the agent to call with get_cost:true first and by implying the license must belong to the caller's own account. It still says nothing about the lizenz_id format or provenance (e.g. where to obtain it, from lab_lizenzen).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Accept a license'), plus a scope qualifier ('addressed to your own account (studio: owner account)'). An agent can distinguish it from the decline/offer siblings, though those alternatives are never named explicitly, so differentiation is implied rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a concrete pre-call workflow: 'First call get_cost:true, show the exact credits, and obtain confirmation before accepting,' and explains the zero-price case. It does not name when to use lab_lizenz_ablehnen or the widerruf siblings instead, so the when-not/alternative dimension is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List received and offered asset licenses with their status in the current workspace. Free.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already declares the safe-read profile, so the description's burden is lighter. It does add genuinely non-structured facts — the read covers both received and offered licenses, includes status, is limited to the current workspace, and is 'Free' (no credit cost). It stops short of describing result shape, ordering or pagination.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with the scope and coverage front-loaded and no filler. The trailing 'Free.' fragment is efficient but slightly opaque out of context (cost vs. license-type ambiguity).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless, read-only listing with no output schema, the description covers what is listed, in what state, and in what scope — enough to call it correctly. Only the shape of the returned list (fields, ordering) is left unstated, which is a minor gap here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The stated scope ('current workspace') usefully explains why no workspace argument exists.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('List') and resource ('received and offered asset licenses') plus scope ('current workspace'), which separates it from the mutation siblings like lab_lizenz_anbieten or lab_lizenz_annehmen. It never names a sibling explicitly, but the list-vs-act distinction is inferable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied — an agent deduces it calls this to see the license state before acting. There is no explicit when-to-use, no precondition (e.g. required workspace context), and no pointer to an alternative such as lab_list_assets for the underlying assets.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a private PDF certificate URL, valid for five minutes. Only for the parties to this license.
| Name | Required | Description | Default |
|---|---|---|---|
| lizenz_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so safety is covered; the description adds genuinely new behavior: the certificate is private, returned as a URL, and expires after five minutes. It omits what happens on unauthorized or expired access, but the core traits an agent needs are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler, with the return value and its expiry front-loaded before the access caveat. Nothing could be removed without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, single-parameter tool with no output schema, the description covers what is returned (a private PDF URL) and its validity window. Only failure modes for non-parties and the meaning of the id remain underspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter has 0% schema description coverage, so the description carries the burden, and it only implies that 'this license' is identified by the input id. The UUID format and exact meaning of lizenz_id come entirely from the schema's type/pattern, not the prose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Get a private PDF certificate URL' for a license. That is clearly distinct from license siblings such as lab_lizenzen (listing) or lab_lizenz_annehmen (accepting), though it does not name any of them explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Only for the parties to this license' gives an access precondition but is a restriction, not routing guidance. It never says when to call this versus lab_lizenzen or the other license tools, so usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Owner only: revoke a license, preserving its PDF. First call get_cost:true, show the refund and owner debit, and obtain confirmation. Fixed terms refund remaining inclusive days (full before start); unlimited terms refund fully through day 14 after acceptance, then zero. The owner's 80% share is reversed proportionally, capped at available credits; the platform covers any shortfall. Repeating completes an outstanding refund without double booking.
| Name | Required | Description | Default |
|---|---|---|---|
| get_cost | No | Quote refund, owner debit and uncovered amount without booking or revoking | |
| lizenz_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false and destructiveHint=false; the description goes far beyond by explaining the refund formula per term type, the 80% owner share reversal capped at available credits, platform coverage of any shortfall, and idempotent re-invocation ('repeating completes an outstanding refund without double booking'). Together with the PDF-preservation note, this reconciles why a revoke carries destructiveHint=false rather than contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the two things an agent must know first (owner-only, PDF preserved, call get_cost first) before the refund policy. Every sentence carries operational weight — the term-type refund rules and credit cap are needed to interpret the quote the tool returns.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a financially irreversible mutation with no output schema and only two parameters, the definition covers preconditions, refund math, credit shortfall handling and repeat-call behavior. It stops short of saying what the executed call returns or how failures (insufficient credits, non-owner) surface, which an agent would still have to discover.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%, and the description compensates for the non-trivial parameter by making get_cost:true a required first step tied to showing figures and getting confirmation — semantics the schema only states as 'quote without booking'. lizenz_id is left entirely undefined, but as a UUID identifier its meaning is self-evident from the name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('revoke a license') and immediately names the key preservation side effect ('preserving its PDF'), which reframes what would otherwise look purely destructive. It does not distinguish itself from close siblings such as lab_lizenz_zurueckziehen or lab_widerruf, so an agent facing 'withdraw vs revoke' ambiguity gets no help here.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit preconditions ('Owner only') and a mandatory two-step invocation protocol: call with get_cost:true, present refund and owner debit, obtain confirmation, then execute. What it lacks is routing guidance — no statement of when to prefer this over the sibling withdraw/withdraw-license tools, which is exactly the confusion the naming invites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Withdraw your license offer before acceptance. Free.
| Name | Required | Description | Default |
|---|---|---|---|
| lizenz_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive mutation. The description adds genuinely new information with 'Free' (no cost incurred), which annotations cannot convey. It does not say whether the withdrawal is reversible, whether the offer can be re-issued, or what state the license lands in.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, action first, cost qualifier second. Nothing wasted and no buried information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter mutation with no output schema, the description covers intent and cost but leaves the agent guessing about preconditions, resulting state, and parameter sourcing. Adequate but clearly incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the single parameter lizenz_id carries no textual description; the schema only reveals it is a UUID. The description adds nothing about which license ID to pass or where to obtain it, so it fails to compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('withdraw your license offer') plus a scope qualifier ('before acceptance'), so the agent can distinguish it from post-acceptance revocation siblings like lab_lizenz_widerrufen. It never names those siblings outright, so the differentiation is inferred rather than explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Before acceptance' is a real temporal precondition that implicitly excludes the post-acceptance case, implying a different tool for that. However, no alternative is named and no guidance is given on prerequisite state (must an offer exist first?).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a 360° equirectangular HDRI panorama of a place (costs credits — exact price via get_cost: true). Pass loc_id to persist it on that board, so the viewer finds it again; without loc_id it is a one-off.
| Name | Required | Description | Default |
|---|---|---|---|
| mood | No | Mood/atmosphere (default 'neutral') | |
| intent | No | What the place is — the panorama prompt | |
| loc_id | No | Persist the panorama on this location board (from lab_list_locations) | |
| get_cost | No | Free: the exact price of this operation; nothing is rendered or charged. Name it to the person before the real run. | |
| camera_height | No | Camera height in metres (default 1.6, roughly eye level) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false and destructiveHint=false, so the description carries real weight by disclosing that the call consumes credits, that get_cost is free and renders nothing, and that loc_id changes persistence behavior. It does not say whether generation is synchronous or job-based, which would matter for a credit-spending generation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler, front-loaded with the action and output format before the cost note and persistence guidance. Every clause carries actionable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter generation tool with full schema coverage, minimal annotations and no output schema, the description supplies the essential missing context: credit cost, the free price-check path, and loc_id persistence semantics. It omits only the async/job-return dimension, which an agent might need to retrieve the rendered result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 meaning beyond the schema for loc_id (persisted panoramas are re-findable by the viewer; omitting it makes the result a throwaway) and reinforces the get_cost preview contract. mood, intent and camera_height are left entirely to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Generate) plus a precisely characterized resource (360° equirectangular HDRI panorama of a place), and names the artifact format agents need to distinguish it from siblings like lab_generate_location_variants or lab_restyle_location.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear conditional usage: pass loc_id to persist on a board, omit it for a one-off, and use get_cost:true to preview price before charging. It stops short of naming an alternative tool for related needs (e.g. variants or restyle), so no explicit exclusions or routing to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reconstruct a real place in 3D from a scan clip: keyframes are pulled from the clip server-side and turned into a point cloud / splat on the location board, so a scouted room can be looked at from angles nobody filmed. THE SCAN IS NOT MADE HERE — it is a walk-around clip uploaded by the FilmLab camera app together with the phone's lens data. This tool takes one that already exists; lab_list_location_scans gives you the ids. SLOW AND NOT A JOB ROW: the answer comes back as 'reconstructing', and the finished state is picked up ONLY by lab_list_location_scans — lab_job_status and lab_get_job will never show this one finish. If the call times out, the reconstruction normally keeps running on the server: list the scans instead of firing it again. Re-running is allowed from any state that is not done.
| Name | Required | Description | Default |
|---|---|---|---|
| engine | No | Which reconstruction path. Omit for the backend default. 'vggt' is scene-scale and fast but gives a point cloud; 'vggt-splat' trains a walkable Gaussian splat from the same scan (minutes on a GPU, not seconds). Both need their own model configured on the backend — where it is not, the answer says so instead of falling back silently. | |
| image_id | Yes | Id of the SCAN row (from lab_list_location_scans) — positive integer as string. It is a row in the image gallery whose tool is the location scanner; a normal generated image with that id is rejected, not reconstructed. | |
| max_photos | No | How many keyframes are pulled from the clip and handed to the reconstruction. Omit to let the engine use its own count — more frames mean a wider parallax baseline and a slower run. | |
| project_id | Yes | Project id (from lab_list_projects) — positive integer as string. The scan must belong to it; a scan of another project is not found rather than borrowed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations only marking it as non-readOnly and non-destructive, the description adds critical behavioral context: the tool is slow, returns 'reconstructing', its completion is visible ONLY through lab_list_location_scans, and lab_job_status/lab_get_job will never show it finishing. It also discloses timeout behavior and re-run semantics, which go well beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action, then layers critical caveats in a logical order: source of the scan, job tracking, timeout handling, and re-run rules. Every sentence adds distinct value, and the use of caps for key warnings makes important constraints scannable without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity as an asynchronous 3D reconstruction and the absence of an output schema, the description is complete: it explains the input source, the slow/async nature, where completion is observed, timeout behavior, and re-run limits. The rich schema and annotations cover the rest.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters are already richly documented in the input schema. The description does not add parameter-specific syntax or format details beyond what the schema provides; it only implies that image_id is a scan row. The baseline of 3 is appropriate when the schema carries the full semantic load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Reconstruct a real place in 3D from a scan clip.' It explicitly distinguishes this tool from related operations by stating 'THE SCAN IS NOT MADE HERE' and naming the source of ids (lab_list_location_scans). An agent can easily tell it apart from siblings like lab_analyze_location_image or lab_depth_map.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear when-to-use guidance: it takes an existing scan, ids come from lab_list_location_scans, and re-running is allowed from any state that is not done. It also explicitly tells the agent what to do on timeout — list the scans instead of firing again — and notes that job status tools will never show completion. These are precise alternatives and conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read or set a project's 'look in post' flag. Use it when the person grades in DaVinci Resolve with the FilmLab Look plugin and wants the lens and film look applied there instead of baked into the generated pictures. With project_id only: read. With look_in_post true, image and video prompts of the project no longer ask for grain, halation, vignette, chromatic aberration or soft edges — the plugin adds them in Resolve; false puts them back. It takes effect only while a LensLab lens set is chosen for the project (Pose Director / camera panel in the FilmLab app); without one the flag is stored but changes nothing. The answer always carries look_in_post, optik (the chosen lens set or null), wirkt (whether it takes effect now) and a sentence to pass on.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project id (from lab_list_projects) | |
| look_in_post | No | true: leave the look terms out of prompts and let the Resolve plugin add them; false: keep them in the prompt. Omit to only read |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the minimal annotations by disclosing the actual side effect (removing grain, halation, vignette, chromatic aberration, soft edges from prompts), the precondition that it only takes effect while a LensLab lens set is chosen, and the stored-but-inert case when none is set. This is exactly the mutation context an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded and every sentence carries a distinct fact (when to use, read/write, effect, precondition, return). Some sentences are long and dash-heavy, costing a little readability, but there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description fully specifies the return payload (look_in_post, optik, wirkt, and a pass-along sentence), so an agent knows what comes back. Combined with the precondition detail, nothing needed to call this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so the mechanical meaning of both params is already documented, but the description enriches them by enumerating the affected prompt terms and the rendering precondition tied to the flag value. That is added meaning beyond the schema, though it does not define syntax or defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb pair ('read or set') and resource ('a project's look in post flag'), immediately distinguishing it from the many generate/grade siblings. It does not name any sibling it is not, but the flag-specific scope is unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a concrete when-to-use condition: the person grades in DaVinci Resolve with the FilmLab Look plugin and wants the look applied there instead of baked in. It also specifies read vs write via omitted vs present look_in_post. No explicit exclusions or named alternatives, hence not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check the colour CONTINUITY of a scene in the edit (Murnau): every shot is compared with the scene's reference shot (the first, or referenz_clip_id) at the SAME scene points — found by feature matching (ORB + homography) between the two frames, each rendered through its export path. Image-wide statistics would measure the framing, not the grade (measured: up to 5000 K apart with no grade change). At those points: white point (Kelvin and mired), lightness (L*), colour distance (ΔE). Over the threshold (8 mired, L* 4, ΔE 3) a shot gets a befund with the number (e.g. '150 K wärmer als die Szene (13 Mired)') and a vorschlag.grade: a clip grade fitted so the shot's source colours land on the reference colours, with the deviation expected afterwards. Pass it to lab_grade_clip, then run lab_look_match again. Shots without enough shared content (reverse shot, different subject) come back as vergleichbar: false with the reason — nothing is guessed. Scenes come from the sequence's shots (lab_shots); without them give the shots as clip_ids. At most 24 shots per call. Writes nothing, costs nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| szene | No | Only this scene (scene_ref from lab_shots); default: every scene with two or more shots | |
| seq_id | Yes | Sequence id — positive integer as string | |
| clip_ids | No | Compare exactly these shots instead of the scenes from lab_shots | |
| referenz_clip_id | No | The shot the others are matched to; default the first of the scene |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=true; the description adds cost ('costs nothing'), edge-case behavior ('vergleichbar: false' with a reason, nothing guessed), thresholds that trigger a finding (8 mired, L* 4, ΔE 3), the per-call cap, and the exact shape of the returned grading suggestion. That is substantial behavioral disclosure beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose and workflow, then outputs, then caveats. It is dense but most sentences carry actionable content; the implementation aside (ORB + homography) and the measured 5000 K justification are slightly verbose for an agent that only needs to know the method is robust, but they do support trust in the result.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and only a readOnly annotation, the description carries the full burden and meets it: it describes inputs, the comparison method, success and failure result shapes, thresholds, limits, and the downstream tool call. Nothing needed to invoke or interpret the tool correctly appears to be missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 goes further: it explains what `referenz_clip_id` means conceptually (the reference shot every other shot is matched against), what `szene` defaults to, and how `clip_ids` bypasses the lab_shots scene derivation. It adds interpretive meaning rather than repeating the schema text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a specific verb and resource — checking colour continuity of a scene in the edit — and immediately names the mechanism (reference-shot comparison at matched scene points) and the outputs (`befund`, `vorschlag.grade`). An agent can distinguish this from generic grading tools (lab_grade_clip, lab_grade) because the description frames it as a diagnostic that feeds another tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear workflow: get scenes from lab_shots, pass the resulting `vorschlag.grade` to lab_grade_clip, then re-run lab_look_match; and it names the fallback path (supply `clip_ids` when lab_shots output isn't available). It also states the operational limit of 24 shots per call. It does not, however, differentiate itself from the plausible siblings lab_continuity_check or lab_look_in_post, so no explicit when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the sound mix of a sequence: per track volume_db, pan, mute, solo and effects. Every field you send is rendered — the backend rejects what it cannot render (422 with the reason), so a saved mix is the mix you hear. Tracks are the stems dialog, music, sfx, atmo, plus master (effects only: eq, compressor, limiter). Only the fields you send change; effects replaces that track's whole effect list. Effects: gate, eq, deesser, compressor, reverb, limiter — fixed order, one of each per track; give a preset (with its written reasoning), a one-knob knopf (0–1) or explicit values. Ducking is an effect too: {type:'ducking', quelle:'dialog', amount_db, attack_ms, release_ms} lowers this track while quelle is active. naht_ms (0–500) fades every seam between the clips of a stem with an equal-power fade — against clicks and room jumps at the cuts of a stem built from pieces; 0 = hard edges. The sfx stem of lab_ton_durchlauf comes with 30. Volume automation replaces the track's breakpoints {t_s, db}, in seconds from the sequence start, interpolated linearly in dB; [] clears it, and master does not support it. Call with katalog: true (and no tracks) to get every effect, its ranges and the presets with their reasoning. Any change discards the rendered mixdown. Changes state, costs nothing. Next: lab_mix_render, then lab_mix_messen.
| Name | Required | Description | Default |
|---|---|---|---|
| seq_id | Yes | Sequence id — positive integer as string | |
| tracks | No | Tracks to change — only the given fields are written | |
| katalog | No | Return the effect catalogue instead of changing anything |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only supply readOnly/idempotent/destructive hints; the description adds substantial behavior: 422 rejection of unrenderable fields, 'only the fields you send change', effects replacing the whole list, and 'Any change discards the rendered mixdown'. These are exactly the side-effect and validation facts an agent needs before writing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is a dense single paragraph, but the core purpose and write semantics are front-loaded before the finer effect/automation details. Given the genuine complexity of the tool, nearly every clause earns its place, with only mild density/redundancy cost.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description compensates by explaining the katalog mode, the 422 error behavior, and the downstream render/measure tools. For a stateful multi-field mix tool with 100% schema coverage, 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.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema carries the field-level documentation (baseline 3). The description nonetheless adds real meaning beyond it: the ducking object shape, the fixed effect ordering and one-of-each rule, preset-vs-knopf-vs-explicit semantics, and that '[] clears it' for automation while master does not support it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise verb+resource: 'Set the sound mix of a sequence'. It enumerates the five per-track fields and explicitly distinguishes itself from the sibling chain by naming 'Next: lab_mix_render, then lab_mix_messen', so an agent can place it in the workflow 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context for when to use it (setting a mix, and the 'katalog: true (and no tracks)' catalogue mode) and names the follow-on tools lab_mix_render and lab_mix_messen. It stops short of stating explicit when-not-to-use conditions, but the sequencing makes the role clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Measure the RENDERED mix: integrated loudness (LUFS), true peak (dBTP) and loudness range (LU) of the master, measured on the mixdown file itself. Per stem the same values, speech-gated (under the dialog / in its pauses), and how many LU each stem sits under (or over) the dialog in dialog passages — exact. A stem's level inside the master is an estimate (stem plus the gain the master applied) and is labelled as such. Needs a current render whose stems are still the ones it was made from: any change with lab_mix discards it, and a newer audio file in a stem makes it stale (409 then — render first). Runs as a BACKGROUND JOB: you get a job_id at once; poll lab_get_job until done — the measurement is in job.result. Measure before and after a change to prove what it did. Writes nothing, costs nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| seq_id | Yes | Sequence id — positive integer as string |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: discloses the background-job execution model (immediate job_id, poll lab_get_job, result in job.result), the 409 staleness behavior, the estimate caveat for stem levels inside the master, and the no-write/no-cost profile. This is exactly the kind of contract an agent cannot infer from readOnlyHint/idempotentHint alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the deliverable (what is measured) before the prerequisites and job mechanics, and every sentence carries information. It is dense and long but not padded; the density is justified by the measurement detail rather than extraneous prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, yet the description explains what the result contains and where to find it (job.result via lab_get_job), plus staleness and estimate caveats. Nothing an agent needs in order to invoke and interpret this call is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (seq_id) and schema description coverage is 100%, so the schema fully documents it ('Sequence id — positive integer as string'). The description adds no extra syntax or format guidance, which is the expected baseline when the schema does the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a precise verb+resource (measure the rendered mix) and enumerates exactly what is produced: integrated LUFS, true peak dBTP, loudness range LU, plus per-stem speech-gated values. It is clearly separable from voiceover/mix siblings like lab_mix and lab_stems_export.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States the operating context ('measure before and after a change to prove what it did'), the prerequisite ('needs a current render whose stems are still the ones it was made from'), and the failure mode that selects a different action ('any change with lab_mix discards it ... render first'). The lab_mix sibling is named as the invalidating operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render the sequence's mixdown, normalised to a loudness target: broadcast (EBU R128), web or youtube. With auto_preset it runs the AUTO-MIX instead: it measures every stem speech-gated (under the dialog vs. in its pauses), sets faders, ducking and a master limiter by the preset (spielfilm: music clearly under the dialog; doku_vo: the narrator leads), renders, and measures the result. Every auto-mix decision comes back as one sentence with its number, plus missed lower loudness bounds — read them, they are the reasoning you can pass on. Runs as a BACKGROUND JOB: the answer is a job_id at once; poll lab_get_job until status is done (the result — mixdown, measured loudness, the auto-mix report — is in job.result) or failed (job.result.status and detail say why: 422 solo on / dialog muted / no speech, 409 the tracks were edited meanwhile — nothing was overwritten). If a render of the same kind is already running for this sequence, you get THAT job_id back instead of a second render. Costs nothing. Next: lab_get_job, then lab_mix_messen.
| Name | Required | Description | Default |
|---|---|---|---|
| seq_id | Yes | Sequence id — positive integer as string | |
| target | No | Loudness target, default broadcast | |
| auto_preset | No | Run the auto-mix with this preset instead of rendering the mix as set |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false and destructiveHint=false; the description goes far beyond by disclosing background-job semantics (immediate job_id, poll lab_get_job), failure modes (422 solo/dialog muted/no speech, 409 concurrent edit with 'nothing was overwritten'), idempotent dedup behavior returning an existing job_id, and 'costs nothing'. This is exactly the extra context annotations cannot convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the render behavior before branching into job mechanics, and every clause is substantive. It is dense and heavily em-dash dependent, which slightly reduces scannability, but no sentence is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description must explain return values, which it does precisely: job.result holds the mixdown, measured loudness and the auto-mix report, plus per-decision sentences and missed loudness bounds. Error statuses and the required polling tool are all covered, so an agent has everything needed to invoke and follow up.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already carries the baseline. The description still adds meaning: 'broadcast (EBU R128)' explains the target enum, and the preset semantics ('spielfilm: music clearly under the dialog; doku_vo: the narrator leads') clarify what each auto_preset value actually does, which the schema's terse 'Run the auto-mix with this preset' does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('Render the sequence's mixdown, normalised to a loudness target') and clarifies the two distinct modes: a plain loudness-normalised render versus the AUTO-MIX path triggered by auto_preset. An agent can distinguish it from siblings like lab_mix and lab_mix_messen 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear operational context — when to expect the auto-mix branch, and the explicit follow-up chain ('Next: lab_get_job, then lab_mix_messen'). It does not, however, state when to prefer lab_mix or another render sibling over this one, or any conditions for exclusion, so guidance is strong but lacks explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a paid Murnau VFX node job in a Murnau session — the same route the editor's start button uses (session ownership, allowed tasks, price, booking). Requires bestaetigt_credits equal to the current price from lab_murnau_vfx_preis; if the price changed, nothing is created and the new price comes back (409). Inputs the editor normally prepares (input_url, params such as mask_url or prompt) must be given; the server refuses incomplete jobs before booking. Poll lab_murnau_vfx_status afterwards.
| Name | Required | Description | Default |
|---|---|---|---|
| fps | No | ||
| task | Yes | Murnau VFX task | |
| hoehe | No | ||
| breite | No | ||
| params | No | ||
| dauer_s | No | ||
| node_id | No | VFX node id in the session graph, if the result belongs to a node | |
| media_id | Yes | Input media in that session's pool | |
| input_url | No | ||
| session_id | Yes | Murnau session | |
| bestaetigt_credits | Yes | The price the person agreed to (from lab_murnau_vfx_preis) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false and destructiveHint=false, so the description carries real weight: it discloses that the call is paid, that session ownership and allowed tasks are enforced, that a stale price yields a 409 with nothing created and the new price returned, and that incomplete jobs are rejected before booking. That is exactly the mutation-risk context an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the action and the price precondition, then the failure mode, then the follow-up poll — a logical order with no filler. It is dense with parentheticals, but each clause carries real information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a paid, non-destructive mutation with no output schema and a nested params object, the description covers the preconditions, the refusal behavior, the 409 payload, and the follow-up status call. The remaining gap is the undocumented half of the input schema, which an agent would have to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 45% for 11 parameters, so the description partially compensates by explaining bestaetigt_credits (must match the price from lab_murnau_vfx_preis), input_url, and the params bag (mask_url, prompt). It leaves task, media_id, node_id, and the numeric geometry/duration fields entirely to the schema, so the compensation is incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Start a paid Murnau VFX node job in a Murnau session') and immediately distinguishes itself from lab_murnau_vfx_preis and lab_murnau_vfx_status by naming them as the price source and the poll target. An agent can place this tool in a workflow 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit call sequence: read lab_murnau_vfx_preis, pass bestaetigt_credits equal to that price, then poll lab_murnau_vfx_status. It also says inputs must be complete before calling because the server refuses incomplete jobs. It lacks an explicit 'do not use this if...' branch versus the plain lab_vfx siblings, but the routing is otherwise clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Price of a Murnau VFX node job (the paid AI nodes of the Murnau editor: outpaint, relight, crowd-fill, person-maske, freistellen, video-denoise, video-extend …) — free, nothing is booked. The same server function the editor's price check and the actual booking use. Without session_id/media_id the price is computed from dauer_s/breite/hoehe/fps; with them, from the real media of that session. Name the price to the person and only start lab_murnau_vfx_auftrag after their yes.
| Name | Required | Description | Default |
|---|---|---|---|
| fps | No | ||
| task | Yes | Murnau VFX task, e.g. relight, outpaint, person-maske, video-denoise | |
| hoehe | No | ||
| breite | No | ||
| params | No | Node parameters that change the price (e.g. upscale_factor) | |
| dauer_s | No | ||
| media_id | No | Media in that session's pool | |
| session_id | No | Murnau session (lab.thefilmradar.com/murnau/?session=…) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true is already declared, but the description adds real value on top: 'free, nothing is booked' rules out side effects, and 'the same server function the editor's price check and the actual booking use' guarantees the quote matches the eventual charge. It does not cover latency, auth, or error behavior, which keeps it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then the no-cost reassurance, then the mode logic, then the workflow mandate. The parenthetical task list is long but useful; the middle sentence about being the same server function is slightly redundant with the 'free' clause.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-param tool with a nested object and no output schema, the description covers purpose, cost model, input modes, and the follow-up workflow. It omits what the returned price actually looks like (currency, units, per-task breakdown), which matters given there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
At 50% schema coverage the description must carry weight, and it does: it defines a conditional split — dauer_s/breite/hoehe/fps without session_id/media_id, real media with them — that the schema cannot express. Only 'params' and 'task' nuances are left to the schema's own descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (price of a Murnau VFX node job) and immediately disambiguates by enumerating the covered node types (outpaint, relight, crowd-fill, …). It is clearly distinguishable from sibling booking/status tools like lab_murnau_vfx_auftrag and lab_murnau_vfx_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit routing: call this first, name the price to the person, and only then start lab_murnau_vfx_auftrag after their yes. It also tells the agent which parameter combinations select which pricing mode, so when-to-use is fully prescribed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Status of a Murnau VFX job started with lab_murnau_vfx_auftrag (or in the editor): queued, running, done, failed; the result media id when done.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | id returned by lab_murnau_vfx_auftrag | |
| session_id | Yes | Murnau session |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real context beyond that: the four possible job states and that the result media id is available when done, which is important since there is no output schema. It doesn't mention polling cadence or what is returned on failure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single compact sentence with zero filler, front-loading the resource and the originating tool before the state list. The parenthetical aside is short and useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read tool with no output schema, the description covers the essentials: what states exist and that a media id comes back on success. It could say slightly more about failure output or whether the call blocks, but nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters are documented there, so the schema does the heavy lifting. The description only indirectly hints at job_id's origin (matching what the schema already says) and adds nothing about session_id, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb+resource ('Status of a Murnau VFX job'), enumerates the possible states (queued, running, done, failed), and ties the job to its originating tool lab_murnau_vfx_auftrag. That linkage separates it cleanly from the many other status siblings (lab_job_status, lab_vfx_status, lab_vfx_preset_status, lab_batch_status).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states the precondition for use — the job must have been started with lab_murnau_vfx_auftrag or in the editor — which is the key selection context. It does not explicitly say when not to use it or name the alternative status tools, 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.
Re-shoot one clip from NEW camera angles: same people, same words in the same timing, same place — only the camera changes, cutting on the spoken lines, as if several cameras had been rolling. This tool plans and checks; it never generates and never charges. Workflow: look at the clip with lab_bilder at exact seconds across its whole length (denser over fast moments), get the spoken lines with lab_wortzeiten, then ask the person ONE question — keep the original look, or a cinematic interpretation (then pick a kino_kopf from aktion optionen). Then call aktion plan with the shot list: every shot says WHERE the camera physically stands, neighbouring shots differ in size, the shots cover the clip without gaps, and original_kamera describes the original angle so the prompt can forbid it. The answer lists findings (hart = fix before anything costs) and the ready runs in stuecke[].lauf. With preis: true it also returns the price of all pieces and an estimate for upscaling afterwards — name it and wait for the yes. Then pass each stuecke[].lauf UNCHANGED to lab_reference_motion, in order. Every run is a low-resolution draft where the model offers one; upscale only what the person likes (lab_upscale). Clips longer than the chosen model can take are split at shot boundaries into several runs (zusammensetzen: true) — for more than a handful of runs propose one lab_auto_lauf with a cap. When all pieces are finished, aktion zusammensetzen puts them into ONE new sequence without gaps, each piece with its original sound. If a result comes back wrong, ONE retry: original angle came back → shorter shot list, describe the original angle more physically, make the first shot radically different (profile or top-down); timing drifted → put the spoken line in quotes on its shot; left and right swapped → describe positions by landmarks, not screen directions; people changed → add a clean still as an image with the job of how the person looks.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | zusammensetzen: title of the new sequence | |
| plan | No | ||
| tool | No | Model key from aktion optionen (only models that take a clip as reference). Default: the first one listed there | |
| preis | No | Also price all pieces (free, books nothing) | |
| aktion | No | optionen: models with their limits, shot sizes, cinematic headers (free, no project needed). plan (default): check the shot list and build the runs. zusammensetzen: finished pieces into one new sequence | |
| bild_urls | No | Image addresses for plan.bilder, same order | |
| laengen_s | No | zusammensetzen: the planned length of each piece (stuecke[].bis_s - von_s), same order | |
| video_ids | No | zusammensetzen: the finished pieces, in order | |
| project_id | No | Project — required for plan and zusammensetzen | |
| rechte_bestaetigt | No | The person confirmed they hold the rights to an uploaded clip — passed into every run. Not needed once the person gave the standing rights statement in the FilmLab app (preis then reports no rechte_noetig); never set it on your own | |
| reference_video_url | No | The clip to re-shoot: an uploaded file (lab_add_media / lab_list_assets) or a finished clip of this project |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and destructiveHint=false, so the write/read profile is already given; the description adds real context beyond it: the tool plans and checks but never generates and never charges, returns findings graded hart (fix before anything costs) plus ready runs in stuecke[].lauf, and every run is a low-resolution draft. That said, it does not say what a plan call actually persists (does it book jobs? does it mutate the project?), which is the key behavioural question for a non-read-only tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded and almost every sentence carries operative information, but the whole definition is one dense block of roughly 350 words mixing workflow, pricing policy, splitting rules and a five-case retry playbook. The retry remedies and the aktion variants would be far easier to act on as separated clauses or bullets; as written the agent must parse a wall of prose to find the branch it needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex, multi-mode tool with no output schema, the description covers what is returned (findings plus stuecke[].lauf), the pricing mode, the splitting-at-shot-boundaries behaviour with zusammensetzen, and even the failure taxonomy with a single concrete retry per failure mode. Nothing an agent needs in order to call this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 91%, so the baseline is 3, but the description compensates for the few thin spots and adds real meaning: original_kamera must be described in physical words so the prompt can forbid it, neighbouring shots must differ in size and cover the clip without gaps, preis: true returns pricing plus an upscale estimate, and zusammensetzen uses lengen_s/video_ids in matching order. This is meaning beyond the field labels, not a restatement of them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (re-shoot one clip from new camera angles) and immediately pins down the scope with a positive/negative contrast: same people, words, timing and place, only the camera changes. That framing is distinctive against the many generation siblings (lab_generate, lab_animate, lab_reference_motion) and an agent can identify it 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit prerequisite chain (lab_bilder at exact seconds, lab_wortzeiten for lines, one question to the person), names the alternative for scale (lab_auto_lauf with a cap when there are more than a handful of runs), and states when to hand off to lab_reference_motion and lab_upscale. It also specifies an exclusion by implication — upscale only what the person likes, retry only once.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an asynchronous orbit turnaround from a project image or a public HTTPS image. To use your own picture, import it first with lab_add_media (art image) and pass the returned asset_key here. Costs credits without get_cost: quote the price first and wait for the person's confirmation, then pass max_credits. Never automatically retry a paid run. Pass job_id to poll the existing run; it takes precedence over starting and needs no project or image. The selected views are approximate angle estimates, unvalidated on AI characters.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | No | Existing orbit job id as a positive integer string; polls status and approximate views. | |
| get_cost | No | Return the catalog price and current balance without starting or charging anything. | |
| asset_key | No | The asset_key of an image imported into this project with lab_add_media (art image); give this OR startbild to start. | |
| startbild | No | Address of an image owned by this project or a public HTTPS image; give this OR asset_key to start. | |
| project_id | No | Project id as a positive integer string; required to start. | |
| max_credits | No | Maximum credits confirmed by the person, as a nonnegative integer string; required to start. | |
| nur_eigene_daten | No | Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare non-read-only and non-destructive. The description adds substantial behavior: asynchronous execution, credit cost, mandatory price quote and confirmation, no automatic retries, job_id precedence, and a caveat that views are approximate/unvalidated on AI characters. This is strong disclosure beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the purpose and then adds only operational caveats. Each sentence carries distinct information (import path, cost handling, retry prohibition, polling precedence, quality caveat), with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given seven optional parameters and no output schema, the description covers the main call paths and cost/quality behavior well. It omits explicit return-value description (though job_id polling implies a job id is returned) and leaves the complex nur_eigene_daten gate entirely to the schema, so it is strong but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds workflow meaning for max_credits (quote then confirm) and job_id (takes precedence, needs no project/image), plus the asset_key import path. It does not elaborate on nur_eigene_daten, but the schema already documents it thoroughly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Create') and resource ('orbit turnaround'), scope ('from a project image or a public HTTPS image'), and distinguishes the import path by naming lab_add_media. The job_id polling mode is also clearly separated from starting a new run.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit operational guidance: use lab_add_media before asset_key, call get_cost and obtain confirmation before max_credits, never auto-retry, and use job_id to poll rather than start. It does not explicitly compare this tool to other image-generation siblings (e.g., lab_neue_winkel) or state when not to use it, which keeps it from a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The rules of one working surface, generated from the code: what the surface is, what an agent can trigger itself, what exists but only by hand, and what does not exist at all. Call this BEFORE answering what is possible on a surface — the three lists come from a table with a code reference per entry, checked in every PR, not from memory. Saying "that does not exist" about something the editor can do is the failure this tool prevents. Surfaces: edit, vfx, audio, idea, script, axis, location, crew, cast, pose, capture.
| Name | Required | Description | Default |
|---|---|---|---|
| flaeche | Yes | The working surface |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds real behavioral context beyond that: the content is generated from code and tied to a table with a code reference per entry, 'checked in every PR, not from memory', which signals authority and freshness. It does not describe pagination or response size, but for a single-enum lookup this is solid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is front-loaded with the core definition in sentence one and the call-timing rule in sentence two, with no filler. The trailing enumeration of surfaces is redundant against the schema enum, which is the only real slack. Overall dense and useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description must convey what comes back, and it does: the three lists (self-triggerable, manual-only, nonexistent) plus their code-backed provenance. For a single-required-param read-only lookup this is close to complete; only pagination/format details are absent, which is minor here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single parameter carries a full 11-value enum, so the schema already does the work. The description's final sentence merely re-lists the same surface names already in the enum, adding no meaning beyond the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb-and-resource: it returns the rules of one working surface, itemized into what an agent can trigger, what is manual-only, and what does not exist. That is far more specific than the title alone, and it is clearly distinguishable from the many lab_* list/get siblings. It stops short of naming a sibling to prefer or avoid, so 4 rather than 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit timing guidance — 'Call this BEFORE answering what is possible on a surface' — and names the failure mode it prevents ('saying that does not exist about something the editor can do'). That is strong when-to-use direction. It does not name an alternative tool or a when-not-to-call condition, so it does not reach 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Turn a loose idea into a production-ready image or video prompt — the same Dreamer engine the FilmLab web UI uses (modes: beautify, storyboard, polish, format, shorten, expand, simplify, custom, stiluebernahme). beautify GENERATES (a 50-character thought comes back as a full prompt); polish/format/shorten/expand/simplify PRESERVE what is there. medium=video plus depth=skeleton yields the 15-block production prompt; depth only applies to video. anlass only applies to beautify. custom and stiluebernahme require instruction. For video the answer carries clip_duration_seconds — hand THAT number to lab_animate(duration_seconds), otherwise a prompt timed to 12s gets rendered as lab_animate's 5s default. In an Apps-capable host this opens as a form you can adjust and re-run; elsewhere it answers with the prompt as plain text. Pass tool (the registry key you will hand to lab_animate/lab_generate) and the finished prompt is laid out in the skeleton of that model family — location, camera, lens and light land where that family reads them, worded the way it reads them; families without a measured rule keep them appended as before, and the answer says so (prompt_skelett).
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Default beautify (generates). beautify: Aus der Idee einen vollständigen Prompt bauen — ergänzt Licht, Optik, Kamera, Stimmung | storyboard: Szene in 4–8 nummerierte Panels zerlegen — je Panel ein eigenständiger Bild-Prompt | polish: Wortwahl polieren, Flow verbessern, Redundanz entfernen — Länge bleibt | format: In // Subject // Lighting // Camera Sektionen ordnen, Wortlaut bleibt | shorten: ~30% kürzer, jedes Wort muss Gewicht tragen | expand: Texturen, Lichtreflexe, atmosphärische Details | simplify: Direkt und klar, weniger Fachjargon | custom: Eigene Anweisung — z.B. 'Mach es düsterer' | stiluebernahme: Licht, Optik und Look aus einer Beschreibung — Motiv und Bildaufbau bleiben wörtlich | |
| tool | No | Optional: the model you will render with, as the registry key from lab_list_models. Decides which family skeleton lays out camera, lens and light — and whether it is a measured rule or the plain appended form. | |
| depth | No | video only: sketch (5 blocks, default) or skeleton (15 blocks) | |
| anlass | No | beautify only: what the image is FOR. Default frei | |
| medium | No | photo (default) or video — decides the section layout | |
| prompt | Yes | The text to work on — a loose thought is enough for beautify | |
| winkel | No | Optional: change the camera angle of the EXISTING prompt — a key such as augen, unter, auf, vogel, frosch, schraeg, ots, pov, profil. Implies mode=custom and needs no instruction; combinable with groesse. | |
| familie | No | Optional, instead of tool: the model family by name when no registry key is at hand. Medium decides whether the image or the video skeleton applies. | |
| groesse | No | Optional: change the shot size of the EXISTING prompt, keeping subject, light and place — a key such as ews, ws, mws, ms, mcu, cu, ecu, macro. Implies mode=custom and needs no instruction. An unknown key is rejected with the known ones. | |
| kontext | No | Optional, for mode beautify: the scene and earlier shots, for continuity only. Characters, objects and places named here stay the same; only the prompt itself is depicted. | |
| techniken | No | Up to three directing technique keys from lab_regie_techniken. Their prompt fragments are appended verbatim after the transform, ordered angle, framing, composition, movement. One angle and one movement at most; movement only with medium=video. | |
| project_id | No | Optional: the project this prompt is for. With tool or familie, its Lens Lab optics, Pose Director framing and gaffer light are laid into the prompt. If the project has look_in_post on and a Lens Lab set chosen, grain, halation, vignetting, chromatic aberration and edge softness are left out — the FilmLab Look plugin adds them in Resolve; the answer lists what was removed. | |
| referenzen | No | The references the prompt may point at, IN THE ORDER you will pass them to lab_animate/lab_propose. Write @bild1, @video1, @ton1 in your prompt and they come back as the markers the model actually reads (@Image1, @Video2, @Audio1) — the reference clip itself is @Video1, so the first video reference is @Video2. A mention with no matching reference is rejected instead of being left in the text, where it would reach the model as a word. | |
| instruction | No | Required for custom (an order, e.g. 'make it darker') and stiluebernahme (a style description) | |
| location_id | No | Optional, only with tool or familie: the location board whose prompt prefix becomes the place block — the same board you will hand to lab_animate/lab_generate. | |
| projektstil | No | Optional, with project_id: the Dreamer writes under the project's style kit and look, as in the app. Without it the project only decides the look_in_post filter. | |
| duration_seconds | No | video only: the clip length in seconds the ACTION TIMING beats are written to. Default 5 (what lab_animate renders without an explicit duration). Rejected for medium=photo. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description carries the real behavioral load: beautify GENERATES while polish/format/shorten/expand/simplify PRESERVE, the host-dependent Apps-form vs plain-text response, rejection of unmatched @-mentions, and the look_in_post filter that strips grain/halation/vignetting with the answer listing removals. These are exactly the non-obvious traits an agent cannot infer from annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose is front-loaded, but the body is a dense em-dash-chained block that restates mode names and medium/depth rules already present in the schema. Information density is high, yet a reader must parse one long paragraph to extract the conditional rules.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 17-parameter tool with no output schema, the description does the necessary work: it names key response fields (clip_duration_seconds, prompt_skelett, the removed-effects list) and explains reference-marker rewriting. It does not fully describe the response shape or the storyboard mode's output, leaving a modest gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description earns above that by adding cross-parameter interaction rules not obvious from per-field text — depth gated on medium=video, anlass gated on beautify, instruction required for custom/stiluebernahme, and tool/familie selecting the skeleton family. The mode list itself is largely repeated from the enum description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Turn a loose idea into a production-ready image or video prompt' via the Dreamer engine, and enumerates the modes. It also clarifies the downstream relationship to lab_animate/lab_generate. It does not differentiate itself from the similarly named sibling lab_transform, which leaves one plausible ambiguity unresolved.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete conditional guidance: 'depth only applies to video', 'anlass only applies to beautify', 'custom and stiluebernahme require instruction', and 'medium=video plus depth=skeleton yields the 15-block production prompt'. It also routes the agent forward ('hand THAT number to lab_animate(duration_seconds)'). It stops short of stating when to choose this over siblings such as lab_transform.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate product-photo views of a prop using Flux 2 Pro. Costs credits per view: front is text-to-image, side/back/top/detail edit the front anchor. First call with get_cost:true, name the exact credits to the person, and obtain confirmation before generating. Missing images are refunded.
| Name | Required | Description | Default |
|---|---|---|---|
| anker | No | ||
| views | No | ||
| prop_id | Yes | ||
| get_cost | No | Free price query: no generation, no charge | |
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say readOnlyHint=false / destructiveHint=false, so the description carries real added weight: it discloses credit cost per view, that the cost query is free with no charge, that missing images are refunded, and the dependency that side/back/top/detail edit the front anchor. Those are exactly the side effects and constraints an agent needs before spending a user's credits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences, front-loaded with purpose then cost then required workflow. Nothing is padded — each sentence delivers either scope, pricing behavior, or a mandatory pre-call step.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a credit-spending generation tool with no output schema and a mutation flag, the description covers cost, refunds, the confirmation gate, and the view dependency chain. It still leaves unclear what the call returns (asset/image references) and does not explain the 'anker' flag, keeping it just under complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 20%, so the description must compensate, and it partly does: it explains that 'front' is text-to-image while the other view values edit the front anchor, and it restates get_cost as a free price query. However, the 'anker' boolean and the prop_id/project_id parameters get no semantic explanation anywhere, so the compensation is incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — 'Generate product-photo views of a prop' — plus the underlying model (Flux 2 Pro), which distinguishes it from the generic lab_generate or the character-reference generator. It does not explicitly name a sibling it could be confused with, so it stops just short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a concrete operating protocol: call first with get_cost:true, quote exact credits to the person, obtain confirmation before generating. That is clear when-to-use and prerequisite ordering. It does not address when to skip this tool or which sibling to pick instead, leaving a minor gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| 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. 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. | |
| 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). | |
| dreamer_signatur | No | 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. | |
| 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. |
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.
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.
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.
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.
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.
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.
Render a new clip FROM the motion of an existing one: your reference clip leads (camera move, blocking, timing), the model restyles what happens in it. Pass the clip's URL directly — the one you already have from lab_list_assets (asset_type 'video'), lab_job_status or lab_review_queue; nothing is looked up. Reference images bind cast, place and look; in_sec/out_sec cut the reference server-side before it ever reaches the provider, so you pay for the excerpt, not the source. Same backend path as lab_animate's source_video_id, with the fields that only exist there. Costs credits when called without get_cost. A reference clip made with an older version of a character is refused (figur_veraltet); the get_cost answer lists figur_veraltet beforehand, so you see whether that threatens — only the human may decide to go on anyway (veraltete_figur_ok). WITHOUT a reference clip (leave reference_video_url out), the images and sounds in referenzen alone guide the run — only for models whose lab_list_models entry says referenzen_ohne_video: true, and only FACELESS references (ort, stil, bild, stimme, ton): Seedance 2.5 rejects faces as reference images, even invented characters (measured 2026-09-27), so figur is refused before anything is charged. For a person, build a still with them first and animate it with lab_animate. Name the references in the prompt as 'reference only, never shown on screen', and avoid the word 'static' for short shots — it tends to return frozen frames.
| Name | Required | Description | Default |
|---|---|---|---|
| ton | No | Which sound the result carries. quelle: the reference clip's own audio is laid back under the new picture after generation — the way to keep a spoken take, since models that regenerate audio replace the voice. generiert: keep the model's sound (needs generate_audio: true). keiner: no sound. Omitted: quelle when a reference clip is given and generate_audio is off, generiert when generate_audio is on, keiner otherwise. The finished run reports in metadata what actually lies underneath (ton) and how far picture and sound differ in length (ton_drift_s). | |
| task | No | reference (default): the references guide a new clip. editing: the picture of the reference clip stays and only what the prompt names changes — e.g. 'keep the picture, generate matching sound effects, no music' with generate_audio: true. Needs a reference clip. Edit verbs in the prompt are expected here, not refused. | |
| tool | No | Video model id — copy it verbatim from lab_list_models (kind: video), and only models the catalog marks v2v take a reference clip at all. Omit to let the backend use its own default for this path. Durations, resolutions and price live in the catalog, this text names none. | |
| draft | No | Render a cheap DRAFT first (Seedance 2.5 and wan_vace only — other models refuse it before anything is charged). On Seedance 2.5 the draft is 480p, priced at that tier, and carries a draft_id that stays valid for 7 days and only for the account that ordered it. Finish an accepted draft in 1080p ONLY with lab_fertigstellen — never by downloading and re-uploading it: that is a new run with new motion, not the draft. Any `resolution` you pass is ignored for a draft, and the answer says so. | |
| in_sec | No | Cut the reference clip server-side before it reaches the provider: start of the excerpt, in seconds from the clip's beginning. Only together with out_sec. | |
| prompt | Yes | What the new clip should show. Describe it — do NOT phrase it as an instruction to edit or extend the reference; some models classify the run by the verb and then reject the aspect ratio and duration after queueing. | |
| out_sec | No | End of the excerpt in the reference clip, in seconds. Must lie behind in_sec; both are set together or neither. | |
| get_cost | No | Preflight: return the price in credits and your balance WITHOUT generating and without spending anything, reading the same catalog as lab_list_models. Do this before a long take or when the user should confirm the cost. | |
| prop_ids | No | Prop ids from lab_list_props (an @prop_ tag in the prompt does the same). Their descriptions go into the prompt; each prop's front view joins the reference images after yours, on free slots only, with its own @Image line (never on wan_vace). The answer says which way it went (props.weg). | |
| scene_ref | No | The shot this clip belongs to, as `sb_N` (N = the shot number in the shot list, e.g. `sb_4`). With it the clip shows on the story axis and, once accepted, joins the main sequence in story order via the rough cut. Without it the clip only lands in the gallery and neither the axis nor the rough cut sees it. | |
| use_depth | No | Condition the run on a depth pass of the reference clip. Defaults to ON (true = 'voll': depth of the whole frame); pass false to opt out. Models that do not have a depth stage ignore it — the answer says so rather than pretending it happened. 'personen': depth ONLY on the people, the original footage around them — the model stops copying build, hair and clothing of the original performers and the room keeps its colours. 'mannequin': the same path as 'personen', but the people become plain grey mannequins that keep each performer's pose, silhouette and body structure (the depth is normalised to the person, so arms and limbs stay readable) instead of a depth pass — use it when 'personen' loses the inner motion of the people. With 'personen' or 'mannequin' the run PAUSES after the mask: only the mask (SAM) is charged, the answer carries cost (mask) and cost_lauf (the run), and the clip waits as wartet_auf_freigabe until the human has looked at the preview (metadata.personen_referenz_url) and you call lab_freigeben. Needs a reference clip and a model with a depth stage; not together with face masks or task='editing'. To RE-FILM a take from new camera angles, pass false: a depth pass locks the geometry of the reference, and the new angles cannot happen. task='editing' ignores it anyway. | |
| kamerapfad | No | The camera move as INPUT instead of prose: an object following shared/kamerapfad/schema.json — poses over time (position, look-at or quaternion, metres, Y up) from the Kadrage terrain flight or drawn by hand, or motion phases as lab_kamerafahrt reads them from a clip (its answer carries a ready `kamerapfad`). The backend validates it, derives phases, and adds the move as a paragraph after your prompt, before the reference markers (the reference clip still leads the motion as the first video reference). WHICH FORM that paragraph takes depends on the model: prose for most families, bracketed director commands for the MiniMax/Hailuo family, which parses them. NO MODEL RECEIVES THE POSES TODAY — the answer says which form went out (kamerapfad.angewandt = als_text or als_regiebefehle), names the family rule and the source it rests on (kamerapfad.sprache), and lists what that form could not carry. If your own prompt already carries bracketed commands, the path is NOT sent on top of them (angewandt = eigene_regie, with kamerapfad.eigene_regiebefehle naming what it found). A `zusammenfassung` inside the path is display only and is NEVER sent — the move is always rebuilt from the phases; if nothing can be built, the answer says angewandt = nicht_ableitbar with the reason, and nothing of the path is in the prompt. Mutually exclusive with kamerapfad_url. | |
| project_id | Yes | Project id (from lab_list_projects) — positive integer as string. On this path it travels in the request BODY, not in the URL, but it is just as required: the new clip is filed under this project. | |
| referenzen | No | The typed successor of character_ref_urls: each reference says WHAT it is, so a place or a look no longer has to travel disguised as a character. Since 2026-09-03 it carries all three channels, not just images: motion references ride alongside the reference clip, sound references go into the model's audio slots. The position IS the address — the images are @Image1..n, the reference clip is @Video1 and the extra motion references follow it, the sounds are @Audio1..n. Image references are MEASURED before they are sent and scaled up to the model's minimum if they fall below it; a reference is never rejected for being small. Mutually exclusive with character_ref_urls — two sources for one list means one of them silently loses. What a model takes per channel is in lab_list_models (referenz_grenzen). | |
| resolution | No | Render resolution on this path, copied verbatim from the model's resolutions in lab_list_models. The run is priced at the resolution you choose — the low tier costs a fraction of the default — so pass it for sound-only or test runs. Omitted, the model's default applies. | |
| kamera_frei | No | New camera angles (lab_neue_winkel): @Video1 carries the action, the words and the timing, but NOT the camera — the camera follows the timestamped shot list in the prompt. Replaces the default sentence 'follow the motion, camera movement and timing of @Video1 exactly', which would pull the model back to the original angle. Needs a reference clip and use_depth=false, not with task='editing'. Normally you pass the ready `lauf` object from lab_neue_winkel unchanged instead of setting this by hand. | |
| stil_kit_id | No | Style kit id (lab_list_stil_kits; an @stil_ tag in the prompt does the same). Omit it and the project's default kit applies. Its rules and palette go into the prompt; its images join the reference images AFTER yours and the props, only on slots the model still has free (never on wan_vace, where an image would be read as a character). The answer says which way it went (stil_kit.weg). | |
| wechsel_von | No | The model id this call switches AWAY from (as listed in lab_list_models), with the same references as before. The answer then carries `wechsel`: which references the switch cuts off and why, and which ones the new model picks up. Nothing is sent to the old model; the field only names the comparison. | |
| aspect_ratio | No | Output aspect ratio on this path, written as width:height or 'auto'. Only models whose lab_list_models entry takes it on the reference path accept it; for any other model the backend refuses it before anything is charged, and the refusal lists the allowed values. Omitted, the model's fixed default applies. | |
| ton_fuehrung | No | What the model HEARS as guidance while it renders — not what the result carries (that is `ton`). voll (default, same as omitting it): unchanged behaviour. stimme: the backend splits the reference excerpt (after in_sec/out_sec) with demucs and sends ONLY the vocal stem, unchanged, as the single audio reference @Audio1 — so a speaking or singing performer moves the lips without the music bed dragging along. The stem is never pitch-shifted or altered in any way. The demucs split is charged per second of the excerpt and shows up in get_cost (ton_fuehrung.cost); it is cached per clip and in/out, a repeat costs nothing. Needs a reference clip and a model with an audio slot; not together with sound references in `referenzen`. keine: no audio reference at all. With ton='quelle' the original mix of the clip — not the stem — is laid back under the result. | |
| ohne_stil_kit | No | true switches the project's default style kit off for this one call. | |
| generate_audio | No | Let the model generate sound with the clip — only models whose lab_list_models entry can output audio take it on this path. Omitted = no generated sound. Generated audio REPLACES any voice in the reference — to keep a spoken take, leave it off. | |
| kamerapfad_url | No | Address of a kamerapfad JSON instead of the object — the url of a file in THIS project (lab_list_assets), e.g. the kamerapfad JSON that Kadrage writes next to its flight video. Fetched by the backend under the same ownership rule as every reference: a file of another project is a named rejection before anything is charged. Mutually exclusive with kamerapfad. | |
| last_frame_url | No | Guiding frame for the END of the new clip (image URL). Same rule as first_frame_url: wan_vace only, rejected elsewhere rather than dropped. | |
| first_frame_url | No | Guiding frame for the START of the new clip (image URL). Only the wan_vace path binds guiding frames to the provider — with any other model the backend REJECTS this field instead of swallowing it, because a swallowed guiding frame means paying for a run identical to the one without it. | |
| dreamer_signatur | No | Proof from the Dreamer (lab_prompt_transform, or the dreamer_fassung of a previous call) that THIS prompt went through it. Without a valid one the tool does not generate: it runs the Dreamer and returns its version first. | |
| duration_seconds | No | Length of the NEW clip. Must lie inside the chosen model's duration grid from lab_list_models — the per-model ceiling is enforced by the backend and rejected rather than silently clamped. | |
| nur_eigene_daten | No | Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only. | |
| raum_beschreiben | No | With depth on, a vision call describes ONLY the room of a still from the reference (place, light, colours, materials — no people) and adds it as a paragraph to the prompt, so a depth run does not come back grey. ON by default; false switches it off. The setting is remembered per project — omit it to use the project's last choice. Skipped automatically when an `ort` reference is given. The answer reports raum.angewandt and the text; metadata.prompt_gesendet holds the prompt as sent. | |
| rechte_bestaetigt | No | REQUIRED when the reference clip or a character image was uploaded (not made in FilmLab), including characters whose sheet comes from an uploaded photo. It stands for this statement by the HUMAN: 'Ich habe die Rechte an Bild und Ton dieses Clips und die Einwilligung der gezeigten Personen.' Never set it on your own — show the human the statement and pass true only after they agreed. Without it the backend refuses with rechte_fehlen before anything is charged; get_cost tells you up front (rechte_noetig). Not needed once the human gave the standing rights statement in the FilmLab app: get_cost then reports no rechte_noetig. Only the human can give that statement, in the app; no tool can. | |
| character_ref_urls | No | Ready image URLs that bind the cast's identity. The name says URLs on purpose: lab_animate's `character_refs` takes character sheet IDS, this path takes ADDRESSES, and the two are not interchangeable. Get them from lab_get_character_sheet. Omit to let the backend use the project's world-bible characters. Mutually exclusive with `referenzen`. | |
| veraltete_figur_ok | No | Exception for a reference clip that was made with an OLDER version of a character: such a clip is refused (figur_veraltet, nothing charged), because the new run would render the figure in its old look. Set it to true ONLY after the human has seen that warning and said yes to going on with the old version — ask first, name the price, wait for the yes; never set it on your own. Default off, and an ordinary call is unchanged without it. The alternative is to re-create the clip with the current version of the figure. get_cost lists figur_veraltet beforehand, so you see whether the refusal threatens. | |
| reference_video_url | No | URL of the clip whose motion is taken. Use the url/video_url a previous answer gave you (lab_add_media, lab_list_assets with asset_type 'video', lab_job_status, lab_review_queue) — never a hand-built address: the bucket is not guessable and a wrong one renders and bills into a 404. An asset_key from lab_add_media (filmlab/projects/<id>/…) is accepted too and turned into a signed address here. Leave it out to run on `referenzen` alone (at least one image reference, no `figur`, no in_sec/out_sec, no depth) — the models that allow it carry referenzen_ohne_video in lab_list_models. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, which only declare a non-read-only, non-destructive write, the description discloses costs credits, preflight behavior via get_cost, server-side excerpt cutting, refusal codes such as figur_veraltet and drittland_dritte_gesperrt, draft restrictions, depth-mask pauses requiring lab_freigeben, and how kamerapfad is translated per model family. This is unusually rich behavioral context for a generation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The opening sentence is front-loaded and clear, but the description is a dense block that packs many caveats, German field names, and cross-references into long sentences. Given the 33-parameter complexity some length is warranted, yet the text could be split into clearer sections and trimmed of redundant asides.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 33-parameter generation tool with no output schema, the description covers the critical operational details: cost preflight, reference clip sourcing, model capability gates, refusal conditions, human approval steps, and the fallback no-reference path. An agent has enough context to call it correctly or route to the right sibling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 adds some workflow context, such as where to obtain reference_video_url and that in_sec/out_sec are cut server-side before provider billing, but most parameter meaning is already documented in the schema itself.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Render a new clip FROM the motion of an existing one,' and immediately explains that the reference clip leads camera move, blocking, and timing while the model restyles the content. It explicitly distinguishes this path from lab_animate's source_video_id and from the no-reference path, so an agent can tell what this tool is for 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: use a reference clip for motion transfer, use get_cost before long takes, use lab_animate instead for a person built from a still, and only use the no-reference mode when the model supports referenzen_ohne_video and references are faceless. It also names when-not conditions such as Seedance 2.5 rejecting faces and the human-only decisions around figur_veraltet and rechte_bestaetigt.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Attach an existing project image (an image_id from lab_umzug, lab_get_job result.bildzeilen or lab_generate) as reference: ziel: 'figur' makes it a view of a character (default view 'detail', the face anchor). personenbezug is REQUIRED for a character and has no default: 'keine_reale_person' or 'reale_person' — the latter needs a likeness_ref from the Likeness Register and turns the character into a digital double, checked before every later generation. ziel: 'location' stores it as the location's reference (viewer, continuity check). It does NOT steer generation — only the description does; beschreibung_ableiten: true derives the description from the image (does not overwrite an existing one unless ersetzen). An occupied character view answers 409 unless ersetzen: true. Free, except the description derivation (one vision call).
| Name | Required | Description | Default |
|---|---|---|---|
| view | No | ||
| ziel | Yes | ||
| ziel_id | Yes | Character id or location id | |
| ersetzen | No | ||
| image_id | Yes | Image id from lab_umzug {bilder}, lab_get_job result.bildzeilen or lab_generate | |
| likeness_ref | No | Character + reale_person only: Likeness Register id | |
| personenbezug | No | Character only, REQUIRED there: does the image show a real person? | |
| beschreibung_ableiten | No | Location only |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds real behavioral context beyond that: a 409 conflict on an occupied character view, that it does NOT steer generation, that beschreibung_ableiten won't overwrite an existing description unless ersetzen is set, the downstream likeness check on every later generation, and the cost profile (free except one vision call).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core action ('Attach an existing project image ... as reference') before branching into the two ziel modes, and every clause carries operational content. It is a dense, near run-on single paragraph, which costs a point on readability but not on waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter, conditional, no-output-schema tool, the description covers mode branching, defaults, required-ness, conflict handling, side effects and cost. It does not say what the call returns (e.g. the updated reference record), a minor gap given no output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema coverage at 63%, the description compensates well: it documents the default view of 'detail' (the face anchor) and the purpose of view values, clarifies that personenbezug has no default and is required for characters, and ties ersetzen to both the 409 bypass and the description overwrite. It adds meaning the schema descriptions alone don't carry.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (attach) and resource (an existing project image as reference) and immediately scopes the two targets, figur vs location. An agent can distinguish it from lab_generate (which creates images) and from lab_generate_character_reference without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains when each ziel branch applies, names the exact upstream tools that produce a valid image_id (lab_umzug, lab_get_job result.bildzeilen, lab_generate), and states preconditions (personenbezug mandatory for characters, likeness_ref for reale_person). It stops short of explicitly routing away from neighbouring generation tools, so 4 rather than 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when the person asks HOW to stage or shoot a feeling or effect (which angle, movement, framing or light makes a scene feel tense, tender, triumphant, uneasy) or wants directing options for a shot. Directing techniques: camera angle, framing, composition, movement, lighting and atmosphere (haze, dust, embers, backlit rain), each with the emotional effect it creates (wirkung), when to use it (zweck_de), when it backfires (vermeiden_de) and a model-neutral prompt fragment (prompt_en). Search by effect (e.g. wirkung=bedrohung, isolation, sehnsucht) to find the ways to get there, then pass up to three schluessel to lab_prompt_transform(techniken) — the fragments are appended verbatim, not rewritten. One angle, one movement, one lighting setup and one atmosphere per shot; framing and composition stack. With handwerk=true it also returns the camera craft: how to state a shot so a model renders it (rules), look-alike pairs with a check sentence each (verwechslungen — e.g. low angle vs Dutch angle, OTS vs POV), focal lengths and the frame boundary of every shot size. Read-only, free.
| Name | Required | Description | Default |
|---|---|---|---|
| gruppe | No | Only one group | |
| wirkung | No | Only techniques with this effect key — the answer lists all keys under `wirkungen` | |
| handwerk | No | Also return the camera craft (rules, look-alike pairs, focal lengths, frame boundaries) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true is already in annotations, and 'Read-only, free' merely restates it without contradiction. The description does add real behavioral context: fragments are appended verbatim, not rewritten; handwerk=true additionally returns craft material (rules, look-alike pairs, focal lengths, frame boundaries); the response exposes the available effect keys under `wirkungen`. With annotations already covering safety, this is solid but not exhaustive (no pagination/volume expectations).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the trigger sentence before the content inventory, and every sentence carries information (what it returns, how to consume the output, composing rules, handwerk extras). It is dense and parenthetical-heavy, though, reading closer to one long run-on block than cleanly separated guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, yet the description names the returned fields (wirkung, zweck_de, vermeiden_de, prompt_en), explains how to consume them downstream, and describes the optional handwerk payload. For a read-only 3-parameter lookup tool, an agent has everything needed to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters, including the handwerk behavior. The description adds useful example values for `wirkung` (bedrohung, isolation, sehnsucht) and hints at `gruppe` semantics via the per-shot categories, but does not elaborate the 'Only one group' constraint beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific retrieval purpose (directing techniques for staging/shooting a feeling) and enumerates the exact resource contents: camera angle, framing, composition, movement, lighting, atmosphere, each with wirkung/zweck_de/vermeiden_de/prompt_en. The effect-key search plus prompt-fragment payload makes it clearly distinguishable from catalog tools like lab_wissen or lab_neue_winkel.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit trigger ('Use when the person asks HOW to stage or shoot a feeling or effect') and a workflow: search by effect, then pass up to three `schluessel` to lab_prompt_transform(techniken). It also states practical composing rules (one angle, one movement, one lighting setup, one atmosphere per shot; framing and composition stack). It stops short of saying when NOT to use it versus a sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
See the DELIVERED film: up to 12 frames from the finished export (lab_start_export → lab_get_export status done), tiled into one image and shown. This is the rendered picture WITH everything the render adds — lens/grade, lower thirds, title cards and the AI badge — so use it to check the result, e.g. 'is the lower third readable at 7 s, does the badge cover anything'. lab_capture shows the cut BEFORE rendering (computed from the timeline, without those layers); this tool shows what was actually delivered. Give sekunden (seconds into the exported film) or verteilt (n frames spread evenly; default 6 when both are missing). A second past the end is an error with the film's length, not a silently clipped frame. Only finished exports with a video (not archive/PNG-sequence profiles). Free (no credits).
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | Export job id from lab_start_export / lab_list_exports — positive integer as string | |
| preview | No | Show the image inline (default true) | |
| sekunden | No | Seconds into the exported film, e.g. [0.5, 7.0]. Order is kept (4 per row) | |
| verteilt | No | Instead of sekunden: this many frames spread evenly over the film | |
| kachel_breite | No | Width of one frame in px (default 480) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare idempotentHint=true and destructiveHint=false but leave readOnlyHint=false unexplained for a tool that mainly renders a preview image; the description fills this gap by stating it renders layers the timeline lacks and is free (no credits). It also adds valuable failure behavior: a second past the end errors with the film's length rather than silently clipping.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose, then prerequisites, sibling contrast, parameters and cost. Dense and mostly earning its place, though the quoted example questions and layered parentheticals push it slightly past what an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description must cover what comes back — it does ('tiled into one image and shown', inline via preview), and it covers scope limits (max 12 frames), cost, prerequisites and error behavior. Nothing needed 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.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3; the description still adds semantics beyond the schema, notably the mutual exclusivity of `sekunden` vs `verteilt` and the default of 6 frames when both are omitted, plus the failure mode for out-of-range seconds.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb and resource: 'See the DELIVERED film: up to 12 frames from the finished export ... tiled into one image and shown.' It names the exact pipeline stage (lab_start_export → lab_get_export status done) and explicitly differentiates itself from the closest sibling lab_capture by contrasting pre-render cut vs delivered render.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use with a concrete example ('is the lower third readable at 7 s, does the badge cover anything'), an explicit when-NOT-to-use route to lab_capture, prerequisites (finished export with video, not archive/PNG-sequence profiles), and the free/no-credit cost note.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restyle an existing board towards a wish (costs credits — exact price via get_cost: true) — same place, different look, e.g. 'the same flat, twenty years later'. Changes the board itself, so images generated afterwards follow the new style. Also the repair path for a board whose prompt_prefix_en is a raw field dump (lab_create_location returned prefix_generated: false): restyle it with a wish like 'keep the place, write a proper image prompt'.
| Name | Required | Description | Default |
|---|---|---|---|
| wish | No | The desired change, in prose | |
| loc_id | Yes | Location board id (from lab_list_locations) | |
| get_cost | No | Free: the exact price of this operation; nothing is rendered or charged. Name it to the person before the real run. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag this as a non-read-only, non-destructive mutation. The description adds important context annotations cannot: it costs credits, exact price is retrievable via get_cost: true, and the change persists so future generations follow the new style. It doesn't quantify credit cost or describe reversibility, but that's largely covered by the get_cost escape hatch.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded and information-dense, but the em-dash interruptions and parenthetical asides ('costs credits — exact price via get_cost: true', the long repair-path clause) make it denser than needed for a three-parameter tool. Every sentence earns its place, but the structure is a bit tangled.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation with no output schema and full schema coverage, the description sufficiently covers cost, persistence of the change, and the repair use case. Return values aren't explained, but with no output schema and full param coverage, the remaining gap is minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 goes beyond by explaining the get_cost parameter's purpose in practice ('Name it to the person before the real run') and by situating 'wish' as the agent's prose instruction, adding workflow meaning the raw schema does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb (restyle) + resource (existing board/location) with an illustrative example ('the same flat, twenty years later') that pins down what restyling means. It also distinguishes itself from lab_create_location and lab_enrich_location_prefix by describing the repair-path use case and the create sibling by name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives two clear when-to-use conditions: general restyling and the specific repair path when lab_create_location returned prefix_generated: false. It doesn't state when NOT to use it (e.g., to create a brand-new place you'd use lab_create_location), so an agent still has to infer the exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Review generated assets: set verdict (accepted|rejected|pending), selected and/or defect tags. Pass ONE id, or ids for a bulk review — after a generation run there are usually dozens to sort, and clicking through them one by one is why the review fields went unused. Rejected assets drop out of the default listings and become prunable. Note: single-id calls make selected exclusive per scene (one chosen variant per scene_ref); bulk calls do NOT, because a bulk over one scene would keep resetting itself and only the last id would stay selected. To record WHAT is wrong, pass tags (see the field) — with or without a verdict; a call with only tags changes no verdict. Tags are written after the verdict: if the tags fail, the verdict stays saved and the answer says so under tags_error. Bulk tagging is not available on a device grant.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Single asset id (positive integer as string). Use this for the per-scene selection | |
| ids | No | Many asset ids for a bulk review (max 200). Mutually exclusive with `id` | |
| tags | No | Defect tags: WHAT is wrong, from a fixed list — independent of the verdict (an accepted asset can carry tags; tags never change verdict or selected). At most 5 per asset. Pass only tags that apply to the asset type (the brackets show where each applies). action_wrong [video/image] — a requested action does not happen or happens differently (also ambient movement such as shadows, lights, crowds); expression_wrong [video/image] — facial expression, gaze or blinking is wrong; camera_motion [video] — the camera moves differently from the request (handheld shake or push-in missing, wrong direction); framing [video/image] — shot size, angle, horizon or position in the frame differs from the request; colour_shift [video/image] — colour or light differs from the request or jumps; wrong_count [video/image] — wrong number of people or things (e.g. fewer extras than asked); missing_element [video/image] — a requested object or detail is not there; identity_drift [video/image] — face, wardrobe or build differs from the reference; wrong_place [video/image] — the place or layout does not match; anachronism [video/image] — something from the wrong era in a period setting; extra_people [video/image] — a person who is not part of the cast; text_wrong [video/image] — requested text is wrong or unreadable; anatomy [video/image] — hands, limbs or face are distorted; artifacts [video/image] — flicker, distortion, watermark, logo or a visible seam; frozen [video] — the picture freezes; continuity_jump [video] — the join at a cut or chained clip jumps; lip_sync [video] — lips do not match the sound; audio_wrong [video/sound] — sound is missing, jumps or does not fit; other [video/image/sound] — anything else — put the detail in `reason`. | |
| reason | No | Why — stored as verdict_reason, useful when reviewing a rejection later | |
| verdict | No | Acceptance verdict. Feeds the acceptance telemetry (which provider/mode/price actually produced usable shots) | |
| selected | No | Mark as the chosen variant | |
| tags_mode | No | add (default): add to the tags this person already set on the asset. replace: set exactly these tags (an empty list clears them). Only the caller's own tags are touched, never another person's or the machine tags. | |
| reference_type | Yes | What kind of asset these ids refer to |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavior beyond the annotations: rejected assets drop out of default listings and become prunable, single-id selection is exclusive per scene while bulk selection is not, tags are written after the verdict with partial-failure reporting under `tags_error`, and bulk tagging is unavailable on a device grant. These are exactly the operational details an agent needs before invoking a mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action and bulk/single distinction, and most sentences carry operational information. It is somewhat long and includes a motivational aside about clicking through assets one by one, but the detail is mostly justified by the complexity of the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex mutation tool with no output schema, the description covers the important behavioral caveats: selection semantics, bulk limitations, tag write ordering, and partial failure. It does not fully describe the response shape beyond `tags_error`, but overall it gives enough context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all eight parameters thoroughly. The description still adds valuable cross-parameter semantics, especially the single-id `selected` exclusivity versus bulk behavior and the rule that tags alone change no verdict. It does not add much beyond the schema for parameters like `reason` or `reference_type`, so a 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: review generated assets and set verdict, selected state, and defect tags. It immediately distinguishes single-id review from bulk review via `ids`, so an agent can understand the tool's scope 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear usage context: pass one `id` for per-scene selection, or `ids` for bulk review after a generation run where dozens of assets need sorting. It also explains that tags can be passed with or without a verdict. It does not explicitly name sibling alternatives such as lab_review_queue, so it falls 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.
Browse GENERATED rows (images or videos) — newest first, each with the INPUTS it ran on. Every row carries inputs[] (start/reference images, reference videos, character refs — role + url) and params (model, mode, resolution, seed…). Read those before comparing two runs: a run without its inputs is a claim with a picture attached, and a comparison described as one-variable has more than once turned out to differ in three. An input whose URL was never recorded appears as origin: 'unrecorded' — that is a gap in the write path, NOT a text-to-* run.
Two modes. PER PROJECT (pass project_id + type): adds the review filters — verdict, selected_only, scene_ref — and carries selected. ACROSS PROJECTS (omit project_id, or pass since/until/tool_used/cursor): the time-range view for 'what ran on August 3rd?'. The review filters do not exist there and are rejected rather than silently dropped. Page with next_cursor.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Which generated rows. Required per project; across projects, omit for both | |
| limit | No | Max rows (per project default 50). Across projects the page is capped at 20 so next_cursor stays exact | |
| since | No | ACROSS PROJECTS. created_at >= this ISO-8601 timestamp (e.g. 2026-08-03T00:00:00Z) | |
| until | No | ACROSS PROJECTS. created_at <= this ISO-8601 timestamp | |
| cursor | No | ACROSS PROJECTS. The next_cursor of the previous page. Opaque — do not build one by hand | |
| preview | No | Attach the pictures themselves, downscaled to 512px, so a generation run can be SORTED by looking instead of by reading prompts. At most 4 per call — narrow the list with scene_ref/limit rather than expecting more. Rows without an image URL (all videos) are named in preview.notes, not silently dropped. | |
| verdict | No | PER PROJECT ONLY. Exact verdict filter. Omit to get everything except rejected | |
| scene_ref | No | PER PROJECT ONLY. Only this scene | |
| tool_used | No | ACROSS PROJECTS. Exact tool/provider name, e.g. seedance-2.5 | |
| project_id | No | Project id (from lab_list_projects). Omit to search across all projects | |
| selected_only | No | PER PROJECT ONLY. Only the chosen variants | |
| include_rejected | No | PER PROJECT ONLY. Include rejected in the default listing |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint already covering the safety profile, the description adds substantial non-obvious behavior: rows carry inputs[]/params, `origin: 'unrecorded'` signals a write-path gap rather than a text-to-* run, review filters are rejected in cross-project mode, and pagination uses next_cursor. These are behavioral traits an agent would otherwise get wrong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded and information-dense, with the two-mode split clearly separated by a paragraph break. The aphoristic aside about runs and pictures is memorable but stylistically heavier than the rest, slightly blunting conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 12-parameter tool with no output schema, the description covers the return shape (inputs[] with role+url, params, selected, next_cursor, preview.notes) and the limits (page cap of 20 across projects, 4 previews). Nothing needed to call or interpret the call is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 goes further by explaining the cross-parameter interaction that selects the two modes and the meaning of unrecorded origins. It does not add format or syntax detail beyond the schema for individual fields, so it stops short of 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise verb+resource+ordering ("Browse GENERATED rows (images or videos) — newest first, each with the INPUTS it ran on") and distinguishes the two operating modes. An agent can tell this apart from list/asset tools like lab_list_assets or lab_review_asset by the generation-row scope and input-join behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly partitions into PER PROJECT vs ACROSS PROJECTS modes with selection criteria for each ("what ran on August 3rd?"). It also names the consequence of using the wrong filters ("rejected rather than silently dropped") and points to lab_list_projects as the source of project_id.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The Montage recipe: one recurring character in 8–16 independent everyday gags, cut on the beat into a 9:16 reel of about 6–11 seconds with a music bed. It runs the existing steps in order — gags (lab_situationen), stills with the character and the phone-flash look (auto-storyboard 9:16), identity check with ONE retry per deviating still, a STOP until the human accepts the stills (lab_review_asset), music, sequence, beat grid and rhythm, beat-length clips, placing them, export (social_vertical). If the export contains a synthetic PERSON or VOICE, it needs a release only a signed-in human can give: the recipe STOPS with stopp freigabe_noetig — the human exports that sequence with social_vertical in the web app and confirms the wording; the next weiter takes over that export and checks it. Each call with aktion weiter does exactly ONE step and stores the state in the project, so an interrupted run continues where it stopped; call it again until phase is fertig. MONEY: aktion preis (or get_cost) returns the expected and the maximum price per item and a recommended cap — free. Paid steps run only inside a released lab_auto_lauf (lauf_id) and the recipe checks its free amount before every paid step. The character must already have a sheet with a reference image (lab_create_character with gattung, then lab_generate_character_reference) — it is not part of the price. aktion stand shows the state, abbrechen deletes it (generated material stays).
| Name | Required | Description | Default |
|---|---|---|---|
| bpm | No | Start only: tempo written into the default music prompt (default 120) | |
| thema | No | Start only: theme or setting for the gags, e.g. 'big city at night' | |
| aktion | Yes | preis: price per item; weiter: one step; stand: show state; abbrechen: delete the state | |
| anzahl | No | Number of gags and shots, 8–16 (default 10) | |
| lauf_id | No | Released auto run (lab_auto_lauf) whose cap pays for the steps — required for paid steps | |
| figur_id | No | Start only: character sheet id with a reference image — positive integer as string | |
| get_cost | No | Same as aktion preis — nothing is generated or charged | |
| project_id | Yes | Project id (from lab_list_projects) — positive integer as string | |
| situationen | No | Start only: your own gags instead of suggested ones (e.g. picked from lab_situationen) | |
| musik_prompt | No | Start only: music prompt; default is an instrumental groove with a steady beat |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavior beyond the annotations: persisted state, resumability, one-step-per-call execution, a human STOP for stills review, release requirements for synthetic person or voice, and paid-step gating through lab_auto_lauf. It also clarifies that abbrechen deletes recipe state while generated material remains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The overview is front-loaded and every part carries relevant workflow, money, or safety information. It is dense and run-on in places, but the length is justified by the complexity of the recipe and it avoids obvious filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complex multi-step workflow, lack of output schema, and minimal annotations, the description supplies the critical state-machine, cost, prerequisite, and human-release details needed to invoke the tool correctly. It explains the important return semantics for preis and stand sufficiently for an agent to proceed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description still adds useful semantics for aktion, get_cost, lauf_id, and figur_id, especially by explaining weiter as one step, preis/get_cost as free cost lookup, and paid steps as requiring a released lauf_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific orchestration purpose: producing a Montage reel from 8–16 gags with a recurring character, beat-cut 9:16 output, and named downstream steps. It distinguishes this recipe from sibling capabilities by naming lab_situationen, lab_review_asset, social_vertical, lab_auto_lauf, and character-generation prerequisites.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly explains the operating loop: each aktion weiter performs exactly one step, state is saved, and the caller repeats until phase is fertig. It also gives prerequisites and payment constraints, but it does not explicitly contrast this recipe with alternative workflow tools beyond naming the internal steps it runs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run ONE pipeline module for a project (context is injected from upstream modules + crew agents). SYNCHRONOUS and LLM-heavy: light modules return in seconds; heavy ones can exceed ~55s and then time out (504) — run those in the FilmLab web app instead. Pass an invalid module name to get the list of valid module keys. Returns the module output.
| Name | Required | Description | Default |
|---|---|---|---|
| module | Yes | Pipeline module/stage key, e.g. mod_concept, mod_storyboard, mod_shotlist, mod_script | |
| message | Yes | Your instruction/prompt for this module (the user turn in the module chat) | |
| project_id | Yes | Project id (from lab_list_projects) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false / destructiveHint=false; the description adds substantial context beyond that — synchronous blocking execution, LLM-heavy latency variance, the 504 timeout ceiling, upstream context injection, and a non-obvious discovery trick. It does not say whether module output is persisted to the project or what happens on re-run, which is the main remaining behavioral gap for a non-read-only tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tight sentences, front-loaded with the core action and scope, then execution characteristics, then the fallback, then the discovery trick. No filler, no repetition of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description at least states that the tool returns the module output, and it covers sync/timeout/call-shape concerns thoroughly. A brief note on what that output contains (text, structured artifact, or job handle) or whether it mutates project state would close the last gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description adds real value on the 'module' parameter by teaching how to enumerate valid keys (send an invalid one) and clarifies that 'message' is the user turn in the module chat, plus notes project_id provenance. It stops short of anything beyond that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource+scope: 'Run ONE pipeline module for a project', and immediately qualifies it as synchronous and LLM-heavy with context injected from upstream modules and crew agents. This is clearly distinguishable from sibling tools like lab_run_proposal or lab_generate, which the description implies are different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use/when-not: light modules are fine, but heavy modules exceeding ~55s will 504 and should be run in the FilmLab web app instead. It also gives a discovery path — pass an invalid module name to get the list of valid module keys — which removes any need to guess or ask.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a proposal exactly as shown — same model, same parameters, same price. Called by the card's button, or by you after the user confirmed. Single use: the proposal is consumed BEFORE the run, so a second call is refused instead of paying twice. Valid 15 minutes, for the account that created it. Costs credits. The run is checked against what you confirmed only when it FINISHES; poll lab_job_status and read review there. This answer carries review only if the run completed synchronously.
| Name | Required | Description | Default |
|---|---|---|---|
| vorschlag_id | Yes | The id from lab_propose or plan_b in lab_job_status. Do not construct one — an unknown id answers 'vorschlag_abgelaufen', not an error you can work around. | |
| ohne_keyframe | No | Skip the keyframe checkpoint on purpose. By default a paid clip only starts from a start image the user has approved (lab_review_asset verdict: accepted) — look at the frame first, then spend on the clip. Set true only when the user explicitly asked to skip the frame check. | |
| prompt_override | No | Replace ONLY the prompt text of the stored proposal. Every other parameter — model, resolution, duration, references — and the price stay exactly as shown. This is the path for a prompt the user edited on the card: the price does not depend on the text, so no new proposal is needed. Standbild-Bewegung uses no model prompt; confirm that proposal unchanged. An edited text goes through the Dreamer first: without a matching dreamer_signatur the call does NOT run, the proposal stays valid, and the answer carries the Dreamer version to confirm. | |
| dreamer_signatur | No | Dreamer proof for prompt_override (from the previous answer's dreamer_signatur). | |
| nur_eigene_daten | No | Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, it discloses consumption-before-run, refusal on a second call, 15-minute expiry, account binding, cost, and that review is available only at finish or synchronously. These are the high-stakes behaviors an agent needs before invoking a paid, single-use operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is front-loaded with the action and the critical single-use behavior, and each sentence adds a constraint or next step. There is no filler; it is dense but appropriate for a paid, single-use operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the lifecycle and async follow-up, but with no output schema it only partially describes the answer shape when the run is asynchronous: 'poll lab_job_status' implies a job identifier without stating what comes back. The rich parameter schema compensates for parameter-level details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter already explains vorschlag_id, ohne_keyframe, prompt_override, dreamer_signatur, and nur_eigene_daten. The description reinforces proposal immutability but does not add per-parameter meaning beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a specific verb ('Run') and resource ('a proposal'), and the qualifiers 'same model, same parameters, same price' plus 'single use' make it distinct from proposal-creation or general generation tools. It clearly frames execution of an already-created proposal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It says the tool is invoked by the card button or by the agent after user confirmation, and it sets hard constraints: single use, consumed before the run, 15-minute validity, account-bound, and credit cost. It also routes async follow-up to lab_job_status.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export ONE sequence as an editing file for DaVinci Resolve, Premiere or Final Cut, so the cut can be finished there. Costs nothing. fcpxml (recommended for Resolve): V1 as the main storyline with gaps, the sequence's transitions as centered cross dissolves (dropped where the next clip has no head or at a gap), audio stems and V2+ as connected clips. otio: OpenTimelineIO JSON (video and gaps, speed; no audio, no transitions). edl: CMX 3600 (video plus up to 4 audio channels; no transitions). For Premiere Pro use edl: Premiere does not read fcpxml, and OTIO import is only available in Premiere Pro Beta. The EDL carries no paths (relink by clip name) and no transitions. The answer carries the whole file in inhalt and a file name — write it to disk for the person. Media are referenced by their FilmLab URLs: in Resolve, File > Import > Timeline, then relink offline clips by file name.
| Name | Required | Description | Default |
|---|---|---|---|
| format | Yes | fcpxml for Resolve/Final Cut (carries transitions), otio for OpenTimelineIO tools, edl as the lowest common denominator | |
| seq_id | Yes | Sequence id (from lab_list_sequences/lab_get_sequence) — positive integer as string |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say readOnlyHint=true; the description adds substantive behavior: it costs nothing, the whole file comes back in `inhalt` with a filename to write to disk, media are FilmLab URLs needing relink by clip name, plus per-format lossiness (EDL no paths/transitions, otio no audio). That is real operational context beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose and cost, then format trade-offs, then the procedural relink note. Dense but nearly every sentence carries actionable content; the trailing Resolve relink instructions push it slightly toward long, but nothing is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by describing the return payload (`inhalt` + filename) and the relink workflow. For a 2-parameter read-only export tool, an agent has everything needed to call it and deliver the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description still earns above-baseline by explaining what each enum value actually yields (fcpxml carries transitions as centered cross dissolves, edl carries up to 4 audio channels, otio drops audio/transitions). seq_id semantics are left to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete verb+resource+scope: 'Export ONE sequence as an editing file' for three named NLEs, with the goal (finish the cut there). This is unmistakably distinct from generation/export siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Excellent format-selection guidance: fcpxml recommended for Resolve, edl for Premiere (with the reason: no fcpxml support, OTIO only in Beta), otio for OpenTimelineIO tools. It stops short of routing between sibling tools (lab_start_export, lab_get_export, lab_stems_export), so it doesn't fully answer 'when this tool vs. those'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Measure ONE clip of the edit as numbers instead of a picture: a frame is rendered through the clip's export path (input profile, grade LUT, secondary correction) and measured — luma percentiles (P1/P50/P99, Rec.709), mean R/G/B, green excess (G minus the mean of R and B: >0 green cast, <0 magenta), vectorscope centroid (Cb, Cr), clipped highlights and crushed shadows. befund says what is off in words with the number; vorschlag.grade is a correction computed on a sample of the source through the clip's full grade (gamma wheel master first, then exposure, temperature, tint, gain wheel) towards median luma 0.42 and no cast WITHOUT pushing highlights into clipping, with the values it expects — pass it to lab_grade_clip, then measure again. When nothing more is gained, vorschlag.grade is null and grund says why. Give clip_id (from lab_grade_clip without grade) or zeit_s (seconds on the timeline); default is the middle of the clip. Writes nothing, costs nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| seq_id | Yes | Sequence id — positive integer as string | |
| zeit_s | No | Timeline position in seconds (picks the clip there; within a clip_id: the frame) | |
| clip_id | No | Clip to measure |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description reinforces this with 'Writes nothing, costs nothing.' Beyond that it discloses substantive behavior: the frame is rendered through the clip's export path (input profile, grade LUT, secondary correction) and the correction is computed on a sample of the source through the full grade toward median luma 0.42 without pushing highlights into clipping. This is rich context the annotation alone does not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the purpose and efficient overall, but the middle sentence is a dense, jargon-heavy run-on (befund, vorschlag, grund interleaved with grading parameters) that would scan faster as a short list. Every sentence still earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description carries the return-value burden and largely meets it, explaining befund, vorschlag.grade, grund, and the measured quantities. The stopping condition is covered; the exact output field structure could be spelled out further, keeping it just short of fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 adds genuine meaning beyond the schema: clip_id comes 'from lab_grade_clip without grade', zeit_s is seconds on the timeline, and the default with neither is the middle of the clip — details absent from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise verb+resource+scope: 'Measure ONE clip of the edit as numbers instead of a picture,' and specifies exactly what is measured (luma percentiles, mean R/G/B, green excess, vectorscope centroid, clipping). It also implicitly distinguishes itself from the write-side sibling by directing the resulting vorschlag.grade to lab_grade_clip.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lays out the intended workflow loop: pass vorschlag.grade to lab_grade_clip, then measure again, and stop when vorschlag.grade is null. This is clear context for when to use it, though it never explicitly names an alternative measurement tool (e.g. lab_mix_messen) or states when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the FilmLab universe catalog of AI tools, news and companies. Query must be at least 2 characters. Returns up to 20 matches with a total count.
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Search query, min 2 characters |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so safety is covered, but the description adds useful behavioral context: the result cap of 20 matches and the inclusion of a total count. It does not describe pagination beyond that cap or any rate limits, so it stops short of full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with zero waste: purpose first, then the input constraint, then the output shape. Every sentence carries distinct information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only search, the description covers the resource, the input constraint, and the return behavior (up to 20 matches plus a total count) even without an output schema. Nothing needed to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single parameter 'q' already documents its minLength in the schema. The description repeats 'Query must be at least 2 characters' without adding syntax, format, or matching-behavior detail, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Search') and resource ('FilmLab universe catalog of AI tools, news and companies'), which no sibling tool duplicates. An agent can identify this as the catalog-search tool 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives constraints (min 2 characters, up to 20 results) but no when-to-use guidance, no when-not-to-use, and no named alternatives among the many lab_* siblings. The agent must infer that this is for catalog lookup rather than, say, lab_wissen or lab_dossier.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate or CLEAN UP a SOUND track other than music — sound effects, ambience/atmosphere, dialog, a voiceover, FOLEY scored to an existing clip, or the repair kinds that take an EXISTING recording apart instead of inventing one: denoise (take the noise out), split (separate it into stems), isolation (keep the voice, drop the rest). All of it goes through the same audio pipeline as lab_generate_music. ASYNCHRONOUS: the call returns immediately with a row whose audio_url is null and metadata.status is 'pending'. Nothing is playable yet. Poll lab_list_audio (matching audio_type) until that row's status is 'completed' and audio_url is set; a failed row refunds its credits and carries metadata.error. The backend picks the provider for the chosen art on its own — there is no tool parameter here.
| Name | Required | Description | Default |
|---|---|---|---|
| art | Yes | Kind of track — sfx (a single sound effect), ambience (a continuous atmosphere/soundscape), dialog (a spoken line), voiceover (narration), foley (sound derived FROM an existing clip and synced to what happens in it — needs `video_id`, ignores `duration_seconds`, and takes its length from the source). The repair kinds work on a recording you already have and need exactly one source (`audio_id`, `video_id` or `audio_url`), never a prompt: denoise (take out hiss, hum and room noise), split (separate the recording into stems — one audio row per stem), isolation (keep only the voice, drop room, noise and music). Their length follows the source, so `duration_seconds` is ignored. Not 'music' — that stays lab_generate_music, it binds a different stem | |
| stems | No | SPLIT ONLY: which parts to separate out. Left out, you get the voice and the rest of the recording, each part as its own audio row. Asking for a subset drops what you leave out — there is no combined everything-but-the-voice file, that would be a mixdown the provider never made. | |
| prompt | No | What the sound should be. For sfx/ambience: name the source and character of the sound. For dialog/voiceover: the line or text to speak. Required for every art EXCEPT foley — foley watches the clip, so leaving it empty means 'take what you see', and a prompt merely steers it | |
| audio_id | No | REPAIR KINDS ONLY, and the best of the three ways to name a source: an existing audio row of this project (from lab_list_audio), which has an owner and an address that belongs to us. Chain it — denoise a row, then split the result. The row must already carry an audio_url; a pending one has no file yet. | |
| get_cost | No | `true` reports the price and your balance WITHOUT generating anything and without spending quota. Not drawn from the lab_list_models catalog (that covers image/video models only) — audio pricing follows the provider FilmLab picks for `art`, and each kind is billed by its own unit: per run, per second, or per character. For the spoken kinds the price follows the length of your text, which the cost endpoint cannot take: the answer then names the provider and your balance and reports `cost_generations` as null rather than inventing a number — the real amount comes back with the call. | |
| video_id | No | The clip to work from. For FOLEY it is required to RUN one; for the repair kinds it is one of the three ways to name a source, and the backend extracts the audio track from it. From lab_list_assets or the row an animate call returned; the clip must belong to this project. The backend measures its length and rejects sources it will not process, before anything is charged. A price question (`get_cost: true`) does NOT need it — the price follows a length, not a particular clip. | |
| audio_url | No | REPAIR KINDS ONLY, and the last resort: a bare address of a sound file. It carries no owner, so nothing can be checked against the project — prefer `audio_id` or `video_id`. A provider address is copied into our own storage first, and if that fails the call is refused rather than stored with a deadline. | |
| scene_ref | No | Optional scene label, stored on the row. Useful to tell several tracks of one project apart | |
| project_id | Yes | Project id (from lab_list_projects) — positive integer as string | |
| duration_seconds | No | Desired length in seconds. The backend clamps this to what the chosen provider actually supports for this `art` — dialog/voiceover ignore it entirely, the length follows the text, and foley ignores it too, its length follows the clip. The repair kinds ignore it as well: you clean up a file, not a stretch of it. One exception, and only for asking: in a `get_cost` query on foley or a repair kind, naming it prices THAT length instead of the ceiling. There is no lab_list_models entry for audio: the provider isn't a choice you make here, it's picked automatically per `art`. | |
| nur_eigene_daten | No | Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only. Matters only for the repair kinds: a source recording can carry voices. Text-to-sound never needs it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false and destructiveHint=false, so the description carries the burden and does it well: it discloses the asynchronous contract (row returned with audio_url null, status 'pending'), the credit refund on failure with metadata.error, and that no `tool` parameter exists because the backend picks the provider per `art`. The one residual gap is that it doesn't quantify expected latency or poll cadence, though it does name the polling tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then async lifecycle, then provider note — a sensible order. Dense and every clause is load-bearing, though the heavy capitalization and triple enumeration of the repair kinds make it longer than strictly necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter, no-output-schema, credit-spending generation tool with minimal annotations, the description supplies what's required: the async return shape, the polling loop, the failure/refund semantics, and the provider-selection rule. An agent could invoke and follow up correctly from this text alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the per-parameter docs are already exhaustive, so the description's parameter contribution is limited to reinforcing the art-vs-music boundary and stating there is no `tool` parameter. Baseline 3 is appropriate since the schema, not the description, does the semantic heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource ('Generate or CLEAN UP a SOUND track other than music') with the full enumeration of kinds (sfx, ambience, dialog, voiceover, foley, denoise, split, isolation). It explicitly excludes music and routes it to lab_generate_music, so the agent can distinguish it from the nearest sibling 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use (generate vs repair kinds), when-not ('Not music — that stays lab_generate_music'), and what to do after the call (poll lab_list_audio matching audio_type until completed). It also names get_cost as the price-check route without generating.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read how far each shotlist shot (sb_N) of a project is covered — takes, the chosen take, the bound characters and location, and where it sits in the cut. Per shot: takes_bild / takes_clip (counts), gewaehlt (the chosen take, or null), referenzen (characters and location planned vs. actually bound), im_schnitt (clips in the sequence and how that was established) and luecken, which names what is still missing. kopf totals it up: shots overall, with a clip, with a chosen take, in the cut. A clip in the sequence WITHOUT a proven shot does not count as coverage — it is reported in kopf.clips_im_schnitt_ohne_shot. Clips nobody has reviewed yet count as takes_clip, never as gewaehlt. A project without a shotlist answers with kopf.hinweis = 'keine_shotliste' and no shots: that is a finding, not an error. Costs nothing, writes nothing — one read. NOT lab_shots: that one reads the shot layer of a sequence (which clips form one cut shot); this one reads the shotlist shots of the project and whether each has material.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project id (from lab_list_projects) — positive integer as string |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=true; the description adds real behavioral context beyond that: 'costs nothing, writes nothing — one read', the counting rule that unreviewed clips count as takes_clip but never as gewaehlt, and that an unproven shot in the sequence is excluded from coverage and surfaced separately. These are non-obvious semantics an agent cannot infer from the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and scope are front-loaded, and the field-by-field enumeration is justified because there is no output schema to carry it. The density of German field names makes it heavy, but each sentence contributes either a return shape or a counting rule, so little is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, this description carries the full burden and does so: it documents every returned section (takes_bild/takes_clip, gewaehlt, referenzen, im_schnitt, luecken, kopf) plus the aggregation fields. Given a single trivial parameter and read-only behavior, an agent has everything needed to call and interpret it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single project_id parameter is fully documented (including the lab_list_projects provenance), so the description need not repeat it. The description still adds meaning about what values the id can designate, e.g. a project with no shotlist is a valid input returning kopf.hinweis='keine_shotliste'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Read how far each shotlist shot ... is covered') and enumerates the concrete dimensions of coverage (takes, chosen take, bindings, cut). It also explicitly distinguishes itself from the nearest sibling, lab_shots, so an agent can separate the two without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The closing sentence names the alternative tool and the exact condition that selects between them: lab_shots reads the shot layer of a sequence, this one reads project-level shotlist shots and their material. It also clarifies the legitimate empty-case (no shotlist = a finding, not an error), which prevents misuse as an error path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the SHOT layer of a sequence — which clips form one shot, which scene it plays in, who is in it, and what the continuity pass found. This is the layer above the timeline: lab_get_sequence gives you clips in a row, this one gives you the cut. Costs nothing, writes nothing. Use it before changing a cut: a shot binds clip_ids, so the times come out of the timeline and a shot whose clips you shorten simply gets shorter. Read clips_ohne_shot as well — it says how far the meaning lags behind the timeline, and an empty shots list usually means nobody has derived them yet (lab_shots_ableiten does that, for free). Every shot reports clips_verwaist (clip_ids that no longer exist in the timeline) and zusammenhaengend (false when another shot's clip sits between this one's): a torn shot is allowed — one location cut into twice — but it says so, instead of showing a duration longer than the sum of its clips.
| Name | Required | Description | Default |
|---|---|---|---|
| rung | No | Which level to read. 'shot' (the default) is one take; 'movement' groups shots into arcs. They are independent layers over the same clips — reading one never shows the other | |
| seq_id | Yes | Sequence id (from lab_create_sequence/lab_list_sequences) — positive integer as string |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say readOnlyHint=true; the description goes well beyond, promising 'Costs nothing, writes nothing' and explaining non-obvious semantics: shots bind clip_ids so shortening a clip shortens the shot, torn shots are permitted, and empty results mean derivation hasn't run. This is exactly the behavioral context annotations can't carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Dense but front-loaded: purpose, cost, and usage come first. Every sentence carries information, though the closing clauses about continuity and torn shots are heavy and slightly rambling for the payoff they deliver.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description carries the return-value burden and does so: it names and explains clips_ohne_shot, clips_verwaist, zusammenhaengend, and the shots list. An agent knows what it will get and how to interpret edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the `rung` enum is already fully documented in the schema, including the shot-vs-movement distinction. The description discusses shot semantics but adds little about the two parameters themselves, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource: 'Read the SHOT layer of a sequence — which clips form one shot, which scene it plays in, who is in it.' It explicitly distinguishes itself from the sibling lab_get_sequence ('gives you clips in a row, this one gives you the cut'), 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States when to use it ('Use it before changing a cut'), names the contrasting sibling (lab_get_sequence) and the derivation tool (lab_shots_ableiten). It also flags the empty-`shots` condition that routes the agent elsewhere. Alternatives and the trigger condition are explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Derive the shot layer from what the clips already say about themselves — consecutive clips of the same scene become one shot, and a scene that returns later becomes a second one (one location cut into twice is two shots). Costs nothing: it groups rows and reads titles, it generates nothing. Titles come from the project's shotlist where the scene is in there, so this is more than a regrouping — it fetches meaning the pipeline already produced. SHOTS YOU SET BY HAND SURVIVE. Only derived ones are replaced, and clips already held by a manual shot are left out of the grouping entirely — a derivation does not take handwork's material away. Read clips_ohne_szene in the answer: those clips say nothing about where they belong, so each became its own shot. That number is a job for the pipeline, not a fault of this call — and grouping two nameless clips would be a claim about connection that nobody made.
| Name | Required | Description | Default |
|---|---|---|---|
| seq_id | Yes | Sequence id (from lab_create_sequence/lab_list_sequences) — positive integer as string |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by defining the mutation boundary precisely: only derived shots are replaced, manual shots and their clips are excluded from grouping, and no generation/compute occurs. That is exactly the information an agent needs before invoking a non-readOnly, idempotent operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core rule is front-loaded, but the text is prose-heavy and padded with editorializing ('a claim about connection that nobody made', 'a job for the pipeline, not a fault of this call'). The valuable clips_ohne_szene explanation is buried near the end.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully explains the one response field (clips_ohne_szene) and its meaning, and covers preservation semantics. It leaves minor gaps such as preconditions (e.g., must clips already exist) and the returned shape overall.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single seq_id parameter is fully documented in the schema (100% coverage, including its source tools), and the description adds nothing about it. Baseline 3 is appropriate when the schema carries all parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (derive the shot layer) and spells out the grouping rule — consecutive same-scene clips merge, a returning scene yields a second shot. It implicitly separates itself from lab_shots_setzen via 'SHOTS YOU SET BY HAND SURVIVE', but never names that sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clear context for when the call applies: clips must carry scene information, and clips without it come back in clips_ohne_szene rather than being grouped. It stops short of an explicit 'use lab_shots_setzen instead for manual shots' routing statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
State the shot cut yourself: which clips form one shot, what it is called, which scene it plays in. This is the counterpart to lab_shots_ableiten — that one groups by the scene the clips already name, this one is for the judgement no field carries. Costs nothing. Use it where derivation cannot reach: ingested footage has no shotlist by nature, and a sequence whose clips name no scene would come out of a derivation as one shot per clip — the timeline under another name. It is also the ONLY way to build the 'movement' layer (arcs over shots); the derivation only ever writes 'shot'. REPLACES the whole level in one go: every shot of this rung that you do not list is gone. The other level is untouched — recutting shots does not throw the arcs away. Refusals happen BEFORE anything is written: an unknown clip_id, or the same clip in two shots of one level. A half-set shot list looks like a result and is none. Read lab_shots first and send its clip_ids back — a shot binds clip identities, not time ranges, so shortening a clip later simply shortens the shot. What you set here counts as handwork: a later lab_shots_ableiten leaves these shots alone and does not touch their clips.
| Name | Required | Description | Default |
|---|---|---|---|
| rung | No | Which level to replace. 'shot' (the default) is one take; 'movement' groups shots into arcs. Independent layers over the same clips — writing one never touches the other | |
| shots | Yes | The whole level, in order. The order here IS the order of the shots | |
| seq_id | Yes | Sequence id (from lab_create_sequence/lab_list_sequences) — positive integer as string |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false, but the description goes further: it states the whole level is replaced atomically ('every shot of this rung that you do not list is gone'), that refusals fire before any write, that the other rung is untouched, and that hand-set shots survive later derivation. This is strong disclosure, though return/response shape is not described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and the sibling contrast are front-loaded, and most sentences earn their place. It is slightly long with some aphoristic asides ('Costs nothing', 'A half-set shot list looks like a result and is none') that add tone more than information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, atomic, layer-scoped mutation tool with no output schema, the description covers replacement semantics, atomic refusal, layer independence, ordering, and persistence across later derivation. Nothing an agent needs to call it safely is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 genuine semantics beyond the schema: clip_ids bind clip identities rather than time ranges (so trimming a clip later shortens the shot), and the two rungs are independent layers. That meaning is not carried by the field descriptions alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a concrete verb and resource: state the shot cut yourself, defining which clips form one shot, its name, and its scene. It explicitly names the sibling it contrasts with (lab_shots_ableiten) and the level it operates on, so an agent can distinguish it without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use ('where derivation cannot reach: ingested footage has no shotlist'), when-not (derivation's scope), and the exclusive capability ('the ONLY way to build the movement layer'). The alternative tool is named with the condition that selects it, leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Suggest independent visual gags for a character and theme. Free text generation, no images or credits spent. Returns anzahl entries with titel, bild_en and bewegung_en: one moment and one strong action each, no story sequence or references between entries. figur accepts a character-sheet id (uses its prompt_prefix_en) or a free-text character description. Select 8–16 suggestions for lab_auto_storyboard with figur_id.
| Name | Required | Description | Default |
|---|---|---|---|
| figur | Yes | Existing character-sheet id or free-text character description | |
| thema | Yes | Theme or setting for the independent gags | |
| anzahl | No | Number of suggestions, default 20 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds meaningful behavior beyond readOnlyHint: 'Free text generation, no images or credits spent' and describes the returned entry fields and their semantics. It does not discuss latency, determinism, or limits beyond those in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Dense but front-loaded: purpose first, cost/no-credits note second, return shape third, parameter behavior fourth, downstream usage last. Every sentence carries actionable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by naming the return keys (titel, bild_en, bewegung_en) and their semantics ('one moment and one strong action each'). Combined with the cost note and downstream usage, an agent has enough to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds real meaning for 'figur': it accepts a character-sheet id and uses that sheet's prompt_prefix_en, or a free-text character description, going beyond the schema's brief text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Suggest independent visual gags for a character and theme.' It also explicitly distinguishes the output from a story sequence ('no story sequence or references between entries'), which differentiates it from downstream storyboard siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear downstream use case: 'Select 8–16 suggestions for lab_auto_storyboard with figur_id.' It also clarifies intended output scope ('no story sequence'), but does not explicitly name when not to use it or compare against other ideation siblings beyond the downstream link.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read or set where a project's generated material is kept. With project_id only: read. 'cloud' keeps it in FilmLab's private storage (default). 'lokal' and 'server' keep it private until publication: FilmLab only parks each new file for pickup, the local FilmLab bridge (DaVinci Resolve panel, FilmLab Drop for Final Cut Pro, Avid and Premiere Pro, or filmlab_abholen in the local bridge MCP) stores it on this computer ('lokal') or the studio's shared storage such as a NAS or Avid NEXIS ('server'), checks it and confirms. FilmLab keeps a private working copy (never public, signed access only) so export, sound mix and chains keep working, and deletes it when the project is closed with abschliessen: true, or when the period ends. Use 'lokal' or 'server' whenever the person wants generated material to stay off the cloud until release. The change applies to material generated from now on. abschliessen: true (only after the person confirms the project is finished or published) deletes all working copies at FilmLab; it is refused while files are still waiting for pickup unless auch_offene: true, which deletes those for good. The answer carries speicherort, privat, offen (files still waiting for pickup), arbeitskopien (copies FilmLab still holds), abholfrist_tage (after that, working copies are deleted) and a sentence to pass on.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project id (from lab_list_projects) | |
| auch_offene | No | With abschliessen: also delete files that were never picked up (they are then gone for good) | |
| speicherort | No | 'cloud', 'lokal' (this computer) or 'server' (studio storage). Omit to only read | |
| abschliessen | No | true: the project is finished — delete all of FilmLab's working copies. Ask the person first |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states that abschliessen: true deletes all working copies at FilmLab, and that auch_offene: true deletes never-picked-up files for good. This contradicts the annotation destructiveHint: false, which tells the agent the tool is non-destructive. The description is otherwise detailed, but the annotation contradiction forces a score of 1.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the read-versus-set distinction and then explains storage modes and deletion behavior. It is long and dense, but most sentences carry necessary operational detail. Slightly better paragraphing or bullets would improve readability, so it is not a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a four-parameter tool with no output schema, the description covers the read/write modes, storage semantics, deletion rules, confirmation requirements, and even the fields returned in the answer. An agent has enough context to invoke it correctly, apart from the annotation inconsistency.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 adds meaningful cross-parameter semantics beyond the schema: 'cloud' is the default, 'lokal' and 'server' require pickup by a local bridge, and auch_offene only matters with abschliessen and permanently deletes unpicked files. This is useful inter-parameter guidance not fully captured by the individual schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: reading or setting where a project's generated material is kept. It also distinguishes read mode from write mode based on whether speicherort is supplied, so an agent can understand the operation 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear conditions for using 'lokal' or 'server' versus 'cloud', and explicitly says abschliessen should only be used after the person confirms the project is finished. It also specifies the refusal condition for open files and the auch_offene override. It does not name sibling tools as alternatives, keeping it below a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start an ASYNC export render of a project sequence. Returns a job_id immediately (status 'queued') — does NOT block. Then poll lab_get_export with that job_id until status is done|failed. Needs the sequence_id to render (an integer from the project's sequences). derivatives asks for extra cut-downs of the SAME render (portrait for social) alongside the main file — their URLs come back in the finished job's derivatives. The finished job also carries zielmarkt_checkliste (delivery checklist per target market, set with lab_zielgruppe).
| Name | Required | Description | Default |
|---|---|---|---|
| profile | No | Delivery profile (default 'web'). See lab_export_profiles. 'alpha_prores4444' and 'alpha_png_sequence' keep transparency and are refused with an explanation unless a clip in the sequence really carries an alpha channel. | |
| quality | No | Quality preset (default 'standard') | |
| project_id | Yes | Project id (from lab_list_projects) | |
| derivatives | No | Extra cut-downs rendered from the FINISHED export, on top of the main file. '9x16' is a deterministic crop of the wide render into portrait — what falls outside the portrait frame is gone, not filled in. Their URLs arrive in the completed job's `derivatives`. | |
| sequence_id | Yes | Sequence id to render (positive integer as string, e.g. '27') | |
| ohne_clipton | No | Leave the clips' OWN audio out of the export (e.g. a video model whose sound is always on) — the film then sounds only from the bound stems and the mixdown (music bed, narrator). Default false: the clips' own audio is mixed under the bed as before. | |
| include_stems | No | Also export audio stems separately (default false) | |
| ki_kennzeichnung | No | How the visible AI disclosure (EU AI Act Art. 50(4)) appears when the sequence contains AI material. Default 'minimal': a small 'KI' mark in the corner for the whole film. 'durchgehend': the larger 'KI-verändert' box. 'leitfaden': an 'AI' mark top right for the whole film, as in the German regulator's (Bundesnetzagentur) transparency guide. 'anfang': the mark for the first 4 s plus a 4 s end card. 'abspann': only the 4 s end card. 'anfang' and 'abspann' require werk_kuenstlerisch=true; there is no option without any disclosure. | |
| derivative_region | No | Which part of the wide frame the portrait crop keeps. Default 'center' — pick 'left' or 'right' when the subject stands off to one side, otherwise the crop cuts it in half. | |
| werk_kuenstlerisch | No | Confirm the work is artistic, fictional or satirical — only then may the disclosure be limited to the opening or the end card. Set it only when that is true; the choice is recorded with the export. | |
| kennzeichnung_umfang | No | For a film that mixes people-made material ('eigen', see lab_herkunft) with AI material: 'film' (default) marks the whole film; 'abschnitte' shows the mark only while an AI or undeclared clip is on screen. Only with ki_kennzeichnung minimal, durchgehend or leitfaden. Audio counts too: an AI or undeclared sound track (bed, stems, mixdown) runs under the whole film, so the export then marks the whole film and reports umfang_bestellt. Declare own music or dialogue with lab_add_media(herkunft) or lab_herkunft. A film with no AI clip at all carries no mark either way. The choice and the clip-by-clip origin are recorded in the provenance record. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag a non-destructive write, but the description adds substantial behavior beyond them: the render is async and does NOT block, it returns a queued job_id, polling is the completion mechanism, alpha profiles are refused with an explanation unless a clip really has alpha, and derivatives are destructive crops ('what falls outside the portrait frame is gone'). It also discloses which artifacts land in the finished job.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the most decision-relevant facts (async, non-blocking, follow-up tool) and largely free of filler. It is dense and long for a description, but nearly every clause carries operational weight; the closing note on zielmarkt_checkliste is the softest sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists and this is an 11-parameter, enum-heavy production tool, so the description carries real burden. It covers the async lifecycle, the job_id/status return, where derivative URLs appear and the checklist field, which is strong output-side context, though it does not touch several schema-documented parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 11 parameters in detail and the baseline is 3. The description only elaborates on derivatives (extra cut-downs of the SAME render, portrait for social) and sequence_id's origin, leaving the other nine parameters to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Start an ASYNC export render of a project sequence') and immediately fixes the operational character (async, non-blocking, returns job_id). It distinguishes itself from the sibling poller by naming lab_get_export as the follow-up, so an agent can tell it apart from lab_list_exports, lab_get_export and the other export tools 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context and a workflow: call this to queue, then poll lab_get_export until status is done|failed, and it names the required input (sequence_id). It does not, however, state when to prefer it over neighbors like lab_schnitt_export or lab_stems_export, nor any explicit 'do not use this when' condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Hand the sound over to whoever mixes next (Resolve/Fairlight, Pro Tools, a dubbing studio): every stem of the sequence (dialog, music, sfx, atmo) as a 24-bit / 48 kHz stereo WAV, rendered the way it goes into the mix — effects, fader, pan and ducking baked in — plus an M&E file (music + effects + atmo WITHOUT the ducking on the dialog, for dubbed versions). All files start at the start of the sequence and are exactly the same length, so they line up at 00:00 in any DAW. Delivered as ONE zip with stems.json (format, length in samples, loudness/true peak per file) and LIESMICH.txt. The master (EQ/compressor/limiter) and the loudness normalisation are NOT in the stems: their sum is the mix before the master. Needs bound stems (lab_bind_audio). Runs as a BACKGROUND JOB: poll lab_get_job — stems_zip_url is in job.result. Changes nothing in the mix, costs nothing. Picture handover is lab_schnitt_export.
| Name | Required | Description | Default |
|---|---|---|---|
| seq_id | Yes | Sequence id — positive integer as string |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by disclosing what is baked into the render (effects, fader, pan, ducking), what is explicitly excluded (master EQ/compressor/limiter and loudness normalisation), how files are aligned (all start at sequence start, equal length), and the delivery artifacts (single zip with stems.json and LIESMICH.txt). It also confirms the operation is non-destructive to the mix and costs nothing, consistent with destructiveHint=false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and output contents are front-loaded, then constraints, then workflow. It is long, but nearly every sentence carries operational detail an agent needs (format, sample rate, alignment, exclusions, job polling). Slightly dense with parenthetical asides, but no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description itself explains the return entirely: one zip, its contents, the metadata manifest, and where the URL appears in the job result. For a background-job export with a single param, this is complete enough to call and consume correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one parameter (seq_id) and schema coverage is 100%, so the schema already fully documents it. The description implies scope ('every stem of the sequence') but adds no format or syntactic detail beyond the schema, which is the expected baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (export the sequence's sound stems) and enumerates exactly what is produced: dialog/music/sfx/atmo stems at 24-bit/48kHz plus an M&E file. It also distinguishes itself from the picture sibling lab_schnitt_export, so an agent can separate the audio handover from the shoot/picture handover.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit context ('hand the sound over to whoever mixes next'), names the mechanism to use it (background job, poll lab_get_job, read stems_zip_url from job.result), and states the prerequisite (needs bound stems via lab_bind_audio) and the alternative for non-audio delivery (lab_schnitt_export). Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the project's default style kit (it then runs in every image and clip of the project), or clear the default by omitting stil_kit_id. Free.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| stil_kit_id | No | Kit id from lab_list_stil_kits; omit to clear the default |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so safety is covered. The description adds valuable behavioral context beyond that: the kit becomes project-wide in effect, and the default can be cleared by omission. It does not mention whether an existing default is replaced or what happens to previous settings, but it is materially more informative than the annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single compact sentence with the core action front-loaded, followed by effect and clearing semantics. Every clause earns its place, including the brief 'Free' cost note.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter mutation tool with annotations covering safety and no output schema, the description is largely complete: it covers purpose, project-wide effect, and clearing. Minor gaps remain around whether an existing default is replaced rather than cleared, and the role of project_id.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: stil_kit_id is documented in the schema, project_id is not. The description reinforces the omit-to-clear semantics for stil_kit_id but adds no meaning for project_id. Baseline 3 is appropriate for partial coverage where the schema already handles the documented parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Set the project's default style kit') and explains the consequence ('runs in every image and clip of the project'). The clearing behavior is also stated, which distinguishes it from sibling tools like lab_create_stil_kit and lab_list_stil_kits without needing to name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly says when this tool is appropriate (to set a project-wide default) and how to clear it (omit stil_kit_id). It stops short of naming alternatives or stating exclusions, but the usage context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ask what clip durations the project's cutting preset WOULD give a sequence — and change nothing (angewendet: false). Use it to see the consequence before lab_apply_rhythm writes it, or to size a sequence that has no clips yet (pass anzahl). It knows nothing about the measured beat grid: the tempo it uses is the text from the preset's music brief ('mittel bis schnell, 100–128'), which is a promise, not a measurement. Only lab_apply_rhythm reaches for the grid that lab_beatgrid measured. Reads only — no state, no credits.
| Name | Required | Description | Default |
|---|---|---|---|
| anzahl | No | How many shots to distribute. Omit to use the sequence's existing clip count — required if the timeline is still empty, which otherwise answers 400 | |
| seq_id | Yes | Sequence id (from lab_create_sequence/lab_list_sequences) — positive integer as string |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=true; the description adds substantial context beyond that, notably that it uses the preset's music-brief text ('mittel bis schnell, 100–128') rather than the measured beat grid, that lab_apply_rhythm is the only tool that reaches for lab_beatgrid's data, and that it touches no state or credits. This is exactly the kind of caveat an agent needs before trusting the output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded: the core 'would give, changes nothing' claim is the first clause, followed by use cases and then the important grid caveat. It is dense prose with a mixed-language artifact (`angewendet: false`) that slightly hurts scannability, but no sentence is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only preview tool with no output schema, the description covers scope, non-mutation, the alternative tool, and the critical measurement-vs-text caveat. The only gap is that the shape of the returned durations is never described, which matters since the return value is the entire point of the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both `seq_id` and `anzahl`, including the 400 behavior when the timeline is empty. The description's mention of passing `anzahl` for an empty sequence restates schema content rather than adding syntax or format detail, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource+scope: it reports what durations the project's cutting preset WOULD produce for a sequence, and explicitly states it changes nothing. It also distinguishes itself from lab_apply_rhythm, so an agent can route correctly without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives two concrete use cases — previewing the consequence before lab_apply_rhythm writes it, and sizing a clip-less sequence via `anzahl` — and names the alternative tool plus the condition that selects it. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write a WHOLE cut into a sequence in one call — clips in order with their lengths, an optional dissolve between them, an optional bed underneath. This is the counterpart to lab_get_sequence: that one reads the timeline, this one writes it. Prefer it over a chain of lab_add_clip calls whenever you already know the whole cut: a chain that breaks in the middle leaves half a sequence behind, this either applies or refuses. Costs nothing — it validates and writes rows, it generates nothing. Every video_id is checked against the project BEFORE anything is written, so a wrong id is a refusal here and not a gap in the cut nobody notices. Pass sequence_id to write into THAT sequence; omit it and a new one is created. Pass sequence_id WITHOUT a manifest to read back the stored cut as a manifest — for an agent that already has the sequence_id and wants to see what is in there before changing it. (The Resolve bridge does NOT go through here: it talks to the FilmLab server directly with its own bridge key and does not know this MCP.) Reworking a cut you read back? Keep each clip's clip_id. A clip that comes back with its identity keeps its track, its in-point in the source and its scene, and the shots bound to it stay bound; a clip without one is treated as new and gets a fresh identity, which orphans whatever pointed at the old one. Speed per clip: tempo (fixed, 0.0625–16) or tempo_kurve (a ramp in timeline seconds, which wins over tempo); read-back returns them the same way, and nothing is charged for either. Two honest limits: the Resolve bridge applies the clips but reports uebergang and the bed's level/fade as not applied (its scripting API has neither a transition call nor a clip volume property). The FilmLab sequence render applies the bed with its level and fade, but NOT uebergang yet — dissolves are stored and render as hard cuts (checked 2026-10-03).
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Title for the sequence created when `sequence_id` is omitted | |
| manifest | No | The cut as one object. Omit it only together with a `sequence_id`, to read back what is stored | |
| project_id | Yes | Project id (from lab_list_projects) — positive integer as string | |
| sequence_id | No | Sequence to write into (from lab_create_sequence/lab_list_sequences). Omit to create a new one. Given WITHOUT a manifest, the stored manifest is read back instead of written | |
| erwartete_revision | No | The `revision` you read (from lab_get_sequence or this tool's read-back). The cut is written only if the sequence still has exactly that content — otherwise nothing is written and you get `revision_veraltet` with the current revision: read again, merge, write again. Without it this tool still protects the moment between its own read and write, but not the time since YOU read the sequence. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, it discloses important behavior: the write validates all video_id values before writing, applies atomically or refuses, costs nothing, and supports optimistic concurrency via erwartete_revision. It also names concrete downstream limitations for the Resolve bridge and FilmLab render, which an agent could not infer from the schema or annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but appropriate for a complex nested mutation tool; it front-loads the core write action, the alternative, and the atomicity guarantee. Some details repeat the very thorough schema, notably around clip_id and tempo, so it is effective but not maximally tight.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with nested objects, no output schema, and multiple modes, the description covers the write path, read-back path, validation behavior, concurrency error, identity semantics, and known downstream gaps. An agent has enough context to invoke it correctly and interpret major failure modes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the detailed per-parameter docs already carry most semantics. The description still adds useful cross-parameter meaning: sequence_id's dual write/read-back mode, clip_id's identity-preserving effect when reworking a cut, tempo vs tempo_kurve precedence, and the consequence of omitting clip_id (orphaned bindings).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Write a WHOLE cut into a sequence in one call', covering ordered clips, dissolves, and an optional bed. It explicitly distinguishes this from lab_get_sequence and from chaining lab_add_clip calls, so an agent can select it without opening sibling schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit alternatives: prefer this over a chain of lab_add_clip when the whole cut is already known, use lab_get_sequence to read, and pass sequence_id without a manifest to read back a stored cut before changing it. It also states that the Resolve bridge does not go through this tool, which prevents a plausible wrong selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate SOUND EFFECTS for a whole sequence, shot by shot — Simon Meyer's pass: every shot is muted, padded with black frames up to the model's minimum length, re-rendered by Seedance 2.5 in editing mode at its low resolution with sound on, and only the generated sound is kept, stretched back to the original timing (the black padding is the sync marker) and laid at the shot's position. The result is ONE sfx track in sequence length, bound to the sequence's sfx stem; the other stems stay as they are. Each piece and its offset are listed in the audio row's metadata (stuecke). Shots come from the sequence itself, in export order and export length — no cut detection. Costs credits, priced per shot over the seconds actually sent (the padding counts); call with get_cost first. ASYNCHRONOUS: returns a job_id; poll the job until done. A shot that fails is refunded on its own and named in fehlende_einstellungen; if the whole run fails, all of it is refunded. The model is told: keep the picture, diegetic sound only, no music, no dialogue, no voices — hinweis adds a setting line for every shot.
| Name | Required | Description | Default |
|---|---|---|---|
| seq_id | Yes | Sequence id (from lab_create_sequence/lab_list_sequences) — positive integer as string | |
| hinweis | No | One line about the setting that applies to every shot, e.g. 'kitchen, wooden floor, rain on the window'. Helps the model pick the right room sound. Leave it out if the shots differ too much. | |
| get_cost | No | Return the price in credits WITHOUT starting anything — per shot over the seconds actually sent, at the rate lab_list_models lists for the model. Do this first; long sequences add up. | |
| nur_eigene_daten | No | Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say readOnly=false, destructive=false; the description adds substantial context beyond that — muting and black-padding shots, only generated sound retained, the result being ONE sfx track bound to the sequence's sfx stem while other stems stay untouched, metadata key 'stuecke', credit pricing that includes padding, and refund behavior for failed shots and whole runs. It stops short of saying whether the existing sfx stem content is overwritten or appended, which is the one mutation detail an agent would still want.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and every sentence carries operational substance (padding as sync marker, stuecke metadata, refunds, async polling). It is a single dense block that occasionally repeats schema text, e.g. the per-shot credit pricing restated alongside get_cost, but nothing is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an asynchronous, credit-consuming, sequence-mutating tool with no output schema, the description covers the return contract (job_id + polling), cost model, partial-failure and refund semantics, the prompt constraints sent to the model, and where results land. An agent has enough to call it correctly and to explain the outcome without further inspection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description earns an extra point by adding ordering semantics ('call with get_cost first') and by restating hinweis as 'adds a setting line for every shot', tying the parameter to the prompt construction described earlier. It does not add syntax beyond the schema, but it does clarify how the parameters interact with the run.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Generate SOUND EFFECTS for a whole sequence, shot by shot') and immediately distinguishes itself from single-shot sound tools by describing the whole pipeline: mute, pad, re-render with sound, keep only audio, stretch to original timing. A reader knows this is a sequence-level SFX pass, not a one-shot generate or a music/dub tool among the siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit preconditions and routing: 'call with get_cost first', 'ASYNCHRONOUS: returns a job_id; poll the job', 'no cut detection' (shots come from the sequence in export order), and a concrete fallback when the data-residency gate refuses ('use a non-gated model or text only'). It also names the gated-model condition under which nur_eigene_daten is required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Relight and restyle an EXISTING clip while the performance stays untouched (Beeble Switch X): lighting, background and props change, the subject and its motion do not. The source is the clip of a generated-video row — or, with asset_id, an uploaded file that stands in for it. in_sec/out_sec cut the source server-side first, so a long take can be transformed in pieces. ASYNCHRONOUS: a new video row comes back as pending; poll it with lab_job_status. Costs credits when called without get_cost.
| Name | Required | Description | Default |
|---|---|---|---|
| in_sec | No | Cut the source server-side before it reaches the provider: start of the excerpt, in seconds. Only together with out_sec. What is billed is the MEASURED length of the cut, not out_sec minus in_sec. | |
| out_sec | No | End of the excerpt, in seconds. Must lie behind in_sec; both are set together or neither. | |
| asset_id | No | R2 asset key of an uploaded video (the `key` from lab_list_assets, asset_type 'video') to transform INSTEAD of the row's own clip. The row from video_id still supplies project and scene; only the pixels come from the asset. The key must belong to that same project. | |
| get_cost | No | `true` returns the published rate per unit and your balance WITHOUT transforming and without spending anything — NOT a total. Switch X charges by the MEASURED length of the source, which only the server knows before the run, and it is not priced from the lab_list_models catalog (that covers generation models). The real amount comes back with the actual call. | |
| video_id | Yes | Generated-video id (from lab_animate/lab_job_status/lab_review_queue) — positive integer as string. ALWAYS required, also together with asset_id: this row anchors the run (project, scene, billing) and the backend answers 404 without it. | |
| alpha_mode | No | How the subject is cut out from its background. Omit to let the backend decide ('auto'); the other modes fill, take a supplied matte, or work on a selection. | |
| resolution | No | Output tier of the transform. This is Switch X's OWN tier list, not one of the video-model resolutions in lab_list_models — that catalog covers generation models and has no entry for this path. The tier drives the price; omit it for the backend default. | |
| nur_eigene_daten | No | Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only. | |
| transformation_prompt | Yes | What the clip should look like afterwards — light, place, props. The subject and its performance are preserved by the model; describing them again does not help. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds substantial behavior on top — pending-row async semantics, credit spend on real calls, server-measured billing length, and the drittland_dritte_gesperrt refusal that occurs before any charge. It does not cover output format or how to cancel/retry a failed run, which keeps it off a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core transformation contract, then source, then async/billing caveats — good ordering and no filler sentences. It is dense and long for a description, and the paragraph form makes the async and cost warnings slightly harder to scan than a short bulleted structure would.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter, asynchronous, credit-consuming mutation with no output schema, the description covers everything an agent needs before calling: what changes, what is preserved, which id is mandatory, how to preview cost, how to poll, and what refusal means. No material gap remains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema does not: the cut happens server-side first so a long take can be transformed in pieces, asset_id substitutes only the pixels while the row still supplies project and scene, and get_cost returns a rate rather than a total. These are relationships between parameters, not restatements.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb pair and resource ('Relight and restyle an EXISTING clip'), names the provider path (Beeble Switch X), and draws the boundary that matters most: the subject and its motion are preserved while lighting, background and props change. That distinguishes it from generation siblings like lab_animate and lab_generate without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains the two source modes (the row's own clip vs. an uploaded asset via asset_id), when to slice with in_sec/out_sec, that the call is asynchronous and must be polled with lab_job_status, and that get_cost must be used first to avoid spending credits. It also gives an explicit fallback when the gating flag is missing: use a non-gated model or text only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bring Midjourney exports into a project (FilmLab calls this 'Umzug'). Midjourney has no API, so the person downloads their images or ZIP and this tool carries them on. Give EXACTLY ONE of: dateien (names/types/sizes of local files → signed PUT addresses with a ready curl line; PUT the raw bytes, then call again with quellen from weiter), quellen (after the PUT: starts the import job → job_id; poll lab_get_job — result.bildzeilen lists image_id and datei per image (the prompt per image comes with bilder: true), result.gesperrt names refused images with the reason, result.ungeprueft images whose check was unreachable), prompts (pasted Midjourney prompts, one per line → parameters split and what does not carry over, e.g. --sref codes; free, no job), anker ({name, image_ids ≤ 12} → a look anchor for lab_generate's anker_id; images of real people are refused) or bilder: true (the project's imported images with image_id and prompt). Every imported image is declared AI material (EU AI Act Art. 50) — no herkunft question. An image_id works directly in lab_animate (source_image_id), as a seed in lab_generate and in lab_referenz_aus_bild. Uploading is free.
| Name | Required | Description | Default |
|---|---|---|---|
| anker | No | Build a look anchor from imported images | |
| bilder | No | true: list the project's imported images | |
| dateien | No | Local files to upload: ZIP archives or single PNG/JPG/WEBP | |
| prompts | No | Pasted Midjourney prompts, one per line | |
| quellen | No | After the PUT: exactly the `quellen` from the previous answer's weiter.argumente | |
| project_id | Yes | Project id (from lab_list_projects) — positive integer as string |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnly=false/destructive=false, so the description carries the real burden and delivers: uploading is free, prompts cost no job, real-person images and look-anchor images are refused, and every imported image is declared AI material under EU AI Act Art. 50 with no herkunft prompt.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the purpose, then a single dense paragraph enumerating modes in workflow order; every clause carries operative information (cost, refusals, handoffs). It is long and parenthetical-heavy, but not padded — slightly harder to scan than optimal for a polymorphic tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description documents return semantics (job_id, result.bildzeilen/gesperrt/ungeprueft, weiter), the polling target, and downstream handoffs, so an agent has everything needed to drive the multi-step import.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (baseline 3), but the description adds semantics the schema cannot express: the sequence dependency of quellen on the previous 'weiter' payload, the ≤12 image_ids cap for anker, and per-mode output behavior (job_id, weiter, result fields). This exceeds the structured data meaningfully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Bring Midjourney exports into a project') and maps the internal alias 'Umzug'. An agent can distinguish this from sibling import/media tools 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names the five mutually exclusive modes (dateien, quellen, prompts, anker, bilder) and the 'EXACTLY ONE of' rule, spells out the ordered workflow (dateien → PUT → quellen → poll lab_get_job), and points to the sibling tools where an image_id is consumed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enlarge an EXISTING clip (Topaz, passed through fal): same shot, same length, same sound — more pixels. There is no prompt here; nothing is re-imagined, the frames are scaled. The source is the clip of a generated-video row. Both the length and the source height are measured server-side before anything is charged, and a source too tall for the larger factor is refused rather than run. ASYNCHRONOUS: a new video row comes back as pending; poll it with lab_job_status. Costs credits when called without get_cost.
| Name | Required | Description | Default |
|---|---|---|---|
| faktor | No | How many times larger, per side. Omit for the smaller one. Whichever you pick, the RESULT has to stay inside the published rate tiers — a source too tall for the factor you asked for is refused by name, with the ceiling in the message, instead of billing a run nobody can price. What the tier costs is in lab_list_models and in the preflight, not here. | |
| get_cost | No | `true` returns what upscaling THIS clip costs (`cost_generations`, measured server-side from its length and the height of the RESULT, exactly what the run would charge) plus the published rate per output second per tier and your balance — WITHOUT scaling and without spending anything. For a clip that is still pending there is no total yet: then `cost_generations` is null and `preis_grund` says why. Which tiers are measured and which are catalog values is the same distinction lab_list_models makes. | |
| video_id | Yes | Generated-video id (from lab_animate/lab_job_status/lab_review_queue) — positive integer as string. The row must already have its clip; a run still pending is refused, and nothing is charged for asking. | |
| max_credits | No | The most you agree to pay — pass the amount from get_cost that the person confirmed. If the measured price is higher when the run starts, it is refused before anything is charged. | |
| nur_eigene_daten | No | Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare non-readonly and non-destructive; the description adds the async contract (pending row, poll via lab_job_status), the credit charge and the get_cost preflight, and the server-side measurement plus refusal-instead-of-billing behavior. It does not state the cost tier numbers itself, but it correctly defers those to lab_list_models.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with what it does and what it is not, then constraints, then the async/cost contract. Dense but every sentence carries information; some clauses (the height/refusal explanation) appear twice, once in the description and once in the faktor field.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly explains the return (a new video row, pending) and the polling path. For a billed async mutation with consent gating, it covers the essentials; the per-tier pricing is deliberately deferred to lab_list_models, which is a reasonable handoff.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 the workflow meaning behind the parameters: get_cost → human confirmation → max_credits guard, and that source height is validated against the chosen factor before billing. That connects parameters across the call sequence in a way the individual schema fields do not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (enlarge an EXISTING clip) and immediately distinguishes itself from the generation siblings: 'There is no prompt here; nothing is re-imagined, the frames are scaled.' An agent can tell it apart from lab_animate without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clear on the operating context: source must be a generated-video row with a completed clip, use get_cost first to avoid spending, poll with lab_job_status afterward. It implies 'use lab_animate instead if you want new content' rather than naming that sibling, so the when-not guidance is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render several clips as CHAINS: within a scene one after another (continuity), across scenes in parallel (speed) — the plan follows scene_ref of each job in order. aktion: plan (free: shows the chains) · preis (free: same checks as a real start; returns preis_geschaetzt_credits, preis_hoechstens_credits (with every allowed retry) and reicht against balance, project cap and an active auto run, plus startbilder_offen when a chain's first start image is not approved yet — nothing is created) · starten (COSTS CREDITS, ONLY after the person confirmed the price from aktion=preis). Each clip is charged when it starts; an active lab_auto_lauf cap applies. The FIRST clip of every chain needs an approved start image (keyframe checkpoint, as in lab_animate) unless ohne_keyframe; later clips derive from the chain. Sending starten twice returns the running chain (wiederverwendet: true) instead of paying twice. Transition between clips of a chain (uebergang): schnitt (default) = hard cut to a NEW camera angle — the next clip does NOT start from the last frame; its prompt begins with the previous clip's end state (wardrobe, props, place, light), characters and location come from each job's own character_refs/location_id. A schnitt follow-up clip is TEXT-TO-VIDEO: without character_refs/location_id the person and place hang on one sentence of text — give them for real continuity. CONTINUITY CHECK: in a chain with more than one clip every clip is checked against its prompt BEFORE the next one starts (status pruefen, wartet_auf: abgleich while the check runs — that is not a hung job). On mismatch the clip is re-rendered at most neuversuche times (default 1, prompt led by the failed claims, charged like the clip); if it still deviates the chain STOPS before the next clip is paid (chain status abgebrochen, clip status abweichung, issues and verworfen at the clip). The last clip of a chain gets its retry too but the chain then ends fertig with the verdict at the clip. Single clips are only checked in the background. durchgehend = the last frame becomes the start image — only for one unbroken take. Follow a started chain with lab_get_job(job_id): result.zusammenfassung (laeuft/fertig/abgebrochen), result.ketten (status and grund per chain) and result.clips (keyed by clip index: video_id, status, fehler_klasse). Job status done only means nothing runs any more — check result.zusammenfassung.abgebrochen before reporting success. A failure stops only its own chain. Dispatch rule: continuous scene → one chain with schnitt; one unbroken motion → a single clip ≤ 15 s, else durchgehend; separate scenes, time jumps, costume changes or montage → separate scenes (parallel). Over ~3 minutes total: suggest narrowing the scope first.
| Name | Required | Description | Default |
|---|---|---|---|
| jobs | Yes | One entry per clip, IN ORDER — the same fields as lab_animate (prompt, scene_ref, tool, duration_seconds, resolution, character_refs, location_id, source_image_id, nur_eigene_daten …). nur_eigene_daten is per clip and follows the rule of lab_animate. Each prompt: 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. scene_ref decides the chains: consecutive clips with the same scene_ref chain, a clip without scene_ref stands alone. | |
| modus | No | hybrid (default): chain within scenes; parallel: every clip alone; sequenziell: one chain over everything | |
| aktion | Yes | plan and preis are free; starten costs credits | |
| uebergang | No | Transition at each cut inside a chain; default schnitt | |
| project_id | Yes | Project id (from lab_list_projects) | |
| neuversuche | No | Retries per clip after a failed continuity check: 1 (default) or 0 (stop at the first deviation). Name preis_hoechstens_credits to the person before starten. | |
| ohne_keyframe | No | Skip the keyframe checkpoint on purpose. By default a paid clip only starts from a start image the user has approved (lab_review_asset verdict: accepted) — look at the frame first, then spend on the clip. Set true only when the user explicitly asked to skip the frame check. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Far exceeds the annotations: it discloses cost behavior (each clip charged at start, retry 'charged like the clip'), a duplicate-call rule returning wiederverwendet: true instead of double charging, the keyframe approval prerequisite, the continuity-check state machine (pruefen / wartet_auf / abweichung / abgebrochen) and its stop-before-next-payment semantics, plus the trap that job status done does not imply success. There is a mild tension with idempotentHint=false given the double-submit dedupe, but it does not contradict readOnlyHint or destructiveHint and is best read as partial, not full, idempotency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core concept is front-loaded and almost every clause carries real information, but the whole definition is one dense run-on block with no line breaks or bullets, mixing German and English mid-sentence. Several items are restated from the input schema (uebergang default, ohne_keyframe approval rule, neuversuche default), so a portion of the text does not earn its place beyond structured fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although there is no output schema, the description supplies the return shape explicitly (result.zusammenfassung with laeuft/fertig/abgebrochen, result.ketten with status and grund, result.clips keyed by clip index with video_id/status/fehler_klasse) and names the follow-up tool lab_get_job. For a 7-parameter, cost-incurring orchestration tool this is essentially complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so 3 would be the baseline, but the description goes well beyond it: it explains that jobs are ordered and that scene_ref is what actually decides chain membership, that neuversuche must be named to the person as preis_hoechstens_credits, that ohne_keyframe is an explicit user-authorized skip, and what schnitt versus durchgehend mean at the frame level. These are semantic rules the schema cannot express.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Render several clips as CHAINS'), then immediately defines the two chaining axes (sequential within a scene, parallel across scenes) and the three actions. It is clearly distinguished from single-clip rendering by the explicit note that 'Single clips are only checked in the background' and by referencing lab_animate only as the field-compatibility baseline.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit dispatch rule ('continuous scene → one chain with schnitt; one unbroken motion → a single clip ≤ 15 s, else durchgehend; separate scenes … → separate scenes (parallel)'), gates the paid action on a prior aktion=preis confirmation, and adds a scope guard ('Over ~3 minutes total: suggest narrowing the scope first'). Alternatives and exclusion conditions are named, not implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a VFX operation on an image already in the project gallery — the same pipeline the Resolve bridge uses. inpaint (clean plate: what is inside the box disappears, the surroundings close over it) · replace (same path, other intent: something new goes into the box) · relight (no box — the light changes across the whole frame; by default the scene stays exactly as it is, licht_weg 'iclight' instead repaints the background and may change the scenery) · mask (no box — you describe what should be cut out and get the matte back). inpaint/replace need box AND prompt; relight needs light_preset or prompt and REJECTS a box; mask needs prompt and REJECTS a box too. box is given in FRACTIONS of the image (0..1), not pixels — the worker builds the mask. inpaint/replace start at 5 credits per run on the reference area (larger areas cost more); relight costs 4 flat per image (licht_weg 'iclight': from 9, by area); mask costs 1, flat per request. Returns immediately with an operation_id; poll lab_vfx_status until status is done|failed. NOT offered here: composite, move, color_grade — the server knows them and has no consumer for them.
| Name | Required | Description | Default |
|---|---|---|---|
| box_x | No | Box left edge as a fraction of image width (0..1) | |
| box_y | No | Box top edge as a fraction of image height (0..1) | |
| prompt | No | inpaint/replace: what should be seen there instead — required. mask: what should be cut out (e.g. 'the red toolbox') — required. relight: optional, replaces the preset | |
| image_id | Yes | Id of the source image in the project gallery (from lab_list_assets / lab_generate) | |
| box_hoehe | No | Box height as a fraction of image height | |
| licht_weg | No | relight only. kontext (default): only the light changes, scene, people and framing stay. iclight: the background is repainted from the light description — the scenery may change | |
| operation | Yes | inpaint: Die rote Werkzeugkiste wird durch eine Holzkiste auf der Werkbank ersetzt. | replace: Derselbe Weg, andere Absicht: in die Box kommt etwas Neues. | relight: Keine Box: die Lichtrichtung wandert über das ganze Bild. | mask: Keine Box: du beschreibst, was heraus soll, und bekommst die Maske. | |
| box_breite | No | Box width as a fraction of image width | |
| project_id | Yes | Project id (from lab_list_projects) | |
| light_preset | No | relight only. There is no 'bottom' — the server does not carry one |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (readOnly false, destructive false), so the description carries the load and does so well: it discloses credit costs per operation (5/4/1, iclight from 9), the async contract (returns operation_id, poll lab_vfx_status until done|failed), the default non-destructive relight behaviour vs the iclight repaint, and box-rejection rules.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the action and then a dense but scannable operation breakdown separated by '·'. Every clause carries information, though the single long paragraph is heavy and could be slightly tighter for a 10-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description still tells the agent what comes back (operation_id) and how to follow up, plus cost, defaults and per-operation input rules. Nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 real meaning beyond the schema: box is 'in FRACTIONS of the image (0..1), not pixels — the worker builds the mask', and it cross-links which params each operation demands. That exceeds what the per-field schema strings convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Run a VFX operation on an image already in the project gallery') and then decomposes the four operations with distinct meanings (inpaint removes, replace inserts, relight changes light, mask returns a matte). It also names the sibling to poll (lab_vfx_status) and explicitly excludes composite/move/color_grade, so an agent can separate it from neighbours like lab_vfx_preset.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives per-operation requirements: inpaint/replace need box AND prompt, relight needs light_preset or prompt and rejects a box, mask needs prompt and rejects a box. It also states what is NOT offered here, which is exactly the kind of exclusion that steers an agent to the right tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a video VFX preset on a whole clip. Today only 'gesichter_verpixeln' (pixelate every face) is live. Costs credits per frame — call with dry_run=true first to see the price. With rerender_from (a finished job_id) it re-renders for free with other settings, e.g. exceptions: object ids that stay sharp. Tell the person: "Pixelated automatically, not guaranteed to catch everything — check before publishing." Poll lab_vfx_preset_status until done|failed.
| Name | Required | Description | Default |
|---|---|---|---|
| effekt | No | mosaik | |
| preset | No | gesichter_verpixeln | |
| dry_run | No | Only return the price | |
| ausnahmen | No | Object ids to leave unpixelated (rerender only) | |
| video_url | No | HTTPS URL of the clip (project asset) | |
| project_id | Yes | Project id | |
| rerender_from | No | job_id of a finished run to re-render for free |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds the material facts an agent needs — per-frame credit cost, the free dry-run escape hatch, and that rerender is free. It also surfaces a required user-facing disclaimer about imperfect face detection. It does not say whether the source clip is overwritten or a new asset is produced, which is a notable gap for a mutating job tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and the live-preset constraint, and every sentence carries distinct operational information. The dry-run, rerender, disclaimer and polling instructions are run together in a dense block without visual separation, which costs a point but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter mutating job tool with no output schema, the description covers the full lifecycle (start, dry-run pricing, free rerender, poll to done|failed) and the compliance message. It leaves unstated what the call returns — notably the job_id that rerender_from later depends on — and the effekt style options.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 71%, and the description adds real meaning on top of it: dry_run returns only the price, rerender_from must be a finished job_id and makes the run free, and ausnahmen are object ids that stay sharp and only apply on rerender. The one blind spot is the effekt enum (mosaik/weich/schwarz), whose three values are left entirely unexplained in both description and schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Run a video VFX preset on a whole clip') and immediately narrows scope by naming the single live preset 'gesichter_verpixeln' with a plain-language gloss. It also names the polling sibling lab_vfx_preset_status, so an agent can distinguish start-vs-status without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit operating order: call with dry_run=true first to see the price, and use rerender_from with a finished job_id for a free re-render with other settings. It also tells the agent to poll lab_vfx_preset_status until done|failed. It stops short of contrasting with the sibling lab_vfx / lab_vfx_status tools, so no explicit when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Poll a video VFX preset job. status is queued|proxy|spur|render|done|failed; progress shows frames done. When done: result_url is the finished clip (give it to the person as karte_ansehen), kontakt_url is the review contact sheet, spur.objekte lists detected faces with ids usable as exceptions in lab_vfx_preset(rerender_from, ausnahmen).
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | job_id returned by lab_vfx_preset |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already covers the safety profile, and the description goes well beyond it by enumerating the status lifecycle (queued|proxy|spur|render|done|failed) and explaining that progress counts frames done. It also discloses which fields only materialize in the done state. It stops short of saying how often to poll or what a failed job returns, which would be useful for a polling tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences, front-loaded with the core action and then the state-to-field mapping, with no filler. It is slightly dense with domain jargon (spur.objekte, karte_ansehen, ausnahmen) that requires prior familiarity, but every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does the heavy lifting for return values by naming result_url, kontakt_url, and spur.objekte and their meaning. It is nearly complete for a one-parameter poll, though it leaves the queued/failed payloads and any polling cadence unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is a single parameter with 100% schema coverage, and the schema already states it is the job_id returned by lab_vfx_preset. The description adds no format, validation, or lifecycle detail for job_id beyond what the schema provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: "Poll a video VFX preset job." It is clear this is a status/read tool for a job created by lab_vfx_preset, and the mention of lab_vfx_preset(rerender_from, ausnahmen) ties it to the right family. However, it never disambiguates from the very similar sibling lab_vfx_status, which an agent must distinguish on name alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is strongly implied by "Poll" plus the schema note that job_id comes from lab_vfx_preset, and the description gives concrete downstream routing: hand result_url to the person as karte_ansehen, and use spur.objekte ids as exceptions in a rerender call. What's missing is an explicit when-not clause or a pointer to lab_vfx_status as the alternative for non-preset VFX jobs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Poll a VFX operation started with lab_vfx. status is pending|processing|done|failed; when done, result_url carries the finished image. Call repeatedly until done|failed — an image run usually takes under 30 seconds.
| Name | Required | Description | Default |
|---|---|---|---|
| operation_id | Yes | The operation_id returned by lab_vfx |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only safety profile, and the description adds useful behavior: the status lifecycle, that result_url carries the finished image when done, and that polling should continue until a terminal state. It omits error handling and rate-limit details, but adds solid context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tightly written sentences with no filler. The polling instruction and timing detail are front-loaded after the core purpose, so every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple polling tool, the description covers the essential lifecycle, the key return field, and the expected polling duration. Given the schema and read-only annotation, no meaningful gap remains for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the operation_id is already documented as 'returned by lab_vfx'. The description reinforces that origin but adds no syntax, format, or edge-case guidance beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States the specific verb 'Poll' and resource 'a VFX operation started with lab_vfx', immediately tying it to its sibling lab_vfx. The status values and result_url outcome make the tool's scope unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to call repeatedly until done|failed and gives a typical duration under 30 seconds, which tells the agent how to use it. However, it does not name alternative status tools or state when not to use this one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clone a voice from real audio or video material into a project (provider you choose: minimax via fal.ai, or fish_audio) — the source for lab_voice_tts and for lab_dub's voice_id+dub_text path. SYNCHRONOUS: the clone runs inside the request and can take a while to return; there is no job_id to poll. The source needs a clean speech track of workable length — too short or silent material is rejected before anything is spent. Voice cloning from real material is consent-sensitive: every path requires einwilligung: true — it is your own voice, or the person whose voice it is has explicitly agreed. Without it the backend refuses before anything is charged. You must choose the provider explicitly (provider: minimax or fish_audio): there is no default, because both houses process the voice outside the EU. Without it the backend refuses with stimmklon_anbieter_fehlt before anything is charged.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | A label for this cloned voice, shown in lab_list_voices — needed to tell several clones of one project apart later. | |
| get_cost | No | `true` reports the price and your balance WITHOUT cloning anything and without spending quota. A clone is billed per clone (a MiniMax clone costs far more than a Fish clone — ask with get_cost) — the length of the source material does not change it, and the clone is then reusable for as many readings as you like. Not drawn from the lab_list_models catalog (that covers image and video models only); there is no model to pick here. | |
| provider | Yes | Which voice house clones it. REQUIRED — there is no default: neither house has a documented legal basis for the transfer, so you name the one that receives the voice. A request without it is refused before anything is charged (stimmklon_anbieter_fehlt). The choice sticks to the voice: whichever house made it is the one that later speaks with it, so lab_voice_tts has no say in this. What each house can do and what it charges is not stated here — lab_list_models carries that. | |
| project_id | Yes | Project id (from lab_list_projects) — positive integer as string | |
| einwilligung | No | Consent of the person whose voice is being uploaded (or confirmation that it is your own voice). Required on every path — the backend refuses without it before anything is charged. This is not the moderation gate: that one reads the label for abuse, this one asserts you are allowed to use this person's voice at all. Do not set it to be rid of the error — set it because the consent exists. Provider capabilities and prices: lab_list_models. | |
| likeness_ref | No | Consent id from the Likeness Register (LK-XXXXX-XXXXX-XXXXX-XXXXX) for the person whose voice this is. When set, the register is checked live (active, purpose voice_synthesis, the project's target markets) and the clone is refused if the consent does not hold. Needed for a real person's voice in a project for children or young people. | |
| nur_eigene_daten | No | Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only. | |
| sample_audio_url | Yes | URL of the source audio or video the voice is cloned from. Needs a real, sufficiently long speech track — material without one is rejected before anything is spent. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well past the annotations: it declares the call SYNCHRONOUS with no job_id to poll, warns the clone can take a while, states that bad material is rejected before anything is spent, and describes the consent and third-country gates with their specific error codes (stimmklon_anbieter_fehlt). It also discloses the billing model (per clone, not per source length, reusable afterwards), which the readOnlyHint/destructiveHint pair cannot convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose and the SYNCHRONOUS warning are front-loaded well, but the text repeats 'refuses before anything is charged' in three separate places and ends on a dangling fragment ('Without it the backend refuses with stimmklon_anbieter_fehlt before anything is charged'). The consent point and the provider point restate the same gate twice, padding an otherwise informative paragraph.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex, multi-gate mutation with no output schema, the description covers cost, latency model, consent, provider choice and rejection behavior thoroughly. The one remaining gap is what comes back on success — there is no output schema and the description never says a voice_id is returned, leaving the agent to infer it from lab_voice_tts.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter is already documented in the schema, including provider, einwilligung, likeness_ref and nur_eigene_daten. The description largely restates those points (provider has no default, consent is required, source needs a real speech track) rather than adding new semantics. Baseline 3 is appropriate when the schema carries the parameter burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (clone a voice from real audio/video material into a project) and names the two providers inline. It also positions the output downstream ('the source for lab_voice_tts and for lab_dub's voice_id+dub_text path'), so an agent knows exactly where this sits relative to sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly says what triggers a working call: clean, sufficiently long speech track, explicit provider, and consent on every path. It points to get_cost for pricing and to lab_list_models for provider capabilities, which is real routing guidance. It stops short of an explicit 'do not use this when…' exclusion, so it is clear context rather than a full when/when-not map.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Speak text in a project's cloned voice (via lab_voice_clone) — SYNCHRONOUS, returns a ready audio_url, no job_id. The voice house is whichever one cloned this voice; you do not pick it here. Consent-sensitive like the clone itself: only speak text you have the right to put in that voice's mouth.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | The line(s) to speak in this voice. | |
| get_cost | No | Price this call instead of running it: returns the estimate and the balance, charges nothing, produces no audio. Worth doing before a long passage, because both houses bill by the size of the text, not per run — so the same tool can cost wildly different amounts depending on what you hand it. The rates behind the estimate are not repeated here; lab_list_models carries them. | |
| provider | No | Cross-check, not a choice: the house that cloned this voice is the one that speaks with it, because a voice id from one house means nothing to the other. Pass it only to assert what you believe the voice is; a mismatch is refused before anything is charged. Omit it and the stored voice decides. Which house a voice belongs to: lab_list_voices. What each house can do: lab_list_models. | |
| voice_id | Yes | A cloned voice's id (lab_cloned_voices.id, from lab_voice_clone or lab_list_voices) — positive integer as string, NOT the raw provider voice id. | |
| project_id | Yes | Project id (from lab_list_projects) — positive integer as string | |
| nur_eigene_daten | No | Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare non-readOnly and non-destructive, so the description carries real weight: it discloses the synchronous execution model and that the result is a ready audio_url with no job_id to poll. The consent warning adds a behavioral constraint the annotations never express; only the absence of any mention of failure modes or cost/auth beyond consent keeps it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the execution model, then the provider constraint, then the consent caveat. No filler, though the parenthetical '(via lab_voice_clone)' and the semi-idiomatic phrasing lean terse enough to be slightly cryptic.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a generation tool with no output schema, the description does the one thing it must: tells the agent the call is synchronous and returns audio_url rather than job_id. With all six parameters documented in the schema and safety covered by annotations, the definition is sufficient to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters (including the provider cross-check and the get_cost flag) are already fully explained in structured data. The description only reinforces that the caller does not choose the voice house here, which the provider schema property already states — baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete verb and resource (speak text in a project's cloned voice) and immediately differentiates itself from the clone step by pointing at lab_voice_clone as the prerequisite. A reader can separate it from lab_dub_tts or lab_voice_clone without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear operating context — synchronous, returns audio directly, voice house is fixed by the clone — plus a consent condition that gates use. It does not name a competing tool (e.g. lab_dub_tts) as an alternative or state when-not-to-use, 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.
Read the sound of a clip (video_id), an audio track (audio_id) or an uploaded file (project_id + asset_key from lab_add_media) as numbers: peak level 0..1 per channel, 16 values per second, up to 60 s per page. Use it to find where music or speech starts, where silence is (below stille_unter), and whether a cut lands on a beat or mid-word — before you move cut points. Continue with weiter_von_s for the next page. Read-only, free.
| Name | Required | Description | Default |
|---|---|---|---|
| bis_s | No | End of the page; at most 60 s after von_s | |
| von_s | No | Start of the page in seconds (default 0) | |
| audio_id | No | Audio track id (from lab_list_audio). Give exactly one of video_id, audio_id, asset_key | |
| video_id | No | Generated video id — its own soundtrack. Give this OR audio_id | |
| asset_key | No | Storage key of an uploaded sound or video file (from lab_add_media). Needs project_id | |
| project_id | No | Project the asset_key belongs to — required with asset_key |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=true; the description adds real behavioral context — the numeric output shape (peak level 0..1 per channel, 16 values/second, 60 s per page) and the 'Read-only, free' cost/safety note. However, it cites pagination via `weiter_von_s`, which does not exist in the schema, muddying the behavioral picture.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads purpose, then input forms, then the use case, then pagination. Dense but nearly every clause carries information; the one wasted clause is the non-existent `weiter_von_s` reference.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers input selection, output semantics, pagination, and the analytical purpose with no output schema to lean on. It falls short only because the pagination parameter it names does not match the actual schema (`von_s`/`bis_s`), leaving the continuation path ambiguous.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description usefully maps video_id/audio_id/asset_key to input forms, but it also references `weiter_von_s` and `stille_unter`, neither of which is a schema property, which can mislead an agent trying to paginate or set a threshold.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (read) and resource (the sound/waveform of a clip, audio track, or uploaded file) and enumerates exactly which id combination selects each input. An agent can tell this apart from sibling analyzers 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete when-to-use guidance: find where music/speech starts, locate silence, check whether a cut lands on a beat or mid-word, and explicitly 'before you move cut points'. It does not name a sibling alternative or state when NOT to use it, 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.
Build a walkable 3D WORLD (Gaussian splat, World Labs Marble) from ONE location picture (costs credits — exact price via get_cost: true). Source: a location board's time variant (loc_id + variante) OR a gallery image of the project (quell_bild_id). stufe 'entwurf' is a cheap draft (about a minute), 'voll' the full world (5-15 min). ASYNCHRONOUS: returns welt_id; poll lab_welt_status. When done, open the studio link, place a camera and save angles — they land in the project gallery and work as seed_image_url for lab_generate. The world only holds near the spot the picture was taken from: reverse shots from inside the room work, flying through walls does not.
| Name | Required | Description | Default |
|---|---|---|---|
| stufe | No | 'entwurf' = cheap draft, 'voll' = full world (default) | |
| loc_id | No | Location board id (from lab_list_locations); needs variante | |
| get_cost | No | Free: the exact price of this operation; nothing is built or charged. Name it to the person before the real run. | |
| variante | No | Which picture of the board: a time variant or its 360° panorama | |
| project_id | Yes | Project id (from lab_list_projects) — the world is filed in this project's gallery | |
| text_prompt | No | Optional description of the place; for a board its prompt prefix is used when left out | |
| quell_bild_id | No | Instead of a board: a finished gallery image of THIS project |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly=false/destructive=false annotations it discloses credit cost with a free pricing probe, that the run is asynchronous and returns welt_id, wall-clock expectations ('about a minute' vs '5-15 min'), a post-run studio workflow, and a real limitation ('flying through walls does not'). That is the mutation/async/cost profile an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads what it builds and the cost caveat, then moves to inputs, then async behavior and limits. Dense with parenthetical asides and some overlap with schema text, but nearly every sentence carries actionable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a costly, asynchronous, multi-input generation tool with no output schema, the description covers cost, duration, return handle, polling target, downstream use of results, and a geometric limitation — nothing needed 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.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description adds value by explaining the entwurf-vs-voll trade-off in time terms and by spelling out the two mutually exclusive input paths (loc_id+variante vs quell_bild_id) at the tool level rather than per-field.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and artifact ('Build a walkable 3D WORLD (Gaussian splat, World Labs Marble)') plus the exact input ('from ONE location picture'), which differentiates it from siblings like lab_generate_location_variants or lab_depth_map that also consume location imagery.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete selection rules: a board time variant (loc_id + variante) OR a project gallery image (quell_bild_id), plus 'call get_cost: true first' and 'poll lab_welt_status'. It stops short of stating when NOT to use it versus neighbouring world/location tools, so it is strong context but not a full when/when-not map.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Status of a world from lab_welt: processing | completed | failed. When completed, studio is the link to walk it and save angles (free). A failed world has been refunded. Read-only, free. Pass wait_s (up to 15) to wait inside the call.
| Name | Required | Description | Default |
|---|---|---|---|
| wait_s | No | Wait up to this many seconds (max 15) for completed/failed; the answer says gewartet_s | |
| welt_id | Yes | The welt_id returned by lab_welt | |
| project_id | Yes | Project id the world belongs to |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description reinforces this with 'Read-only, free'. Beyond that it adds real operational context: failed worlds are refunded, wait_s blocks inside the call up to 15s, and a completed world exposes a studio link. These are traits an agent could not derive from structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the status meaning, then the outcome-specific guidance, then the wait behavior — every sentence carries signal. Slightly terse phrasing ('the link to walk it and save angles') costs a bit of clarity but no padding is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does the necessary work by naming the status states, the studio link, the refund behavior, and the wait result. A few returned fields (e.g. error payloads or project metadata) are unaddressed, but an agent has enough to call and interpret the response correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all three parameters including the wait_s maximum and the gewartet_s response field are already documented. The description restates the wait_s ceiling ('up to 15') and its blocking behavior but adds no syntax or edge-case detail beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Status of a world') and enumerates the possible outcomes (processing | completed | failed). The mention of welt_id being returned by lab_welt implicitly separates this polling tool from the creation tool, so an agent can tell them apart 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly signals when to use it: poll for a world's status, pass wait_s to block for up to 15s instead of re-calling, and follow the studio link once completed. It does not explicitly name an alternative tool to use instead, 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.
Who is connected: the FilmLab account (email, user id, name, tier, credits) and how this connection signed in (oauth, oauth_geraet, bridge_key, legacy service user, or anonym). For a device sign-in it also lists the device limits (projects, credits, end date). Call it when results look like someone else's — two clients signed in with two accounts see different projects. Works without an account. Read-only, free.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already covers safety, yet the description adds genuinely useful traits: it works without an account (auth-free), it is free, and it enumerates the sign-in method variants (oauth, oauth_geraet, bridge_key, legacy service user, anonym) plus device limits for device sessions. That is substantive behavioral context beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, all front-loaded on what is returned before the usage trigger. The middle sentence, listing sign-in variants and device limits, is somewhat dense, but no sentence is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no parameters, the description carries the entire burden of explaining return contents, and it does so thoroughly — account fields, sign-in method, and device limits. An agent knows exactly what it will get back and under what conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to clarify. It correctly omits any parameter discussion rather than inventing options.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the exact resource (the FilmLab account: email, user id, name, tier, credits) and the exact secondary payload (how the connection signed in, including the sign-in-method enum). It is unmistakably distinct from diagnostic siblings like lab_diagnose or identity checks like lab_identitaet_pruefen.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a concrete trigger: 'Call it when results look like someone else's — two clients signed in with two accounts see different projects.' That is an explicit when-to-use condition. It does not, however, name an alternative tool or state when not to use it, 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.
Record a correction in the FilmOS knowledge layer when the user contradicts something you asserted from it. Use this the moment a contradiction is stated — not at the end of the session, and not instead of accepting the correction in your answer. It stores the claim AND what is actually true, owned by the user who said it, so lab_wissen surfaces it first next time. It does not delete anything: a deleted false claim returns with the next ingestion, a corrected one does not. Quote the user's own wording for korrektur where you can.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Source URL of the claim, if a hit carried one | |
| thema | Yes | Short topic, so the correction is findable later | |
| quelle | Yes | The source_slug the wrong claim came from — take it from a lab_wissen hit. A source that does not exist is refused, not silently stored. | |
| korrektur | Yes | What is actually true — the user's wording where possible | |
| behauptung | Yes | The claim that is wrong, as it was stated |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say readOnlyHint=false and destructiveHint=false, which the description extends meaningfully: it explains that nothing is deleted, that a deleted false claim returns with the next ingestion while a corrected one does not, and that corrections are stored with owner attribution and surfaced first by lab_wissen. That is exactly the behavioral context annotations cannot convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tight sentences, each carrying distinct weight: trigger condition, timing rule, what gets stored, deletion semantics, and one authoring convention. No filler, well front-loaded with the primary instruction.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers trigger, timing, persistence semantics, refusal behavior for unknown sources (carried by the schema for `quelle`), and the lab_wissen readback loop. For a mutation tool with no output schema, this is complete enough to call correctly on the first try.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five properties are already documented in the schema. The description adds one operational hint — quote the user's own wording for `korrektur` — but the other parameters (quelle, thema, behauptung, url) get no additional narrative. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (record a correction) and resource (in the FilmOS knowledge layer), scoped to the trigger (when the user contradicts something you asserted from it). The sibling lab_wissen is named as the surface that reads this data back, so the tool's role in the knowledge loop is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit timing rule ('the moment a contradiction is stated — not at the end of the session') and an explicit exclusion ('not instead of accepting the correction in your answer'). This is textbook when/when-not guidance tied to an observable condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when the person asks a film-craft question: what a term means, which rule or convention applies, how something is usually done in camera, editing, sound or production — answer from here, not from memory. Ask the FilmOS knowledge layer — measured craft knowledge from vetted sources, with the KNOWN CORRECTIONS first: documented false assumptions plus what is actually true. Call this before asserting a craft fact you did not measure yourself in this session. Every hit carries its source and its usage_policy; quote within that policy and name the source. An empty result means nothing matched — it never means the claim is true.
| Name | Required | Description | Default |
|---|---|---|---|
| frage | Yes | The question, in the language the sources are written in | |
| anzahl | No | How many knowledge hits at most (default 8). Corrections come on top. | |
| mindest_autoritaet | No | Authority floor. Defaults to 0.85 — expert voices only. Below that the corpus holds forum members: useful as context, not as the ground for a craft claim. Lower it only deliberately, and say so in the answer. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already covers the safety profile, and the description still adds substantial behavioural context: KNOWN CORRECTIONS (documented false assumptions plus what is actually true) are returned first, every hit carries a source and usage_policy that bounds quotation, and an empty result means 'nothing matched — it never means the claim is true'. That last clause prevents a serious misreading of the tool's output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Five sentences, each carrying a distinct load: trigger, tool identity, timing precondition, sourcing obligation, and empty-result semantics. The trigger is front-loaded and no sentence is filler or restatement of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description carries the burden of describing returns — and it does: hits with source, usage_policy and corrections first, plus the empty-result interpretation. Nothing an agent needs to invoke this correctly or read its output is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the parameter docs are already unusually rich (authority floor default 0.85, corrections coming on top of anzahl), so the baseline is 3. The description adds no syntax or format detail beyond what the schema states, though it does reinforce the citation/usage_policy expectation that shapes how results are used.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — 'Ask the FilmOS knowledge layer' — and scopes it precisely to 'film-craft question: what a term means, which rule or convention applies, how something is usually done in camera, editing, sound or production'. It resolves the boundary against the wider lab_* family by declaring what belongs here ('answer from here, not from memory') versus what does not ('a craft fact you did not measure yourself in this session').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Opening clause gives the trigger ('Use when the person asks a film-craft question'), and it names the explicit alternative to avoid ('not from memory') plus a pre-condition ('Call this before asserting a craft fact you did not measure yourself in this session'). When-to-use, when-not-to-use and the substitute behaviour are all present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every spoken word with its start and end time, for a clip (video_id), an audio track (audio_id) or an uploaded file (project_id + asset_key). Use it to cut pauses without cutting into a word, to time captions, or to land a graphic on an exact word — instead of guessing seconds from the waveform. Up to 20 min of sound per source; the first call transcribes (Fish Audio, about 0.36 USD per audio hour, booked to the operator, not your credits), every later call for the same sound is served from the cache for free. Returns at most 300 s of words per page; continue with weiter_von_s. Speech recognition spells names the way they sound — check names before you put them on screen.
| Name | Required | Description | Default |
|---|---|---|---|
| bis_s | No | End of the page; at most 300 s after von_s | |
| von_s | No | Start of the page in seconds (default 0) | |
| sprache | No | Spoken language (default de) — the same list the backend accepts | |
| audio_id | No | Audio track id (from lab_list_audio) | |
| video_id | No | Generated video id — its own soundtrack. Give exactly one of video_id, audio_id, asset_key | |
| asset_key | No | Storage key of an uploaded sound or video file (from lab_add_media). Needs project_id | |
| project_id | No | Project the asset_key belongs to — required with asset_key | |
| nur_eigene_daten | No | Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite readOnlyHint already covering the safety profile, the description adds substantial non-obvious behavior: a 20-minute per-source cap, first-call transcription via Fish Audio at ~0.36 USD per audio hour billed to the operator rather than the caller's credits, free cached repeat calls, and a 300 s per-page return limit. It also discloses the gating failure mode (drittland_dritte_gesperrt before any charge) and the ASR caveat about names being spelled phonetically.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded paragraph that leads with what is returned and follows with sources, use cases, limits and cost. Most sentences earn their place, though the pricing/billing parenthetical is longer than the decision it supports needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters, no output schema and no annotations beyond readOnlyHint, the description covers sources, limits, cost model, caching, paging and a quality caveat — enough to call it correctly. The misleading `weiter_von_s` continuation hint and the absence of any statement about what a page item looks like keep it from the top score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, so the baseline is 3; the description restates the source-selection rule and adds pagination semantics. However it instructs the agent to continue with `weiter_von_s`, a parameter that does not exist in the schema — the actual fields are von_s/bis_s — so the one piece of added parameter guidance is actively inconsistent with the input contract.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
"Every spoken word with its start and end time" names a concrete resource and output shape, and the parenthetical enumeration of the three accepted sources (video_id, audio_id, project_id + asset_key) makes the scope unambiguous. It is clearly distinguishable from siblings such as lab_wellenform (waveform) and lab_dub: this is transcript-level word timing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives three concrete scenarios (cutting pauses, timing captions, landing graphics on a word) and contrasts them with a named inferior approach — "instead of guessing seconds from the waveform" — which implicitly routes the agent away from the waveform tool. It does not name a sibling tool explicitly or state when not to use it (e.g. silent media, sources over 20 min).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read or set a project's audience (zielgruppe) and target markets (zielmaerkte). With project_id only: read. Set zielgruppe 'kinder' or 'jugendliche' whenever the project is made for children, families or teenagers — do it BEFORE creating characters or generating. That switches on blocks for the whole project: the adult mode is off even for unlocked accounts, real people are refused (likeness photos, voice clones, lipsync with a consent id, digital doubles as characters), generation stops instead of running unchecked when the content check is down, and the export must mark the whole film as AI. Setting it fails with a readable conflict while a digital double sits in the cast — take it out first. An empty string clears the audience. zielmaerkte (ISO country codes of the researched European countries plus 'EU'; 'UK' is accepted for GB) blocks nothing: it adds a checklist per country of what the customer must observe when delivering there (age rating scale, national AI label, registration duties for creator channels, advertising rules, warnings). The list replaces the previous one; an empty list clears it. The answer always carries zielgruppe, zielmaerkte, zielgruppe_regeln (the active blocks as sentences) and zielmarkt_checkliste — pass the checklist on to the person, it is not legal advice.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project id (from lab_list_projects) | |
| zielgruppe | No | Audience of the project: 'kinder', 'jugendliche' or 'erwachsene'; an empty string clears it. Omit to leave it unchanged | |
| zielmaerkte | No | Target markets as ISO country codes plus 'EU', e.g. ['DE', 'AT', 'CH']. Replaces the whole list; an empty list clears it. Omit to leave it unchanged |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say readOnlyHint=false / destructiveHint=false; the description goes far beyond by enumerating the concrete consequences of setting zielgruppe (adult mode off, real people refused, generation halts if the content check is down, export must mark the film as AI). It also discloses the conflict failure mode, the clearing semantics (empty string / empty list), and the replacement (not merge) behavior of zielmaerkte.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The read/set distinction and the primary 'when to use' rule are front-loaded, and almost every sentence carries operational weight. It is, however, a dense and lengthy block; a few clauses (e.g. the detailed enumeration of every block type) run longer than strictly necessary for invocation decisions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description fully specifies the return payload (zielgruppe, zielmaerkte, zielgruppe_regeln, zielmarkt_checkliste) and even instructs the agent to pass the checklist to a human and flags that it is not legal advice. Nothing needed to invoke or interpret the call correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 real meaning beyond the schema: it explains the downstream effects of each zielgruppe value, the per-country checklist nature of zielmaerkte, and that the list replaces rather than appends. The only reason it isn't a 5 is that value syntax (the ISO/EU/UK code format) is already fully carried by the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a precise verb pair and resource: 'Read or set a project's audience (zielgruppe) and target markets (zielmaerkte).' It immediately splits the two call modes ('With project_id only: read') so the agent knows the tool is dual-purpose, and the resource is distinct from anything in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit triggering conditions ('whenever the project is made for children, families or teenagers') and a required ordering ('do it BEFORE creating characters or generating'). It also names the blocker condition for failure ('fails with a readable conflict while a digital double sits in the cast — take it out first') and clarifies that zielmaerkte blocks nothing, so the agent can reason about which parameter to set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
lab_animate1 field changedInput schema / properties / nur_eigene_daten / descriptionPrevious value: -"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only."New value: +"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only."lab_animate_batch1 field changedInput schema / properties / jobs / items / properties / nur_eigene_daten / descriptionPrevious value: -"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only. Per clip: it covers only THIS job, never the others in the batch."New value: +"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only. Per clip: it covers only THIS job, never the others in the batch."lab_dub1 field changedInput schema / properties / nur_eigene_daten / descriptionPrevious value: -"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only."New value: +"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only."lab_face_fix_freigeben1 field changedInput schema / properties / nur_eigene_daten / descriptionPrevious value: -"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only."New value: +"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only."lab_fertigstellen1 field changedInput schema / properties / nur_eigene_daten / descriptionPrevious value: -"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only."New value: +"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only."lab_freigeben1 field changedInput schema / properties / nur_eigene_daten / descriptionPrevious value: -"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only."New value: +"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only."lab_generate1 field changedInput schema / properties / nur_eigene_daten / descriptionPrevious value: -"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only."New value: +"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only."lab_neue_winkel1 field changedInput schema / properties / rechte_bestaetigt / descriptionPrevious value: -"The person confirmed they hold the rights to an uploaded clip — passed into every run"New value: +"The person confirmed they hold the rights to an uploaded clip — passed into every run. Not needed once the person gave the standing rights statement in the FilmLab app (preis then reports no rechte_noetig); never set it on your own"lab_orbit1 field changedInput schema / properties / nur_eigene_daten / descriptionPrevious value: -"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only."New value: +"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only."lab_reference_motion2 fields changedInput schema / properties / nur_eigene_daten / descriptionPrevious value: -"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only."New value: +"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only."Input schema / properties / rechte_bestaetigt / descriptionPrevious value: -"REQUIRED when the reference clip or a character image was uploaded (not made in FilmLab), including characters whose sheet comes from an uploaded photo. It stands for this statement by the HUMAN: 'Ich habe die Rechte an Bild und Ton dieses Clips und die Einwilligung der gezeigten Personen.' Never set it on your own — show the human the statement and pass true only after they agreed. Without it the backend refuses with rechte_fehlen before anything is charged; get_cost tells you up front (rechte_noetig)."New value: +"REQUIRED when the reference clip or a character image was uploaded (not made in FilmLab), including characters whose sheet comes from an uploaded photo. It stands for this statement by the HUMAN: 'Ich habe die Rechte an Bild und Ton dieses Clips und die Einwilligung der gezeigten Personen.' Never set it on your own — show the human the statement and pass true only after they agreed. Without it the backend refuses with rechte_fehlen before anything is charged; get_cost tells you up front (rechte_noetig). Not needed once the human gave the standing rights statement in the FilmLab app: get_cost then reports no rechte_noetig. Only the human can give that statement, in the app; no tool can."lab_run_proposal1 field changedInput schema / properties / nur_eigene_daten / descriptionPrevious value: -"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only."New value: +"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only."lab_sfx1 field changedInput schema / properties / nur_eigene_daten / descriptionPrevious value: -"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only. Matters only for the repair kinds: a source recording can carry voices. Text-to-sound never needs it."New value: +"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only. Matters only for the repair kinds: a source recording can carry voices. Text-to-sound never needs it."lab_ton_durchlauf1 field changedInput schema / properties / nur_eigene_daten / descriptionPrevious value: -"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only."New value: +"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only."lab_transform1 field changedInput schema / properties / nur_eigene_daten / descriptionPrevious value: -"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only."New value: +"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only."lab_upscale1 field changedInput schema / properties / nur_eigene_daten / descriptionPrevious value: -"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only."New value: +"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only."lab_voice_clone1 field changedInput schema / properties / nur_eigene_daten / descriptionPrevious value: -"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only."New value: +"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only."lab_voice_tts1 field changedInput schema / properties / nur_eigene_daten / descriptionPrevious value: -"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only."New value: +"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only."lab_wortzeiten1 field changedInput schema / properties / nur_eigene_daten / descriptionPrevious value: -"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only."New value: +"Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. Not needed when the human has declared this material in the FilmLab app: the backend reads that declaration, also for material derived from it; only the app can store one. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only."lab_prompt_transform2 fields changedInput schema / properties / kontextAdded value: +{
+ "description": "Optional, for mode beautify: the scene and earlier shots, for continuity only. Characters, objects and places named here stay the same; only the prompt itself is depicted.",
+ "maxLength": 1500,
+ "type": "string"
+}Input schema / properties / projektstilAdded value: +{
+ "description": "Optional, with project_id: the Dreamer writes under the project's style kit and look, as in the app. Without it the project only decides the look_in_post filter.",
+ "type": "boolean"
+}lab_dub3 fields changedInput schema / properties / eigene_personAdded value: +{
+ "description": "Set true ONLY if the person whose mouth this dub re-syncs is you, the user (\"the person shown and speaking is me\"). It is the only way to dub without a likeness_ref and must come with einwilligung:true and einwilligung_notiz. For anyone else, a valid likeness_ref is mandatory: without one the call is refused with dub_fremde_person_braucht_kennung (403) before anything is spent. A declaration, not a proof — logged, not verified. Do not set it for somebody else. Unrelated to nur_eigene_daten, which concerns the third-country data flow.",
+ "type": "boolean"
+}Input schema / properties / einwilligung / descriptionPrevious value: -"Consent of the person whose mouth this dub re-syncs, when there is no Likeness Register id for them yet. Required together with einwilligung_notiz if likeness_ref is not given — a dub always alters a real person's mouth in existing footage, so one of the two consent forms is mandatory, checked before anything is spent. This is a caller attestation, not a registry check like likeness_ref — logged, not verified against likeness.thefilmradar.com. Do not set it to be rid of the error — set it because the consent exists."New value: +"Consent of the person whose mouth this dub re-syncs. Only valid together with eigene_person:true and einwilligung_notiz when there is no likeness_ref — a dub always alters a real person's mouth in existing footage, so a likeness_ref or the own-person form is mandatory, checked before anything is spent. This is a caller attestation, not a registry check like likeness_ref — logged, not verified against likeness.thefilmradar.com, and it covers only YOUR OWN person. Do not set it to be rid of the error — set it because the consent exists."Input schema / properties / likeness_ref / descriptionPrevious value: -"A Likeness Register consent id (likeness.thefilmradar.com) for the person whose mouth this dub re-syncs. Checked live against the register before anything is spent; a revoked or unknown id refuses the call. Mutually exclusive with einwilligung+einwilligung_notiz — one form of consent is required, not both."New value: +"A Likeness Register consent id (likeness.thefilmradar.com) for the person whose mouth this dub re-syncs. Checked live against the register before anything is spent; a revoked or unknown id refuses the call. REQUIRED for every person other than yourself — a plain confirmation no longer stands in for it (DSFA E3, 2026-11-06). Mutually exclusive with eigene_person+einwilligung+einwilligung_notiz — one form of consent is required, not both."lab_voice_clone2 fields changedInput schema / properties / provider / descriptionPrevious value: -"Which voice house clones it. Omit to stay on the default path — an existing workflow does not change vendor just because another one exists. The choice sticks to the voice: whichever house made it is the one that later speaks with it, so lab_voice_tts has no say in this. What each house can do and what it charges is not stated here — lab_list_models carries that."New value: +"Which voice house clones it. REQUIRED — there is no default: neither house has a documented legal basis for the transfer, so you name the one that receives the voice. A request without it is refused before anything is charged (stimmklon_anbieter_fehlt). The choice sticks to the voice: whichever house made it is the one that later speaks with it, so lab_voice_tts has no say in this. What each house can do and what it charges is not stated here — lab_list_models carries that."Input schema / requiredPrevious value: -[
- "project_id",
- "name",
- "sample_audio_url"
-]New value: +[
+ "project_id",
+ "name",
+ "sample_audio_url",
+ "provider"
+]lab_animate1 field changedInput schema / properties / nur_eigene_datenAdded value: +{
+ "description": "Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only.",
+ "type": "boolean"
+}lab_animate_batch1 field changedInput schema / properties / jobs / items / properties / nur_eigene_datenAdded value: +{
+ "description": "Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only. Per clip: it covers only THIS job, never the others in the batch.",
+ "type": "boolean"
+}lab_auto_storyboard1 field changedInput schema / properties / nur_eigene_datenAdded value: +{
+ "description": "Same rule as lab_animate: set it only after the human has said this material shows or contains no real person other than them, for this step. Needed for figures from photos or a style reference on a model without a documented transfer basis.",
+ "type": "boolean"
+}lab_dub1 field changedInput schema / properties / nur_eigene_datenAdded value: +{
+ "description": "Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only.",
+ "type": "boolean"
+}lab_face_fix_freigeben1 field changedInput schema / properties / nur_eigene_datenAdded value: +{
+ "description": "Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only.",
+ "type": "boolean"
+}lab_fertigstellen1 field changedInput schema / properties / nur_eigene_datenAdded value: +{
+ "description": "Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only.",
+ "type": "boolean"
+}lab_freigeben1 field changedInput schema / properties / nur_eigene_datenAdded value: +{
+ "description": "Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only.",
+ "type": "boolean"
+}lab_generate1 field changedInput schema / properties / nur_eigene_datenAdded value: +{
+ "description": "Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only.",
+ "type": "boolean"
+}lab_orbit1 field changedInput schema / properties / nur_eigene_datenAdded value: +{
+ "description": "Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only.",
+ "type": "boolean"
+}lab_reference_motion1 field changedInput schema / properties / nur_eigene_datenAdded value: +{
+ "description": "Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only.",
+ "type": "boolean"
+}lab_run_proposal1 field changedInput schema / properties / nur_eigene_datenAdded value: +{
+ "description": "Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only.",
+ "type": "boolean"
+}lab_sfx1 field changedInput schema / properties / nur_eigene_datenAdded value: +{
+ "description": "Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only. Matters only for the repair kinds: a source recording can carry voices. Text-to-sound never needs it.",
+ "type": "boolean"
+}lab_ton_durchlauf1 field changedInput schema / properties / nur_eigene_datenAdded value: +{
+ "description": "Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only.",
+ "type": "boolean"
+}lab_transform1 field changedInput schema / properties / nur_eigene_datenAdded value: +{
+ "description": "Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only.",
+ "type": "boolean"
+}lab_upscale1 field changedInput schema / properties / nur_eigene_datenAdded value: +{
+ "description": "Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only.",
+ "type": "boolean"
+}lab_verkettung1 field changedInput schema / properties / jobs / descriptionPrevious value: -"One entry per clip, IN ORDER — the same fields as lab_animate (prompt, scene_ref, tool, duration_seconds, resolution, character_refs, location_id, source_image_id …). Each prompt: 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. scene_ref decides the chains: consecutive clips with the same scene_ref chain, a clip without scene_ref stands alone."New value: +"One entry per clip, IN ORDER — the same fields as lab_animate (prompt, scene_ref, tool, duration_seconds, resolution, character_refs, location_id, source_image_id, nur_eigene_daten …). nur_eigene_daten is per clip and follows the rule of lab_animate. Each prompt: 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. scene_ref decides the chains: consecutive clips with the same scene_ref chain, a clip without scene_ref stands alone."lab_voice_clone1 field changedInput schema / properties / nur_eigene_datenAdded value: +{
+ "description": "Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only.",
+ "type": "boolean"
+}lab_voice_tts1 field changedInput schema / properties / nur_eigene_datenAdded value: +{
+ "description": "Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only.",
+ "type": "boolean"
+}lab_wortzeiten1 field changedInput schema / properties / nur_eigene_datenAdded value: +{
+ "description": "Only for a model that sends inputs to China or a US recipient without a documented basis, when the step carries images, clips, voices or faces. Means: this material shows or contains no real person other than the human using this account. Set it ONLY after the human has said exactly that for THIS step; never assume it, never reuse it for the next step. An LK reference, a licensed likeness or another person's agreement does not replace it. Without it the backend refuses with drittland_dritte_gesperrt before any charge; then use a non-gated model or text only.",
+ "type": "boolean"
+}lab_shot_abdeckunglab_animate1 field changedInput schema / properties / veraltete_figur_okAdded value: +{
+ "description": "Only with source_video_id (the clip path); animating an image rejects it. Exception for a reference clip made with an OLDER version of a character: such a clip is refused (figur_veraltet, nothing charged). Set it to true ONLY after the human has seen that warning and said yes to going on with the old version — ask first, name the price, wait for the yes; never set it on your own. Default off. The alternative is to re-create the clip with the current version of the figure.",
+ "type": "boolean"
+}lab_reference_motion1 field changedInput schema / properties / veraltete_figur_okAdded value: +{
+ "description": "Exception for a reference clip that was made with an OLDER version of a character: such a clip is refused (figur_veraltet, nothing charged), because the new run would render the figure in its old look. Set it to true ONLY after the human has seen that warning and said yes to going on with the old version — ask first, name the price, wait for the yes; never set it on your own. Default off, and an ordinary call is unchanged without it. The alternative is to re-create the clip with the current version of the figure. get_cost lists figur_veraltet beforehand, so you see whether the refusal threatens.",
+ "type": "boolean"
+}lab_reference_motion1 field changedInput schema / properties / scene_refAdded value: +{
+ "description": "The shot this clip belongs to, as `sb_N` (N = the shot number in the shot list, e.g. `sb_4`). With it the clip shows on the story axis and, once accepted, joins the main sequence in story order via the rough cut. Without it the clip only lands in the gallery and neither the axis nor the rough cut sees it.",
+ "pattern": "^sb_\\d{1,4}$",
+ "type": "string"
+}lab_review_asset2 fields changedInput schema / properties / tagsAdded value: +{
+ "description": "Defect tags: WHAT is wrong, from a fixed list — independent of the verdict (an accepted asset can carry tags; tags never change verdict or selected). At most 5 per asset. Pass only tags that apply to the asset type (the brackets show where each applies). action_wrong [video/image] — a requested action does not happen or happens differently (also ambient movement such as shadows, lights, crowds); expression_wrong [video/image] — facial expression, gaze or blinking is wrong; camera_motion [video] — the camera moves differently from the request (handheld shake or push-in missing, wrong direction); framing [video/image] — shot size, angle, horizon or position in the frame differs from the request; colour_shift [video/image] — colour or light differs from the request or jumps; wrong_count [video/image] — wrong number of people or things (e.g. fewer extras than asked); missing_element [video/image] — a requested object or detail is not there; identity_drift [video/image] — face, wardrobe or build differs from the reference; wrong_place [video/image] — the place or layout does not match; anachronism [video/image] — something from the wrong era in a period setting; extra_people [video/image] — a person who is not part of the cast; text_wrong [video/image] — requested text is wrong or unreadable; anatomy [video/image] — hands, limbs or face are distorted; artifacts [video/image] — flicker, distortion, watermark, logo or a visible seam; frozen [video] — the picture freezes; continuity_jump [video] — the join at a cut or chained clip jumps; lip_sync [video] — lips do not match the sound; audio_wrong [video/sound] — sound is missing, jumps or does not fit; other [video/image/sound] — anything else — put the detail in `reason`.",
+ "items": {
+ "enum": [
+ "action_wrong",
+ "expression_wrong",
+ "camera_motion",
+ "framing",
+ "colour_shift",
+ "wrong_count",
+ "missing_element",
+ "identity_drift",
+ "wrong_place",
+ "anachronism",
+ "extra_people",
+ "text_wrong",
+ "anatomy",
+ "artifacts",
+ "frozen",
+ "continuity_jump",
+ "lip_sync",
+ "audio_wrong",
+ "other"
+ ],
+ "type": "string"
+ },
+ "maxItems": 5,
+ "type": "array"
+}Input schema / properties / tags_modeAdded value: +{
+ "description": "add (default): add to the tags this person already set on the asset. replace: set exactly these tags (an empty list clears them). Only the caller's own tags are touched, never another person's or the machine tags.",
+ "enum": [
+ "add",
+ "replace"
+ ],
+ "type": "string"
+}lab_cast_kandidatenlab_cast_autopopulate1 field changedInput schema / properties / herkunftAdded value: +{
+ "description": "Allow the origin as the casting deviation (default false). Only turn it on when the person asked for casting against type by origin.",
+ "type": "boolean"
+}lab_identitaet_pruefen4 fields changedInput schema / properties / clip_framesAdded value: +{
+ "description": "Frames cut out of generated clips; images and frames together at most 16.",
+ "items": {
+ "properties": {
+ "sekunden": {
+ "description": "Seconds into the clip to cut a frame at, no duplicates (lab_bilder shows what is there)",
+ "items": {
+ "minimum": 0,
+ "type": "number"
+ },
+ "maxItems": 16,
+ "minItems": 1,
+ "type": "array"
+ },
+ "video_id": {
+ "description": "Generated-video id of a clip in this project (from lab_orbit, lab_animate or lab_job_status) — positive integer as string; one entry per clip",
+ "type": "string"
+ }
+ },
+ "required": [
+ "video_id",
+ "sekunden"
+ ],
+ "type": "object"
+ },
+ "maxItems": 16,
+ "type": "array"
+}Input schema / properties / image_ids / descriptionPrevious value: -"Completed image ids of this project (from lab_generate/lab_auto_storyboard) — positive integer strings, no duplicates"New value: +"Completed image ids of this project (from lab_generate/lab_auto_storyboard) — positive integer strings, no duplicates. Give this and/or clip_frames."Input schema / properties / image_ids / minItemsRemoved value: -1Input schema / requiredPrevious value: -[
- "project_id",
- "character_id",
- "image_ids"
-]New value: +[
+ "project_id",
+ "character_id"
+]lab_murnau_vfx_auftraglab_murnau_vfx_preislab_murnau_vfx_statuslab_speicherort2 fields changedInput schema / properties / abschliessenAdded value: +{
+ "description": "true: the project is finished — delete all of FilmLab's working copies. Ask the person first",
+ "type": "boolean"
+}Input schema / properties / auch_offeneAdded value: +{
+ "description": "With abschliessen: also delete files that were never picked up (they are then gone for good)",
+ "type": "boolean"
+}lab_speicherortlab_timeline_apply2 fields changedInput schema / properties / manifest / properties / clips / items / properties / tempoAdded value: +{
+ "description": "Fixed speed of this clip: 1 = normal, 2 = twice as fast, 0.5 = slow motion. The clip keeps its length on the timeline and shows dauer_s × tempo seconds of its source. Setting it removes a ramp the clip had. Ignored (and reported) when a non-empty tempo_kurve is given. Omit both to keep what an existing clip_id has",
+ "maximum": 16,
+ "minimum": 0.0625,
+ "type": "number"
+}Input schema / properties / manifest / properties / clips / items / properties / tempo_kurveAdded value: +{
+ "description": "Speed ramp across the clip — takes precedence over tempo. Needs dauer_s. [] removes a ramp (the clip keeps its average speed; add tempo: 1 for normal). Sound is muted wherever the speed is below 0.5× or above 4×, as in the editor and the export",
+ "items": {
+ "properties": {
+ "kurve": {
+ "description": "Shape from this point to the next: linear, ease (smooth) or halt (hold this speed). Default linear",
+ "enum": [
+ "linear",
+ "ease",
+ "halt"
+ ],
+ "type": "string"
+ },
+ "t": {
+ "description": "Seconds from the clip start ON THE TIMELINE (output time), not in the source",
+ "minimum": 0,
+ "type": "number"
+ },
+ "wert": {
+ "description": "Speed at this point",
+ "maximum": 16,
+ "minimum": 0.0625,
+ "type": "number"
+ }
+ },
+ "required": [
+ "t",
+ "wert"
+ ],
+ "type": "object"
+ },
+ "maxItems": 32,
+ "type": "array"
+}lab_face_fixlab_face_fix_freigebenlab_reference_motion1 field changedInput schema / properties / reference_video_url / descriptionPrevious value: -"URL of the clip whose motion is taken. Use the url/video_url a previous answer gave you (lab_list_assets with asset_type 'video', lab_job_status, lab_review_queue) — never a hand-built address: the bucket is not guessable and a wrong one renders and bills into a 404. Leave it out to run on `referenzen` alone (at least one image reference, no `figur`, no in_sec/out_sec, no depth) — the models that allow it carry referenzen_ohne_video in lab_list_models."New value: +"URL of the clip whose motion is taken. Use the url/video_url a previous answer gave you (lab_add_media, lab_list_assets with asset_type 'video', lab_job_status, lab_review_queue) — never a hand-built address: the bucket is not guessable and a wrong one renders and bills into a 404. An asset_key from lab_add_media (filmlab/projects/<id>/…) is accepted too and turned into a signed address here. Leave it out to run on `referenzen` alone (at least one image reference, no `figur`, no in_sec/out_sec, no depth) — the models that allow it carry referenzen_ohne_video in lab_list_models."lab_animate1 field changedInput schema / properties / apply_grundtonAdded value: +{
+ "description": "Defaults to TRUE on the backend: the project's ground tone (the filmmaker's own creative signature, set in the Composer's prompt stage) goes right after the prompt. Pass false only to deliberately opt out for this one call.",
+ "type": "boolean"
+}lab_animate_batch1 field changedInput schema / properties / jobs / items / properties / apply_grundtonAdded value: +{
+ "description": "Defaults to TRUE on the backend (the project's ground tone goes right after the prompt). Pass false to opt out for this clip only",
+ "type": "boolean"
+}lab_generate1 field changedInput schema / properties / apply_grundtonAdded value: +{
+ "description": "Defaults to TRUE on the backend: the project's ground tone (the filmmaker's own creative signature, set in the Composer's prompt stage) goes right after the prompt. Pass false only to deliberately opt out for this one call.",
+ "type": "boolean"
+}AI film studio: shoot video, images and sound, review takes, audit scripts, quote before you shoot.
AI film studio: your stories, shots and edits, plus Unreal and Unity orders, from your account.
Make AI short films with your agent: script, storyboard, quoted image and video, review and export.
AI creative studio for your assistant: ads, short films, video, image and audio, estimate first.
Add one secure layer between your agents and this server.