create_effect_style

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

Annotations declare readOnlyHint=false and destructiveHint=false, consistent with a creation operation. The description adds value by specifying the return shape ({ ok, styleId, name }) and conditional requirements (shadows need color+offset, blurs need radius), which are not in the annotations. This gives the agent more context about expected behavior and side effects.

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?

Two sentences deliver the core purpose, the parameter requirements, and the return value. No filler or redundant phrasing; every sentence adds new information. Front-loaded with the action verb.

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 creation tool with no output schema, the description provides the return shape and parameter guidance, which is sufficient for basic invocation. It doesn't mention error conditions or whether the style is added to the current page or document, but 'local' implies current context. The complexity of the effects array is addressed by the shadow/blur distinction.

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 33% – only color and offset have descriptions. The tool description compensates by explaining the semantic distinction between shadow and blur parameters, which directly tells the agent when to provide color/offset vs radius. However, it doesn't explain 'spread' or the optional 'description', so some parameter semantics still rely on the schema field names.

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 opens with 'Create a local effect style' – a specific verb and resource that clearly identifies the operation. It distinguishes effect styles from other style types (paint/text/grid) via the 'effect' qualifier, and the 'local' scope differentiates from shared/team styles. The parameter note about shadows vs blurs further confirms this is specifically about effect styles.

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?

The description implies usage for creating effect styles but does not explicitly contrast with sibling tools like update_effect_style or apply_style_to_node. It says 'local effect style', which suggests use for file-local styles, but no when-not guidance is provided. There's no mention of alternatives, so the agent must infer from sibling names.

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