Clip Studio MCP

edit_topic_short

Edit a finished Topic Short. Free kinds use no generation allowance: captions (captionStyle: off, spotlight, impact, highlighter, editorial, boxed, kicker), music (trackId from get_topic_short editCapabilities.musicOptions, or none) and swap_shot (beatIndex, shotIndex and an alternateId from get_topic_short shots). Paid kinds are quoted first with quote_topic_short_edit and run on that quoteId with the same fields: revoice (beatIndex plus the new narration for that line) and regenerate_shot (beatIndex and shotIndex of an AI shot); a shortfall returns HTTP 402 with numeric requiredCredits and availableCredits. nl takes an instruction ("make the hook punchier") and only interprets it: it returns a proposal of steps, each with a label and either a ready request (kind and params, with a quoteId and quote facts on paid steps) or the reason it cannot run. Apply each runnable step with its own edit_topic_short call, passing its params fields and quoteId. Each applied edit makes a new version; poll get_topic_short until it is completed. A public page stays on the version it was published from until you call publish_generation again. Restoring an earlier version is done on the clip page. Up to 20 free edits per short.

Input Schema

TableJSON Schema

Name	Required	Description
`id`	Yes	Topic Short generation id from generate_topic_short.
`kind`	Yes	captions restyles or removes the burned-in captions; music swaps or removes the music bed; swap_shot replaces one shot with a judged alternate; revoice re-records one line; regenerate_shot re-rolls one AI shot; nl interprets a written instruction into these edits.
`quoteId`	No	With revoice or regenerate_shot: the quoteId from quote_topic_short_edit (or an nl proposal step) for this exact change. The change runs only on its own quote.
`trackId`	No	With kind music: a music option id from get_topic_short editCapabilities.musicOptions, or none for no music.
`beatIndex`	No	With swap_shot, revoice or regenerate_shot: the beat to change (0 is the hook).
`narration`	No	With revoice: the new spoken line for that beat, in the short’s language.
`shotIndex`	No	With swap_shot or regenerate_shot: the shot inside that beat (default 0).
`alternateId`	No	With swap_shot: an alternate clip id for that shot from get_topic_short shots.
`instruction`	No	With nl: a written edit request, for example “make the hook punchier” or “more footage of the harbour”.
`captionStyle`	No	With kind captions: the new caption look, or off for a clean frame.
`idempotencyKey`	No	Optional. Reuse the same key when retrying an ambiguous edit so it is applied once.

Output Schema

TableJSON Schema

Name	Required	Description
`edit`	No	The new version (editId, version, kind, status, outputUrl, current, published). Poll get_topic_short until it is completed.
`proposal`	No	kind nl only (nothing is applied): summary, steps (each with op, label, request with kind and params plus quoteId on paid steps, quote with numeric requiredCredits and facts on paid steps, and unavailable when the step cannot run), total numeric requiredCredits and availableCredits, and affordable. Apply each runnable step with its own edit_topic_short call.
`replayed`	No	True when this idempotencyKey already made this edit and the same version is returned.

Schema Changelog

Changes observed during successful MCP inspections.

AddedOct 4, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only cover the safety profile (readOnlyHint false, destructiveHint false, openWorldHint false), and the description adds substantial behavior beyond that: HTTP 402 with requiredCredits/availableCredits on shortfall, each edit creating a new version that must be polled via get_topic_short, published pages staying pinned until publish_generation, restoration happening on the clip page, and a 20-free-edit cap.

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-loaded with the core purpose before diving into kind-specific detail, and nearly every sentence carries operational information (quote flow, 402 semantics, versioning, polling). The main weakness is that the middle is one dense run-on paragraph, which costs scannability, but there is little filler to cut.

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 multi-kind mutation tool with an output schema already present, the description covers what an agent still needs: the free/paid split, the quote prerequisite, error behavior, versioning and publication semantics, and the follow-up polling loop. Nothing material about invoking it correctly is missing.

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 baseline is 3, but the description goes further by mapping each kind to its relevant fields (captionStyle for captions, trackId from editCapabilities.musicOptions, beatIndex/shotIndex/alternateId for swap_shot, quoteId for paid kinds) and clarifying that nl takes an instruction. It stops short of documenting idempotencyKey usage beyond what the schema already 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?

Opens with a specific verb+resource ('Edit a finished Topic Short') and immediately distinguishes itself from generate_topic_short by operating on an existing generation. It then enumerates the exact kinds of edits it supports, so an agent can tell it apart from siblings like quote_topic_short_edit or get_topic_short without opening a 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?

Explicitly partitions usage into free kinds (captions, music, swap_shot) versus paid kinds (revoice, regenerate_shot) and states the prerequisite that paid edits must be quoted first via quote_topic_short_edit and run on that quoteId. It also names the alternative path for natural language (nl returns a proposal to be applied step-by-step) and points to quote_topic_short_edit and get_topic_short as companion tools.

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

All Clip Studio MCP 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?