Skip to main content
Glama

uploadFolder

Uploads a local directory to Pinata IPFS as a single folder CID, preserving subdirectories, with resumable per-file uploads. Use it for websites, datasets, or image sets instead of single-file uploads.

Instructions

Upload a local directory to Pinata IPFS as one folder with one CID, keeping its subdirectories. Use this instead of uploadFile when the content is a directory (a website, a dataset, a set of images); use uploadFile for a single file. Every regular file under the directory is sent as its own resumable upload, several at a time, each retried on its own, so a large folder or a flaky connection does not restart from zero. Symlinks are followed only to files inside the allowed directories; skipped entries are listed in the result. When some files fail, the result names them and gives the arguments that send only those files again into the same folder (folderId + paths). Also adds files to an existing folder: pass its folderId and its name (listFolder shows it as root). A folder holds at most folder_max_files files (see getUploadLimits; 30,000 unless the account has its own limit): a new folder of more files is refused before any is sent, with the file count of each top-level subdirectory, so the directory can be uploaded as several folders, one call per subdirectory (directory set to it, with its own name). Progress is reported per file to clients that ask for it.

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": {
      "directory": "<directory>"
    },
    "name": "uploadFolder"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameNoName of the folder on Pinata; the top directory of every file path in it. Defaults to the directory's name. When adding files to an existing folder, pass that folder's name.
pathsNoUpload only these files: paths relative to the directory, with / separators (e.g. the failed paths of an earlier call). Defaults to every file.
networkNoWhether to upload to public or private IPFSpublic
folderIdNoID of an existing folder to upload into, instead of a new one: to send failed files again, or to add files. A file whose path is already in the folder replaces it.
group_idNoID of a group to add the folder to
directoryYesPath of the local directory to upload (or its file:// URI); must be inside the allowed directories
keyvaluesNoMetadata key-value pairs for the folder
cidVersionNoCID version of the folder and its files (default v1)
concurrencyNoHow many files send their bytes at the same time (default 4)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.4.0

TDQS

A4.8/5.0
Behavior5/5

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

No annotations exist, so the description carries the full burden and does: per-file resumable uploads several at a time, independent per-file retry so a large folder or flaky connection does not restart, symlink policy (followed only to files inside allowed directories), skipped entries surfaced in the result, partial-failure behaviour with the folderId+paths re-run, and pre-flight refusal above folder_max_files with per-subdirectory counts. This is the kind of operational detail an agent cannot infer from elsewhere.

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 correctly: purpose, then the sibling contrast, then failure/limit/adding-to-existing behaviour in descending priority. It is a dense single block running long, and the closing progress-reporting sentence is low value, but nearly every clause carries actionable information.

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 9-parameter mutation tool with no annotations and no output schema, the description covers the safety-adjacent behaviour (pre-flight refusal, per-file retry, partial failure), the discovery path for folderId (listFolder) and for the cap (getUploadLimits), and even what the result contains for skipped and failed entries. An agent has what it needs to call this correctly in both normal and degraded cases.

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 per-parameter baseline is 3. The description still earns a step up by explaining cross-parameter semantics the schema states only piecewise: folderId combined with paths to resend only failed files into the same folder, folderId plus the existing folder's name, and directory being reset to a subdirectory with its own name when splitting an oversized upload.

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?

Opens with a specific verb+resource+outcome: upload a local directory to Pinata IPFS as one folder with one CID while keeping subdirectories. It immediately distinguishes itself from uploadFile by naming the content-type condition (directory vs single file), so an agent can route 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?

Explicit when-to-use versus the sibling (uploadFile for a single file), explicit secondary mode (folderId + name to add into an existing folder, with listFolder as the way to discover it), and explicit fallback when the file cap is exceeded: one call per top-level subdirectory with directory set to it. Alternatives and exclusions are all named.

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