execute_extendscript

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

With no annotations provided, the description carries the full burden and does so well: it discloses independent eval with no shared state, availability of QE DOM, no undo grouping, and the full destructive capability. This is exactly the behavioral context an agent needs before invoking an arbitrary-code tool.

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: core function, return contract, state semantics, structured-result guidance, and a warning. It is front-loaded with the most important information and contains no filler.

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?

Despite having no annotations and no output schema, the description covers the essential operational facts: what the tool runs, what it returns, its state isolation, and its risk profile. An agent has enough information to decide whether and how to call it, including how to format complex results.

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?

The schema already fully documents the single script parameter, so the baseline is 3. The description adds value by requiring the script to be self-contained and recommending a JSON-shaped string for structured results, both of which help the agent construct correct invocations.

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 states a concrete action: run arbitrary ExtendScript in Premiere Pro and return the script's string result. It also distinguishes itself from the large roster of named siblings by labeling itself a power tool and telling the agent to prefer named tools when available.

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?

It gives explicit when-not-to-use guidance: prefer the named tools when one exists, and warns to back up the sequence before structural timeline edits. Combined with the sibling list, an agent can decide to use this only when no dedicated tool covers the operation.

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