Write Take Parameter Overrides

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

With no annotations, the description must carry the behavioral disclosure burden. It does reveal that the tool wraps take.OverrideNode + UpdateSceneNode + override[descid] = value, indicating a mutating operation on take data and scene state. However, it omits constraints like the Take must not be Main and leaves clear/remove_all semantics to the schema rather than the description.

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?

Three tight sentences: action and scope, use case with example, and path-syntax clarification. Every sentence contributes, and the definition is front-loaded with the most important information.

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 complex write tool with six parameters, nested target definitions, and no output schema, the description covers what is written, to which node types, and in which workflow context. It is adequate for an agent to select and invoke the tool, though exclusion criteria and clearing semantics are left to the schema.

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 100%, so the baseline is 3. The description adds the useful note that paths use the same syntax as set_params and a Focal Length example, but much of this is already stated in the schema for values. It does not add meaningful guidance for the complex target handle union.

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 specific verb-resource pair: 'Write per-Take parameter overrides onto a target node' and enumerates accepted node kinds (object / tag / material / render_data / video_post / shader). This clearly distinguishes it from ordinary parameter-setting tools like set_params, though it does not explicitly name that sibling as the alternative.

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?

'Use this for shot-by-shot variations that share a single scene' provides an explicit intended context, reinforced by the concrete example of overriding Focal Length per Take while reusing one Camera. It stops short of stating exclusions or directly naming when to prefer set_params, so it is clear but not fully prescriptive.

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