set_effects

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

With no annotations, the description carries the full burden and does a good job: it discloses the bridge's hidden normalization ("fills those in and strips any key the effect variant does not declare"), the shader-import prerequisite, and variable binding. It never states whether existing effects are replaced or appended, which is the key behavioral fact for a mutation tool.

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?

Front-loaded with the one-line purpose, then dense reference material; virtually every clause carries actionable detail. It is a wall of semicolon-separated fields in a single paragraph, which is harder to scan than a small bulleted structure would be, but little text is wasted.

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 complex, unannotated mutation tool with no output schema, the description covers payload shapes, engine requirements, key-stripping behavior, and a shader alternative. The main omissions are replace-vs-append semantics and how the target node is identified, given the empty input 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?

The input schema is an empty object that documents nothing, so the description is the sole source of parameter meaning, and it delivers: effectStyleId vs effects, per-type field shapes, enum values, required fields, and boundVariables.color. This more than compensates for the vacuous schema.

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?

"Set effects on a node" is a specific verb+resource and the description goes further by enumerating every supported effect type and payload shape. It distinguishes itself from apply_shader with an explicit routing note, but never mentions the very close sibling apply_effect_style, which overlaps its effectStyleId path.

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 clear selection logic ("Pass effectStyleId to apply an existing style, or effects as a raw array"), an explicit alternative ("Prefer apply_shader for shaders"), and a strong exclusion ("never echo back an effect read off another node"). It omits any guidance relative to apply_effect_style, which appears to do the same thing as the effectStyleId path.

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