pr_setEffectProperties

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

Annotations already indicate this is a non-read-only, non-destructive mutation. The description usefully adds that effects are addressed by displayName and that values may be static or keyframed, but it does not disclose whether existing values or keyframes are overwritten, what permissions are needed, or how failures behave.

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 a single dense but front-loaded sentence with no wasted clauses. Parentheses carry useful examples and format details without burying the main action.

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 mutation tool with nested parameters and no output schema, this covers the main naming and format concepts reasonably well. It still omits important operational details such as how the properties object maps parameter names to values and whether keyframe edits replace or augment existing keyframes.

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 only 40%, so the description needs to add meaning. It does so by explaining effect displayName usage with examples, keyframe notation with timeline seconds, and hex colors. It still leaves the properties object and some keyframe-entry structure details unexplained, keeping it below a 5.

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 specific verb/resource: setting parameters of effect components on a Premiere Pro clip. It adds useful examples of component displayNames and distinguishes effects from other clip properties implicitly. However, it does not explicitly differentiate itself from nearby siblings such as pr_applyEffect or pr_setClipProperties.

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 implies the tool is used when an effect already exists on a clip and the user wants to adjust its parameters, either statically or via keyframes. But it gives no explicit when-to-use versus alternatives, no prerequisites, and no exclusions.

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