figma_apply_shader

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

With no annotations, this description carries the full burden and does well: it discloses that unknown property names change nothing and return the valid names, that replace:true discards the existing list, and that Desktop Bridge is required. It omits what the call returns on success and any limits on shader counts, keeping it just short of full disclosure 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 core action, then progressively refined into property syntax, index/replace behavior, target mapping, and failure behavior. Dense with parenthetical clauses, but essentially every sentence adds operative information.

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 10-parameter, nested-object mutation tool with no annotations and no output schema, the description covers the risky parts: destructive replace, index-based mutation, valid property discovery, variable binding, and the Desktop Bridge prerequisite. Only the success response shape and the interaction with Cloud vs Local Mode (documented only in the fileKey schema) are left unaddressed.

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?

At 70% schema coverage, the description adds real meaning beyond the schema: the properties object is by name with a concrete example ({turbulence: 40, cloudColor: '#E8F4FF'}), colors accept hex strings or {r,g,b,a}, and any property can bind a variable via {variableId}. Index, replace and target semantics are restated compactly, though opacity/blendMode constraints merely echo what the schema already says.

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?

States a specific verb and resource: apply a shader to a node's fills, strokes or effects, or mutate properties of an already-applied shader. The scope is precise enough to distinguish it from siblings like figma_set_fills or figma_list_shaders, which is named as the source of property metadata.

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?

Gives clear routing rules: pass index to modify an existing shader, omit it to add on top, or use replace:true to swap the whole list; fill shaders go on fills/strokes, effect shaders on effects. It also points at figma_list_shaders for names/types/defaults and notes the Desktop Bridge requirement. It stops short of naming an alternative for non-shader fill/stroke work (e.g. figma_set_fills), so exclusions are implied rather than stated.

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