create_cinematic_plan

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

With no annotations, the description carries the full burden, and it does disclose the most important behavioral trait: the tool does not launch or control the game, so it is safe as a pre-flight check. It says nothing about whether a plan file is written, what validation failures look like, where output goes, or whether game_dir/documents_dir must already exist.

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?

One short, front-loaded sentence with no filler; the exclusion clause is placed immediately after the purpose. It is efficient rather than padded, though the brevity comes at the cost of coverage rather than because the essentials were captured.

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 tool taking a free-form array plus three path/filter strings, with no annotations and no output schema, the description does almost nothing: it never explains shot element structure, path resolution, or what a successful plan/validation result contains. An agent would have to guess at nearly every argument and at the return value.

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 description coverage is 0% across four parameters, and the description only obliquely gestures at the required 'shots' argument via the phrase 'draft shot list'. It adds no meaning for game_dir, pp_filter, or documents_dir, and gives no hint about the expected shape of elements inside the free-form shots array, which is the crux of getting the call right.

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 gives a concrete verb and resource ('Validate a draft shot list') and rules out game interaction, which helps distinguish it from siblings like prepare_replay_launch. However, it conflicts with the tool name create_cinematic_plan: nothing says whether a plan is created/persisted or merely checked, so an agent cannot tell what the tool actually produces.

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?

There is a single implied cue (do this before launching the game), but no explicit when-to-use/when-not-to-use guidance. Siblings validate_camera_capability and validate_filter_compatibility exist and the description never routes between them or says what prior state a draft shot list must satisfy.

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