import_storyboard_table

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It reveals side effects (confirm_replace converts old shots to deleted-but-recoverable state, 409 when storyboards already exist), default auto-complete behavior with billing implications, asynchronous polling via get_autofill_status, and that reviewing before autofill completes invalidates tokens. This is thorough and operationally critical.

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 section carries operational value and the key decision rule is front-loaded. The numbered three-step checklist and star-marked warnings make the density navigable. Some formatting could be tightened, but the length is justified for a mutation tool with import, cost, and async side effects.

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?

With 4 parameters, no output schema, and a large sibling set, this description provides everything needed: prerequisites, exact input format, fallback content source, error/status codes, replacement behavior, auto-complete flow, billing notice, and follow-up tool sequencing. An agent can confidently invoke the tool and orchestrate the subsequent workflow without further lookups.

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 75%, but the description adds substantial meaning beyond the schema: content can be omitted to read the episode's raw content, content declaration format is fully specified with examples, auto_complete explains default-on, pay-per-token behavior, and confirm_replace explains the replacement semantics. Episode_id is only implicitly tied to '本集', but the overall parameter guidance far exceeds the baseline.

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 clear directive: import a client-finished storyboard table directly into storyboard shots, skipping rewriting and shot-splitting ('把客户做完的分镜表直接建成分镜，跳过改写与拆镜'). It states the resource (storyboard table → shots), the verb (import), and distinguishes itself from the normal set_script→rewrite_script→generate_storyboards pipeline with a concrete production example.

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?

The description explicitly says when to use this tool ('客户交来的不是剧本而是成品分镜表') and when not to use it ('没有任何逐镜声明会被 400 拒...请走正常拆镜'). It prescribes a three-step prerequisite workflow naming sibling tools get_storyboard_table_spec and check_storyboard_table, and explicitly warns against the script-rewrite path, making tool selection unambiguous.

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