670+ named visual and music styles: deal a look for a feeling, get paste-ready AI prompts.
Scored across 6 tools
Each tool has a distinct role: dealing hands, searching cards, showing one card, listing suits, linting combinations, and generating prompt blocks. The only mild overlap is between deal_hand and brief, since both can produce prompt text, but the descriptions clearly position brief as the block-expansion step after deal_hand.
Most names follow a clear verb_noun snake_case pattern: deal_hand, find_styles, lint_hand, list_suits, show_card. The tool 'brief' is still a verb and readable, but it is the lone name without an explicit object, making the pattern slightly less uniform.
Six tools are well-scoped for a curated card lookbook: discover, inspect, deal, validate, enumerate, and brief. Each tool has a clear job, and the set does not feel bloated or thin.
The surface covers the full read-only workflow: browse suits, search styles, inspect a card, deal a matched hand, lint custom combinations, and generate paste-ready prompt blocks. No obvious lifecycle gap exists for a curated lookbook that is not meant to be edited through the MCP.
Turn card ids into paste-ready prompt blocks, worded verbatim from the cards: IMAGE PROMPT, VIDEO PROMPT, PALETTE (hexes), TYPE, SUNO STYLE and SUNO EXCLUDE, SITE PROMPT, or for job game: KEY ART, CAPSULE, SPRITE/TILESET, UI MOCKUP, MUSIC; for job drama: SHOT blocks for the hook, twist and payoff plus BEATS (timing, shot, what happens, a placeholder line with its length rule), END CARD (title, promise, call to action, set in the type card), CAPTION RULES (safe band y 210 to 1345 on 1080x1920, nothing in the bottom 30%) and DON'T. Pass the ids from deal_hand (or find_styles), at most one card per suit, except camera: several camera cards make a shot list (one SHOT block each). A camera card of kind light lights every shot; a film card of kind fx adds a post effect. tool respells the blocks: midjourney (--ar, --style raw, --sref with the film card's example image), runway or kling (camera line first, 5 or 10 s clips), suno (music blocks only). seconds splits a running time over the shots, beats says what happens in each, vocals picks lyrics or instrumental. A lens card in a shot list shapes every shot. Example: {"hand_ids": ["film-gold-200", "camera-closeup", "color-golden-hour"], "job": "photo", "subject": "an older woman teaching a young man to dance", "tool": "midjourney"}. Drama example: {"hand_ids": ["type-futura", "film-vision3-500t", "color-blue-hour", "camera-closeup", "camera-pull", "camera-push"], "job": "drama", "subject": "a meal-kit app", "feeling": "a quiet breakup at a dinner table", "title": "Dinner for Two", "seconds": 30}. Also returns the don't-list, tone words, deliverables, lint warnings and a site_url.
| Name | Required | Description | Default |
|---|---|---|---|
| job | No | What the brief is for (default reel); use the job you dealt for. photo = a still image, video = reel, song = Suno blocks only, site = SITE PROMPT, game = key art set, drama = short drama ad (beats, end card, caption rules). | reel |
| tool | No | Target tool: any (plain prose), midjourney, runway or kling (camera line first, shots capped at 10 s), suno (music blocks only), openfilm (leads with a FILM PLAN and a LOOK.CSS for a coding agent building the film as web pages in OpenFilm). | any |
| beats | No | Optional: what happens in each shot, in order, e.g. ["they sit in silence", "she slides a photo across the table"]. Beat n goes into SHOT n (or the one VIDEO PROMPT). | |
| title | No | Optional title lettering for the image or key art (set in the type card). For drama, the show or brand name on the end card. | |
| aspect | No | Optional aspect ratio, e.g. "16:9", "9:16", "4:5", "1:1", "2.39:1". Default 9:16 for reel and lyric, 16:9 for game. | |
| vocals | No | Optional for music: "lyrics" lifts vocal bans out of SUNO EXCLUDE so a sung track can exist; "instrumental" adds them. | |
| feeling | No | Drama only: the story's feeling or situation, e.g. "a quiet breakup at a dinner table". The hook opens on it and every shot carries it. | |
| seconds | No | Optional running time in seconds, e.g. 15 for a reel or 60 for a short: split across the SHOT blocks (or the one VIDEO PROMPT) as "Duration: N s." Drama: 15 to 60, default 30, timed hook, twist, payoff. | |
| subject | No | Who or what is in the shot, e.g. "a lighthouse keeper on a rocky coast". Without it the prompts say [your subject]. For drama, the product being advertised. | |
| hand_ids | Yes | Card ids from deal_hand or find_styles, e.g. ["film-gold-200", "camera-closeup", "color-golden-hour"]. One per suit, except several camera cards = a shot list. |
| Name | Required | Description |
|---|---|---|
| job | No | the job as asked |
| hand | No | |
| lint | No | |
| site | No | |
| tool | No | the tool the blocks are spelled for |
| error | No | Set instead of the fields above when the input was wrong. |
| aspect | No | the frame the blocks use |
| blocks | No | block name to paste-ready text |
| ignored | No | suits the job does not use |
| seconds | No | drama: the running time the beats are timed to |
| handover | No | |
| job_note | No | a note for this job |
| site_url | No | opens the hand on directorslookbook.app |
| beat_plan | No | drama: each beat with its seconds and shot |
| shot_order | No | the SHOT block names in order |
| substitute | No | set when a stand-in card covers a genre the library lacks |
| job_internal | No | the deck term when it differs from the job asked (video = reel, photo = still) |
| end_card_from | No | drama: the second the end card starts |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, non-destructive behavior, and the description adds substantial context: tool-specific respelling for midjourney/runway/kling/suno, camera-light and film-fx effects, lens behavior, seconds/beats/vocals effects, and extra returns like lint warnings and site_url. It does not discuss errors or validation, but it is well beyond what the annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded, but the body becomes a dense semicolon-heavy run-on that mixes job types, tool variants, card rules, and two examples in one block. The content is useful, but the structure and length hurt 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?
Given 10 parameters, multiple enums, and an output schema, the description covers the important call-time concepts: job/tool variants, id constraints, examples for still and drama, and extra return fields. Missing return-value detail is acceptable because an 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?
Schema coverage is 100%, so the baseline is 3; the description adds cross-parameter meaning such as several camera cards producing a shot list, light/fx/lens cards affecting shots, seconds splitting duration, beats mapping to SHOT n, and vocals toggling SUNO EXCLUDE. It does not re-document every schema field, but it meaningfully explains interactions the 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?
States a specific verb and resource: 'Turn card ids into paste-ready prompt blocks,' then enumerates the block families and job-specific outputs. This clearly distinguishes it from siblings like deal_hand and find_styles, which supply the ids rather than compile prompts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 pass ids from deal_hand or find_styles and gives the 'one card per suit, except camera' rule, plus photo and drama examples. It does not explicitly say when to avoid this tool or route to lint_hand/show_card, so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| 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). |
| 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 |
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.
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.
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.
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.
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.
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.
Search the 777 cards by feeling, mood, era, technique or style name. Use it when someone names or describes a specific look, lens, film stock, light, palette, font or music style ("what does Portra 400 look like", "ring light macro", "Wes Anderson-style symmetry" finds Planimetric Tableau), to identify a named look ("Kodak Gold" finds Gold 200), to find a replacement for one card in a hand, or to browse one suit. Examples: {"query": "film noir"}, {"query": "90s camcorder"}, {"query": "cozy rainy", "suit": "color"}, {"query": "bossa nova", "suit": "score", "top": 3}. Returns ranked cards (id, suit, kind, name, what, example image). When nothing matches directly it says so and returns related styles or did-you-mean suggestions. For a full matched set of cards for a project use deal_hand instead.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | How many results (1 to 50, default 8). | |
| suit | No | Optional filter. type = typefaces, camera = shots, moves, lenses and lighting, film = looks and mediums, color = palettes and grades, score = music styles, web = site motion and layout. | |
| query | Yes | A feeling, mood, era, technique or style name, e.g. "dreamy 70s summer", "anamorphic", "risograph", "lo-fi beats". Words after "no"/"not" count against a card. |
| Name | Required | Description |
|---|---|---|
| note | No | set when nothing matched directly |
| site | No | |
| count | No | |
| error | No | Set instead of the fields above when the input was wrong. |
| matched | No | |
| results | No | |
| suggestions | No | did-you-mean cards when nothing matched |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-openWorld, so the safety profile is covered. The description adds genuinely new behavior: ranked results with fields listed, graceful no-match handling with related styles and did-you-mean suggestions, and that 'no'/'not' words count against a card. It stops short of pagination or ranking-explanation detail, keeping it below a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then triggers, then examples, then return shape, then the alternative — a sensible ordering with no filler. It is on the long side and the example list is slightly redundant with the prose, but every clause carries routing or behavioral 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?
Given an output schema exists, the description needn't explain return values, yet it still summarizes them and covers the degenerate no-match case. Together with the sibling routing to deal_hand, an agent has everything needed to call this 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 coverage is 100%, so baseline is 3; the description goes further by framing `suit` as a browse mode ('browse one suit') and showing `top` in a real call ('bossa nova' with suit=score, top=3). It also reinforces the negation syntax on `query`. It does not add format guidance beyond the schema's own enum descriptions, 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 ('Search the 777 cards') plus the dimensions searched (feeling, mood, era, technique, style name). It distinguishes itself from siblings by naming deal_hand for full matched sets, so an agent can separate retrieval modes 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 explicit when-to-use triggers (user names or describes a look; identify a named look; find a replacement card; browse one suit) and an explicit alternative ('For a full matched set of cards for a project use deal_hand instead'). Four concrete example calls remove ambiguity about scope and filtering.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check card ids you combined yourself for clashes before briefing: black-and-white film with a colour grade, two grades stacked, daylight with a night palette, an anamorphic lens in a vertical frame, an interior light with an outdoor subject. Example: {"hand_ids": ["film-pushed-bw-1600", "color-teal-orange"], "aspect": "9:16"}. ok: true means clean. deal_hand and brief already lint their own output.
| Name | Required | Description | Default |
|---|---|---|---|
| aspect | No | Optional frame, e.g. "9:16". | |
| subject | No | Optional subject; enables the light-vs-setting check. | |
| hand_ids | Yes | Card ids to check. |
| Name | Required | Description |
|---|---|---|
| ok | No | |
| site | No | |
| error | No | Set instead of the fields above when the input was wrong. |
| problems | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description only needs to add check semantics — and it does, enumerating the clash categories (bw film + colour grade, stacked grades, day/night palette mismatch, anamorphic in vertical frame, interior light + outdoor subject) and stating 'ok: true means clean'. It does not describe the failure payload or whether a failed lint blocks briefing, but with annotations and an output schema carrying much of the load this is a minor 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?
Purpose and scope are front-loaded, followed by the worked call example and the 'ok: true' contract. The middle clash enumeration is a dense run-on that would scan faster as a list, but every clause carries real information about what gets validated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 linter with a full output schema, the description supplies enough: what it validates, an example invocation, and the success signal. It stops short of describing the failure report, which the output schema presumably covers, so nothing critical is missing for invoking it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds semantics the terse schema blurbs do not: it ties aspect to a concrete check ('an anamorphic lens in a vertical frame') and subject to another ('an interior light with an outdoor subject'), showing how those optional params activate additional checks. The worked example also clarifies the hand_ids array shape.
Input schemas describe structure but not intent. Descriptions should explain 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 ('Check card ids you combined yourself for clashes before briefing') and immediately distinguishes itself from siblings by scoping to hand-authored combinations rather than deals or briefs. An agent can tell it apart from deal_hand and brief 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 both the positive condition ('card ids you combined yourself ... before briefing') and an explicit exclusion ('deal_hand and brief already lint their own output'). The alternative tools that would otherwise look relevant are named and ruled out, 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.
Card counts per suit and per kind (for example camera: shot, move, lens, light). Use it to see what the lookbook covers before searching.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds genuine behavioral context beyond that: the response is aggregated counts grouped by suit and kind, and the tool is intended as a discovery/orientation step. Return format specifics are unnecessary since an output schema exists.
Agents need to know what a tool does to the 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: the first defines the output, the second defines the use case. Front-loaded, zero filler, and the example is compact and illustrative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 parameters, a present output schema, and full annotation coverage, the description only needs to convey intent — which it does by explaining both the grouping dimension and the pre-search orientation role. Minor gap: it never clarifies the 'suit'/'kind' vocabulary for an agent unfamiliar with the domain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies a parameterless, whole-corpus scan rather than a filtered query.
Input schemas describe structure but not intent. Descriptions should explain 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 concrete deliverable — 'card counts per suit and per kind' — with a parenthetical example (camera: shot, move, lens, light) that makes the aggregation semantics unambiguous. It is clearly an inventory/aggregation tool rather than a search tool, though it does not name any sibling to sharpen the contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 an explicit usage moment: 'Use it to see what the lookbook covers before searching,' which frames this as an orientation step preceding search-style siblings like find_styles. It stops short of naming the alternatives or stating when-not to use it, so it is clear context rather than full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One card in full: what it is, the prompt wording ("ask"), what not to do, feels, moods, pairs, swatch hexes or font details, plus image, clip and music_sample URLs when it has them. Example: {"id": "film-gold-200"}. A wrong id returns did-you-mean suggestions.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Card id from find_styles or deal_hand, e.g. "film-gold-200", "camera-dutch", "score-bossa-nova". |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent and non-destructive, and the description adds genuine behavioral context beyond them: what a correct call returns and that a wrong id returns did-you-mean suggestions rather than an error.
Agents need to know what a tool does to the 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 'One card in full' then lists contents in one flowing sentence; the field enumeration is long but earns its place by telling the agent what a card contains. No wasted preamble.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return values need not be spelled out, yet the description usefully sketches them anyway; combined with the error-behavior note, an agent has enough to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already documents the id with examples, so the description's example and did-you-mean note add only marginal value. Baseline 3 is appropriate when the schema carries the parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: retrieving one card by id, and enumerates the fields returned (ask, feels, moods, pairs, swatches, media URLs). It is clearly distinguishable from list/find siblings in substance, though it never explicitly names 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?
Usage is implied rather than stated: the id must come from find_styles or deal_hand, but that sourcing hint lives in the schema, not the description, and there is no explicit when-to-use-this-vs-siblings guidance.
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.
brief2 fields changedInput schema / properties / tool / descriptionPrevious value: -"Target tool: any (plain prose), midjourney, runway or kling (camera line first, shots capped at 10 s), suno (music blocks only)."New value: +"Target tool: any (plain prose), midjourney, runway or kling (camera line first, shots capped at 10 s), suno (music blocks only), openfilm (leads with a FILM PLAN and a LOOK.CSS for a coding agent building the film as web pages in OpenFilm)."Input schema / properties / tool / enumPrevious value: -[
- "any",
- "midjourney",
- "runway",
- "kling",
- "suno"
-]New value: +[
+ "any",
+ "midjourney",
+ "runway",
+ "kling",
+ "suno",
+ "openfilm"
+]Search, compare, and blend structured visual aesthetics, palettes, and creative directions.
One sentence in, the best-matching visual style out: art reference chart and prompt encyclopedia.
Design-style library for AI agents: find a style by use or mood, preview it, apply its spec.
Search decoded art styles and their prompts; decode your own images with your account.
Add one secure layer between your agents and this server.
