Skip to main content
Glama

Create a character episode

autoshort_create_character_episode
Idempotent

Create a 3-8 shot narrated short-video episode with one consistent character from a reviewed season plan, charging credits only after a confirmed quote.

Instructions

Make the episode: 3-8 shots, 12-60 seconds, the same fictional character in every shot, narrated with captions. CHARGES credits. The series must have a REVIEWED, CONFIRMED season plan and the episode must be one of its episodes exactly as planned (SEASON_PLAN_REQUIRED / SEASON_NOT_REVIEWED / EPISODE_NOT_IN_PLAN otherwise, with a nextAction, nothing charged); the narrator voice, language, style, look and outfit come from the plan. ALWAYS call autoshort_quote_character_episode first and get the customer yes: this call refuses unless confirm is true and expectedCredits equals the quoted price (a changed price answers 409 and charges nothing). Credits are held when it starts. A shot that cannot be animated keeps a still image and its clip credits go back; if too few shots move, or anything else fails, everything goes back. Takes about 10-25 minutes: poll autoshort_get_video with arguments { id: <the returned id / videoId> } (or use a webhook); it reports status, stage and, when COMPLETED, videoUrl. Pass idempotencyKey so a retry never charges twice. One episode at a time per account, 3 per day.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "seriesId": "<seriesId>",
      "confirm": "<confirm>",
      "expectedCredits": "<expectedCredits>"
    },
    "name": "autoshort_create_character_episode"
  }
}

Input Schema

NameRequiredDescriptionDefault
shotsNoShots you write yourself (better pictures than the automatic split). Give `shots` OR `script`.
titleNoOptional title.
scriptNoThe narration, about 29-138 words. The system splits it into shots by sentence. Give `script` OR `shots`.
confirmYesMust be true: making an episode spends credits.
sheetIdNoOmit it: the character sheet is the one the season plan names for this episode. If given it must equal that sheet.
languageNoOmit it: the narration language is the season plan's. If given it must equal the plan's.
seriesIdYesA series id from autoshort_list_series whose season plan is reviewed and confirmed.
shotCountNoWith `script`: how many shots to split it into. Omit for an automatic count.
resolutionNoClip resolution. Default '480p'. '720p' costs more per second (see quote.pricePerResolution) and is only accepted when it is listed as available there; the quote and the create must use the same resolution.
idempotencyKeyNoRetry-safe: a repeat with the same key returns the first answer (replayed: true) and charges nothing.
expectedCreditsYesThe credits the quote showed. Must match the current price.
caption_secondary_languageNoOptional second caption line: a translated line under the caption, in this language code such as 'vi' or 'en'. 'none' for no second line. Omit to follow the series, then the account default (off unless set). No extra charge.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv2.3.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only say readOnlyHint=false, idempotentHint=true, destructiveHint=false; the description goes well beyond them by disclosing that credits are charged, held at start, partially refunded for unanimated shots, and fully refunded on failure or a 409 price change. It also gives runtime expectations (10-25 minutes) and operational limits (one episode at a time per account, 3 per day). Nothing here contradicts the annotations, though the credit spend is worth noting against 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.

Conciseness4/5

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

Front-loads the core operation, then prerequisites, cost confirmation, refund policy, polling and limits in a logical order. Very dense but nearly every clause carries operational fact; the parenthetical error-code list and the combined polling/limits tail are slightly crammed and could be split for scannability.

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 12-parameter mutation with no output schema, the description supplies everything an agent needs: prerequisites, the quote gate, cost/refund semantics, expected duration, how to retrieve the result, idempotency, and concurrency quotas. No output schema is present, and the description correctly names the polling tool and the returned id/videoId rather than describing the payload.

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 description coverage is 100%, so a baseline of 3 applies, but the description adds cross-parameter meaning the schema does not: `confirm` and `expectedCredits` are tied to the prior quote and a 409 on price drift, `idempotencyKey` is explained as retry-safety against double charging, and resolution is tied to cost. The shots-vs-script and shotCount relationship is left mostly to the schema.

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?

Opens with a concrete verb and resource plus hard constraints: 'Make the episode: 3-8 shots, 12-60 seconds, the same fictional character in every shot, narrated with captions.' That immediately separates it from siblings like autoshort_quote_character_episode (pricing) and autoshort_get_video (polling), both of which the description names.

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 mandatory pre-step ('ALWAYS call autoshort_quote_character_episode first and get the customer yes') and an explicit follow-up path ('poll autoshort_get_video ... or use a webhook'). It also states preconditions (reviewed, confirmed season plan; episode must match the plan) and their failure codes with nextAction, so an agent knows exactly when this call is and is not appropriate.

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