> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asquareportal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Portal Agent canvas tools: complete reference

> A full reference for the 40+ canvas tools Portal Agent uses to create, edit, move, connect, and organize elements across all three workspace modes.

Portal Agent executes actions on your canvas by calling named tools — each with a defined purpose and set of parameters. When you send a prompt, the agent chooses which tools to call, in what order, and with what arguments. Understanding the available tools helps you write more precise prompts and predict what the agent will do.

## Brainstorming canvas tools

These tools operate on the infinite brainstorming canvas. They are available whenever you are in Brainstorming mode.

<AccordionGroup>
  <Accordion title="create_brainstorm_card">
    Creates a new card on the brainstorming canvas. The agent positions cards intelligently by default — you do not need to specify coordinates.

    | Parameter         | Type   | Required | Description                          |
    | ----------------- | ------ | -------- | ------------------------------------ |
    | `content`         | string | Yes      | Text content for the card            |
    | `width`           | number | No       | Card width in pixels (default: 200)  |
    | `height`          | number | No       | Card height in pixels (default: 150) |
    | `type`            | string | No       | `text`, `image`, or `ai-generated`   |
    | `backgroundColor` | string | No       | Card color as a hex value            |

    **Example prompt:** `Create five cards with the core pillars of UX design`
  </Accordion>

  <Accordion title="create_content_card">
    Creates a card and immediately populates it with meaningful content on a given topic. Use this when you want the agent to generate the card text itself rather than providing it explicitly.

    | Parameter         | Type   | Required | Description                                                    |
    | ----------------- | ------ | -------- | -------------------------------------------------------------- |
    | `topic`           | string | Yes      | Subject for the card (e.g., "climate change", "SWOT analysis") |
    | `content`         | string | Yes      | The detailed content to populate the card with                 |
    | `title`           | string | No       | Optional title; generated from `topic` if omitted              |
    | `backgroundColor` | string | No       | Card color as a hex value                                      |

    **Example prompt:** `Add a card about the benefits of async communication for remote teams`
  </Accordion>

  <Accordion title="edit_brainstorm_card">
    Edits the text content of an existing card by its ID.

    | Parameter | Type   | Required | Description            |
    | --------- | ------ | -------- | ---------------------- |
    | `cardId`  | string | Yes      | ID of the card to edit |
    | `content` | string | Yes      | New text content       |

    **Example prompt:** `Update the blue card to say "Q3 2025 targets"`
  </Accordion>

  <Accordion title="move_brainstorm_card">
    Moves a card to an explicit canvas position.

    | Parameter | Type   | Required | Description                        |
    | --------- | ------ | -------- | ---------------------------------- |
    | `cardId`  | string | Yes      | ID of the card to move             |
    | `x`       | number | Yes      | Target X coordinate in world space |
    | `y`       | number | Yes      | Target Y coordinate in world space |

    **Example prompt:** `Rearrange the cards so the "Research" card is at the top`
  </Accordion>

  <Accordion title="place_card">
    Positions a card relative to another card using spatial relationships like "below", "to the right of", or "centered above". Prefer this over `move_brainstorm_card` when you want to express layout intent in natural language.

    | Parameter         | Type   | Required | Description                                    |
    | ----------------- | ------ | -------- | ---------------------------------------------- |
    | `cardId`          | string | Yes      | ID of the card to position                     |
    | `referenceCardId` | string | Yes      | ID of the card to position relative to         |
    | `side`            | string | Yes      | `top`, `bottom`, `left`, or `right`            |
    | `align`           | string | Yes      | `start`, `center`, or `end`                    |
    | `sideOffset`      | number | No       | Distance from the reference card (default: 10) |
    | `alignOffset`     | number | No       | Offset along the alignment axis (default: 0)   |
    | `intent`          | string | Yes      | Human-readable positioning description         |

    **Example prompt:** `Place the "Execution" card directly below the "Strategy" card`
  </Accordion>

  <Accordion title="create_connection">
    Draws a line or arrow connector between two cards. You can identify cards by their ID or by a description like "the red card" or "the first card".

    | Parameter         | Type   | Required | Description                                       |
    | ----------------- | ------ | -------- | ------------------------------------------------- |
    | `fromCardId`      | string | No       | Source card ID (if known)                         |
    | `toCardId`        | string | No       | Target card ID (if known)                         |
    | `fromDescription` | string | No       | Description of the source card (e.g., "red card") |
    | `toDescription`   | string | No       | Description of the target card                    |
    | `type`            | string | No       | `line` or `arrow` (default: `arrow`)              |
    | `color`           | string | No       | Connector color as a hex value                    |
    | `strokeWidth`     | number | No       | Line thickness (default: 2)                       |

    **Example prompt:** `Connect the "Problem" card to the "Solution" card with an arrow`
  </Accordion>

  <Accordion title="modify_connection">
    Updates or removes an existing connector between cards.

    | Parameter      | Type   | Required | Description                            |
    | -------------- | ------ | -------- | -------------------------------------- |
    | `connectionId` | string | Yes      | ID of the connection to modify         |
    | `action`       | string | Yes      | `update` or `remove`                   |
    | `type`         | string | No       | New connector type (`line` or `arrow`) |
    | `color`        | string | No       | New connector color                    |
    | `strokeWidth`  | number | No       | New line thickness                     |

    **Example prompt:** `Remove all connectors between the idea cards`
  </Accordion>

  <Accordion title="create_template">
    Generates a structured layout template on the canvas from a central topic and list of subtopics.

    | Parameter         | Type    | Required | Description                                        |
    | ----------------- | ------- | -------- | -------------------------------------------------- |
    | `templateType`    | string  | Yes      | `mindmap`, `wordweb`, or `flowchart`               |
    | `centralTopic`    | string  | Yes      | The root topic of the template                     |
    | `subtopics`       | array   | Yes      | 2–8 branch topics as strings                       |
    | `useAIGeneration` | boolean | No       | Let AI expand the template with additional content |

    **Example prompt:** `Create a mind map for a product launch with subtopics for marketing, design, engineering, and sales`
  </Accordion>

  <Accordion title="create_section">
    Creates a named container area on the canvas with an internal layout for organizing cards placed inside it.

    | Parameter     | Type   | Required | Description                                      |
    | ------------- | ------ | -------- | ------------------------------------------------ |
    | `name`        | string | No       | Section label shown in the section tab           |
    | `x`           | number | No       | World-space center X position                    |
    | `y`           | number | No       | World-space center Y position                    |
    | `width`       | number | No       | Section width (default: 1200)                    |
    | `height`      | number | No       | Section height (default: 800)                    |
    | `layoutType`  | string | No       | `row`, `column`, `waterfall`, `grid`, or `bento` |
    | `strokeColor` | string | No       | Section border color                             |

    **Example prompt:** `Create a "Research" section and a "Concepts" section side by side`
  </Accordion>
