match_style

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

Annotations establish a non-readonly, non-destructive, non-idempotent mutation; on top of that the description discloses the pipeline stages that will be altered and states the return payload (steps plus a report with similarity, confidence and limitations), which correctly signals that results may be approximate. It stops short of saying how changes interact with project history or whether the fitted grade is reversible.

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?

Four tight sentences in a deliberate order — what it builds, mode semantics, strength default, then return values. No filler, and the core operation is front-loaded before the mode detail.

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 9-parameter mutating tool with no output schema, the description covers the conceptual model and returns but omits the apply-vs-dry-run behavior, what 'parametric+lut' mode changes, the meaning of preserve_skin, and the accepted form of the reference parameter. Adequate to start, not sufficient to call confidently without reading 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 0%, so the description must carry the burden, and it only partly does: matching and strength are explained well, and the stage list hints at include_grain/include_vignette. The mode enum (parametric vs parametric+lut), apply, preserve_skin, project_id and reference are left entirely to bare schema titles.

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?

It states a specific verb and resource — 'fit an editable grading pipeline' — and enumerates the pipeline stages it builds (white balance, tone curve, 3-way grade, saturation, HSL, grain, vignette), so the agent knows exactly what is produced. It never names a sibling, so the boundary with analyze_style or apply_preset has to be inferred.

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 explicit selection guidance for the matching parameter, explaining that 'look' transfers the grade without copying scene content while 'exact' targets the same-scene case, and it explains what strength=null does. It does not say when to prefer this tool over analyze_style (analysis only) or apply_preset, which is a real gap given how many style-related siblings exist.

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