aicut

Write a story cast (free draft)

generate_cast

Writes the CAST for an AI Video Story series (named characters, each with a role and a one-line description) as a DRAFT for the user to read. FREE: it spends no tokens, generates no portraits and saves nothing to the character library. WHEN: as soon as the episode idea is settled, on a series whose cast.required is true (or whose user wants custom characters). Do NOT ask permission: it costs nothing and the webapp writes this roster automatically at the same point. Never call it for a cast.writer_owned series, which casts itself. WHAT IT RUNS: a showrunner model reads the series and your idea and answers with the cast that idea needs; IT DOES NOT WRITE THE STORY. The response's idea is the one you sent, unchanged (translated if needed); with NO idea the call authors a logline and returns that, which the user has not seen: show it and ask whether to keep it. AFTER: show the names and roles, one line each, and never present their own idea back as news. If they dislike the roster, call this AGAIN with a sharper idea (a re-draft is free and replaces it); never buy portraits for a cast they have not accepted. THE PRICE OF THE NEXT STEP RIDES THIS RESPONSE: portraits_needed (the members whose needs_portrait is true; a preset-bound member arrives photographed and costs nothing) and portrait_models, each with per_portrait_tokens and the roster's total_tokens (default: true is what the series is tuned for). Use those figures verbatim; never multiply anything yourself. generate_cast_portraits with this draft_id is the money step (the draft stays redeemable about two hours). WEBAPP-ONLY: renaming a member, adding your own, adding one from a photo. Never re-draft the whole cast for one member: once portraits are bought, describe_cast_member changes what one member IS. A 400 invalid_request for a series that ships its own FIXED cast, casts itself or has no cast-first flow means: go straight to generate_story_video without a cast. A 429 utility_rate_limited is the free AI-writing allowance shared with the webapp: wait the retry-after, never top up tokens.

Input Schema

Name	Required	Description
`idea`	No	The episode idea the cast should serve, one short paragraph: pass the user's idea whenever there is one. Only when omitted does the writer author a logline.
`world`	No	The visual world for the cast (`fruits`, `humans`, `animals`). Unset lets the writer pick.
`language`	No	Omit unless the user asked for another language (the series' `defaults.language` is used). Pass the SAME language to `generate_story_video`.
`series_id`	Yes	The series id, exactly as `list_series` returns it.

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 23, 2026

TDQS

A4.2/5.0

Behavior3/5

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

Without annotations this would be near-perfect: it discloses that the call is free, persists nothing, produces a redeemable `draft_id` for roughly two hours, and documents the exact 400 `invalid_request` and 429 `utility_rate_limited` recovery paths. However, the annotations already declare openWorldHint=true and destructiveHint=false, and the description's "saves nothing" claim sits uneasily beside readOnlyHint=false (a draft object with an id is created), so a small part of its behavioral framing is redundant rather than additive relative to the structured fields. The remaining cost/error/expiry context is genuinely beyond annotations, lifting it to a 3 rather than higher given the overlap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and the free/no-permission facts are front-loaded, and nearly every sentence carries actionable content (costs, ordering, error recovery, pricing fields). It is still a very dense single block of roughly 300+ words with shouted inline section markers (WHEN, WHAT IT RUNS, AFTER, WEBAPP-ONLY) inside one paragraph, which costs some scannability for a four-parameter tool.

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?

There is no output schema, and the description compensates fully: it enumerates the response fields an agent must act on (`draft_id`, `idea` echo, `portraits_needed`, `portrait_models` with `per_portrait_tokens` and `total_tokens`) and warns against recomputing them. Combined with the next-step routing, expiry window, and error-code handling, 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.

Parameters3/5

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 documented in the schema; the baseline is therefore 3. The description adds real but partial value beyond it: the no-`idea` fallback behavior (an authored logline the user has not seen, which must be shown back) and the instruction to reuse the same `language` in `generate_story_video`. It adds nothing for `world` beyond what the schema states.

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 ("Writes the CAST for an AI Video Story series") with a concrete definition of the artifact (named characters with a role and one-line description) and its modality (DRAFT). It also explicitly bounds what it is not ("IT DOES NOT WRITE THE STORY") and routes to the sibling `generate_cast_portraits`, so an agent can distinguish it from neighbors 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.

Usage Guidelines5/5

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

Gives an explicit WHEN trigger (after the episode idea is settled, on a series with `cast.required` true), an explicit prohibition ("Never call it for a `cast.writer_owned` series"), and an explicit no-confirmation rule ("Do NOT ask permission"). It also names alternatives and the escalation path: re-draft with a sharper `idea` instead of buying portraits, and `describe_cast_member` for post-portrait edits.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All aicut tools Inspect

Try in Browser