Add a rectangle

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

Annotations already mark destructiveHint=true and readOnlyHint=false, so the mutation intent is disclosed. The description adds a behavioral detail about the fill parameter ('Omit the fill for an empty one') but does not elaborate on other side effects, such as whether the rectangle is inserted into the current page or a specified parent, or what the return value is. It neither contradicts annotations nor adds substantial new behavioral context.

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?

The description is two sentences with zero filler. It front-loads the essential action ('Creates a rectangle'), then adds the workhorse use cases and the fill nuance. Every sentence contributes value, and it is appropriately brief for the tool's complexity.

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 tool with 8 optional parameters and no output schema, the description is too sparse. It omits key operational details like what x and y represent (coordinates, units), what the tool returns (likely a node reference), and the meaning of parameters like name and cornerRadius. The fill note is helpful but the overall context is insufficient for an agent to use the tool correctly without additional information.

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 50% (fill, width, height, parentId have descriptions), while x, y, name, and cornerRadius lack any schema description. The description only clarifies the fill parameter ('Omit the fill for an empty one'), leaving the undocumented parameters (x, y, name, cornerRadius) entirely unexplained. With half the parameters undocumented, the description fails to compensate, offering meaning for only one parameter.

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 a clear verb and resource: 'Creates a rectangle.' It adds practical context by calling it 'the workhorse shape' and enumerating typical uses (dividers, bars, backgrounds, placeholders), which helps an agent understand its primary role. It also conveys a behavioral nuance (omit fill for an empty rectangle), so the purpose is both specific and actionable.

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 common use cases for rectangles but does not explicitly contrast this tool with siblings like figma_create_ellipse or figma_create_frame. There is no 'when not to use' guidance or mention of alternatives. It states 'the workhorse shape' and typical uses, but an agent would need to infer when this is preferred over other shape creators.

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