add_color_matte

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

With no annotations, the description carries the full burden and does so well: it discloses the filesystem side effect (a matte written to "MCP mattes" next to the project, reused, never in a temp folder), the bin it is imported into, and the track fallback behaviour (V1 when free, otherwise a new top track). It does not say what is returned or what happens on failure, which keeps it short of a 5.

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 purpose is front-loaded in the first clause, and every subsequent clause carries new information (colour options, frame size, file location, bin, placement). It is dense with parentheticals and reads as one long run-on sentence, which is the only structural weakness.

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 seven-parameter mutation tool with no annotations and no output schema, the description covers side effects, defaults and fallback behaviour thoroughly. The remaining gap is what the agent gets back from the call and how to recover from a failed import, which the description is silent on.

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 100%, so the schema already documents color, start/end, track fallback, name defaults and sequence targeting; the prose mostly restates those (white/black default, whole-sequence span, #RRGGBB). The one piece of added meaning is that the matte is generated at the sequence frame size, which explains an implicit constraint. Baseline 3 is appropriate.

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?

States a specific verb and resource: it creates a solid colour matte on the timeline at sequence frame size and imports it into a dedicated bin. The level of concrete detail makes it clearly distinct from generic add_color_layer/add_adjustment_layer siblings, though no sibling is named explicitly, so there is no direct differentiation statement.

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?

"The plate a logo sits on" implies the intended use case, and the note about Premiere's blocking colour picker explains why the tool exists. However, there is no explicit when-to-use vs. when-not guidance and no pointer to alternatives such as add_color_layer or add_scene_color_layers, which is a real ambiguity given the number of colour-layer siblings.

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