Skip to main content
Glama

Upload local files

open_upload_ui
Read-onlyIdempotent

Open the shared upload picker in an MCP Apps client. Pass exactly one destination: brand_session_id to save images directly to an existing Brand Library, or workspace_id to stage files for another tool. Use workspace_id: null for the personal workspace.

With brand_session_id, the widget uploads and saves up to 10 PNG, JPEG, WebP, or AVIF images per batch, up to 10 MiB each. Read the widget's model context to collect the final Library image IDs before using them in another tool. There is no Continue step.

With workspace_id, the widget stages local files, including before a Brand exists. It accepts up to 30 files, 100 MiB per file, and 256 MiB combined. Temporary uploads expire after two hours, and the consuming tool may have stricter file requirements.

Wait for the user to choose Continue and send an upload reference. Resolve that reference with get_file_picker_handoff. Use its verified upload IDs with tools that accept them in the returned workspace; use each file's temporary url where a generation model input expects a file URL. The reference itself is not an upload ID. Partial uploads may proceed only after explicit Continue with the successful files. Cancellation or zero successful uploads must not trigger onboarding. Staging alone creates no brand or asset.

If the picker is unavailable and the client can read local files and make HTTP requests, call create_upload_urls and PUT the raw bytes using the returned instructions. Then use the upload IDs with tools that accept them in the same workspace, and each file's temporary url where a generation model input expects a file URL; use upload_image to save Library images. Otherwise, ask for publicly reachable HTTPS file URLs. Never use private host attachment URLs.

Does NOT change the brand's logo. To use an uploaded image as a logo, add it to the Brand Library, then use its image_id in an exact profile change with create_brand_edit. An SVG or GIF logo must already exist in the Brand Library before it can be assigned.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "open_upload_ui"
  }
}

Input Schema

NameRequiredDescriptionDefault
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.
workspace_idNoSelected workspace ID from list_workspaces, or null for the personal workspace.
brand_session_idNoBrand session ID from `list_brands` for the Brand Library that receives the images.

Output Schema

NameRequiredDescriptionDefault
modeNoIdentifies temporary-file staging mode. Present with workspace_id and workspace_name, without brand_session_id. Resolve the user's Continue reference with get_file_picker_handoff to obtain upload IDs.
workspace_idNoDestination for staged files. Present with mode and workspace_name; null identifies a personal workspace that has no ID. Consuming tools must use the same workspace.
workspace_nameNoName of the staging destination. Present with mode and workspace_id.
brand_session_idNoDestination Brand Library. Present only in image-saving mode, without mode or workspace fields. Completed Library image IDs arrive later in widget context.
message_for_assistantNoContext, explanations, or actionable guidance for the calling assistant. Hosts may display it, but it is not copy that must be shown to the user verbatim.

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 readOnlyHint/idempotentHint/destructiveHint, but the description goes well past them: per-mode file type and size limits, the 10-image vs 30-file caps, the two-hour expiry, the absence of a Continue step in the brand path, and the guarantee that staging creates no brand or asset. What it leaves thin is what the tool call itself returns before the user interacts, though the output schema carries that. The readOnlyHint=true is not contradicted because the text explicitly scopes staging as non-persistent.

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?

The branching is front-loaded by destination and then by fallback, so the structure matches how an agent will read it. It is dense but nearly every sentence is an actionable constraint; the main flaw is that the 'verified upload IDs / temporary url' instruction is repeated almost verbatim in the picker path and again in the create_upload_urls fallback.

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 multi-modal tool with a user-in-the-loop step, the description covers the follow-up handoff (get_file_picker_handoff), reference resolution, partial-upload and cancellation edge cases, and the full fallback chain. With an output schema present it does not need to describe return values, and 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 a constraint the schema cannot express: the three destination parameters are mutually exclusive and exactly one must be supplied, plus the non-obvious null-means-personal-workspace semantics. It adds little on llm_model beyond what the schema already says, which keeps it from 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?

The opening sentence names a specific verb and resource ('Open the shared upload picker in an MCP Apps client') and immediately splits the tool into two named modes. It also explicitly separates itself from the fallback path (create_upload_urls) and the logo-assignment path (create_brand_edit), so an agent can place it against siblings without opening a 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?

It states the selection rule directly: pass exactly one destination, brand_session_id for an existing Brand Library, workspace_id to stage files for another tool, and workspace_id: null for personal. It also gives explicit when-nots (picker unavailable, no HTTPS reachability, logo assignment) and names the alternative tool for each case, including the prohibition on private host attachment URLs.

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