cascadeur_set_properties

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

The annotations already mark the tool destructiveHint=true; the description adds beyond that by warning that editing channels can change rig/physics behavior. It also implies a low-level mutation rather than simple keyframe editing. No contradiction with annotations.

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 short sentences: core action, risk warning, prerequisite. Each sentence adds distinct information and the most important guidance is front-loaded. There is no filler or repetition of schema details.

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 destructive, low-level setter with no output schema, the description covers the essential behavior, the advanced risk, and the required discovery step. It omits examples and does not specify how frame relates to channel edits, but that is largely recoverable from the schema and the clear prerequisite.

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 coverage is 0%, so the description must compensate. It indirectly explains object/name/value semantics via 'discovered data channels' and 'no guessed names', and scalar/vector hints value shapes. However, it does not explain the required frame parameter or the structure of properties beyond that, so the compensation is only partial.

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 clear verb+resource: 'Edit discovered scalar/vector data channels'. It also signals scope by warning not to guess names and to read get_object first, which helps distinguish this low-level channel editor from pose/animation tools like cascadeur_set_pose and cascadeur_set_keys, though it does not name those siblings explicitly.

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 a concrete prerequisite and operating rule: 'Read get_object first; no guessed names.' This tells the agent how to prepare and when the operation is valid, and the 'Advanced' warning flags it as not a routine pose edit. It does not list explicit alternatives/exclusions, but the context is clear enough.

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