Skip to main content
Glama

upload_artifact

Upload files, code, logs, or other artifacts to a task; use file_path for binary data and content for short text, with optional sha256 verification.

Instructions

Upload an artifact (file, code, log, etc.) to a task. For a file on disk — any binary (screenshot, image, pdf, archive) — pass file_path: this process reads the bytes, they never pass through your context, and the response carries their sha256. Use content only for short text you generated; inline base64 of a binary larger than a few KB gets corrupted in transit. file_path works over stdio only (a remote SSE/HTTP server refuses it). Downloading an artifact is two GETs. Step 1: GET /api/v1/artifacts//download with header X-Agent-Key: -> 200 JSON {"url": ""}. Step 2: GET that url with NO headers -> 200, the file bytes. Pitfalls: on step 1 only X-Agent-Key is accepted (X-API-Key and Authorization: Bearer give 401); on step 2 any extra header, Authorization in particular, breaks the presigned signature (400). The artifact's download_path is step 1's path. browser_only_url is a human page and answers 401 to an agent key by design.

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": {
      "task_id": "<task_id>"
    },
    "name": "upload_artifact"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameNoArtifact filename. Required with content; defaults to the file's basename with file_path.
sha256NoOptional hex sha256 of the DECODED bytes. Verified before upload; a mismatch fails the call. Recommended for binary, since it is the only check that catches a payload truncated in transit.
contentNoInline artifact content, for short text. Plain text by default; encoding="base64" for binary (prefer file_path). Mutually exclusive with file_path.
task_idYesTask ID.
encodingNoHow to interpret content: "text" (stored as-is) or "base64" (decoded before storing). Required for binary — without it a base64 string is stored literally as the file body.text
metadataNoAdditional metadata, stored on the artifact as JSON.
file_pathNoAbsolute path of a regular file to upload (no symlinks or directories, max 25 MB). Preferred for every binary. Mutually exclusive with content; stdio transport only.
mime_typeNoMIME type. Auto-detected from name if omitted. For png/jpeg/gif/pdf/zip the content is checked against the type's magic bytes and the upload is refused on a mismatch.
artifact_typeNoCategory used to label and filter the artifact: file (default), code, log, report, link, image or data. It does not affect how content is decoded; encoding and mime_type do.file

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.1.7
    • changedInput schema / properties / content / description
      Previous value: -"Artifact content. Plain text by default; set encoding=\"base64\" to send binary."New value: +"Inline artifact content, for short text. Plain text by default; encoding=\"base64\" for binary (prefer file_path). Mutually exclusive with file_path."
    • addedInput schema / properties / file_path
      Added value: +{
      +  "description": "Absolute path of a regular file to upload (no symlinks or directories, max 25 MB). Preferred for every binary. Mutually exclusive with content; stdio transport only.",
      +  "type": "string"
      +}
    • changedInput schema / properties / name / description
      Previous value: -"Artifact filename."New value: +"Artifact filename. Required with content; defaults to the file's basename with file_path."
    • changedInput schema / required
      Previous value: -[
      -  "task_id",
      -  "name",
      -  "content"
      -]New value: +[
      +  "task_id"
      +]
  2. Changed1 schema field changedv0.1.6
    • changedInput schema / properties / artifact_type / description
      Previous value: -"Type: file, code, log, report, link, image, data."New value: +"Category used to label and filter the artifact: file (default), code, log, report, link, image or data. It does not affect how content is decoded; encoding and mime_type do."
  3. First observedv0.1.1

TDQS

A4.4/5.0
Behavior4/5

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

Goes well beyond the annotations: bytes never traverse the agent's context, the response carries sha256, sha256 is verified pre-upload, magic bytes are checked for png/jpeg/gif/pdf/zip, 25 MB cap, and stdio-only file_path. Gaps remain on mutation semantics that annotations imply — idempotentHint=false is never explained (whether re-uploading the same name duplicates or overwrites), and no rate or concurrency behavior is given.

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?

Front-loaded correctly and the upload guidance is tight, but a multi-step download tutorial with header pitfalls occupies roughly a third of the text and belongs to get_artifact, not this tool. Useful content, but a notable share of the length does not earn its place in this definition.

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

Completeness4/5

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

Covers the hard parts of a 9-parameter mutation tool with no output schema: transport constraints, verification options, size limits, and mutual exclusion. It does not describe the success response beyond sha256, nor overwrite/conflict behavior, which is the main remaining gap.

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, but the description adds real decision value: file_path and content are mutually exclusive, encoding must be base64 for binary or the string is stored literally, and mime_type mismatches are refused. It reinforces rather than merely restates the schema's parameter docs.

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?

"Upload an artifact (file, code, log, etc.) to a task" gives a concrete verb and resource, and the definition immediately contrasts this with retrieval ("Downloading an artifact is two GETs"), so an agent can distinguish it from get_artifact without inspecting schemas.

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?

Explicit routing rules: use file_path for any binary on disk, use content only for short generated text, and file_path is unavailable over remote SSE/HTTP. The failure modes that should push an agent to the other path (inline base64 corruption above a few KB, transport refusal) are stated outright.

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