arrange_item

Change an item's stacking order (z-order) within its container. Items are drawn in order, so a new item covers everything created before it. position: "front" (above all siblings), "back" (behind all siblings - e.g. a backdrop shape), "forward" / "backward" (one step). get_project returns each item's zIndex with fields ["zIndex"] (0 = back-most within its container). To recolor the whole canvas use update_project instead of a backdrop.

Tool name: arrange_item

Parameters

Parameter	Type	Required	Default	Description
projectId	string	Yes	—	Target project (map) id.
itemId	string	Yes	—	Id of the item to move, e.g. from get_project.
position	enum	Yes	—	"front", "back", "forward" or "backward". Any other value is rejected.

position	Moves the item
"front"	Above all its siblings — drawn last
"back"	Behind all its siblings — drawn first, e.g. a backdrop shape
"forward"	One step up
"backward"	One step down

The order is per container: an item only moves among the items with the same parent. get_project reports each item's place with the field zIndex, 0 being the back-most.

Returns

{ "updated": true, "itemId": "77gg88hh-...", "containerId": "f0e1d2c3-...", "oldIndex": 5, "newIndex": 0 }

When the item is already where position would move it, nothing is changed:

{
  "updated": false,
  "itemId": "77gg88hh-...",
  "containerId": "f0e1d2c3-...",
  "zIndex": 0,
  "reason": "The item is already back-most in its container."
}

When the project holds no such item, the tool returns an error whose message starts with NOT_FOUND:.

Example

"Put the big grey box behind the cards."

{
  "projectId": "a1b2c3d4-...",
  "itemId": "77gg88hh-...",
  "position": "back"
}

New items are drawn on top of existing ones, so a backdrop created after its content covers it until it is sent to the back. To recolor the whole board, change the canvas background with update_project instead of placing a backdrop.