adopt_external_script

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It reveals the server-side format gate (errors → 400 with the list returned as-is), the warning tolerance matching save_script, the fact that old scripts are saved to previous_script, the fallback recovery via get_script(include_previous=1), and the billing/speed characteristics. This goes well beyond what a minimal mutation-tool description would offer.

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 long but every sentence earns its place: the core purpose is front-loaded, then the hard gate, then usage/exclusion conditions, then sibling differentiation, then rollback behavior. Bold markers and star bullets create scannable structure with zero filler or repetition. This is dense, pragmatic documentation rather than padding.

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?

Given the tool's complexity, the lack of annotations, and the absence of an output schema, the description covers prerequisites, routing, side effects, and recovery comprehensively. The only notable gap is that it never states what a successful response contains or how an agent should confirm adoption succeeded — this is a minor omission because the gate and rollback behavior are well documented.

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 50%: content has a meaningful schema description, but episode_id has none. The tool description compensates for content by clarifying that it must be a complete production-annotated script that has already passed check_script_format, and by explaining the warning/error semantics that affect acceptance. episode_id receives no added semantics in the description, but its meaning as an episode identifier is reasonably unambiguous from the parameter name alone.

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?

The description opens with a specific and unique verb+resource pair: 'directly adopt the external AI's script produced per template as a shootable script' (出口 A). It explicitly distinguishes itself from edit_rewritten_script ('首次落稿' vs '改已有改写稿') and from the set_script+rewrite_script alternative (出口 B), so there is no ambiguity about what the tool does or how it differs from siblings.

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 guidance is extremely explicit: it states when to use ('客户要求一个字都别改我的稿、且外部 AI 已经产出含制作层标注的完整稿') and when NOT to use (story-layer-only scripts, for which 出口 B is recommended). It also names the exact sibling tool edit_rewritten_script and clarifies the division of labor, including the 400 condition that differentiates them. No inference is required.

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