Skip to main content
Glama

switch

by ai.switchapp
OverviewDiscussionsAdmin

Upload Reference

upload_reference_asset

Upload an image, video, or audio reference into your Switch cloud and get an opaque asset_id (never a raw storage URL) to pass in reference fields. First inspect the asset and record what its actual chip controls. Preserve its thumbnail, media type, order, and role; uploading never authorizes replacing the visual chip with text or silently dropping, merging, reordering, converting, or repurposing it. A clear speaking and moving video is usually strongest for realistic identity, performance, motion, and voice when supported; still images sharpen appearance, wardrobe, products, logos, typography, and scenes. Pass kind=image|video|audio. Returns reference_image_urls / reference_video_urls / reference_audio_urls for generate_image and generate_video. Uploads stay separate from active Studio references by default, including images uploaded for video work. Set activate=true only when the user explicitly asks to add this image to the Studio image workspace. Video and audio never touch the Studio strip. PREFERRED for real files: call with presign=true to get an upload_url, PUT the bytes straight to it (no base64 through the model), then call again with confirm_path to verify and record it — works for image, video, and audio. base64/url is only for tiny inline files.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
urlNoPublic https URL to fetch server-side.
kindYesReference type to upload.
mimeNoMIME for base64. Images: jpg/png/webp/gif. Videos: mp4/mov. Audio: mp3/wav/m4a/aac.
base64NoBase64 bytes (optionally a data: URL). Best for small files; large video should use presign.
presignNoReturn an upload_url to PUT the file bytes directly to (no base64). Video always; image/audio when enabled.
activateNoImage only. Set true only for an explicit user request to add this image to the Studio image workspace. Default false: upload and return a reusable reference without changing Studio. On presigned uploads, set this on the confirm_path call. Video and audio never activate Studio.
filenameNoOptional source filename for extension/display.
frame_typeNoImage strip label: ref (default), face, body, clothes, scenery, product, typography. Use "face" for a person's face/likeness — face uploads are stored as untouched originals in the private reference bucket and their returned asset_id is the ONLY handle face-capable generation accepts (KYC-verified accounts only).
confirm_pathNoThe storage_path from a presign call, after you PUT the file — verifies the object and records it; only activate=true on this call adds an image to Studio.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • addedInput schema / properties / activate / default
      Added value: +false
    • changedInput schema / properties / activate / description
      Previous value: -"Image only: add to the active Studio reference strip. Default true. The strip is photos only — video and audio never touch it regardless of this flag."New value: +"Image only. Set true only for an explicit user request to add this image to the Studio image workspace. Default false: upload and return a reusable reference without changing Studio. On presigned uploads, set this on the confirm_path call. Video and audio never activate Studio."
    • changedInput schema / properties / confirm_path / description
      Previous value: -"The storage_path from a presign call, after you PUT the file — verifies the object, records it, and adds it to your strip."New value: +"The storage_path from a presign call, after you PUT the file — verifies the object and records it; only activate=true on this call adds an image to Studio."
  2. Changed1 schema field changed
    • changedInput schema / properties / activate / description
      Previous value: -"Image/video: add to the active Studio reference strip. Default true. Audio never touches the strip."New value: +"Image only: add to the active Studio reference strip. Default true. The strip is photos only — video and audio never touch it regardless of this flag."
  3. Changed1 schema field changed
    • changedInput schema / properties / frame_type / description
      Previous value: -"Image strip label: ref (default), face, body, clothes, scenery, product, typography."New value: +"Image strip label: ref (default), face, body, clothes, scenery, product, typography. Use \"face\" for a person's face/likeness — face uploads are stored as untouched originals in the private reference bucket and their returned asset_id is the ONLY handle face-capable generation accepts (KYC-verified accounts only)."
  4. Changed2 schema fields changed
    • changedInput schema / properties / confirm_path / description
      Previous value: -"kind=video only: the storage_path from a presign call, after you PUT the file — adds it to your strip."New value: +"The storage_path from a presign call, after you PUT the file — verifies the object, records it, and adds it to your strip."
    • changedInput schema / properties / presign / description
      Previous value: -"kind=video only: return an upload_url for a large direct upload instead of sending base64."New value: +"Return an upload_url to PUT the file bytes directly to (no base64). Video always; image/audio when enabled."
  5. Added

TDQS

A4.9/5.0
Behavior5/5

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

The description goes far beyond the annotations (readOnlyHint=false, idempotentHint=false) by detailing preservation guarantees, that uploads never replace, drop, merge, reorder, convert, or repurpose assets, and that uploads stay separate from Studio by default. It also explains the two-step presign/confirm_path behavior and the activate side effect, giving rich behavioral context.

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 description is relatively long but well-structured: it front-loads the core upload function and asset_id constraint, then logically covers behavioral guarantees, usage modes, and activation rules. It is not as tight as it could be, but every sentence adds operational value and the flow is easy to follow.

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?

This is a complex 9-parameter tool with no output schema, yet the description gives complete guidance: it names return fields, explains the presigned flow, defines when activation happens, and covers edge cases like face uploads and video/audio restrictions. An agent has everything needed to invoke it correctly without additional lookup.

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

Parameters5/5

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

With 100% schema coverage, a baseline of 3 applies, but the description adds substantial operational meaning: it explains the presign/confirm_path workflow, enforces base64 for tiny files only, clarifies activate semantics (only on explicit request, only on confirm_path), and elaborates frame_type with face-specific storage and KYC implications. This exceeds schema descriptions.

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 description states a specific verb (upload), resource (image/video/audio reference), and outcome (opaque asset_id to pass in reference fields). It also clarifies the key distinction from raw storage URLs and shows how it feeds generate_image/generate_video, making it easily distinguishable from sibling upload tools.

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?

The description gives explicit when-to-use guidance: presign flow for real files, base64/url only for tiny inline files, and activate=true only on explicit user request for Studio. It also specifies that video/audio never activate Studio and that face uploads have special KYC requirements, leaving no ambiguity about when this tool is appropriate.

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

All switch toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources