Generate or replace AI background music for an entire episode based on its emotional arc. Returns segment count and estimated time; poll status. Re-compose the episode to apply.
给整集生成/更换 AI 配乐(按情绪弧线)。后台异步,按用量后付不欠费。返回情绪弧线段数与预估耗时;用 get_bgm_status 轮询生成进度。★配乐生成/改动不会自动进已有成片——完成后必须重新 compose_episode(免费)才能听到;get_final_cut 的 bgm_stale=true 就是在提示这一步。别用 re-render(吃旧时间线,不含新配乐)。
| Name | Required | Description | Default |
|---|---|---|---|
| episode_id | Yes |
Changes observed during successful MCP inspections.
v0.1.57Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations to fall back on, the description carries full disclosure burden and succeeds: it reveals async background execution, postpaid billing, the returned segment count/estimated duration, stale-flag semantics (bgm_stale=true), and the fact that generated BGM does not automatically enter the existing final cut. No contradiction with annotations (none provided).
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 description is dense but every sentence earns its place: scope, async/billing, return value/polling, finalization requirement, and the rerender pitfall. It is front-loaded with the core action and preserves the most important integration warning near the end without redundancy.
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 one-parameter async tool with no output schema, it tells the agent what it returns, how to monitor progress, how to get the BGM into the final cut, what get_final_cut's bgm_stale means, and which sibling to avoid. The full relevant workflow is covered.
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 0% and the description never formally defines episode_id. However, the tool name, the phrase '整集' (entire episode), and a single self-explanatory required property make the parameter's role reasonably inferable. The description compensates little beyond the schema, but the ambiguity risk is low.
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?
Description opens with a specific verb+resource: '给整集生成/更换 AI 配乐(按情绪弧线)'—generate or replace AI BGM for an entire episode by emotional arc. It is unmistakably distinct from audio siblings like generate_tts and generate_sfx, and from episode finalization tools like compose_episode.
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 tells when to use the tool (for episode-level BGM generation/replacement), how to follow up ('用 get_bgm_status 轮询生成进度'), and which workflow is required to apply results ('必须重新 compose_episode'). It also provides a clear exclusion: '别用 re-render(吃旧时间线,不含新配乐)'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.