Skip to main content
Glama

Upload Image

upload_image

Save one image in a Brand Library from either a public URL or a completed temporary upload.

The server validates the image, then reuses an exact match in the brand or stores a new one. If your client can read the local file and make HTTP requests, first call create_upload_urls, PUT the raw bytes as directed, and pass the resulting upload_id here. In an MCP Apps client, call open_upload_ui with only brand_session_id instead; its widget completes the Library upload and returns final image IDs in widget context. Read that context before using the images.

Pass exactly one of image_url or upload_id.

Args:

  • image_url: Public URL of the image to save.

  • upload_id: Completed temporary upload containing the image to save.

  • brand_session_id: Brand session ID that owns the Library image.

Returns the final image ID for generation references, edit references, edit subjects, or a Brand Skill primary-logo update.

Supported formats: PNG, JPEG, WebP, AVIF. Max file size: 10MB.

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

Input Schema

NameRequiredDescriptionDefault
image_urlNoPublic URL of the image to save in the Brand Library. The file must be PNG, JPEG, WebP, or AVIF and no larger than 10MB. Supply this URL or upload_id, but not both.
llm_modelNoThe model identifier you are running as, for example "claude-opus-4-8" or "gpt-5.2". Omit it or pass "unknown" if you are not certain; the tool runs the same either way. Recorded only for the server developer's analytics.
upload_idNoCompleted temporary upload containing the image to save in this Brand Library. Obtain its ID from create_upload_urls or get_file_picker_handoff, and supply it instead of image_url.
brand_session_idYesBrand session ID of the brand that owns this image.

Output Schema

NameRequiredDescriptionDefault
idYesImage ID of the saved Library image.
widthYesWidth in pixels.
heightYesHeight in pixels.
existingYesTrue when the brand already held this exact image and it was reused.
mime_typeYesMIME type of the stored image.

Schema Changelog

Changes observed during successful MCP inspections.

  1. 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 a non-read-only, non-destructive, non-idempotent, open-world write. Beyond that, the description discloses genuinely non-obvious behavior: the server validates the image and reuses an exact match rather than always creating a new asset, and it returns the final image ID. It stops short of stating auth/scoping requirements or quota effects for a write that touches a shared Brand Library.

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 the core action and the two ingestion paths, then constraints, then return value and format limits. The Args block and the format/size sentence restate schema content that is already documented field-by-field, so some lines do not fully earn their space.

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 four-parameter write with an output schema, the description covers the decision path between siblings, the either/or parameter rule, the dedup-vs-store behavior, and the client-context caveat about reading widget output before using image IDs. Nothing an agent needs to invoke it correctly is missing.

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 baseline would be 3, but the description adds the mutual-exclusivity rule between image_url and upload_id that the schema's required list (brand_session_id only) does not express. Format and 10MB limits are repeated from the schema rather than adding new meaning, which keeps this just below the top score.

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 specific verb and resource: "Save one image in a Brand Library" and names both accepted sources (public URL or completed temporary upload). It distinguishes itself from the nearby upload/picker siblings by explicitly routing to create_upload_urls and open_upload_ui rather than doing their job.

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 when-to-use branches: direct HTTP-capable clients call create_upload_urls then pass upload_id; MCP Apps clients call open_upload_ui with only brand_session_id and read the widget context. It also states the hard constraint "Pass exactly one of image_url or upload_id," which prevents the most likely misuse.

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.

Resources