Director's Lookbook

Deal a hand

deal_hand

Read-onlyIdempotent

Start here whenever someone asks for an image, video or music prompt, a photo or film look, or art direction from a description ("a moody product shot of perfume", "rainy cafe at night", "a Suno style for a sad song"): deal one matched card per slot for the job from their plain-language feeling. photo = one image (film, camera, color, light); still = image with title type; cover = album or poster art (film, color, type); video or reel = clip or short (film, camera, color, type, score, light); lyric = lyric video (same as reel); song = music only (score); site = website (film, color, type, web); game = key art, store capsule, sprites, UI and loop music (film, color, type, score); drama = a short drama ad where the ad is the show (film, camera, color, type, score, light, and three shots: hook, twist, payoff); all = every suit. Example: {"feeling": "lonely astronaut on a desert planet at dusk", "job": "video", "shots": 3}. Same seed + same inputs = same hand; a new seed re-deals; hold keeps chosen cards ({"film": "film-gold-200"}). For job drama the hand also carries three shots (hook close-up, twist reveal, payoff wide or push) and the look is dealt from the feeling, with the subject read as the product. Returns the hand (slot to card id and name), the main paste-ready prompt for the job (prompt), why each card was picked, clashes, and a site_url showing the hand with pictures. Show the user the prompt and the site_url; use brief with the hand ids for every block (shot lists, palette, Suno, Midjourney spelling).

Input Schema

Name	Required	Description	Default
`job`	No	What the hand is for (default photo); see the job list above.	photo
`hold`	No	Optional cards to keep, as {slot: card id}, e.g. {"film": "film-gold-200", "score": "score-bossa-nova"}. Slots: type, camera, film, color, score, web, light.
`seed`	No	Optional integer for a repeatable deal. Omit for a fresh random deal.
`moods`	No	Optional mood chips that weigh more than words. One or more of: cozy, eerie, nostalgic, epic, playful, tense, dreamy, gritty, elegant, kinetic, melancholy, hopeful, futuristic, handmade, serene, bold.
`shots`	No	Optional, for video, reel, lyric or all: also pick a shot list of this many camera cards (the dealt camera first, then matched shots and moves). Pass them all to brief to get one SHOT block each. A drama hand always has 3 (hook, twist, payoff).
`aspect`	No	Optional frame for the clash check, e.g. "2.39:1" for a film or "9:16" for a reel (default 9:16 for reel and lyric). Pass the same aspect to brief.
`feeling`	No	The feeling or scene in plain words, e.g. "rainy cafe at night, melancholy". Words after "no"/"not" count against a card. For drama, the story's feeling or situation, e.g. "a quiet breakup at a dinner table".
`subject`	No	Optional subject, e.g. "a jazz singer". It is folded into the feeling so scene and person words count. For drama, the product being advertised (used for the setting check, not for picking the look).

Output Schema

Name	Required	Description
`hand`	No	slot to card id
`lint`	No
`note`	No	why each card was picked
`site`	No
`weak`	No	slots filled on little evidence
`error`	No	Set instead of the fields above when the input was wrong.
`names`	No	slot to card name
`shots`	No	shot list camera ids when shots was asked
`images`	No	slot to example image URL
`prompt`	No	the main paste-ready prompt for the job, compiled from this hand (brief gives every block)
`swapped`	No	cards swapped to clear a clash
`job_used`	No	the job the hand was dealt for
`site_url`	No	opens the hand on directorslookbook.app
`warnings`	No	holds or options that could not be honoured
`moods_read`	No
`alternatives`	No	slot to other card ids worth a look
`neg_moods_read`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 15, 2026

addedOutput schema / properties / prompt

Added value: +{
+  "description": "the main paste-ready prompt for the job, compiled from this hand (brief gives every block)",
+  "properties": {
+    "block": {
+      "description": "which block, e.g. IMAGE PROMPT, VIDEO PROMPT, SUNO STYLE",
+      "type": "string"
+    },
+    "text": {
+      "description": "the paste-ready prompt for this hand",
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

First observedOct 11, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Beyond the safety annotations the description adds real behavioral context: same seed + inputs = same hand, a new seed re-deals, hold pins chosen cards, drama always carries 3 shots, and it lists exactly what comes back (slot→card mapping, prompt, per-card rationale, clashes, site_url). The only soft spot is a mild tension with idempotentHint=true, since an omitted seed produces a 'fresh random deal' each call.

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 entry-point line is correctly front-loaded, and the job enumeration genuinely carries required information, but the middle is one sprawling run-on packed with nested parentheticals ('film, camera, color, type, score, light, and three shots: hook, twist, payoff') that force re-reading. It earns most of its length but the density hurts scanability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter tool with a nested hold object and an output schema, the description covers seed determinism, hold semantics, drama's special case, and the return payload well beyond what the schema provides. Gaps are minor: no mention of error/validation behavior and no explicit sibling routing.

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 baseline is 3, but the description is actually load-bearing here: the schema's job param says only 'see the job list above', and the description supplies that list plus the slot mapping for every job value. Examples for hold and seed ('{"film": "film-gold-200"}') also add usage meaning beyond the schema notes.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence names a specific verb and effect ('deal one matched card per slot for the job') and calls out the trigger conditions (image/video/music prompt, photo or film look, art direction). It also positions itself relative to a sibling by naming 'brief' as the downstream consumer, so an agent can distinguish it from list_suits/find_styles 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.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Start here whenever someone asks for...' gives explicit entry-point context, and it flags the hand-off ('use brief with the hand ids for every block'). It never states when NOT to use it — e.g. browsing cards via find_styles or inspecting a single card via show_card — so routing against the other siblings 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.

All Director's Lookbook 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?