AI film lab for filmmakers: generate and review images/clips with input provenance, cost preflight
Scored across 127 tools
The set is enormous and contains several near-sibling clusters (lab_job_status vs lab_get_job vs lab_batch_status vs lab_jobs_inflight; lab_grade vs lab_grade_clip vs lab_scopes vs lab_look_match; lab_bilder vs lab_capture vs lab_render_frames vs lab_contact_sheet; lab_shots vs lab_shots_ableiten vs lab_shots_setzen), but the descriptions actively fence them off, often explicitly ('This is NOT lab_shots_ableiten', 'different from lab_get_generation'), so a careful agent can tell them apart.
Every name uses the same lab_... prefix and snake_case, which is a strong, predictable surface. There is a mild inconsistency in that the second token mixes English and German and mixes verbs with nouns (lab_get_project vs lab_scopes vs lab_aufloesung), but the convention itself never breaks.
127 tools is far past any usable ceiling for one server; the surface is fragmented into many single-purpose tools, multiple polling tools, and per-family step tools that could have been parameters or grouped endpoints. This volume guarantees the agent must read dozens of descriptions before acting and makes mis-selection likely.
Coverage is unusually deep: projects, sequences, timeline, shots, characters, locations, media, audio, mixing, export, review, jobs, workflows and knowledge all have tools. Minor gaps exist at the lifecycle edges — no update/delete project, no update/delete character, no delete sequence — which an agent can mostly work around but which leave dead ends.
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). 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 readOnlyHint=false and destructiveHint=false, so the description carries the real behavioral burden and does so richly: 100 MB cap, server-side fetch, signed upload_url with hour-long validity, exact-header requirement, 403 on missing header, refusal of internal addresses, and that the call is free. It also flags the EU AI Act disclosure consequence and the C2PA/IPTC override on herkunft.
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 and front-loaded, leading with the purpose and the two paths before edge cases. It is long, but nearly every clause carries operational detail an agent needs (headers, 403, abschluss_key). Slightly heavy on em-dash-embedded asides, which costs it 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?
For a 7-parameter tool with no output schema, the description fills the gap by describing all relevant return values (asset_key, upload_url, header, anleitung, abschluss_noetig, abschluss_key) and the full two-phase conditional flow. An agent can complete the call chain end-to-end 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 coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: the 100 MB limit on media_url, that file_name/content_type yields a signed upload URL and header, and the exact semantics of the abschluss_key follow-up call. It stops short of adding format detail for every field, so not a 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 specific verb and resource ('bring your own video, audio or image into a project') and explicitly distinguishes itself from generation ('not generated, yours'), which separates it from siblings like lab_generate. An agent knows exactly what this 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?
Names the two mutually exclusive input paths (media_url vs file_name + content_type), gives the selection condition for each, and describes the conditional abschluss_key re-invocation flow plus the alternative for consuming the result (lab_timeline_apply). Nothing about routing 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.
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 | |
| 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. | |
| 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. | |
| 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. | |
| 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. | |
| 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. | |
| 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. |
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 most of the burden. It does add a key behavioral fact — 'Costs credits when called without get_cost' — which the annotations do not express. But for a 31-parameter, quota-consuming tool it omits other important behavior: that it is asynchronous (results via lab_job_status), the keyframe-approval checkpoint (ohne_keyframe), and the several named refusal paths.
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 front-loaded, no filler. Each sentence carries a distinct instruction (what it does, which model to pick, how to check cost). Slightly shy of 5 only because it is thin relative to the tool's surface rather than wasteful.
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 31 parameters, nested objects, no output schema, and only two weak annotations, the description should orient the agent more than it does. It covers purpose and cost flow but omits the video-source mode, the async job/result pattern, and the batch alternative — all of which an agent must know before choosing 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 description coverage is 100%, so per the rubric the baseline is 3. The description adds only a pointer to get_cost as a preflight mode, which the schema already documents in depth; it contributes no syntax, ordering, or interaction detail 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 and resource: 'Animate a completed image into a clip with a video model.' That is unambiguous and clearly not a batch, generation, or grading tool. However, it never mentions that the tool can also animate FROM a clip (source_video_id / reference-motion path) or how it differs from siblings like lab_generate, lab_animate_batch, or lab_reference_motion.
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 real pre-call routing: pick the model from lab_list_models, preflight with get_cost, or confirm a card via lab_propose. That is genuine usage guidance for the cost workflow. It stops short of when-to-use-this vs alternatives (batch, video-source, reference_motion), so usage is implied rather than delimited.
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. 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 give readOnlyHint=false and destructiveHint=false, so the description carries the real behavioral burden and delivers: all jobs validated before quota spend, quota billed once collectively (one ledger row), per-clip refunds on partial failure, and a returned batch_id. These billing/validation/refund semantics are exactly the non-obvious traits 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 core action and scope, then each following clause adds a distinct, non-redundant fact (validation ordering, quota pooling, per-clip refunds, batch_id polling, cost preflight). No filler sentences.
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 2 required params, the description fills the gap by naming the return value (batch_id) and the correct follow-up tool (lab_batch_status), plus quota and refund behavior. An agent has everything needed to invoke and continue 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 only parameter mentioned, get_cost, largely restates its own schema text about preflighting price without generating, adding little beyond what the field already documents.
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 (animate many images into videos) with explicit scope (max 25 jobs, one call) and immediately distinguishes itself from the looping alternative lab_animate. An agent can tell what it does and how it differs from its closest sibling 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?
Explicitly says 'Prefer this over looping lab_animate' with the reason (pre-validation avoids orphaned paid generations), and routes the agent onward to lab_batch_status for polling and to get_cost for a dry run. When-to-use, when-not, and alternatives are all named.
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). | |
| 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?
Adds substantial behavior beyond the readOnlyHint=false/destructiveHint=false annotations: credits are charged up front per scene, failed reference frames are refunded and never generated, the scene split is synchronous and can 504 after ~55s, and frames render in the background. This is exactly the disclosure a credit-spending mutation 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 purpose and the script/situationen split, and every sentence carries operational information. It is long and heavy with caps-emphasis, but almost nothing is 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?
For a 10-parameter, credit-spending tool with no output schema, the description covers return values (figuren, figuren_kosten_geschaetzt, kosten_je_bild, new image ids), background rendering, and polling. 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 meaning: situationen ignores max_scenes and yields exactly one frame per entry, bewegung_en is persisted for later animation, style_reference_url counts as one extra reference in pricing, and figuren_raten is recorded per frame. It mainly reinforces schema text rather than extending it, so 4.
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 (auto-generate a storyboard) and precisely distinguishes its two input modes: script (LLM-split into scenes) vs situationen (one frame per entry, no LLM). An agent can tell exactly what this produces and how the two paths differ.
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 routing rules: script OR situationen are mutually exclusive, situationen requires figur_id, figuren_raten is an opt-out only when the human asks, and 'Ask the human before running it.' It also names the fallback path (run in the app on 504) and the follow-up tool (lab_job_status).
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?
Adds substantial behavior beyond the annotations: it is free and generates nothing itself, refuses with 409 if a start image is not accepted, must choose the smallest duration covering the slot to avoid off-beat drift, is repeatable, and reports open items and undersized videos left as stills.
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 workflow, then constraints, with every sentence carrying weight. It is dense and mixes German/English labels, which slightly reduces readability, but there is little true redundancy.
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-mode, dependency-heavy tool with no output schema, the description fully covers the workflow, the shape of the returned `jobs`, the stated failure mode (409), and the reporting behavior an agent needs to chain calls 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 adds genuine semantic value: it explains the plan/einsetzen aktion split in workflow terms and the constraint that the `tool` model must be the smallest duration that still covers the slot. It does not add anything for `resolution`, so it stops short of a 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 specific verb+resource+scope: turning still-image clips of a sequence into beat-snapped video clips that exactly fill their slots. The beat-length framing and the two-phase aktion model distinguish it cleanly from generic siblings like lab_animate or lab_add_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?
Explicit sequencing: run lab_beatgrid and lab_apply_rhythm BEFORE plan, then pass returned jobs to lab_animate_batch (get_cost first, then run), and use aktion einsetzen once videos are done. Names alternatives and prerequisites with no inference left to the agent.
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.
| 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=false and destructiveHint=false; the description goes well beyond them by disclosing the LLM-run cost per call, the 6-item cap, the project binding, the absence of reference images on created sheets, and explicit fail-open semantics (empty `created` list plus `note` rather than an error). These are exactly the behavioral traits an agent needs to budget and handle the 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-loaded with the core purpose and the sibling comparison, and every sentence carries distinct information (cost, cap, prerequisite, image gap, fail-open). It is dense and slightly long for a single-parameter tool, 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?
With no output schema, the description still covers the return contract (a `created` list, plus a `note` on failure), the prerequisite workflow, and the cost model. Nothing an agent needs to invoke 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 description coverage is 100% and the sole parameter is fully documented there, so the baseline is 3. The description only implies the project scoping ('a project's material', 'binds each to the project') without adding format or sourcing detail beyond what the schema already states.
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 ('Create character sheets for the people found in a project's material') and immediately differentiates itself from siblings by naming lab_cast_gaps as its read-only counterpart and lab_create_character's territory. An agent can distinguish it from the other cast 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 explicit when-to-use ('Run lab_cast_gaps first if you want to see what it would create'), a hard operational boundary ('at most 6 per call'), and a downstream prerequisite chain (sheets need lab_generate_character_reference before lab_generate accepts them as `character_refs`). Nothing about sequencing 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.
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. Optionally set a title.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Project title (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description adds that it returns the new project id and that title is optional, which is useful, but it says nothing about permissions, side effects, or whether the project becomes active/selected after creation.
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 the return value. Slight redundancy: 'Optionally set a title' duplicates the schema's own description of the only parameter.
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, stating the return value (the new project id) is the key piece of missing structured information, and the description supplies it. For a one-optional-parameter creation tool this is nearly complete, though it omits any notion of what state the new project starts in.
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 as 'Project title (optional)'. The description's 'Optionally set a title' merely restates the schema, adding no format, length, or default-value detail. 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 ('Create') and resource ('FilmLab project'), which cleanly separates it from lab_get_project and lab_list_projects and from the other create_* siblings (character, location, sequence). An agent can identify the target entity 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?
Usage is implied by the verb — you call this when you need a new project container — but the description names no alternatives, prerequisites, or when-not-to-use conditions (e.g., whether a project must not already exist, or how it relates to lab_create_sequence). Minimum viable guidance.
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.
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, 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. | |
| 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. Mutually exclusive with einwilligung+einwilligung_notiz — one form of consent is required, not both. | |
| 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. | |
| 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, so the description carries the real burden and does: it flags ASYNCHRONOUS behavior with an immediate job_id, the mandatory consent prerequisite checked before spend, and the fact that a dub always alters a real person's mouth. It also notes mutually exclusive audio sources and that a choice is not made silently because the other option may already have been paid for.
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 the two input modes, then async behavior and prerequisites — a sensible ordering. It is dense but mostly earns its length; the main waste is that the backend ROI-crop/veed_v2 explanation largely restates the schema's own backend 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?
For an 11-parameter mutation tool with no output schema, the description covers the lifecycle (async job_id then lab_job_status), the cost/quota implications, the consent requirement, and the audio-source decision. 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% and the per-parameter descriptions are already very rich, so the baseline would be 3. The description adds integration-level semantics the schema states only in isolation — the two mutually exclusive audio paths, backend selection heuristics, and that the voice/consent parameters gate each other — which meaningfully helps an agent assemble a valid call, though it does not introduce new syntax or 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?
States a specific verb+resource ('Dub a sequence into another language') and immediately clarifies the two input modes (ready audio track vs cloned-voice text). It distinguishes itself from siblings by name, notably lab_dub_tts (which just produces audio) and the async job flow, so an agent can tell them apart without opening the 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?
Explicit branch conditions: use en_audio_url when a track already exists, use voice_id+dub_text for a clone reading; pick ROI-crop/replicate for one long static talking-head shot and veed_v2 for multi-shot or partly hidden mouths. It also states prerequisites (need a cloned voice first, via lab_voice_clone/lab_list_voices) and the follow-up step (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.
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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover readOnlyHint=false/destructiveHint=false; the description adds the retention nuance (a NEW video row comes back, the draft stays), the four named backend refusals, and the credit-charging rule that avoidable via get_cost with nothing charged on failure. This is substantial behavior 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-loads the core action and outcome, then conditions, then the anti-pattern warning and cost note. Dense and mostly waste-free, though the 1080p/seed/sound restatement and repeated cost/refusal framing make it slightly 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 compensates by describing the returned artifact (new video row, draft retained) and enumerating failure modes. Preconditions, account scoping, and cost behavior are all covered, 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 description coverage is 100%, so every parameter is already fully documented, including get_cost's preflight semantics. The description reinforces get_cost's role as the charge-avoiding path but adds no syntax, format, or constraints the schema lacks, matching the baseline 3 for high-coverage schemas.
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 (finish) and resource (an accepted DRAFT) with the exact outcome (1080p, same motion/seed/sound). It ties the draft back to lab_reference_motion with draft:true and explicitly rules out the common mistaken path (download and re-upload), so it is unmistakable 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 explicit preconditions (draft must still be valid, must be called through the ordering account), names the exact refusal reasons, and tells the agent to call get_cost first and let the human confirm. It also states a clear when-not: never re-upload a draft to reach this operation.
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. 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?
Beyond readOnlyHint=true, the description discloses the actual status vocabulary (wartet, laeuft, fertig, fehlgeschlagen, abgebrochen), the per-node payload (status, attempts, result, error), and the crucial contract that a node's result is exactly what the tool returned and its ids feed subsequent tools. It also explains the `gefunden: false` outcome for angebot_id, which is non-obvious behavioral semantics.
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 'Use when...' and then the resource definition, with zero filler. It is dense but every clause carries operational information (status values, node payload, id lineage, fallback lookup); the only minor cost is that the angebot_id/gefunden explanation reads as a slight appendage.
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 burden and does so: overall status, per-node status/attempts/result/error, and the sentinel `gefunden: false` case. Both (optional) parameters are covered, and the read-only safety profile is declared by annotations, so 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 goes further: it explains that angebot_id substitutes for lauf_id to locate the run started from that offer, and what `gefunden: false` implies (no run created, nothing charged). That is real meaning beyond the schema's terse 'From lab_flow_angebot' 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?
It gives a precise verb+resource ('State of a Flow (Pipeline) run started with lab_flow_starten') and explicitly enumerates what is reported: overall run status plus per-node status, attempts, result and error. This clearly separates it from lab_flow_starten, lab_flow_fortsetzen and lab_flow_angebot 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?
The opening clause is a strong intent trigger list ('how far a run is, whether it finished, why it stopped or hangs, or what a step returned'), and it states the fallback path when lab_flow_starten's answer was lost. It never states when NOT to use it or names a competing status tool (e.g. lab_job_status, lab_batch_status), so it stops short of the top band.
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') 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnlyHint=false/destructiveHint=false annotations: it discloses that the call spends credits, that only the mask had been charged until now, that a NEW video row is returned while the paused row persists, and that the backend refuses with named reasons (nicht_wartend, bereits_freigegeben) before charging.
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 and the cost warning, and every sentence carries consequence (preview check, refund/charging behavior, refusal reasons). It is dense and slightly run-on with multiple em-dash asides, which costs it a point on structure.
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 (a new video row plus the retained paused row), the error surface (named refusal reasons), and the cost model. An agent has everything needed 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 the baseline is 3, but the description adds genuine meaning: it explains the job_id/video_id alternatives resolve to the same paused row, and that omitting get_cost is what actually incurs the charge. It stops just short of adding format/syntax detail 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 precise verb and resource: it releases a paused PERSON-reference run (lab_reference_motion with use_depth 'personen') and starts the paid model run. It is clearly distinguished from sibling lab_reference_motion, which produced the paused row this tool acts on.
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: only after the human has inspected the mask preview, and it names where the preview lives (metadata.personen_referenz_url). It also prescribes the get_cost preflight before spending credits, and routes to lab_job_status for the paused id.
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. | |
| 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. | |
| 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. | |
| 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds quota tracking, persistence to the gallery, budget-exhaustion signaling (fertig:false), pending-row behavior, and silent-drop warnings (referenz_warnung, seed_nicht_unterstuetzt). Much of this detail is also carried in the schema field descriptions, but the core write/commit behavior is well 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?
Long, but front-loaded with purpose and the wait/pending contract before the routing advice, and every clause carries operational information (defaults, polling, cost preflight, identity handling). Density is justified by 19 parameters, though the closing character paragraph repeats points already made in character_refs.
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 describe returns — and it does: finished rows with image_url and inline previews, pending rows, fertig:false on budget exhaustion, and warning fields on reference/model switches. Combined with full schema coverage, 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 description coverage is 100%, so baseline is 3, but the description adds concrete values the schema deliberately withholds — it names the default model flux_pro and the nano_banana_pro alternative for a specific look, and explains seed_image_url's img-to-img role. It goes beyond restating the schema for the highest-impact parameters.
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+environment: 'Generate an image on the production pipeline (fal.ai, quota-tracked, persisted to the project's gallery).' It distinguishes itself from siblings by naming lab_job_status (for polling) and the character tools (lab_list_characters, lab_create_character, lab_generate_character_reference) it complements.
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 guidance for multiple modes: pass wait_s:0 then poll lab_job_status, use nano_banana_pro for the Papercut look, use character_refs instead of re-describing a person across prompts, and call get_cost before a batch or use lab_propose for a confirm card. Alternatives and exclusions are spelled out rather than implied.
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 (Stable Audio via fal.ai) — the first step of the rhythm chain, and the only one that costs credits. 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 |
|---|---|---|---|
| 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, Stable Audio's ceiling is 190). 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 only declare readOnlyHint=false and destructiveHint=false, so the description carries real behavioral load and delivers: asynchronous return with a pending row and null audio_url, nothing playable or bindable yet, polling target, ~1 minute typical / 5 minute timeout, 'failed' status with metadata.error, credit refund on failure, and that this is the only credit-consuming step. This is far 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?
Front-loaded with purpose, then async contract, then prompt advice, then the next-step chain. The measured-confidence example (0.164 vs 0.621) and the autocorrelation detail are concrete justification for the tempo instruction rather than padding, so each 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?
There is no output schema, so the description must describe the return shape — and it does (row with null audio_url, metadata.status 'pending', later 'completed'/'failed' with metadata.error). Combined with cost, timeout, polling and downstream chaining, 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 schema already documents all five parameters including the tempo guidance and the duration-vs-timeline caveat. The description reinforces the prompt/tempo point but adds little parameter detail the schema does not already contain; 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 ('Generate a MUSIC track for a project') plus the provider (Stable Audio via fal.ai) and its position in the workflow ('first step of the rhythm chain'). It is clearly distinguishable from siblings like lab_apply_rhythm and lab_bind_audio, which it names as downstream steps.
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 use it (first step of the rhythm chain), how to follow up (poll lab_list_audio with audio_type 'music'), and the conditional guidance 'PUT THE TEMPO IN THE PROMPT if you intend to cut on the beat' with supporting measured evidence. It also names the three subsequent tools in order, so the agent knows what comes next.
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.
| 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?
Annotations already declare readOnlyHint=true, so the safety profile is covered. Beyond that the description adds real behavior: the four possible status values, the shape of result for a clip chain vs. an Umzug import, and the semantics of waiting inside the call (with gewartet_s reported). It omits what happens on an unknown/expired job_id, keeping it out of the top band.
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 the status enum, then return shapes, then the wait hint. Dense and mostly waste-free, though the two long result-shape enumerations make it longer than a minimal status tool 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?
With no output schema, the description correctly takes on the burden of explaining the return value for two concrete job types and the wait behavior. It is nearly complete; only failure/unknown-job handling and the sibling overlap remain unaddressed.
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 (job_id and wait_s, with its 0-80 bound) are already fully documented in the schema. The description largely restates this ('wait_s (up to 80)'), adding only the rationale for using it over rapid polling, which is the expected baseline-plus behavior.
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 the status of a background job by job_id') with the domain of statuses enumerated. It does not, however, distinguish itself from the very similar siblings lab_job_status or lab_batch_status, so an agent must guess which of the three to 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?
Explicitly says to poll this 'after starting a long-running generate/export' and to prefer wait_s 'instead of polling in quick succession', which is actionable context. It stops short of naming the sibling alternatives (lab_job_status, lab_jobs_inflight) that would resolve the overlap.
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. 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?
readOnlyHint=true already establishes the safety profile, so the description's job is lighter. It adds the meaningful detail that the response is the project's 'full stage state' rather than a summary, which tells the agent what depth of data to expect. No auth or rate-limit notes, which is acceptable for a simple read.
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, front-loaded with the triggering user situation before the technical action. Minor redundancy between the enumerated examples ('current stage, what is finished, what comes next') and the later 'project's state', but nothing is wasted outright.
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 getter with no output schema, the description covers purpose, usage trigger, and parameter provenance adequately. It stops short of describing return structure, but with no output schema declared that omission 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 coverage is 100% for the single project_id parameter, so the baseline would be 3. The description earns above baseline by telling the agent where the id comes from (lab_list_projects), 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 specific verb and resource ('Get a single FilmLab project with its full stage state') and distinguishes itself from the sibling list tool by naming lab_list_projects as the source of the id. An agent can tell it apart from lab_list_projects or lab_get_sequence 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 when-to-use trigger ('when the person asks where a project stands... or wants the project's state before continuing') and points to lab_list_projects for obtaining the id. No when-not or exclusion guidance, 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.
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 | |
| 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 beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false): 'Only the fields you send change,' 'zuruecksetzen: true starts from neutral,' 'sek: null removes it,' 'warper: null removes it,' and 'Murnau bakes the export LUTs when you set it.' It also discloses side effects ('Writes state, costs nothing'), giving a rich behavioral picture consistent with 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 core action and the list/grade distinction before the parameter dump. The middle is a dense, semicolon-chained reference, but nearly every clause encodes semantics the schema does not provide, so most of it earns its place. Readability suffers slightly from the run-on formatting.
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 correctly describes the listing return ('clip_id, start/end, current grade, input profile') and the programme grade. For a deeply nested mutation tool with 5 parameters, it covers the fields, their interactions (serial schritte, secondary schutz), and the reset/remove semantics that an agent needs 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?
Although schema description coverage is nominally 100%, the schema itself is a thin container with additionalProperties, so the description carries the real semantics. It supplies units and ranges for every field (exposure in stops ±5, hue ±180, lift/gamma/gain {x,y,master} ±1), log-wheel behavior, curve encoding, secondary/warper coordinate systems, and null semantics — far beyond anything in 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: 'Set the colour grade of ONE clip in the edit ... or of the whole programme with programm: true.' The scope distinction (clip vs programme) and the dual list/grade mode are explicit, so an agent knows what it does. It does not name or differentiate itself from the sibling grading tools (lab_grade, lab_grade_from_resolve, lab_grade_suggest), keeping it 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 clear workflow context: 'Measure first and after with lab_scopes — its vorschlag.grade is a computed correction you can pass here as grade,' and 'Call WITHOUT grade to list the clips.' This tells the agent when to invoke it and how to obtain inputs. It does not explicitly scope itself against the other lab_grade* siblings, so not a full 5.
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).
| 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 tell the agent this is a non-destructive write. The description adds real behavioral context the annotations cannot: undeclared material defaults to AI, declaration inspects the file for an AI mark, a found mark overrides the declaration back to AI and the response explains why, and listing surfaces the `wirksam` effect. These are exactly the side effects 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 definition, then the two operating modes, then the compliance consequence. Dense but purposeful; the parenthetical explanations of 'eigen'/'ki' and the AI-mark check earn their space. Slightly packed into two long sentences.
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 describing what the agent gets back in both modes (the reason an AI mark forced 'ki', the per-declaration effect). For a 3-parameter tool with a clear dual mode, 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?
Schema coverage is 100%, so the baseline is 3. The description still earns a bonus by explaining the joint semantics of the parameters (herkunft and asset_key must be supplied together to declare; project_id alone means list) and by tying the listing output to the `wirksam` effect, meaning beyond the schema's terse 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?
States a specific verb pair (declare or list) plus the exact resource: the origin of a project's material, spelled out as 'eigen' vs 'ki'. An agent can tell immediately this is about provenance declaration, not asset editing or 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 routes usage by parameter combination: 'With asset_key + herkunft: declare' and 'With project_id only: list'. It also gives the downstream rationale (EU AI Act Art. 50 per-clip disclosure). It stops short of naming when NOT to use it versus provenance-adjacent siblings, but the mode selection is unambiguous.
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 per call, all completed images of this project. The sheet needs a reference image (lab_generate_character_reference).
| Name | Required | Description | Default |
|---|---|---|---|
| image_ids | Yes | Completed image ids of this project (from lab_generate/lab_auto_storyboard) — positive integer strings, no duplicates | |
| project_id | Yes | Project id (from lab_list_projects) — positive integer as string | |
| 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?
Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false): it discloses the async execution model (background, HTTP 202, poll via lab_get_job until done|failed), the return payload fields (passt, sicherheit, abweichungen, begruendung / error), the 16-image cap, and the scope limits (judges identity, not style/light/pose/props/micro-details). This is exactly the operational 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?
Dense but front-loaded: purpose first, then scope exclusions, then cost, then async mechanics and prerequisites. Roughly five clauses, all carrying load; it is on the edge of long 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?
With no output schema, the description carries the return-value burden and does so fully (job_id + poll pattern + result fields). Prerequisite, limits, and scope are all covered, so an agent has everything needed to invoke 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 coverage is 100%, so the schema already documents all three parameters (baseline 3). The description adds genuinely new meaning: 'Up to 16 images per call, all completed images of this project' clarifies the expected content and scope of image_ids beyond the schema's per-field 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 ('Check whether...') and resource ('still images of a project show the SAME character as its character sheet'), and explicitly bounds what is compared (the sheet's detail and fullbody views). It is clearly distinguishable from siblings like lab_continuity_check or lab_abgleich because it names the reference artifact and the identity attributes judged.
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 timing/context cue ('before paid clips are made from them') and names a prerequisite ('The sheet needs a reference image (lab_generate_character_reference)'). It does not explicitly say when NOT to use it or name a competing tool, 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.
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. 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.
| 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?
Annotations only declare readOnlyHint, so the description carries the real burden and does so richly: status enum semantics ('pending'|'completed'|'failed'), which fields populate on completion, the one-time nature of the review check, why bild is free, that a silently rescaled reference looks like a bad generation, and the human-confirmation gate on plan_b. This is genuine behavioural disclosure well 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 core purpose and the project_id+id constraint are correctly front-loaded, but the body is an unusually long wall of text dense with German field names whose names duplicate the schema (kamerapfad, referenz_masse, abweichung, angewandt). Much of it concerns rare edge cases, so signal-to-noise is worse than the content deserves.
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 and does so exhaustively: the shape of status/metadata, image_url/video_url, schritte, review, plan_b, kamerapfad, sprache and referenz_masse, including the conditions under which each is present or absent. Nothing an agent needs to interpret a poll 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 all five parameters are already documented in the schema. The description does reinforce why BOTH project_id and id are needed ('the id alone is not enough'), which is useful, but it repeats the schema's own rationale rather than adding syntax or format detail the schema lacks. 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: it polls the status of an image/video generation started by lab_generate/lab_animate, and explains that the backend has no single-item status endpoint so it filters the project's full list. It separates itself from the starter tools but never distinguishes itself from close siblings like lab_get_job, lab_batch_status or lab_jobs_inflight, which an agent could plausibly pick instead.
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 for when to call it (after lab_generate/lab_animate), why wait_s is preferable to tight polling, when review/plan_b fields appear versus stay absent, and when to consult kamerapfad/referenz_masse. It also gives an explicit behavioural rule ('never start them yourself', only call lab_run_proposal after human confirmation), but offers no exclusion against the other status-like siblings.
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); 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 |
|---|---|---|---|
| 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=true; the description adds real context beyond that — brief caching with a `stand` freshness signal, and the crucial output-shape behavior (COMPACT by default, full fields with klasse/voll). It stops short of documenting pagination or size limits, but discloses enough behavioral nuance to be genuinely useful.
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 and long, but front-loaded with the catalog's purpose and every sentence carries information (fields, routing, output modes, filtering). Minor cost from mixed-language inline tokens and run-on phrasing, but nothing is 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?
With no output schema, the description carries the burden of describing returns and does so — one line per model when compact, `klassen` listing every valid class, and full fields when klasse/voll is set. Combined with the 100%-covered input schema and readOnlyHint, 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 the baseline is 3, but the description adds meaning on top: it explains the default COMPACT vs verbose behavior, the silent-audio semantics of `ton` (including switchable audio), and the AND-listing quirk where a switchable-audio model appears under both i2v_ton and i2v. That is value the schema alone 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?
Opens with a specific resource ('the model catalog') and enumerates exactly what it contains — resolutions, durations, aspect ratios, audio, reference limits, pricing — and states it is grouped by capability class. The agent can immediately distinguish it from generation siblings like lab_generate/lab_animate because it is the read-only lookup that precedes 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?
Explicitly says 'Read this before choosing a `tool` for lab_generate/lab_animate/lab_propose; copy ids verbatim', naming the exact alternatives and the trigger condition. It also gives when-to-narrow guidance (filters, klasse, voll) so the agent knows how to invoke it for the common question.
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 a project's sequences, newest first. 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?
readOnlyHint=true already tells the agent this is a safe read. The description usefully adds the sort order (newest first), but says nothing about result volume, pagination, or what a sequence record contains. With annotations covering the safety profile, this is adequate-but-thin.
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, zero filler, with the operation and its ordering stated first and the routing hint second. Every clause 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-parameter, read-only list tool with a fully documented schema and no output schema, the description covers what the agent needs to select and call it. Only minor gaps remain (no return-field or pagination hints), which is why it stops short of 5.
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 explains project_id including its origin (lab_list_projects) and format (positive integer as string). The description adds no parameter meaning beyond that, 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?
States a specific verb and resource ('List a project's sequences') and adds scope ('a project's') plus ordering ('newest first'). An agent can immediately tell this is a project-scoped listing distinct from lab_create_sequence or lab_get_sequence.
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 motive: find a `seq_id` and avoid creating a duplicate sequence for the same cut. That is real routing guidance, though it describes the alternative behavior rather than naming the sibling tool (lab_create_sequence) explicitly.
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.
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.
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. | |
| 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. | |
| 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 only declare readOnly=false, idempotent, non-destructive; the description goes well beyond that by disclosing mode-specific behavior (generate vs preserve), medium/depth interdependencies, that the Apps host opens a re-runnable form while other hosts return plain text, that look_in_post suppresses grain/halation/vignetting and lists removals, and that unmatched references are rejected rather than passed through.
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 and mode-routing are front-loaded and nearly every sentence carries distinct information. However, the heavy em-dash run-on style makes it dense to parse for a 15-parameter tool, and a few clauses could be tightened without losing meaning.
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 15-parameter tool with no output schema, the description covers return-side details (clip_duration_seconds, prompt_skelett, marker rewriting to @Image1/@Video2/@Audio1), host-dependent presentation, and edge cases like unmatched-reference rejection and look_in_post removals. An agent has enough 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%, so the baseline is 3; the description adds integration semantics the schema lacks, such as handing clip_duration_seconds to lab_animate's duration_seconds and using `tool` so the prompt lays out in that model family's skeleton. Most other param text (mode meanings, video-only depth) largely restates the schema, so it does not earn 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?
The opening states a specific verb and resource — 'Turn a loose idea into a production-ready image or video prompt' — and immediately identifies the engine and its modes. An agent can distinguish this transform tool from generation siblings (lab_generate, lab_animate) 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 explicitly routes usage: beautify GENERATES while polish/format/shorten/expand/simplify PRESERVE, custom and stiluebernahme require an instruction, depth only applies to video and anlass only to beautify. It also names the handoff — pass clip_duration_seconds to lab_animate(duration_seconds) — and names sibling tools (lab_animate, lab_generate, lab_list_models, lab_regie_techniken).
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. 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. | |
| familie | No | Video: pick the model ('seedance-2.0', 'seedance-2.5') instead of a route — the card then names and prices the route the server takes for this account, and the run is PINNED to it (a card promises one price, so no silent fallback). Mutually exclusive with tool and intent. | |
| out_sec | No | Video: end of the excerpt in the reference clip, in seconds. Must lie behind in_sec. | |
| variants | No | Image: how many variants (default 1). Multiplies the price — the card shows the multiplication. | |
| audio_url | No | Video: URL of an existing audio track to lay under the clip. Independent of generate_audio. | |
| scene_ref | No | Scene label (e.g. 'SZ 04'). Stored on the row, so the result can be matched back to a shot list. | |
| project_id | Yes | Project id (from lab_list_projects) | |
| referenzen | No | Video, clip path (source_video_id): typed references. The position IS the address — first image @Image1, first extra clip @Video2, first sound @Audio1. Image references are measured before sending and scaled up to the model's minimum rather than rejected. | |
| resolution | No | Resolution tier, exactly as listed for the model in lab_list_models. Omit for the model's default. | |
| location_id | No | Location board id (from lab_list_locations) — anchors the shot in the same place. | |
| aspect_ratio | No | Image: aspect ratio as W:H, from the model's aspect_ratios in lab_list_models. | |
| costume_refs | No | The costume plate of these characters goes along as an extra reference image — the outfit on an invisible mannequin, NO person. Every id must also be in character_refs. Needs a model whose max_references covers characters + plates. Each plate is one more reference and may cost credits. | |
| end_image_id | No | Video: the completed image to land the clip on (last frame). Only where lab_list_models says supports_end_frame. | |
| camera_motion | No | Video: Structured camera move sent to the model itself — only models whose lab_list_models entry lists camera_motions. Prefer this over prose when a keyframe chain must MOVE rather than cross-fade. | |
| character_refs | No | Character ids (from lab_list_characters) whose reference image locks the cast's identity. Counted against the model's max_references and shown on the card by name. | |
| generate_audio | No | Video: ask for the model's native audio. Only meaningful where lab_list_models says audio: schaltbar. | |
| seed_image_url | No | Image: run img-to-img guided by this existing image URL. Shown on the card as the 'before'. | |
| source_image_id | No | Video: the completed image to animate (positive integer as string). Required for a video proposal — unless source_video_id proposes a clip instead. | |
| source_video_id | No | Video: propose a run FROM A CLIP instead of a still — a generated video id (lab_animate/lab_job_status) or an asset key (lab_list_assets). Mutually exclusive with source_image_id; only for models that take a video reference (lab_list_models says v2v). | |
| duration_seconds | No | Video: clip length in seconds, inside the model's duration grid from lab_list_models. The card shows the DELIVERED seconds and says so when the provider snaps. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only carry readOnlyHint=true, but the description adds substantial behavior: validation against the catalog, price computation, dual output (widget card or text object), a hard non-execution guarantee, and the fact that the call is free. It also warns that the answer refuses to present an estimate as a quote, which prevents a real misuse.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with the core action and the execution gate, with the terse 'Free.' closing that earns its place. Slightly dense with em-dash asides, but nothing is padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 24-parameter, no-output-schema tool with minimal annotations, the description covers the lifecycle (propose → confirm → run), the success and refusal cases, and the cost signal. It leaves the returned object's full shape to be discovered, but names the key field (vorschlag_id), which is enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% across all 24 parameters, so the schema already carries the semantics (kind, tool, referenzen channels, cost multipliers, mutual exclusions). The description adds no per-parameter meaning beyond introducing the returned vorschlag_id, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Propose a generation for the user to confirm') and enumerates the concrete work it does: validates parameters against the catalog, computes the price, and renders a card or text object. This clearly separates it from execution siblings like lab_run_proposal and lab_generate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Names the follow-up tool and the condition that triggers it: 'NOTHING runs until lab_run_proposal is called with the returned vorschlag_id — by the card's button, or by you after the user said yes.' It also states the failure path (no measured price means no vorschlag_id and no button), which is exactly the decision an agent needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. 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. | |
| 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. With 'personen' 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. | |
| 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. | |
| 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. | |
| 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. | |
| 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). | |
| 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`. | |
| reference_video_url | No | 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false and destructiveHint=false, so the description must carry the behavioral load, and it does: credits are spent when called without get_cost, in_sec/out_sec excerpts are cut server-side so billing tracks the excerpt, invalid classes/models/rights are refused before anything is charged, drafts carry a 7-day account-bound draft_id, and 'personen' depth pauses the run as wartet_auf_freigabe. It also flags that no model actually receives camera poses and that kamerapfad is reduced to prose or director commands.
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 primary mode are front-loaded in the first two sentences. The remainder is dense and information-bearing but runs long with several multi-clause sentences mixing routing, cost, and constraint details, so it is slightly overstuffed rather than wasteful.
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 tool with nested objects and no output schema, the description covers the two run modes, cost preflight, refusal-before-charge behavior, reference class restrictions, and the draft/freigabe hand-offs, and it sketches what answers carry (wechsel, kamerapfad.angewandt, metadata). Nothing an agent needs to invoke this correctly seems 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 description coverage is 100% and the per-parameter descriptions are themselves extremely detailed (ton defaults, depth semantics, referenzen addressing, rechte_bestaetigt wording), so the schema already carries nearly all parameter meaning. The description reinforces the mode split (with vs. without reference_video_url, reference images binding cast/place/look, excerpt cutting) but adds little parameter detail the schema does not already state. 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 opening sentence names a specific verb and resource ('Render a new clip FROM the motion of an existing one') and immediately defines the division of labor: reference clip leads camera move/blocking/timing, model restyles content. It actively distinguishes itself from siblings, naming lab_animate as the alternative for people and noting it shares lab_animate's source_video_id backend path 'with the fields that only exist there'.
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/when-not branching: with a reference clip pass its URL directly and source it from lab_list_assets/lab_job_status/lab_review_queue; without one, leave reference_video_url out and rely on `referenzen` alone, restricted to models flagged referenzen_ohne_video and to faceless reference classes because Seedance 2.5 rejects faces. It also routes around itself — build a still and use lab_animate for a person — and names lab_freigeben/lab_fertigstellen for the paused and draft flows.
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 and lighting, 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 and one lighting setup 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?
Annotations only declare readOnlyHint=true. The description goes well beyond: it explains that schluessel fragments are appended verbatim and not rewritten, that handwerk=true toggles an extra payload, and that it is read-only and free. These are substantive behavioral traits not derivable 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?
Front-loaded with the trigger condition and follows with structured detail. It is dense and long but each clause (effect keys, three-key limit, stacking rules, handwerk behavior) carries distinct information, so it earns its length despite being near the upper bound.
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 3-param, no-required, no-output-schema tool, the description covers purpose, triggering intent, parameter semantics, the handoff to lab_prompt_transform, composition constraints, and the optional handwerk payload. Nothing an agent needs to invoke it correctly 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%, so baseline is 3, but the description adds real meaning: it gives example wirkung values (bedrohung, isolation, sehnsucht), clarifies gruppe limits to one group, and explains that handwerk returns camera craft. It enriches the enum/boolean semantics beyond 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?
States a specific verb+resource (directing techniques library) and explicitly names the triggering user intent — asking HOW to stage/shoot a feeling. It clearly distinguishes itself from the processing sibling lab_prompt_transform by describing the search-vs-apply handoff.
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 ('person asks HOW to stage or shoot a feeling or effect'), names the downstream alternative lab_prompt_transform and the exact call shape, and gives composition rules (one angle, one movement, one lighting per shot; framing and composition stack) that select correct usage.
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) and/or selected. 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.
| 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` | |
| 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 | |
| reference_type | Yes | What kind of asset these ids refer to |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds substantial behavioral detail on top: rejected assets drop out of default listings and become prunable, and single-id calls make `selected` exclusive per scene while bulk calls deliberately do not, with the reason why (a bulk over one scene would keep resetting itself).
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 and the id/ids rule, then the consequences. The aside about review fields going unused is motivational framing that costs a clause, but it is brief and the whole thing stays tight for the amount of semantics conveyed.
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 mutation tool, the description covers the important consequences (rejection removing assets from listings, selection semantics) and the annotations cover idempotency/safety. It omits auth/permission requirements and any indication of what the call returns, which are minor but real gaps.
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: the id/ids mutual-exclusion rationale, the per-scene exclusivity of `selected` for single-id calls, and the downstream effect of `verdict`. That is meaningful added meaning beyond the field 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 opens with a specific verb and resource: 'Review generated assets: set verdict (accepted|rejected|pending) and/or selected', and enumerates the enum values. It is clearly distinct from listing tools like lab_list_assets or lab_review_queue, though it never names a sibling explicitly to route the agent.
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 usage context: pass ONE id, or `ids` for bulk, and explains that after a generation run there are usually dozens to sort, which justifies the bulk path. It does not, however, name alternatives (e.g. where to fetch the ids to review) or state explicit when-not conditions.
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?
With only readOnlyHint=false and destructiveHint=false from annotations, the description carries the burden and delivers rich behavior: a STOP until a human accepts stills, a freigabe_noetig halt when the export contains a synthetic person/voice requiring a signed-in human release, ONE retry per deviating still, and an abort that deletes state while generated material remains. It also discloses pricing semantics and the free-budget check before every paid step.
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 information-dense, and each sentence roughly earns its place given the orchestration complexity. However it is a single long run-on paragraph with mixed concerns (flow, stops, money, prerequisites) that would scan better as discrete sections.
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 10-parameter, no-output-schema orchestration tool, the description covers everything an agent needs: the step loop and termination (phase fertig), state persistence for interrupted runs, human-gate stops, pricing/budget gating, and prerequisites. Nothing material to 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?
Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: 'weiter does exactly ONE step', preis/get_cost returns expected and maximum price plus a recommended cap without charging, lauf_id is required for paid steps, and abbrechen deletes state while material stays. These clarify the effect of enum values in a way the schema's terse descriptions 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?
Opens with a concrete verb+resource and output shape: '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 also names the sibling step tools it orchestrates (lab_situationen, lab_auto_storyboard, lab_review_asset, social_vertical), so an agent can distinguish this from those individual steps.
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 explicit when/when-not and prerequisites: paid steps run only inside a released lab_auto_lauf, the character must already have a sheet with a reference image created via lab_create_character then lab_generate_character_reference, and each aktion weiter call performs exactly one step until phase is fertig. It also routes to alternatives (use the web-app social_vertical for the release case).
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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: consumption happens BEFORE the run so a retry is refused rather than double-charged, the proposal expires in 15 minutes and is tied to the creating account, credits are spent, and confirmation is only checked at FINISH time. Annotations only supply the generic readOnlyHint=false/destructiveHint=false pair, so this added cost, idempotency and timing context is the real value.
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 cost/single-use constraint are front-loaded, and every sentence carries information. It is dense and slightly telegraphic (fragment-style clauses, mid-sentence language switches), but there is little 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?
With no output schema, the description correctly tells the agent where the result lives (lab_job_status / job review) and when review is returned inline. For a paid, single-use invocation tool this covers everything needed 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 the baseline is 3; the description still adds routing meaning, notably that prompt_override is the correct path for a card-edited prompt because the price does not depend on the text and no new proposal is needed.
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 proposal') plus constraining scope ('exactly as shown — same model, same parameters, same price'), which separates it from lab_propose (creates proposals) and from the many lab_generate/lab_animate siblings. The id provenance ('from lab_propose or plan_b in lab_job_status') further anchors it.
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 two legitimate triggers (the card's button, or the agent after user confirmation) and redirects to lab_job_status for the final verdict, including the synchronous case. The single-use refusal and 15-minute/account-bound validity give clear when-not conditions.
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). 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 declare readOnlyHint=true, which is consistent since this only produces a downloadable file. The description goes well beyond by disclosing what each format drops (transitions/audio in otio/edl, dropped dissolves when clips lack handles), the zero cost, the return payload location (`inhalt`), and the relink workflow. No contradiction with 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, costs, then per-format breakdown and the final write-to-disk instruction. Dense but every line carries operational detail; the per-format paragraphs are warranted but make it long for a 2-param 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?
No output schema exists, so the description correctly explains what the response contains (`inhalt` holding the whole file plus a filename) and instructs the agent to write it to disk. Combined with format semantics and relink steps, 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% and the enum already documents format choice, so baseline is 3; the description adds real value by explaining the exact fcpxml internals (V1 storyline with gaps, centered cross dissolves dropped at headless clips, V2+ as connected clips), otio contents (no audio/transitions), and edl channel limits, extending beyond the schema's one-line summaries.
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 (export) and resource (one sequence as an NLE editing file), names exactly what formats produce what, and is clearly distinguishable from siblings like lab_start_export or lab_export_profiles by naming the NLE/interchange use case.
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 format enum guidance in the schema and the description's per-format notes effectively tell the agent when to pick fcpxml vs otio vs edl. It doesn't explicitly say when NOT to use this tool (e.g. vs a render export), but for the interchange purpose the routing is clear.
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`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses behavior well beyond the annotations (readOnlyHint=false, destructiveHint=false): the call is asynchronous and returns a row with null `audio_url` and status 'pending', nothing is playable yet, a failed row refunds credits and carries metadata.error, and the provider is auto-selected per `art` with no `tool` parameter. That async/flush/refund profile is exactly what an agent needs and cannot get from the 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 purpose, then scope, then the async contract — a sensible order, and every sentence carries information. It is dense and leans on all-caps emphasis for keywords, which costs 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?
For an async, credit-spending generator with ten parameters and no output schema, it covers everything needed to call correctly: the eight art kinds and their source requirements, the async lifecycle and polling tool, the refund path, and the fact that return rows carry status/audio_url/metadata.error. 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?
Schema description coverage is 100%, so the schema already documents all ten parameters in detail, and the description largely restates that (art kinds, the source-selection rules, duration handling). It adds only a small amount beyond the schema — chiefly that no `tool`/provider parameter exists here. Baseline 3 is appropriate when the schema carries the 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?
States a specific verb and resource ('Generate or CLEAN UP a SOUND track') and immediately scopes it against the sibling it could be confused with: 'other than music', then names lab_generate_music explicitly. It also enumerates the eight `art` kinds, so an agent knows exactly what this tool covers 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 routing: music goes to lab_generate_music, the repair kinds (denoise/split/isolation) take an existing recording rather than a prompt, and foley requires `video_id`. It also prescribes the follow-up procedure — poll lab_list_audio matching `audio_type` until status is 'completed'. When-to-use, when-not, and the alternative tool are all stated.
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?
Annotations mark this as a non-read-only but idempotent and non-destructive write; the description elaborates exactly what gets overwritten (only derived shots), what survives (manual shots, whose clips are excluded from grouping entirely), and that it costs nothing because it generates nothing. This is rich behavioral disclosure beyond the structured hints and is consistent with them.
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 mechanism well, but the prose is long and stylized, with several em-dash-broken sentences that could be tightened. Most sentences carry real information (cost, manual survival, clips_ohne_szene) but the density is high and the structure is discursive rather than crisp.
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 a return field (`clips_ohne_szene`) and why those clips each became their own shot, which is valuable for interpreting results. It doesn't fully describe the response shape, but for a one-parameter idempotent tool it is largely 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% for the single seq_id parameter, which the schema already documents as a sequence id from lab_create_sequence/lab_list_sequences. The description adds nothing 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 (derive) and resource (the shot layer) and even spells out the algorithm: consecutive clips of one scene become a shot, and a returning scene becomes a second. It implicitly distinguishes itself from manual sibling lab_shots_setzen by explaining that hand-set shots survive and only derived ones are replaced.
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 for when this applies (clips that already declare their scene) and routes away from the manual path by noting hand-set shots are preserved. It stops short of an explicit when-not or a direct naming of the alternative tool (lab_shots_setzen), so the routing 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.
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?
With readOnlyHint already declared, the description adds real value: zero credit/image cost, the exact return shape (titel, bild_en, bewegung_en), and the constraint that each entry is one moment + one action with no inter-entry sequencing. This goes meaningfully 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, then cost, return format, constraints, and downstream routing in tight clauses. Dense but each sentence carries information; 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?
No output schema exists, yet the description documents the returned fields and their meaning plus the independence constraint, and the figur input handling. Complete enough for a generation tool; only the exact scoring/ordering of suggestions 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 baseline is 3, but the description adds semantics beyond the schema: figur via id uses the sheet's prompt_prefix_en, and anzahl controls the number of returned entries. This clarifies parameter behavior, not just restating 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 specific verb+resource: 'Suggest independent visual gags for a character and theme.' Clearly distinguishes the output type (independent gags, not a story) and names the downstream sibling lab_auto_storyboard, so an agent can tell it apart from other generation 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?
Tells the agent this is free (no credits/images) and routes the result: 'Select 8–16 suggestions for lab_auto_storyboard with figur_id.' This gives clear usage context and a downstream pairing, though it doesn't explicitly exclude alternative sibling tools like lab_regie_techniken or lab_propose.
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.
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. 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?
Goes well beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false): it discloses all-or-nothing atomicity ('either applies or refuses'), pre-write video_id validation, zero generation cost, the clip_id identity rule (kept identity retains track/in-point/scene and bound shots; a fresh identity orphans referrers), and two concrete downstream limits (Resolve bridge ignores uebergang and bed level/fade; FilmLab render stores dissolves but renders hard cuts). This is exactly the kind of 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 core action, then layered with rationale, modes, and caveats in a logical order; every sentence carries information. It is dense and on the long side, with parenthetical asides (the Resolve bridge note) that could be trimmed, 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 a nested-manifest, concurrency-guarded write tool with no output schema, the description covers the return-relevant behaviors (refusal on bad id, revision_veraltet on stale writes), both write and read-back modes, and downstream application limits — 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 already 100%, so the baseline is 3, but the description adds real meaning beyond it: sequence_id's dual write/read-back role, the clip_id identity-vs-orphan distinction, and the optimistic-concurrency contract for erwartete_revision ('written only if the sequence still has exactly that content... you get revision_veraltet'). It stops short of fully restating the nested manifest field constraints, which the schema already covers.
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 with scope: '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.' It also explicitly distinguishes itself from lab_get_sequence ('that one reads the timeline, this one writes it') and from lab_add_clip chains, so an agent can route correctly 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 ('Prefer it over a chain of lab_add_clip calls whenever you already know the whole cut'), the failure-mode rationale (a broken chain leaves half a sequence), and the two conditional modes: pass sequence_id to write into that sequence, omit to create, or pass sequence_id without a manifest to read back. Alternatives and conditions are both named.
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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only give readOnlyHint=false / destructiveHint=false; the description carries far more: async job_id semantics, credit cost basis (padding counts), per-shot vs whole-run refund behavior, fehlende_einstellungen reporting, exactly what gets created and what stays untouched, and the metadata (stuecke) written to the audio row. No contradiction with 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 core action, and nearly every clause carries real operational weight (sync marker, refunds, cost, async). The prose is dense with stacked parentheticals, which slightly impairs readability, but there is little 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 still explains the return shape (job_id, stuecke metadata, fehlende_einstellungen) and the full lifecycle (async polling, per-shot refunds). 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 coverage is 100% and all three parameters are documented in the schema itself. The description reinforces get_cost ('Do this first') and describes hinweis as adding 'a setting line for every shot', adding only marginal meaning beyond the schema's own wording.
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 clearly scopes the output to 'ONE sfx track in sequence length, bound to the sequence's sfx stem'. This is readily distinguishable from sibling sfx/dub/music 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?
Strong operational guidance: 'call with get_cost first', 'poll the job until done', and the clarifying constraint 'Shots come from the sequence itself, in export order and export length — no cut detection.' It does not, however, explicitly name sibling alternatives (e.g. lab_sfx or lab_dub) or state when a per-shot pass beats a single-clip approach.
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. | |
| 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 context: asynchronous execution, a pending row as the return, polling via lab_job_status, credit cost unless get_cost is used, server-side cutting, and required video_id anchoring even with asset_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?
Front-loads the core purpose, then covers source, cutting, async, and cost in five dense sentences. Every sentence earns its place for a complex tool; no redundant or filler 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?
No output schema exists, and the description explains the return behavior (new pending row, poll with lab_job_status) plus cost handling. It is complete enough for an agent to invoke correctly, though it omits failure/retry details beyond the 404 note.
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 eight parameters in detail. The description contextualizes in_sec/out_sec and asset_id but adds no syntax or meaning 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 (relight/restyle an existing clip), names the model (Beeble Switch X), and distinguishes the operation from generation by emphasizing that subject and motion are preserved. It also clarifies source options, so 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?
Explains when to use it (existing clip, performance untouched) and how to source the input (generated-video row or asset_id). It names lab_job_status for polling and get_cost for a no-spend preview, but does not state when to choose this over sibling transform tools like lab_prompt_transform or lab_vfx.
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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false), disclosing the async pending-row lifecycle, server-side measurement of length and height before charging, refusal of too-tall sources, the credit cost model, the max_credits guard, and that get_cost is free and does not scale. A mutation-ish tool with real cost is fully explained.
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 its limits, and every sentence carries information. It is dense rather than padded, though the Topaz/fal detail and the cost framing re-echo points already made in the schema, adding mild length.
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 correctly carries the return behavior (a new pending video row), the polling path (lab_job_status), the cost/preflight flow, and the refusal conditions. Nothing an agent needs to invoke it safely and 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 parameter descriptions are already exhaustive per-parameter, so the description's job is limited. It adds only light framing (cost lives in lab_list_models and the preflight, not here) and does not sharpen the faktor tiers or video_id preconditions beyond what the schema 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 precise verb+resource — 'Enlarge an EXISTING clip (Topaz, passed through fal)' — and immediately scopes it as a pixel-scaling operation, not a generation: 'nothing is re-imagined, the frames are scaled.' This cleanly separates it from generation/restyle siblings like lab_generate and lab_transform.
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 (source must be the clip of a generated-video row, pending runs are refused) and routes the agent to lab_job_status for polling and lab_list_models for tier pricing. It signals that get_cost should precede a paid call ('Costs credits when called without get_cost') but never states that explicitly as a when-to-use rule, and doesn't name a competing upscaling alternative.
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 …). 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?
With annotations only declaring readOnly=false, idempotent=false, destructive=false, the description carries the full behavioral burden and does so richly: credit charging on clip start, active lab_auto_lauf cap, keyframe checkpoint requirement, continuity check states (pruefen, wartet_auf: abgleich — explicitly not a hung job), bounded re-renders, chain abort semantics (abgebrochen/abweichung), and duplicate-start dedup (wiederverwendet: true).
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 chain concept and the aktion cost contract before the deep detail, and nearly every sentence carries operational information. However, it is a single very dense paragraph mixing German state names with prose, so it is heavier to parse than it needs to be for a tool this complex.
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 7-parameter job launcher with no output schema, the description closes the loop: it explains the internal chain/clip statuses, tells the agent to follow up with lab_get_job(job_id) and which result fields to read (zusammenfassung, ketten, clips), and warns that job status done does not imply success. Nothing essential 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?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: aktion costs and the preis/starten sequencing, the instruction to name preis_hoechstens_credits before starten, and the rationale for ohne_keyframe (only when the user explicitly asked to skip the frame check). It stops short of documenting formats for every field, keeping it at 4 rather than 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 specific verb and resource ('Render several clips as CHAINS') and immediately defines chain semantics: within a scene sequentially, across scenes in parallel, following each job's scene_ref. It is clearly differentiated from single-clip siblings like lab_animate and batch alternatives, so an agent can tell what this tool does 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 routing guidance is present: the 'Dispatch rule' tells the agent to use one chain with schnitt for a continuous scene, a single clip for one unbroken motion, and separate scenes for time jumps or costume changes. It also names prerequisites (approved start image, lab_animate-style keyframe) and the aktion contract requiring a confirmed preis before starten.
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: "Automatisch verpixelt, ohne Garantie — vor Veröffentlichung prüfen." 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 mark it non-read-only and non-destructive; the description adds the critical behavioral facts an agent needs — it costs credits per frame, dry_run previews the price, rerender_from re-renders for free, and a mandatory user-facing disclaimer must be conveyed. This is rich disclosure beyond the 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?
The core action and cost warning are front-loaded, and each sentence carries distinct information (preset availability, cost, dry_run, rerender, disclaimer, polling). It is dense, with the embedded quoted disclaimer text making it feel cramped, 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 credit-consuming mutation tool with no output schema, the description covers cost, the preview path, the free re-render path, the compliance disclaimer, and completion polling. Only minor gaps remain around expected return shape and what the job produces.
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 meaningfully extends it: dry_run as a cost preview, rerender_from as a free re-render path using a finished job_id, and ausnahmen as object ids that stay sharp (rerender only). The 'e.g. exceptions' phrasing is slightly muddled but the semantics are conveyed.
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 names the live preset, so the agent knows exactly what executes. It differentiates from siblings by pointing to lab_vfx_preset_status for polling and away from generic lab_vfx 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 clear workflow guidance: call with dry_run=true first to check price, use rerender_from for a free re-render with different settings, and poll lab_vfx_preset_status until done|failed. It does not explicitly state when not to use this tool, but the cost and re-render conditions are well framed.
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?
With readOnlyHint=true already declaring the safety profile, the description adds real behavioral context: the full status vocabulary, what progress counts, and the distinct payload fields available only on completion. It goes beyond the annotations, though it says nothing about polling cadence or terminal-state handling beyond listing 'failed'.
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 state enumeration and return-value mapping are front-loaded and every clause carries information an agent needs. It is a dense single block mixing English and German field names, which is slightly heavy but not wasteful.
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 contract itself, and it does: status values, progress meaning, result_url, kontakt_url, and spur.objekte face ids. Enough is specified for an agent to poll correctly and act on the terminal state without further documentation.
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 and schema description coverage is 100% – the schema already states job_id is returned by lab_vfx_preset. The description adds no new naming, format, or example value beyond that, 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 (poll a VFX preset job) and enumerates the job state machine, which makes it distinguishable from generic pollers. It does not explicitly name siblings like lab_vfx_status or lab_job_status, so an agent must infer the split from the parameter 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?
Gives clear operative guidance: poll this to track a submitted preset job, and when status is done, hand result_url to the user as karte_ansehen, use kontakt_url for review, and feed spur.objekte ids back into lab_vfx_preset(rerender_from, ausnahmen). It never says when to use this instead of the other status tools, so it stops short of full alternative routing.
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 (fal.ai minimax voice-clone) — 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: only clone voices you have the right to use, and the Fish Audio path requires you to say so explicitly.
| 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 | No | 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. | |
| project_id | Yes | Project id (from lab_list_projects) — positive integer as string | |
| einwilligung | No | Consent of the person whose voice is being uploaded. Required on the fish_audio path, which 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. | |
| 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?
Annotations only say readOnlyHint=false/destructiveHint=false, but the description adds the traits that actually matter: it is SYNCHRONOUS with no job_id to poll, bad source material is rejected before anything is charged, billing is per clone (not per source length) and the clone is reusable, and cloning is consent-sensitive with a required assertion on the fish_audio path.
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 synchronous/no-poll constraint are front-loaded, and each sentence carries a distinct point (routing, sync behavior, source quality, consent). Slightly dense with some overlap against the schema's billing notes, but nothing is 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?
With no output schema, the description still covers the non-obvious return behavior (synchronous, no pollable job) and downstream usage, but it only indirectly implies that the result is a reusable voice_id-style artifact. Minor gap for a 7-parameter 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 description coverage is 100%, so provider enum, einwilligung, likeness_ref, get_cost and sample_audio_url are already fully documented in the schema. The description restates the consent/billing intent but adds little parameter-level detail beyond that structured text, 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 (clone a voice from real audio/video material into a project) and explicitly positions it relative to siblings: it is the source for lab_voice_tts and lab_dub's voice_id+dub_text path. An agent can distinguish it from text-to-speech and dubbing tools 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?
Explicit routing: use get_cost to price before spending, omit provider to stay on the default path, use einwilligung/likeness_ref for consent-sensitive real voices. It also names lab_list_models as the place to compare provider capability and price rather than duplicating that here, which is actionable guidance rather than a dead end.
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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false and destructiveHint=false, leaving the sync/async profile and billing undisclosed. The description adds real value: it is synchronous, returns a ready audio_url with no job_id to poll, and is consent-sensitive. The billing-by-text-size behavior is largely carried by the get_cost parameter description rather than the main text.
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 core purpose and the sync/no-job_id distinction front-loaded. The em-dash asides are slightly dense but every clause carries information; 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 usefully states the return shape (ready audio_url). Combined with annotations covering the safety profile and a fully documented schema, an agent has enough to call it correctly; only the explicit sibling alternatives remain unaddressed.
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 fully documents text, voice_id, project_id, get_cost, and provider, including the provider cross-check and the billing rationale. The description adds little beyond this, 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 (Speak) and resource (text in a project's cloned voice), and explicitly distinguishes itself by being SYNCHRONOUS with a ready audio_url and no job_id. It also ties itself to its sibling lab_voice_clone, so an agent can route between cloning and speaking 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?
Conveys when to use it implicitly (to voice text through a cloned voice) and adds a consent constraint ('only speak text you have the right to put in that voice's mouth'). It gives provider guidance ('you do not pick it'), but never explicitly contrasts with alternative TTS siblings like lab_dub_tts or lab_dub.
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?
Annotations only declare readOnlyHint=false and destructiveHint=false, so the description carries real weight and delivers: credit consumption, stufe cost/duration tradeoff (~1 min vs 5-15 min), asynchronous welt_id return, and the spatial limitation that the world only holds near the camera spot (reverse shots ok, flying through walls not).
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 and largely waste-free: purpose, cost, sources, async contract, follow-up workflow, limitation. Slight redundancy with the schema on stufe enum values and the get_cost wording keeps it off 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?
No output schema exists, yet the description still discloses the return value (welt_id) and the polling sibling, plus what happens after completion. For an async, credit-consuming generation tool with 7 parameters, 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 baseline is 3; the description still adds meaning by framing loc_id+variante as a coupled pair, describing quell_bild_id as the alternative source, and explaining what get_cost and each stufe actually do operationally.
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 artifact: 'Build a walkable 3D WORLD (Gaussian splat, World Labs Marble) from ONE location picture.' The output type is unambiguous and clearly separates it from siblings like lab_location_recon, lab_location_panorama 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?
States the two admissible input sources (location board loc_id+variante versus a gallery image quell_bild_id), tells the agent to call with get_cost:true and name the price before a real run, and routes the async flow explicitly to lab_welt_status and onward to lab_generate via seed_image_url.
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 only declare readOnlyHint=true; the description adds real behavioral context beyond that — the operation is free, a failed world has already been refunded, and completed worlds expose a `studio` link for saving angles. It stops short of describing the response shape or polling/rate guidance.
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 with the core purpose front-loaded and no filler; every clause carries information. 'Read-only, free' is slightly redundant with the readOnlyHint annotation, but 'free' and the refund note add value.
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 returns and does so reasonably — state values, the studio link, and the refund-on-failure outcome. Minor gaps remain around exact response fields beyond gewartet_s.
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 welt_id, project_id, and wait_s including its 15s cap and the gewartet_s response field. The description's mention of wait_s largely restates the schema, 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?
States a specific verb+resource — the status of a world produced by lab_welt — and names the sibling that creates it, so an agent can distinguish polling from generation without opening a schema. It also enumerates the possible states (processing | completed | failed).
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 the workflow (call after lab_welt to poll a world) and explicitly tells the agent how to block via wait_s. It does not, however, differentiate this from the other status-polling siblings such as lab_job_status, lab_batch_status, or lab_vfx_status, leaving the selection to inference.
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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true covers the safety profile, yet the description adds the traits that actually matter operationally: 20 min source cap, first-call transcription via Fish Audio with cost (0.36 USD/audio-hour billed to operator, not credits), free cache hits thereafter, 300 s page limit with `weiter_von_s` continuation, and the name-spelling caveat. This is exactly the extra 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-loads what is returned (word + start/end time) then sources, then why, then cost/paging caveats. Dense but every clause carries information; the final name-spelling warning is a slight afterthought but still 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?
No output schema and no annotations beyond readOnlyHint, so the description carries the load — and it does: return shape (words with start/end), cost/caching model, latency implication of first transcription, paging limit, and the source-selection rule. Nothing an agent needs 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 documents von_s/bis_s/sprache/ids on its own; baseline 3 applies. The description reinforces the mutually-exclusive source-id semantics and the paging pair (300 s / weiter_von_s) but adds no syntax 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+resource ('every spoken word with its start and end time') and enumerates the three source modes (video_id, audio_id, asset_key) that distinguish it from siblings like lab_wellenform or lab_list_audio. An agent can immediately tell it returns word-level timings, not a waveform or an asset 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 use cases are named ('cut pauses without cutting into a word, time captions, land a graphic on an exact word — instead of guessing seconds from the waveform'), which also implicitly rejects the waveform-guessing alternative. The multi-source applicability is spelled out per id type.
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_location_recon2 fields changedInput schema / properties / engine / descriptionPrevious value: -"Which reconstruction path. Omit for the backend default. The second path is scene-scale and needs its model configured on the backend — where it is not, the answer says so instead of falling back silently."New value: +"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."Input schema / properties / engine / enumPrevious value: -[
- "fal-sam3d",
- "vggt"
-]New value: +[
+ "fal-sam3d",
+ "vggt",
+ "vggt-splat"
+]lab_weltlab_welt_statuslab_reference_motion1 field changedInput schema / properties / ton_fuehrungAdded value: +{
+ "description": "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.",
+ "enum": [
+ "voll",
+ "stimme",
+ "keine"
+ ],
+ "type": "string"
+}lab_freigebenlab_reference_motion5 fields changedInput schema / properties / raum_beschreibenAdded value: +{
+ "description": "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.",
+ "type": "boolean"
+}Input schema / properties / rechte_bestaetigtAdded value: +{
+ "description": "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).",
+ "type": "boolean"
+}Input schema / properties / use_depth / anyOfAdded value: +[
+ {
+ "type": "boolean"
+ },
+ {
+ "enum": [
+ "voll",
+ "personen"
+ ],
+ "type": "string"
+ }
+]Input schema / properties / use_depth / descriptionPrevious value: -"Condition the run on a depth pass of the reference clip. Defaults to ON in the backend; pass false to opt out. Models that do not have a depth stage ignore it — the answer says so rather than pretending it happened. 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."New value: +"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. With 'personen' 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."Input schema / properties / use_depth / typeRemoved value: -"boolean"lab_look_in_postlab_prompt_transform1 field changedInput schema / properties / project_id / descriptionPrevious value: -"Optional, only with tool or familie: the project whose Lens Lab optics, Pose Director framing and gaffer light should be laid into the prompt."New value: +"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."lab_fertigstellenlab_reference_motion1 field changedInput schema / properties / draftAdded value: +{
+ "description": "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.",
+ "type": "boolean"
+}lab_mix1 field changedInput schema / properties / tracks / items / properties / automationAdded value: +{
+ "description": "Volume breakpoints over time, seconds from sequence start, interpolated linearly in dB. Replaces the track's whole automation; [] clears it. Not on master.",
+ "items": {
+ "properties": {
+ "db": {
+ "maximum": 12,
+ "minimum": -60,
+ "type": "number"
+ },
+ "t_s": {
+ "minimum": 0,
+ "type": "number"
+ }
+ },
+ "required": [
+ "t_s",
+ "db"
+ ],
+ "type": "object"
+ },
+ "maxItems": 500,
+ "type": "array"
+}lab_mix1 field changedInput schema / properties / tracks / items / properties / naht_msAdded value: +{
+ "description": "Fade at every seam between this stem's clips, 0–500 ms (0 = hard edges)",
+ "type": "number"
+}lab_stems_exportlab_rezept_montagelab_beat_clipslab_identitaet_pruefenlab_schnitt_exportlab_auto_storyboard6 fields changedInput schema / properties / figur_idAdded value: +{
+ "description": "Existing character-sheet id with a reference image; required for situationen, only used with situationen",
+ "exclusiveMinimum": 0,
+ "maximum": 9007199254740991,
+ "type": "integer"
+}Input schema / properties / formatAdded value: +{
+ "description": "Frame aspect ratio for every model, default 16:9",
+ "enum": [
+ "16:9",
+ "9:16"
+ ],
+ "type": "string"
+}Input schema / properties / script / descriptionPrevious value: -"Screenplay or scene description to storyboard. Required — the backend splits it into scenes; each scene becomes one image."New value: +"Screenplay or scene description; provide either script or situationen. The backend splits script into scenes; each scene becomes one image."Input schema / properties / situationenAdded value: +{
+ "description": "Independent situations, each exactly one frame. Requires figur_id; excludes script and figuren_raten.",
+ "items": {
+ "properties": {
+ "bewegung_en": {
+ "description": "English motion prompt with a strong movement verb",
+ "maxLength": 1000,
+ "minLength": 1,
+ "type": "string"
+ },
+ "bild_en": {
+ "description": "English still prompt: one moment, one action",
+ "maxLength": 4000,
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "bild_en",
+ "bewegung_en"
+ ],
+ "type": "object"
+ },
+ "maxItems": 16,
+ "minItems": 8,
+ "type": "array"
+}Input schema / properties / style_reference_url / descriptionPrevious value: -"Shared moodboard image applied to ALL frames for one consistent look. Used by the Krea 2 models only. Must be an asset of this project or an absolute URL — anything else is refused before credits are spent."New value: +"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."Input schema / requiredPrevious value: -[
- "project_id",
- "script"
-]New value: +[
+ "project_id"
+]lab_situationenlab_abgleich1 field changedInput schema / additionalPropertiesAdded value: +falselab_add_clip1 field changedInput schema / additionalPropertiesAdded value: +falselab_add_media1 field changedInput schema / additionalPropertiesAdded value: +falselab_analyze_location_image1 field changedInput schema / additionalPropertiesAdded value: +falselab_animate1 field changedInput schema / additionalPropertiesAdded value: +falselab_animate_batch1 field changedInput schema / additionalPropertiesAdded value: +falselab_apply_rhythm1 field changedInput schema / additionalPropertiesAdded value: +falselab_aufloesung1 field changedInput schema / additionalPropertiesAdded value: +falselab_auto_lauf1 field changedInput schema / additionalPropertiesAdded value: +falselab_auto_storyboard1 field changedInput schema / additionalPropertiesAdded value: +falselab_batch_status1 field changedInput schema / additionalPropertiesAdded value: +falselab_beatgrid1 field changedInput schema / additionalPropertiesAdded value: +falselab_bilder1 field changedInput schema / additionalPropertiesAdded value: +falselab_bind_audio1 field changedInput schema / additionalPropertiesAdded value: +falselab_capture1 field changedInput schema / additionalPropertiesAdded value: +falselab_cast_autopopulate1 field changedInput schema / additionalPropertiesAdded value: +falselab_cast_gaps1 field changedInput schema / additionalPropertiesAdded value: +falselab_contact_sheet1 field changedInput schema / additionalPropertiesAdded value: +falselab_continuity_check1 field changedInput schema / additionalPropertiesAdded value: +falselab_create_character1 field changedInput schema / additionalPropertiesAdded value: +falselab_create_location1 field changedInput schema / additionalPropertiesAdded value: +falselab_create_project1 field changedInput schema / additionalPropertiesAdded value: +falselab_create_sequence1 field changedInput schema / additionalPropertiesAdded value: +falselab_delete_location1 field changedInput schema / additionalPropertiesAdded value: +falselab_depth_map1 field changedInput schema / additionalPropertiesAdded value: +falselab_diagnose1 field changedInput schema / additionalPropertiesAdded value: +falselab_dossier1 field changedInput schema / additionalPropertiesAdded value: +falselab_dub1 field changedInput schema / additionalPropertiesAdded value: +falselab_dub_tts1 field changedInput schema / additionalPropertiesAdded value: +falselab_dub_voices1 field changedInput schema / additionalPropertiesAdded value: +falselab_enrich_location_prefix1 field changedInput schema / additionalPropertiesAdded value: +falselab_export_profiles1 field changedInput schema / additionalPropertiesAdded value: +falselab_fassungen1 field changedInput schema / additionalPropertiesAdded value: +falselab_feedback1 field changedInput schema / additionalPropertiesAdded value: +falselab_flow_angebot1 field changedInput schema / additionalPropertiesAdded value: +falselab_flow_fortsetzen1 field changedInput schema / additionalPropertiesAdded value: +falselab_flow_starten1 field changedInput schema / additionalPropertiesAdded value: +falselab_flow_status1 field changedInput schema / additionalPropertiesAdded value: +falselab_generate1 field changedInput schema / additionalPropertiesAdded value: +falselab_generate_character_reference1 field changedInput schema / additionalPropertiesAdded value: +falselab_generate_location_variants1 field changedInput schema / additionalPropertiesAdded value: +falselab_generate_music1 field changedInput schema / additionalPropertiesAdded value: +falselab_get_character1 field changedInput schema / additionalPropertiesAdded value: +falselab_get_character_sheet1 field changedInput schema / additionalPropertiesAdded value: +falselab_get_context1 field changedInput schema / additionalPropertiesAdded value: +falselab_get_dossier1 field changedInput schema / additionalPropertiesAdded value: +falselab_get_export1 field changedInput schema / additionalPropertiesAdded value: +falselab_get_job1 field changedInput schema / additionalPropertiesAdded value: +falselab_get_location1 field changedInput schema / additionalPropertiesAdded value: +falselab_get_project1 field changedInput schema / additionalPropertiesAdded value: +falselab_get_sequence1 field changedInput schema / additionalPropertiesAdded value: +falselab_get_state1 field changedInput schema / additionalPropertiesAdded value: +falselab_grade1 field changedInput schema / additionalPropertiesAdded value: +falselab_grade_clip1 field changedInput schema / additionalPropertiesAdded value: +falselab_grade_from_resolve1 field changedInput schema / additionalPropertiesAdded value: +falselab_grade_suggest1 field changedInput schema / additionalPropertiesAdded value: +falselab_herkunft1 field changedInput schema / additionalPropertiesAdded value: +falselab_job_status1 field changedInput schema / additionalPropertiesAdded value: +falselab_jobs_inflight1 field changedInput schema / additionalPropertiesAdded value: +falselab_layers1 field changedInput schema / additionalPropertiesAdded value: +falselab_letzter_frame1 field changedInput schema / additionalPropertiesAdded value: +falselab_list_assets1 field changedInput schema / additionalPropertiesAdded value: +falselab_list_audio1 field changedInput schema / additionalPropertiesAdded value: +falselab_list_characters1 field changedInput schema / additionalPropertiesAdded value: +falselab_list_exports1 field changedInput schema / additionalPropertiesAdded value: +falselab_list_location_scans1 field changedInput schema / additionalPropertiesAdded value: +falselab_list_locations1 field changedInput schema / additionalPropertiesAdded value: +falselab_list_models1 field changedInput schema / additionalPropertiesAdded value: +falselab_list_project_locations1 field changedInput schema / additionalPropertiesAdded value: +falselab_list_projects1 field changedInput schema / additionalPropertiesAdded value: +falselab_list_sequences1 field changedInput schema / additionalPropertiesAdded value: +falselab_list_voices1 field changedInput schema / additionalPropertiesAdded value: +falselab_location_panorama1 field changedInput schema / additionalPropertiesAdded value: +falselab_location_recon1 field changedInput schema / additionalPropertiesAdded value: +falselab_look_match1 field changedInput schema / additionalPropertiesAdded value: +falselab_mix1 field changedInput schema / additionalPropertiesAdded value: +falselab_mix_messen1 field changedInput schema / additionalPropertiesAdded value: +falselab_mix_render1 field changedInput schema / additionalPropertiesAdded value: +falselab_playbook1 field changedInput schema / additionalPropertiesAdded value: +falselab_prompt_transform1 field changedInput schema / additionalPropertiesAdded value: +falselab_propose1 field changedInput schema / additionalPropertiesAdded value: +falselab_reference_motion1 field changedInput schema / additionalPropertiesAdded value: +falselab_referenz_aus_bild1 field changedInput schema / additionalPropertiesAdded value: +falselab_regie_techniken1 field changedInput schema / additionalPropertiesAdded value: +falselab_render_frames1 field changedInput schema / additionalPropertiesAdded value: +falselab_restyle_location1 field changedInput schema / additionalPropertiesAdded value: +falselab_review_asset1 field changedInput schema / additionalPropertiesAdded value: +falselab_review_queue1 field changedInput schema / additionalPropertiesAdded value: +falselab_run_module1 field changedInput schema / additionalPropertiesAdded value: +falselab_run_proposal1 field changedInput schema / additionalPropertiesAdded value: +falselab_scopes1 field changedInput schema / additionalPropertiesAdded value: +falselab_search_catalog1 field changedInput schema / additionalPropertiesAdded value: +falselab_sfx1 field changedInput schema / additionalPropertiesAdded value: +falselab_shots1 field changedInput schema / additionalPropertiesAdded value: +falselab_shots_ableiten1 field changedInput schema / additionalPropertiesAdded value: +falselab_shots_setzen1 field changedInput schema / additionalPropertiesAdded value: +falselab_start_export1 field changedInput schema / additionalPropertiesAdded value: +falselab_suggest_durations1 field changedInput schema / additionalPropertiesAdded value: +falselab_timeline_apply1 field changedInput schema / additionalPropertiesAdded value: +falselab_ton_durchlauf1 field changedInput schema / additionalPropertiesAdded value: +falselab_transform1 field changedInput schema / additionalPropertiesAdded value: +falselab_umzug1 field changedInput schema / additionalPropertiesAdded value: +falselab_upscale1 field changedInput schema / additionalPropertiesAdded value: +falselab_verkettung1 field changedInput schema / additionalPropertiesAdded value: +falselab_vfx1 field changedInput schema / additionalPropertiesAdded value: +falselab_vfx_preset1 field changedInput schema / additionalPropertiesAdded value: +falselab_vfx_preset_status1 field changedInput schema / additionalPropertiesAdded value: +falselab_vfx_status1 field changedInput schema / additionalPropertiesAdded value: +falselab_voice_clone1 field changedInput schema / additionalPropertiesAdded value: +falselab_voice_tts1 field changedInput schema / additionalPropertiesAdded value: +falselab_wellenform1 field changedInput schema / additionalPropertiesAdded value: +falselab_whoami1 field changedInput schema / additionalPropertiesAdded value: +falselab_widerruf1 field changedInput schema / additionalPropertiesAdded value: +falselab_wissen1 field changedInput schema / additionalPropertiesAdded value: +falselab_wortzeiten1 field changedInput schema / additionalPropertiesAdded value: +falselab_zielgruppe1 field changedInput schema / additionalPropertiesAdded value: +falselab_create_character2 fields changedInput schema / properties / demeanor / descriptionPrevious value: -"How the person carries themselves, in prose"New value: +"How the character moves and behaves, in prose"Input schema / properties / gattungAdded value: +{
+ "description": "Character kind: human, animal or creature. Omitted or empty means mensch. For tier/kreatur, begin the description with the species and its distinctive features.",
+ "enum": [
+ "mensch",
+ "tier",
+ "kreatur",
+ ""
+ ],
+ "type": "string"
+}lab_generate_character_reference1 field changedInput schema / properties / views / descriptionPrevious value: -"Which views to render. Omit for the six core views. 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."New value: +"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."lab_regie_techniken1 field changedInput schema / properties / handwerkAdded value: +{
+ "description": "Also return the camera craft (rules, look-alike pairs, focal lengths, frame boundaries)",
+ "type": "boolean"
+}lab_flow_status2 fields changedInput schema / properties / angebot_idAdded value: +{
+ "description": "From lab_flow_angebot — finds the run started from this offer (when lab_flow_starten's answer was lost)",
+ "minLength": 1,
+ "type": "string"
+}Input schema / requiredRemoved value: -[
- "lauf_id"
-]lab_bind_audio1 field changedInput schema / properties / audio_idsAdded value: +{
+ "additionalProperties": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "number"
+ }
+ ]
+ },
+ "description": "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.",
+ "propertyNames": {
+ "enum": [
+ "dialog",
+ "music",
+ "sfx",
+ "atmo"
+ ],
+ "type": "string"
+ },
+ "type": "object"
+}lab_start_export1 field changedInput schema / properties / ohne_cliptonAdded value: +{
+ "description": "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.",
+ "type": "boolean"
+}AI film studio: shoot video, images and sound, review takes, audit scripts, quote before you shoot.
Create AI images, clips, voice-overs, music and editable storyboard films from your AI assistant.
AI video production, idea to final cut: generate, edit and assemble films, ads and social video.
Search, organize, and publish AI-generated images and video with provenance and lineage.
Add one secure layer between your agents and this server.