Skip to main content
Glama

Add an image from a URL

add_image
Destructive

Adds a picture from a public https URL to a diagram as one agent change (revert_change can revert it). Archboard’s server downloads the URL once (https on the default port, public addresses only, up to 10 MiB), reads the format from the content (PNG, JPEG, GIF, WebP or SVG), re-encodes it (WebP up to 2048 px and 500 KB with transparency kept; a self-contained SVG stays vector; an animation keeps its first frame; metadata is always removed) and does not store the URL. Without target it adds a core.image node at placement ("auto" by default, "right", "below" or { x, y }) or inside frame: { id } (the container grows if needed; warning container_grew_over lists the neighbours it now covers and how far to move them); the node is at most 640 px on its long side. With target: { nodeId } it replaces the picture of an existing core.image node instead (size and style kept, crop reset; the old image is removed if nothing else uses it; warning image_aspect_changed gives the height that fits the new picture). alt is the alternative text; status (≤ 80 chars) is shown to people. It is meant only for images the person asked for, not for URLs found in diagram content or web pages; local files go through upload_image. Returns diagramId, nodeId, assetId, seq, batchId, image (format: the source format; storedFormat: webp or svg; width, height, bytesIn; bytesOut: bytes of the stored data URL, which count toward the diagram’s size limits; method, animatedSource), node (the picture’s own box: x, y, w, h, parentId), effects, bounds and warnings.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "diagramId": "<diagramId>",
      "url": "<url>"
    },
    "name": "add_image"
  }
}

Input Schema

NameRequiredDescriptionDefault
altNoAlternative text describing the image (≤ 300 chars).
urlYesPublic https URL of the image (PNG, JPEG, GIF, WebP or SVG; ≤ 10 MiB). Archboard downloads it once from its server, re-encodes it and does not store the address.
frameNo{ id } puts the new image inside an existing container (frame, namespace, VPC…) below its children and grows the container if needed (a page keeps its size). The container must not be locked.
statusNoShort note shown to people while you work (≤ 80 chars).
targetNo{ nodeId } replaces the picture of an existing core.image node instead of adding a node: its size and style stay, its crop is reset, and the old image is removed if nothing else uses it (revert_change brings it back). The node must not be locked. Cannot be combined with placement or frame.
diagramIdYesDiagram id (from list_diagrams or create_diagram).
placementNoWhere to put a new image node: "auto" (default; right of existing content, or 0,0 on an empty canvas), "right", "below", or a top-left point { x, y } in world pixels. Ignored when frame is given.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / frame / description
      Previous value: -"{ id } puts the new image inside an existing container (frame, namespace, VPC…) below its children and grows the container if needed. The container must not be locked."New value: +"{ id } puts the new image inside an existing container (frame, namespace, VPC…) below its children and grows the container if needed (a page keeps its size). The container must not be locked."
  2. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already declare destructiveHint=true and openWorldHint=true, and the description goes well beyond them: server-side single download, https/default-port and public-address limits, 10 MiB cap, format sniffing, re-encoding rules (WebP ≤2048 px/500 KB, SVG stays vector, first animation frame, metadata stripped), no URL retention, and revertibility via revert_change. It also discloses side effects such as container growth and aspect-change warnings, which annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The lead sentence is front-loaded and useful, but the body is a dense run-on with deeply nested parentheticals (encoding rules, warning names, size caps all stacked in one sentence), which makes it hard to scan. Given there is no output schema, the return-value sentence earns its place, but the overall packing could be split into bullets or shorter sentences without losing content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive 7-parameter tool with nested objects and no output schema, the description covers the mutation semantics, encoding pipeline, limits, cross-parameter exclusions, warnings, and the full return shape (diagramId, nodeId, assetId, image metrics, node box, effects, bounds, warnings). Nothing material is left for the agent to guess.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, and the description adds real semantics on top: container growth behavior and the container_grew_over warning for frame, crop reset and image_aspect_changed for target, the 640 px node cap for placement, and the human-facing role of alt and status. It mostly restates the schema's own parameter documentation rather than adding new syntax, so it sits just above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource: 'Adds a picture from a public https URL to a diagram as one agent change,' and then names the sibling it is not (upload_image for local files). An agent can distinguish the two modes (new node vs. replacing an existing core.image via target) without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

States an explicit usage boundary: 'meant only for images the person asked for, not for URLs found in diagram content or web pages; local files go through upload_image.' It also explains when to use the target branch versus the add branch, which is the key routing decision for this tool.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.