</AccordionGroup>

## Shape and drawing tools

<AccordionGroup>
  <Accordion title="create_shape">
    Creates a single geometric shape at an auto-positioned or specified location. For complex objects (vehicles, figures, buildings), call this multiple times or use `create_smart_shape` instead.

    | Parameter  | Type   | Required | Description                                                     |
    | ---------- | ------ | -------- | --------------------------------------------------------------- |
    | `intent`   | string | No       | Human-readable description of what the shape represents         |
    | `type`     | string | No       | `circle`, `rectangle`, `triangle`, `square`, `star`, or `heart` |
    | `x`        | number | No       | X position (omit for auto-positioning)                          |
    | `y`        | number | No       | Y position (omit for auto-positioning)                          |
    | `size`     | number | No       | Shape size in pixels                                            |
    | `fill`     | string | No       | Fill color as a hex value                                       |
    | `width`    | number | No       | Width override (useful for rectangles)                          |
    | `height`   | number | No       | Height override                                                 |
    | `rotation` | number | No       | Rotation in degrees, around the center                          |

    **Example prompt:** `Draw a large red circle in the center of the canvas`
  </Accordion>

  <Accordion title="create_smart_shape">
    Creates a multi-component object by decomposing it into properly proportioned shapes — useful for recognizable objects like animals, vehicles, or buildings.

    | Parameter        | Type   | Required | Description                                             |
    | ---------------- | ------ | -------- | ------------------------------------------------------- |
    | `object`         | string | Yes      | What to create (e.g., "dog", "spaceship", "coffee cup") |
    | `sizeMultiplier` | number | No       | Scale the whole object up or down (default: 1.0)        |

    **Example prompt:** `Draw a simple cat on the canvas`
  </Accordion>

  <Accordion title="create_compound_object">
    Creates multiple shapes in a single call to form a complex object. More reliable than sequential `create_shape` calls when building multi-part objects.

    | Parameter    | Type   | Required | Description                                                                                        |
    | ------------ | ------ | -------- | -------------------------------------------------------------------------------------------------- |
    | `objectType` | string | Yes      | Type of object (e.g., "house", "car", "robot")                                                     |
    | `shapes`     | array  | Yes      | Array of shape definitions with `type`, `intent`, `color`, `size`, and optional `relativePosition` |

    **Example prompt:** `Build a simple house from shapes`
  </Accordion>

  <Accordion title="resize_shape">
    Resizes or rotates an existing shape by ID.

    | Parameter  | Type   | Required | Description                            |
    | ---------- | ------ | -------- | -------------------------------------- |
    | `shapeId`  | string | Yes      | ID of the shape to resize              |
    | `width`    | number | No       | New width in pixels                    |
    | `height`   | number | No       | New height in pixels                   |
    | `scale`    | number | No       | Uniform scale factor (1.0 = no change) |
    | `scaleX`   | number | No       | Horizontal scale factor                |
    | `scaleY`   | number | No       | Vertical scale factor                  |
    | `rotation` | number | No       | New rotation in degrees                |

    **Example prompt:** `Make the circle twice as large`
  </Accordion>

  <Accordion title="create_sketch_path">
    Renders a freehand sketch as a series of connected points.

    | Parameter     | Type   | Required | Description                          |
    | ------------- | ------ | -------- | ------------------------------------ |
    | `points`      | array  | Yes      | Array of `{x, y}` coordinate objects |
    | `color`       | string | No       | Stroke color (default: `#000000`)    |
    | `strokeWidth` | number | No       | Line thickness (default: 3)          |

    **Example prompt:** `Sketch a rough arrow pointing right`
  </Accordion>

  <Accordion title="create_text_element">
    Adds a floating text label at an explicit position on the canvas.

    | Parameter  | Type   | Required | Description                       |
    | ---------- | ------ | -------- | --------------------------------- |
    | `text`     | string | Yes      | Text content                      |
    | `x`        | number | Yes      | X position in world space         |
    | `y`        | number | Yes      | Y position in world space         |
    | `fontSize` | number | No       | Font size in pixels (default: 16) |
    | `color`    | string | No       | Text color (default: `#000000`)   |

    **Example prompt:** `Add a heading "User Journey" at the top of the canvas`
  </Accordion>
