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

Annotations already declare idempotentHint=true and destructiveHint=false. The description goes beyond by explaining the project-scoped nature, the clearing semantics, the delta-vs-multiplier behavior, and the fact that captions/graphics are untouched. It also warns about the 0.06 misinterpretation. This adds significant behavioral context beyond the 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?

Despite being long, the description is dense and well-structured. It front-loads the project-scoped caveat, then explains composition, then parameter ranges, then usage warnings, then clearing behavior, then exclusions. Every sentence adds critical value; there is no fluff. The structure makes it easy for an agent to parse the most important constraints first.

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?

With 8 parameters, no output schema, and no enum values, the description carries the full burden. It covers all parameter semantics, common use cases, warnings, and edge cases (clearing behavior). It even hints at the return value ('returns the project identity with its result'). For a tool of this complexity, the description is complete and self-sufficient.

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 13% (only project_id has a description), so the description must compensate. It does so thoroughly: it defines exposure range (-1..1), contrast/saturation as either delta or multiplier with specific limits, temperature/tint ranges, and shadows/highlights meanings (positive shadows lifts dark regions, negative highlights recovers bright areas). It also explains the 0.06 misinterpretation. This fully compensates for the schema's lack of descriptions.

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 clearly states the tool's purpose: 'Continuous color controls on all footage, applied AFTER the preset grade.' It specifies the resource (footage) and the verb (set custom grade), and differentiates itself by mentioning composition with a preset grade. It also explicitly excludes captions and graphics, making the scope unambiguous.

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 description provides extensive usage guidance: it explains how controls compose with presets, gives the monochrome alternative ('Use the explicit 'bw' preset'), warns against a common mistake ('Never pass 0.06 intending 6% color'), and maps natural language to parameters ('More light' = exposure up). It also tells the agent to pass only axes to change and clarifies clearing behavior. This exceeds the typical guidance level.

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