Skip to main content
Glama

manage_tracked_changes

DestructiveIdempotent

Accept or reject tracked changes in an Overleaf document by supplying listed change IDs, revision, and user confirmation; prevents unconfirmed or mismatched decisions.

Instructions

Accept or reject tracked changes in one document. First list them with list_tracked_changes and confirm them with the user, then pass that document's filePath and revision, the changeIds (1 to 500, each once), and confirmCount equal to the number of changeIds; a missing or different confirmCount is CONFIRMATION_MISMATCH and nothing is sent. Accepting an insert keeps its text and accepting a delete removes it; rejecting an insert removes its text and rejecting a delete restores it. A tracked replacement is an insert and a delete linked by pairedChangeId: pass both ids. Checked in this order before anything is sent: access (only the owner and collaborators who can edit may decide; review-only and read-only access is PERMISSION_DENIED), whether track changes is available for the project (REVIEW_UNSUPPORTED, details.kind "feature_disabled"; review may need a plan that includes it), the revision (REVISION_CONFLICT), that every id is a tracked change in this document (NOT_FOUND, details.missingChangeIds), and that no change left out overlaps a chosen one (INVALID_ARGUMENT, details.overlappingChangeIds). REVIEW_UNSUPPORTED with details.kind "route_unavailable" or "document_protocol" means this Overleaf cannot decide changes this way. The decision is sent once and verified on a fresh read of the document. One that timed out is observed, never resent: recoveredAfterTimeout: true when it applied, TIMEOUT or REMOTE_ERROR with details.outcome "not_applied" when it did not, REVISION_CONFLICT with details.outcome "unknown" when the document changed meanwhile, and OUTCOME_UNKNOWN when it could not be observed. A repeated decision changes nothing: it fails with REVISION_CONFLICT when the first one changed the document's revision, as every reject and every history-OT decision does, or with NOT_FOUND when it did not, as after an accept on a ShareJS document, which leaves the revision as it was. Rejecting on a ShareJS (legacy editor) document may notify the change's author; on a history-OT document it does not. Returns action, filePath, changeIds, the resulting revision and protocol, remainingChangeCount (tracked changes left in the document), trackChangesActive, and recoveredAfterTimeout. List again after every decision and after REVISION_CONFLICT or NOT_FOUND: ids merge and split, and history-OT ids are valid only with the revision they were listed with.

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>",
      "filePath": "<filePath>",
      "revision": "<revision>",
      "action": "<action>",
      "changeIds": "<changeIds>"
    },
    "name": "manage_tracked_changes"
  }
}

Input Schema

NameRequiredDescriptionDefault
actionYes
filePathYesProject-relative path using forward slashes
revisionYesThe revision list_tracked_changes returned for this document
changeIdsYeschangeId values from list_tracked_changes, all in this document, each once
projectIdYesOverleaf project ID
confirmCountNoMust equal the number of changeIds, after the user has confirmed them

Output Schema

NameRequiredDescriptionDefault
actionYes
filePathYes
protocolYes
revisionYes
changeIdsYes
trackChangesActiveYes
remainingChangeCountYes
recoveredAfterTimeoutNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.3.0

TDQS

A4.8/5.0
Behavior5/5

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

The annotations only declare idempotentHint and destructiveHint; the description adds far more: validation order, specific error codes with details fields, accept/reject semantics for inserts and deletes, pairedChangeId handling for replacements, timeout observation rules, and ShareJS notification behavior. It also clarifies that a repeated decision is a no-op despite the destructive hint, which is genuinely useful context beyond the annotations.

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?

The purpose is front-loaded and nearly every clause carries operational meaning, including error ordering and re-list guidance. The prose is dense and uses long semicolon-linked sentences, which slightly hurts scanability, but there is little filler.

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, stateful mutation with six parameters, the definition covers prerequisites, confirmation requirements, validation order, partial-failure/timeout behavior, idempotency, and return fields. Even though an output schema exists, the extra explanation of recoveredAfterTimeout and outcome values makes the tool safe to invoke.

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 83%, so the schema already documents filePath, revision, changeIds and confirmCount. The description still adds meaningful semantics: confirmCount must equal the number of changeIds or produce CONFIRMATION_MISMATCH, changeIds must be 1–500 and each once, and revision must be the value returned by list_tracked_changes.

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?

The first sentence states a specific verb pair and resource: 'Accept or reject tracked changes in one document.' It immediately names the sibling list_tracked_changes as the prerequisite, so an agent can distinguish this mutation tool from the listing tool without opening a 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 workflow: list with list_tracked_changes, confirm with the user, then pass filePath, revision, changeIds and confirmCount. It also states when to re-list (after every decision, after REVISION_CONFLICT or NOT_FOUND) and why ids become invalid, leaving little to inference.

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