Skip to main content
Glama

upload_file

Destructive

Uploads a local file into an Overleaf project folder, storing it as a text document or binary by extension and UTF-8 validity. Replacing existing files requires overwrite or expectedHash.

Instructions

Upload a local file into a project folder. Overleaf decides whether it becomes a text document or a binary file, by extension and UTF-8 validity. Something already at the path is replaced only when asked for, and otherwise nothing is sent. Replacing a binary needs overwrite: true, or expectedHash equal to its hash from get_project_tree; without either it is CONFIRMATION_MISMATCH, and a different hash is REMOTE_DRIFT. expectedHash is checked just before the upload, not atomically with it. Replacing a text document is a blind write with no revision check, so it needs uncheckedDocumentReplace: true, else INVALID_ARGUMENT: prefer read_file then write_file with localPath, and pass uncheckedDocumentReplace only when nobody else is editing it. overwrite: false refuses any replacement with CONFIRMATION_MISMATCH. A replaced text document keeps its entity ID; a replaced binary file may get a new one. writeMode in the result is tracked when Overleaf records a document replacement as tracked changes, because track changes is on for this account.

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>",
      "localPath": "<localPath>"
    },
    "name": "upload_file"
  }
}

Input Schema

NameRequiredDescriptionDefault
localPathYes
overwriteNotrue allows replacing a binary file at the path; false refuses to replace anything; omitted, replacing a binary needs expectedHash
projectIdYesOverleaf project ID
expectedHashNoThe hash get_project_tree reported for the binary file being replaced; a different one is REMOTE_DRIFT
destinationNameNoName to store the file under; defaults to the local file name
destinationFolderPathNo
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
hashNo
pathYes
entityIdNo
replacedYes
writeModeYes
entityTypeNo
trackChangesActiveYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.3.0

TDQS

A4.6/5.0
Behavior4/5

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

Goes well beyond the destructiveHint/idempotentHint annotations by disclosing error codes (CONFIRMATION_MISMATCH, REMOTE_DRIFT, INVALID_ARGUMENT), that hash checking is not atomic with the upload, that a text document is a blind write, and that a replaced binary may receive a new entity ID. The only shortfall is that the surrounding sentences are dense and require careful parsing to extract these traits.

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 free of filler, but it is one long paragraph with run-on clauses such as 'Something already at the path is replaced only when asked for, and otherwise nothing is sent.' A short enumerated list of replacement scenarios would read faster for a destructive tool.

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?

An output schema exists, so return values needn't be spelled out, yet the description still explains writeMode's meaning when track changes is enabled. Combined with coverage of every risky parameter and its failure modes, an agent has enough to act safely.

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 a moderate 71%, and the description meaningfully extends it: overwrite's three-state behavior (true/false/omitted), expectedHash's drift semantics and non-atomic timing, and uncheckedDocumentReplace's blind-write risk. destinationName and destinationFolderPath get no narrative treatment, leaving a small gap.

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 ('Upload a local file into a project folder') and immediately clarifies the split of responsibility with Overleaf deciding text vs binary. It also names the relevant siblings it interacts with (get_project_tree for hashes, read_file/write_file for the safe text-replacement path), so an agent can distinguish it from plain write_file.

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?

Gives explicit routing rules: use read_file then write_file with localPath instead of replacing a text document, and only pass uncheckedDocumentReplace when nobody else is editing. It also spells out exactly which argument each replacement scenario requires (overwrite: true vs expectedHash) and what happens when they are absent.

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