create_shape

Place a shape on a project canvas. shape comes from six groups: basic shapes (Rectangle, Ellipse, Triangle, Diamond, ...), rectangle variants with snipped or rounded corners, regular polygons (Pentagon to Dodecagon), stars, block arrows (RightArrow, NotchedRightArrow, the DirectionArrow chevrons, ...) and misc (Plus, Donut, Heart, Plaque, Frame, ...) - get_data_model says what each one looks like and which way each arrow points. Position is the world-coordinate top-left and size the box of the shape before it is turned; angle turns it clockwise around its centre. Connector or arrow shape? connect_items draws a thin line/arrow attached to two items that follows them when they move - use it for relationships and flow edges. A block arrow shape (create_shape, e.g. RightArrow) is a standalone filled area, not attached to anything - use it between process steps, as a direction cue, callout or header, and style it like any shape (fillColor, strokeColor, a text label on top). cornerRadius is the corner radius in world units, so shapes of different sizes get the same corners: every corner of a RoundedRectangle, the top two of TwoSameSideRoundCornerRectangle, top left and bottom right of TwoDiagonalRoundCornerRectangle, the round corner of OneRoundCornerRectangle and OneSnipOneRoundCornerRectangle; other shapes reject it. It is capped at half the shorter side. A later size change scales the corners with the shape - send cornerRadius again after resizing to keep them. Colors are hex strings only - "#RRGGBB" (e.g. "#3B82F6"), or "#AARRGGBB" for alpha (alpha first). rgb()/rgba(), hsl() and named colors are rejected. New items are drawn on top of existing ones; to put one behind the rest (e.g. a backdrop) call arrange_item with position "back". Returns the new item id. To recolor it later use style_item. The result may carry warnings: [{itemId, code, message}] for text cut off by its box (TEXT_HEIGHT_TOO_SMALL), text running into other text (TEXT_OVERLAP), text that cannot be read on what is behind it (LOW_CONTRAST), text running past the shape it starts on (OUTSIDE_PARENT_SHAPE) and text a new shape hides (TEXT_COVERED). The write happened; fix what they name before reporting the work as done.

Tool name: create_shape

Parameters

Parameter	Type	Required	Default	Description
projectId	string	Yes	—	Target project (map) id.
shape	enum	Yes	—	Shape type from the supported set below. Any other value is rejected.
position	object	Yes	—	World-coordinate top-left of the shape, { x, y }.
size	object	No	{ width: 100, height: 100 }	Bounding box in world coordinates, { width, height }. When given, both are required and must be greater than 5.
angle	number	No	0	Rotation in degrees, clockwise. Values outside 0–360 are wrapped (-90 → 270).
fillColor	string	No	"#3B82F6"	Fill color, hex.
strokeColor	string	No	Theme default	Outline color, hex.
strokeThickness	number	No	2	Outline width in px. Must be ≥ 0.
parentId	string	No	Project canvas	Container id to place the shape under.
cornerRadius	number	No	The shape's own	Corner radius in world units, for the round-corner shapes only. Must be ≥ 0.

Supported Shapes

Orientations are at angle 0; angle rotates any shape clockwise around its centre, so a RightArrow at 90 points down. position is the top-left of the shape before it is turned.

Basic

Rectangle, RoundedRectangle (all corners rounded), Ellipse (a circle when width equals height), Triangle (apex at the top centre), RightTriangle (right angle at the bottom-left), Diamond, Parallelogram (leans right), Trapezoid (narrow top, wide bottom)

Rectangle variants — some corners snipped (cut off diagonally) or rounded

Shape	Corners
OneSnipCornerRectangle	top-right snipped
TwoSameSideSnipCornerRectangle	both top corners snipped
TwoDiagonalSnipCornerRectangle	top-right and bottom-left snipped
OneRoundCornerRectangle	top-right rounded
TwoSameSideRoundCornerRectangle	both top corners rounded, like a tab
TwoDiagonalRoundCornerRectangle	top-left and bottom-right rounded
OneSnipOneRoundCornerRectangle	top-left rounded, top-right snipped

Polygons — regular, named by their number of corners

Pentagon (point at the top), Hexagon (points left and right), Heptagon, Octagon, Decagon, Dodecagon

Stars

Star4, Star5, Star6

Block arrows — filled arrows that stand on their own, not attached to items

Shape	Direction at angle 0
RightArrow, LeftArrow, UpArrow, DownArrow	as named
LeftRightArrow	two heads, left and right
UpDownArrow	two heads, up and down
QuadArrow	four heads, up, down, left and right
LeftRightUpArrow	three heads, left, right and up (T-shaped)
StripedRightArrow	right, with two stripes at the tail
NotchedRightArrow	right, with a V-notch cut into the tail
DirectionArrowRight	right: flat left edge, pointed right end — first step of a chevron process chain
DirectionArrow	right: V-notched left edge, pointed right end — a middle step of a chevron chain
DirectionArrowLeft	not left: V-notched left edge, flat right edge — the last step of a chevron chain

Misc

Plus (cross with equal arms), Donut (ring), LightningBolt, Heart, Plaque (rectangle with concave corners), Frame (picture-frame border with a rectangular hole), HalfFrame (L-shaped strip along the top and left edges), Corner (L-shape along the left and bottom edges)

The same catalogue is available at runtime via get_data_model, and the names are the enum of the shape parameter.

Corner Radius

cornerRadius gives rounded corners a radius in world units, so cards of different sizes get the same corners. It applies to these shapes, and any other shape rejects it:

Shape	Corners it rounds
RoundedRectangle	all four (default: a tenth of the shorter side)
OneRoundCornerRectangle	top-right
TwoSameSideRoundCornerRectangle	both top corners
TwoDiagonalRoundCornerRectangle	top-left and bottom-right
OneSnipOneRoundCornerRectangle	top-left

The radius is capped at half the shorter side, where a RoundedRectangle becomes a pill. The shape keeps it as a proportion of its size, so a later size change scales the corners with the shape: send cornerRadius again after resizing with update_item_property. get_project reads it back with the field cornerRadius.

Block Arrow or Connector?

• A connector (connect_items) is a thin line/arrow attached to two items. It follows them when they move — use it for relationships and flow edges.
• A block arrow shape is a standalone filled area, not attached to anything — use it between process steps, as a direction cue, callout or header. Style it like any shape (fillColor, strokeColor, a text label on top).

Returns

{ "created": true, "itemId": "77gg88hh-...", "shape": "Hexagon" }

A filled shape drawn over text hides it, and the result then carries a TEXT_COVERED warning: move the shape behind with arrange_item position "back", or create shapes before the text that goes on them.

Example

"Draw a green hexagon next to the sticky note."

{
  "projectId": "a1b2c3d4-...",
  "shape": "Hexagon",
  "position": { "x": 600, "y": 150 },
  "size": { "width": 160, "height": 140 },
  "fillColor": "#22C55E"
}

To recolor the shape later, use style_item.