ai_combine_apply

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

No annotations exist, so the description carries the full burden and does so well: it discloses that the action is undoable, consumes no quota, creates no new draft, uploads a preview video for review when one exists, and auto-creates dependent objects. It also documents the validation failure path precisely (AI_COMBINE_APPLY_FAILED plus the editor's original message, with a concrete example) and the return payload (added_objects with object_path, draft_id nullable).

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 the core action and its user-facing equivalent, then layered with prerequisites, side effects, failure modes, and return values. Sentences are dense but each carries distinct information. Slight cost: the parenthetical object-creation clause and the error example make it long, though both are load-bearing given no output schema.

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 mutation tool with zero annotations and no output schema, the description supplies everything an agent needs: what it mutates, that it is reversible, that it costs no quota, the auto-created objects, the error code and message shape, and the exact return fields including nullable draft_id. It even names the mandatory follow-up call.

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 description coverage is 100%, so both optional selectors (instance_id / project_path) and the required graph_id are already documented in the schema itself, including the '二选一' and 'only one window open' rules. The description reinforces graph_id as 'the workflow' but adds no syntax, format, or edge-case detail beyond the schema. Baseline 3 is appropriate.

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?

Names a specific verb+resource ('把一张 AI 工作流放进场景' = apply an AI workflow into the scene) and pins down the exact user-facing equivalent ('AI 效果窗口的「应用」'). It also enumerates the concrete side effects — compile, upload workflow file, add AI 组合效果 object, auto-create 2D 前景/2D 摄像机 — which separates it cleanly from the sibling ai_combine_new (creation vs. application).

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 context is clear: it is the 'apply' stage that follows a workflow existing, and the description ends with the explicit next step '之后 save_project'. The graph_id schema entry also routes the agent to ai_combine_new / get_workflow_context for the required input. What is missing is an explicit when-NOT clause (e.g., don't call before the workflow node is wired), which is instead surfaced reactively as an error case.

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