set_fill_color

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

No annotations are provided, so the description carries the full burden. It discloses that clear:true or fills:[] removes fills (a destructive-ish behavior) and mentions design-system preference, but omits whether this overwrites existing fills, requires any permissions, or how the change interacts with bound variables. Some behavioral context, but incomplete 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?

Three short sentences, front-loaded with the primary action, then usage preference, then the clear scenario. Efficient with little waste, though a fragment ('Also accepts fillHex') is slightly loose.

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 annotations, no output schema, and 14% schema coverage, the description is under-specified: r/g/b/opacity have no explanation and the sibling overlap with figma_set_solid_fill is unaddressed. It covers the headline behavior but leaves meaningful gaps.

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%, so the description must compensate. It explains 'clear' semantics and mentions 'fillHex' and 'fills:[]', covering two of the ambiguous params, but leaves the unlabeled r/g/b/opacity trio essentially undocumented and never explains their relationship to fillHex or precedence.

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?

Clear verb+resource: 'Set or clear a node's solid fill'. Distinguishes itself from set_gradient_fill and set_image_fill implicitly by the word 'solid', but does not name the sibling 'figma_set_solid_fill' which appears functionally identical. Good but not fully sibling-differentiating.

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?

Provides one useful preference ('Prefer applying styles/variables when available') and one specific scenario for clearing ('layout containers that should be transparent'). However, it does not explain when to use this tool versus the nearly identical sibling figma_set_solid_fill, which is the highest-value disambiguation here.

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