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

Annotations mark this as a non-read-only, non-idempotent mutation but give no detail. The description adds real behavioural context beyond them: it is project-scoped, uses only the explicit project_id, returns the project identity, bakes a persistent LUT, and reports the colour gap before and after. It does not cover reversibility or permissions, but adds meaningful disclosure.

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 scope qualifier is front-loaded and the operational sentence follows immediately. It is dense but every clause carries information; no filler sentences.

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 no output schema, the description tells the agent what is produced (a baked 33^3 LUT) and what is reported back (before/after colour gap, project identity), which is enough to call it correctly. A note on reversibility or expected runtime would round it out.

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 67% and the description adds meaning the schema does not: it clarifies that [start, end) is the section being matched, that hero_t lies outside that section, and that method is the LUT type with mkl/reinhard options. Only strength is left undocumented in both places, so the description compensates well.

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 specific verb and resource: it matches the colour of section [start, end) to the hero frame at hero_t, producing a shot-match LUT baked to 33^3. This is well beyond a tautology and an agent can grasp the operation, though it does not explicitly contrast itself with grading siblings like set_color_grade or apply_look.

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 no when-to-use guidance, no alternatives named, and no conditions distinguishing this from the many other colour/grading tools (set_color_grade, apply_look, isolate_colour). The agent must infer the correct context entirely on its own.

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