Skip to main content
Glama

batch_upload

Destructive

Upload multiple local files to explicit project paths in one call, with per-file conflict handling for fail, skip, or overwrite. Use it instead of sending one upload call per file.

Instructions

Upload a list of local files to explicit project paths in one call, instead of one upload_file call per file. Each destinationPath is the full project path including the file name; missing folders are created. onConflict decides what happens when a document or file is already at a destination path: "fail", the default, refuses the whole call with CONFIRMATION_MISMATCH listing those paths, before anything is uploaded; "skip" leaves them untouched and lists them in skipped; "overwrite" replaces a binary file. Replacing a text document has no revision check, so with "overwrite" each one also needs uncheckedDocumentReplace: true, else that file fails with INVALID_ARGUMENT; use write_file or sync_directory for documents a collaborator may be editing. A folder at a destination path, or a file where a folder is needed, fails that file in any mode. Every path is checked before anything is sent: a duplicate destination or a missing local file fails the call with nothing uploaded. Failures are per file and nothing is retried: the call continues past a failure unless stopOnError, and stops at RATE_LIMITED (Overleaf allows about 500 uploads per project in 15 minutes). It returns status, completed (with replaced per upload), skipped, failed, remaining, and verified, which is true when the tree read back afterwards confirmed every completed entry. A timed-out upload is classified from that read-back, never resubmitted: recoveredAfterTimeout when the path holds the local bytes, OUTCOME_UNKNOWN when the tree cannot tell. It saves tool calls, not time. Confirm overwrites with the user first.

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": {
      "projectId": "<projectId>",
      "files": "<files>"
    },
    "name": "batch_upload"
  }
}

Input Schema

NameRequiredDescriptionDefault
filesYesFiles to upload, in order; at most 500
projectIdYesOverleaf project ID
onConflictNoWhat to do when a document or file is already at a destination path; fail (the default) uploads nothingfail
stopOnErrorNoStop at the first failure instead of continuing
uncheckedDocumentReplaceNoAllow replacing a text document, a blind write with no revision check; prefer write_file with localPath when a collaborator may be editing

Output Schema

NameRequiredDescriptionDefault
failedYes
statusYes
skippedYes
verifiedYes
completedYes
remainingYes
onConflictYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.3.0

TDQS

A4.9/5.0
Behavior5/5

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

Annotations only declare destructiveHint=true and idempotentHint=false; the description goes far beyond by specifying pre-flight validation (duplicate destinations, missing local files fail the whole call with nothing uploaded), per-file failure semantics with no retries, rate-limit stop behavior, and timeout classification from read-back rather than resubmission. It also discloses that overwrite of a text document is a blind write needing uncheckedDocumentReplace, which is exactly the risk profile an agent needs.

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 upload_file contrast, and nearly every sentence carries operational detail. It is dense and clause-heavy, with several policies packed into long sentences, which costs some scannability but not correctness.

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 destructive, multi-file batch tool with conflict modes, the description covers validation, folder creation, partial failure, rate limits, timeout handling, and the meaning of verified in the response even though an output schema exists. Nothing an agent needs in order to call it safely is missing.

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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: onConflict's three modes and their distinct consequences (fail refuses the whole call before upload, skip lists in skipped, overwrite replaces binaries), the coupling between overwrite and uncheckedDocumentReplace, and that stopOnError changes continuation at RATE_LIMITED. That is substantive semantics the enum values alone do not convey.

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 with explicit scope: upload many local files to explicit project paths in one call. It directly contrasts with the sibling upload_file ('instead of one upload_file call per file'), so an agent can choose between them 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?

Names the alternatives and the conditions that select them: use write_file or sync_directory for documents a collaborator may be editing, and confirm overwrites with the user first. It also sets a clear expectation that the tool saves calls, not time, which shapes when it is worth using.

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