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

Annotations already mark it as destructive, but the description adds key behavioral details: 'writes immediately and cannot be undone' and 'omitted fields are left untouched'. It also explains the consequence of using the deprecated dialogue field (duplicate/resurrect lines), which goes beyond the annotation's simple destructive flag.

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 compact and well-structured: three sentences that front-load the core action, then provide usage rules and a caution. Every sentence adds value with no fluff.

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 the complex nested schema, the description covers the essential workflow: read first, send only changes, handle dialogue correctly, and be aware of the irreversible write. It complements the schema without repeating its structure, and since there is no output schema, return value details are not required.

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 provides high coverage (100%) with descriptions for shot_id and patch, including the instruction to send only changed fields and to edit dialogue via camera_setup.short_shots[].dialogue_covered. The description reinforces this and adds the rationale for avoiding the deprecated field, giving extra context beyond the schema's wording.

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 clearly states the verb ('Overwrite') and resource ('one shot'), and distinguishes it from read-only siblings by instructing to read first. It is specific and avoids tautology, making the tool's purpose unambiguous.

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 explicitly says to read the shot first via get_episode_shots or get_episode_editor, then send only changed fields. It also gives a specific alternative for dialogue (camera_setup.short_shots[].dialogue_covered) and warns against the deprecated field, providing clear when-to-use and what-not-to-do guidance.

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