Skip to content
Toado Docs

Annotations

Annotations are vector overlays drawn on top of a captured screenshot. They are stored as structured shapes and rendered as a separate layer, so the underlying screenshot is preserved.

Tools recap

The annotation toolbar is the same surface as in the extension annotation toolbar. Quick recap:

  • Pan, pen, highlighter, circle, arrow, text.
  • A small preset color palette.
  • Redact (opaque) and blur (translucent), eraser for individual shapes.
  • Undo and redo.

For the full keyboard reference, see the annotation toolbar shortcuts.

Two layers, one image

When you draw on a screenshot, Toado:

  1. Adds a shape to the structured annotation array ({type, color, points} for a stroke, {type, color, x, y, w, h} for a circle, etc.).
  2. Renders the shape on top of the screenshot in the canvas.
  3. On save, the rendered annotated PNG is generated server-side and stored alongside the raw screenshot.

So every annotated ticket has two image assets:

  • screenshot: the raw original.
  • screenshot_with_annotations: the rasterized annotated version.

Both are reachable in the UI (the annotated version is what you see) and via the MCP tools.

Why structured shapes

For an AI agent reading the ticket, the annotated PNG is a flattened image: it can see where the user drew, but it has to do vision work to understand it. The structured shape array gives it semantics for free:

[
  {
    "type": "circle",
    "color": "#EF4444",
    "x": 412,
    "y": 198,
    "width": 140,
    "height": 80
  },
  {
    "type": "text",
    "color": "#EF4444",
    "x": 420,
    "y": 290,
    "text": "this overflow"
  }
]

That is much easier to reason about than “image with red pixels in the upper-middle area”.

For agents, prefer get_annotations over rasterizing the annotated image when the question is “what did the user point at?” Use get_capture_asset(asset='screenshot_with_annotations') when you want a single image to look at.

Coordinates

Coordinates are in image-natural pixel space (the size of the captured screenshot, before any UI scaling). For a 1920 x 1080 capture, a circle at (960, 540) is dead center.

If you need normalized coordinates (0 to 1), divide by the screenshot dimensions, which are also in the ticket payload.

Permissions

Anyone who can read the ticket can read the annotations. Anyone who can edit the ticket can add or remove annotations. There is no per-annotation permission in v1.

Editing other people’s annotations

By default, members can edit any annotation on tickets they can edit. There is no per-annotation author lock. If a teammate annotates a ticket and you draw over it, you can clear theirs (and they yours).

If you need annotation history, comment on the ticket with what you changed and why. Comments are append-only and provide the audit trail that annotations themselves do not.

Keyboard

ToolShortcut
Pan V (or hold Space to pan temporarily)
Pen P
Highlighter H
Circle C
Arrow A
Text T
Redact R
Blur B
Eraser E
Undo Cmd + Z
Redo Cmd + Shift + Z

Where to next