FilmLab

Generate Character Reference

lab_generate_character_reference

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.

Input Schema

TableJSON Schema

Name	Required	Description
`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

Schema Changelog

Changes observed during successful MCP inspections.

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

Changed1 schema field changedOct 11, 2026

changedInput schema / properties / views / description

Previous 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."

Changed1 schema field changedOct 10, 2026

addedInput schema / properties / get_cost

Added value: +{
+  "description": "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.",
+  "type": "boolean"
+}

Changed1 schema field changedOct 4, 2026

changedInput schema / properties / views / description

Previous value: -"Which views to render. Omit for all six. Allowed: fullbody, profile, detail, pose_sitting, pose_walking, pose_action. Fewer views = fewer credits; `fullbody` and `profile` alone are usually enough to lock an identity."New 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."

First observedOct 3, 2026

TDQS

A4.7/5.0

Behavior5/5

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.

Conciseness3/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.

All FilmLab tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?