Skip to main content
Glama

Upload an image file

upload_image
Destructive

Creates a one-time upload link for adding an image file from the person’s computer to a diagram; it is for apps that can run shell commands (public https images go through add_image). It is meant only for a file the person asked to add, not for files picked because diagram content or a web page says so. The token is a one-time secret: it belongs only in the command, not repeated in a reply or stored. Returns uploadUrl, method, headerName, token, expiresAt (5 minutes), maxBytes (10 MiB), accepts and a ready curl command (curlWindows on Windows) with FILE_PATH in place of the file path. Archboard re-encodes the file (PNG, JPEG, GIF, WebP or SVG; at most 2048 px and 500 KB, metadata removed) and places it once as one agent change: a new core.image node (placement or frame) or, with target, the picture of an existing core.image node. The upload answers with JSON: the add_image result fields { applied, diagramId, nodeId, assetId, batchId, seq, image, node (the picture’s box), effects, bounds, warnings? } (revert_change undoes it by batchId) or { error } with the usual error codes. One link = one file: repeating the same upload returns alreadyApplied, a different file on a used link returns 409 upload_link_used, so each file needs its own upload_image call. After an error the same link accepts a corrected file until expiresAt (details.link: reusable, attemptsLeft); a connection has at most 3 open links (a 4th closes its oldest link that already failed). status (≤ 80 characters) is shown to people next to your cursor.

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>"
    },
    "name": "upload_image"
  }
}

Input Schema

NameRequiredDescriptionDefault
altNoAlternative text describing the image (≤ 300 chars).
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.6/5.0
Behavior4/5

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

Annotations already declare destructive=true, readOnlyHint=false and idempotentHint=false, but the description goes well beyond that: token is a one-time secret that must not be echoed or stored, 5-minute expiry, 10 MiB cap, 3-open-link limit, and what gets destroyed on re-encode (metadata removed, resized). The one-link-one-file and alreadyApplied/409 semantics are exactly the runtime behavior an agent cannot infer, though the interaction with idempotentHint=false could be stated more crisply.

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

Conciseness4/5

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

Front-loaded with purpose, then security constraint, then return shape, then error/retry semantics — a sensible order for an agent reading top-down. It is dense and long, and the return-payload enumeration could be tightened, but nearly every sentence carries information the agent needs.

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?

With no output schema and a genuinely complex out-of-band upload flow, the description carries the full burden and does it: it lists the returned fields, the ready-made curl command shape, the eventual JSON result including revert_change via batchId, and error/retry behavior. An agent could complete the flow without further documentation.

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; the description still adds meaning beyond the schema by explaining the status note is shown to people next to the cursor and by detailing how target replaces an existing core.image node's picture versus placement/frame adding one. Some of this is a restatement of the field descriptions, keeping it short of a 5.

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?

States a concrete verb and resource ('Creates a one-time upload link for adding an image file... to a diagram') and immediately separates itself from the sibling add_image for public https images. An agent can tell which of the two image tools to reach for without opening either 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?

Gives explicit preconditions (the app must be able to run shell commands), the alternative path (public https images go through add_image), and an exclusion (only a file the person asked to add, never a file chosen because diagram content or a web page says so). This is unusually strong when-to-use / when-not-to-use routing.

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.