Skip to main content
Glama

sync_directory

DestructiveIdempotent

Synchronize a local folder with an Overleaf project by uploading new or changed files and, in mirror mode, deleting project-only files after a confirmed plan.

Instructions

Make a project folder match a local folder: upload new and changed files, and in mirror mode also delete what exists only in the project. Call plan_sync first, confirm the plan with the user, and pass its planToken; if the project or the folder changed since, REMOTE_DRIFT is returned and nothing changes. A planToken is required: without one the call is refused with CONFIRMATION_MISMATCH before anything is read, unless an additive sync passes unplanned: true to run without a plan on purpose (planned is then false); a mirror sync always needs one. Changed text documents are replaced through revision-checked write_file edits, recorded as tracked changes when writeMode is tracked, so a concurrent edit fails that file with REVISION_CONFLICT rather than being overwritten. Binaries and new files are uploaded, and one whose path changed since the plan fails with REMOTE_DRIFT; with writeMode tracked, new .tex, .bib, and similar text files are created with tracked content instead. Missing folders are created. Uploads and writes run first. Deletes run only in mirror mode, only when confirmDeleteCount equals the number of remoteOnly entries, else CONFIRMATION_MISMATCH, and never after any upload or write failed. Failures are per file and nothing is retried: the call continues unless stopOnError, then returns status, completed, failed, remaining, and a planToken to resume with. Each failed entry carries the step's error details, and kind: applied_untracked when a tracked step applied without being recorded as tracked changes (it is live, not reverted); a create that failed with details.created left its document behind, and resuming with the planToken writes it while it is still empty or holds the local text. On a ShareJS (legacy editor) document, text that adds an emoji or another character outside the Basic Multilingual Plane, or reorders existing ones, fails that file with INVALID_ARGUMENT. It saves tool calls, not time.

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>",
      "localFolderPath": "<localFolderPath>",
      "mode": "<mode>"
    },
    "name": "sync_directory"
  }
}

Input Schema

NameRequiredDescriptionDefault
modeYesadditive only uploads and writes; mirror also deletes what exists only in the project
ignoreNoExtra gitignore-style patterns, applied after the defaults (hidden files and folders, __MACOSX/, and LaTeX build output: *.aux, *.log, *.bbl, *.blg, *.out, *.toc, *.synctex.gz, *.fdb_latexmk, *.fls) and after any .olignore file in the folder; "!pattern" re-includes, for example "!.latexmkrc". Ignored paths are never uploaded, compared, or deleted, on either side.
planTokenNoFrom plan_sync, or from a partial sync_directory to resume it; required unless an additive sync passes unplanned
projectIdYesOverleaf project ID
unplannedNoRun an additive sync without a planToken on purpose; never with a planToken or in mirror mode
writeModeNoUse tracked to record inserted and deleted text as Overleaf tracked changes; defaults to untrackeduntracked
stopOnErrorNoStop at the first failure instead of continuing
localFolderPathYesLocal folder on the server's own disk, synced as a whole
confirmDeleteCountNoRequired in mirror mode: the number of entries in plan_sync's remoteOnly, each folder counting once
destinationFolderPathNoProject folder the local folder corresponds to; "" (the default) is the project root

Output Schema

NameRequiredDescriptionDefault
modeYes
failedYes
statusYes
plannedYes
completedYes
planTokenNo
remainingYes
identicalCountYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.3.0

TDQS

A4.6/5.0
Behavior5/5

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

Annotations cover destructive/idempotent hints, yet the description adds substantial behavior: drift and confirmation guards (REMOTE_DRIFT, CONFIRMATION_MISMATCH), revision-checked edits that fail with REVISION_CONFLICT instead of overwriting, ordering (uploads and writes first, deletes last and never after a failure), and no-retry semantics. It also discloses partial-failure reporting (status, completed, failed, remaining, kind: applied_untracked) and an edge case where an emoji outside the BMP fails a legacy ShareJS document with INVALID_ARGUMENT.

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?

The core purpose and required sequence are front-loaded, but the remainder is a single dense block of run-on clauses packed with error codes, making it hard to scan for the one rule an agent needs at call time. The closing line "It saves tool calls, not time." is cryptic and does not earn its place.

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?

For a 10-parameter destructive sync with tracked-change and resume semantics, the description covers the guard rails, ordering, failure modes and resume path thoroughly. Since an output schema exists, its recital of status/completed/failed/remaining is slightly redundant, but 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.

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, and the description exceeds it by adding cross-parameter constraints the schema cannot express: confirmDeleteCount must equal the number of plan_sync remoteOnly entries, planToken may come from plan_sync or a partial sync and is forbidden alongside unplanned, and mirror mode always requires a token. It says little about ignore or destinationFolderPath, but the schema documents those in detail.

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?

"Make a project folder match a local folder: upload new and changed files, and in mirror mode also delete what exists only in the project" names the verb, both resources, and the mode-dependent scope in one sentence. It also states the relationship to the sibling plan_sync ("Call plan_sync first"), so an agent can distinguish it from the planner 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?

It gives an explicit procedure and prerequisites: call plan_sync, confirm the plan with the user, then pass its planToken. It also states the exception precisely — an additive sync may pass unplanned: true, while "a mirror sync always needs one" — and explains when deletes are permitted (mirror mode plus matching confirmDeleteCount).

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