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

With annotations present, the description still adds real behavioral context beyond them: it declares the call is PROJECT-SCOPED, acts only on the explicit project_id (never the active-project pointer), and returns the project identity with its result. It also explains attach semantics ('rides it on the world') and clarifies that light composites as light. It does not discuss reversibility or failure modes, but the annotation-covered mutation profile plus this added scope/return detail is solid.

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 PROJECT-SCOPED constraint is correctly front-loaded, and the dense kind catalogue is reasonably compact for 19 parameters. But the body is a semicolon-chained run-on laden with project-specific jargon ('one family verb', 'embers off its edge'), which makes it harder to parse than its length warrants.

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 19-parameter mutation tool with no output schema and near-zero schema descriptions, the definition covers scope, return identity, the kind taxonomy, key modifier semantics, and exclusions. It still omits units/defaults for timing parameters and the meaning of several secondary parameters, so it is close to but not fully sufficient on its own.

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 only 5% (1 of 19 params documented), so the description must compensate and largely does: it explains emit targets (edge|point|box|frame), 'at = burst times', 'box = from x0,y0 to x1,y1' for lightning, and attach values ('head', 'hand.index_tip', 'track:tr1', or natural-language phrases). Several parameters (start, end, count, intensity, colour, palette, style, text, images, id) remain unexplained and units for start/end are unstated, so it is strong but not complete.

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 states the tool adds a 'procedural element or a light device' and enumerates the concrete kind families (light effects, particle emitters, doodles, lightning, orbit, shapes, pictogram, sprites), so an agent can tell what gets created. It also separates itself from siblings by declaring it adds no sound and no zoom. The opening phrase 'one family verb' is cryptic, but the resource and scope are otherwise clear.

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 usable selection context by describing what each kind does (e.g. 'light_dissolve (the figure turns to light)', 'lightning (box = from x0,y0 to x1,y1; at = strikes)') and an implicit exclusion ('nothing here adds a sound or a zoom'), which routes agents away from add_sfx/add_zoom. However it never names an alternative tool or states a when-to-use/when-not condition explicitly, leaving the agent to infer.

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