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

Goes meaningfully beyond the annotations by disclosing cost ("Free"), the deterministic operation ordering, the null-clears-visual fallback, and the return contract ("Returns the updated draft — show it to the user again"). What it omits is reversibility: whether dropped scenes or overwritten narration can be recovered, which matters for a non-idempotent mutation.

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 purpose and cost, then the ordering rule, then per-operation semantics, then the return instruction — a logical sequence with no filler. The telegraphic style ("Free.", "remove: scene numbers to drop.") is dense but occasionally clipped enough to slow parsing.

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 10-parameter, non-idempotent mutation with no output schema, the description covers purpose, cost, ordering, indexing, and what comes back. Gaps are secondary: no mention of warnings[] semantics (left to schema), no failure modes, and no note on whether removing scenes is recoverable.

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?

At 40% schema coverage the description must compensate, and it does for the core five: it defines edits (narration verbatim, visual null → auto image, seconds), insert with "after N (0 = at the start)", remove, and reorder requiring every current scene number. The crucial 1-based / as-it-is-now indexing rule is stated here and nowhere in the schema. The remaining params (title, artStyle, language, aspectRatio, targetDuration) are left to the schema.

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?

"Change a draft before render" gives a specific verb (change) and resource (draft), and the following sentences enumerate exactly which facets can change. It implicitly separates itself from autoshort_render_draft and autoshort_get_draft via "before render", but never names a sibling, so differentiation is inferred rather than stated.

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?

"Change a draft before render" plus "Free" gives a usable context cue, and the stated application order (edits → reorder → remove → insert) tells the agent how to combine operations. However, there is no explicit routing guidance against close siblings like autoshort_revise_scene or autoshort_get_draft, and no when-not conditions.

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