Skip to main content
Glama

add_comment

Add and verify an anchored review comment in an Overleaf project file using UTF-16 positions and expected text; returns the created thread and document revision when readable.

Instructions

Add and verify an anchored review comment using UTF-16 positions and expectedText. Returns threadId, the created thread (id, status, messages with author { id, displayName }, content, and ISO timestamp) when it could be read back, the resulting document revision and protocol, trackChangesActive, writeMode, and recoveredAfterTimeout when an attachment that timed out, lost its socket, or could not be read back was confirmed by observation.

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>",
      "start": "<start>",
      "end": "<end>",
      "expectedText": "<expectedText>",
      "content": "<content>"
    },
    "name": "add_comment"
  }
}

Input Schema

NameRequiredDescriptionDefault
endYes
startYes
contentYes
filePathYesProject-relative path using forward slashes
revisionYesOpaque revision returned by a prior read or write
projectIdYesOverleaf project ID
expectedTextYes

Output Schema

NameRequiredDescriptionDefault
threadNo
protocolYes
revisionYes
threadIdYes
writeModeYes
trackChangesActiveYes
recoveredAfterTimeoutNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.3.0

TDQS

B3.2/5.0
Behavior3/5

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

Annotations only declare idempotentHint=false and destructiveHint=false; the description adds that a write can succeed while read-back fails ('when it could be read back') and that recoveredAfterTimeout covers timeouts, lost sockets, and unreadable attachments confirmed by observation. That is genuine recovery/verification behavior not covered by annotations. It still omits conflict behavior when expectedText does not match and permission requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is a single run-on sentence whose second half enumerates return fields (threadId, thread shape, author fields, ISO timestamp, protocol, trackChangesActive, writeMode) that an output schema already covers. The purpose is front-loaded, but a large share of the text does not earn its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter mutation with nested start/end objects and an existing output schema, the definition covers anchoring mechanics and recovery semantics but not the critical failure mode: what happens if expectedText no longer matches the document. Combined with the redundant return-value prose, it is adequate but not complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 43% across 7 parameters, so the description needs to compensate. It does add real meaning for start/end by stating they are UTF-16 positions and ties expectedText to verification of the anchor, which the schema does not explain. The other parameters (projectId, filePath, revision, content) are left to the schema, so compensation is partial.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first clause gives a specific verb and resource ('Add and verify an anchored review comment'), plus the anchoring mechanism ('UTF-16 positions and expectedText'). This distinguishes it from siblings like reply_to_comment and set_comment_status, though it never names them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: it creates a new anchored comment rather than a reply, and the mention of 'verify' hints at a read-back step. However, there is no explicit when-to-use, no when-not (e.g. use reply_to_comment for existing threads), and no prerequisite guidance about obtaining a revision first.

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