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

Annotations already declare idempotent, non-destructive, and closed-world; the description adds genuinely useful context beyond them — that it is project-scoped, that it returns the project identity, and that mode='none' acts as a partial undo over a range. It does not state defaults when blur/dim/mode are omitted, nor what happens if at and start/end are supplied together.

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 scoping constraint is front-loaded, and the long sentence about bars is dense but earns its length by covering both bar origins. The telegraphic fragments ('blur: 0.01-0.2 of the frame. dim: 0-0.9.') are efficient but read as notes rather than prose; some of that repeats the schema bounds.

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 7-parameter mutation tool with no output schema and near-zero schema description coverage, the definition covers nearly every parameter, the targeting model, and the return value. The remaining gaps — default values and conflict resolution between at and start/end — are minor but real for a tool that operates on ranges.

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 14% (project_id only), so the description must carry the load and largely does: it defines at as one picture, start/end as program seconds, blur as a fraction of the frame, and mode='none' as removal. The numeric bounds for blur and dim are duplicated from the schema rather than extended, and dim's unit (opacity of the blurred layer) is left implicit.

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 names a specific effect (blurred fill for every picture that has bars) and explains the two ways bars arise (baked into the upload vs. created by the frame), which is far beyond restating 'Set photo fill'. It does not explicitly distinguish itself from near siblings like set_background, set_frame, or add_blur, so an agent must infer the boundary.

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?

Scope guidance is explicit: the whole film by default, a start/end program-seconds range, or a single picture via at, and mode='none' removes the effect for the whole film or a range. It also states that pictures with no bars are left untouched, which prevents needless calls. It stops short of naming alternatives (e.g., set_background) when a different fill is wanted.

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