</AccordionGroup>

## Workflow and utility tools

<AccordionGroup>
  <Accordion title="run_workflow">
    Executes a high-level creative workflow that plans and places a cohesive set of cards on the canvas using a deterministic layout strategy.

    | Parameter        | Type   | Required | Description                                                  |
    | ---------------- | ------ | -------- | ------------------------------------------------------------ |
    | `prompt`         | string | Yes      | High-level intent describing the topic and goals             |
    | `layoutStrategy` | string | No       | `bento`, `waterfall`, `grid`, or `radial` (default: `bento`) |
    | `workflowMode`   | string | No       | `research_board` or `moodboard_radial`                       |
    | `bentoVariant`   | string | No       | Bento composition pattern (default: `auto`)                  |
    | `maxObjects`     | number | No       | Maximum number of objects to create (4–20, default: 10)      |

    **Example prompt:** `Build a complete research board on climate change solutions`
  </Accordion>

  <Accordion title="take_screenshot">
    Takes a screenshot of the current canvas for the agent to visually analyze — useful before creating new content so the agent understands the existing layout.

    | Parameter          | Type   | Required | Description                                                                  |
    | ------------------ | ------ | -------- | ---------------------------------------------------------------------------- |
    | `analysis_purpose` | string | No       | `layout_analysis`, `content_placement`, `visual_context`, or `quality_check` |

    **Example prompt:** `Look at what's on the canvas and suggest how to improve the layout`
  </Accordion>

  <Accordion title="get_canvas_info">
    Reads the current canvas state — all cards, their positions, sizes, and IDs — without taking a screenshot.

    | Parameter | Type   | Required | Description                  |
    | --------- | ------ | -------- | ---------------------------- |
    | `intent`  | string | No       | Why you need the canvas info |

    **Example prompt:** `List all the cards currently on the canvas`
  </Accordion>

  <Accordion title="switch_canvas_mode">
    Switches the workspace to a different mode.

    | Parameter | Type   | Required | Description                             |
    | --------- | ------ | -------- | --------------------------------------- |
    | `mode`    | string | Yes      | `brainstorming`, `design`, or `compose` |

    **Example prompt:** `Switch to Compose mode and build a landing page`
  </Accordion>

  <Accordion title="export_canvas">
    Exports the current canvas content to a file.

    | Parameter           | Type    | Required | Description                                            |
    | ------------------- | ------- | -------- | ------------------------------------------------------ |
    | `format`            | string  | No       | `png`, `jpg`, `svg`, `pdf`, or `json` (default: `png`) |
    | `includeBackground` | boolean | No       | Include the canvas background (default: true)          |

    **Example prompt:** `Export the canvas as a PNG`
  </Accordion>
</AccordionGroup>

## Example prompts that combine tools

```text theme={null}
Create a mind map for a mobile app startup, then connect all branches back to the central idea
```

```text theme={null}
Add three cards for "Discovery", "Design", and "Launch", then draw arrows between them in sequence
```

```text theme={null}
Read the canvas, then reorganize all the cards into a grid layout with sections
```

```text theme={null}
Draw a simple robot using shapes, then add a label below it
```

<Tip>
  You don't need to name tools in your prompt. The agent selects the right tools automatically based on what you describe. Naming tools explicitly (e.g., "use create\_brainstorm\_card") is only necessary when you need to override the agent's default behavior.
</Tip>