generate_palette

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

With no annotations, the description carries the full behavioral burden. It helpfully explains the palette algorithm (light steps mix toward white, dark steps toward black) and names the optional side effects, but it omits whether the tool overwrites existing assets, what context it needs (e.g., current page, target node), and what it returns.

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 sentences, front-loaded with the core action and followed by behavior and optional modes. Every sentence adds actionable information without repetition or filler.

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 an 11-parameter tool with no annotations and no output schema, the description is not complete enough. It does well on the overall behavior but omits explanations for over half the parameters and provides no operational context such as Figma environment requirements or expected return value.

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 0% for 11 parameters. The description gives meaning to only a subset: hex (seed), steps (default 10), createStyles, createVariables, createFrame. It leaves gap, name, prefix, swatchWidth, swatchHeight, and parentNodeId completely undocumented in both schema and prose.

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 a specific verb and resource ('Generate a tonal 50..900 palette') with a clear input ('from a seed hex color') and scope (default 10 steps). It also names the optional artifacts it can produce, making the tool easily distinguishable from siblings like create_paint_style or create_variable, which each handle single artifacts.

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?

There is no explicit when-to-use guidance, no alternatives suggested, and no prerequisites mentioned. The optional flags imply modes of use, but the description never tells the agent when to set createStyles, createVariables, or createFrame versus calling other tools, nor whether the tool requires a Figma selection or existing collection.

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