Skip to main content
Glama

write_section

Destructive

Replace a LaTeX section body in one file using a revision-checked write, optionally as tracked changes, refusing conflicting or multi-file edits before anything is sent.

Instructions

Replace one section body in a single file using a revision-checked write, optionally recorded as tracked changes. By default included files are not traversed. With followIncludes: true, filePath is the document get_sections started from, sectionId comes from that call, and revision is the section's revision from it: the body is replaced in the file holding the heading, through the same revision-checked write, and filePath in the result names that file. The revision is checked against that file first: a file changed since get_sections is REVISION_CONFLICT with details.filePath and details.liveRevision, and nothing is sent. A section with spansFiles: true is refused with INVALID_ARGUMENT, details.kind spans_files, before anything is sent; edit each file with write_file instead. A section in an included file ends where that file ends, so do not add the including file's \end{document} to content. content replaces the whole body as get_section_content returns it, including nested subsections and, for the last section, \end{document}, so read it first and keep what should survive. The write is made as by write_file: on a ShareJS (legacy editor) document, content that adds an emoji or other character outside the Basic Multilingual Plane, or reorders existing ones, is refused with INVALID_ARGUMENT; a timeout, a lost socket, or an Overleaf error after sending is observed, never resent; a review-only collaborator can write only with writeMode tracked and a read-only one cannot write, either being PERMISSION_DENIED before anything is sent; and a tracked write Overleaf applied without recording it as tracked changes by this account is PROTOCOL_UNSUPPORTED with details.kind applied_untracked, live and not reverted.

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>",
      "sectionId": "<sectionId>",
      "content": "<content>"
    },
    "name": "write_section"
  }
}

Input Schema

NameRequiredDescriptionDefault
contentYes
filePathYesProject-relative path using forward slashes
revisionYesOpaque revision returned by a prior read or write
projectIdYesOverleaf project ID
sectionIdYes
writeModeNoUse tracked to record inserted and deleted text as Overleaf tracked changes; defaults to untrackeduntracked
followIncludesNoFollow \input, \include, \subfile, and \import directives from filePath down, as get_full_document does; defaults to false, one file only

Output Schema

NameRequiredDescriptionDefault
filePathNo
protocolYes
revisionYes
writeModeYes
trackChangesActiveYes
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?

Annotations only state destructive=true and idempotent=false, but the description adds the whole behavioral contract: revision checked first with REVISION_CONFLICT plus details.liveRevision and nothing sent, pre-send refusals for spans_files and PERMISSION_DENIED, no resend after timeout/lost socket, ShareJS BMP character limits, and PROTOCOL_UNSUPPORTED applied_untracked. This is far beyond annotation coverage and materially changes how an agent would call it.

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 purpose is correctly front-loaded in sentence one, and almost every clause carries information no other field provides. However, the remainder is one dense run-on paragraph mixing include semantics, error codes and write-mode edge cases; a short structured list would make the same content far easier to scan.

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, revision-dependent write with an output schema, the definition covers the risky edges an agent must know: conflict detection, permission tiers, tracked-vs-untracked outcomes, include boundaries, and post-send failure handling. Return values can be read from the output schema, so nothing critical 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?

With 71% schema coverage the baseline is 3, but the description adds real meaning the schema lacks: sectionId originates from get_sections, revision is that section's revision and is validated against the file holding the heading, content replaces the entire body including nested subsections and trailing \end{document}, and followIncludes changes which file filePath refers to.

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?

Opens with a specific verb, resource and scope: 'Replace one section body in a single file using a revision-checked write.' It immediately names the distinguishing traits (section body vs. whole file, revision-checked) and later contrasts with write_file and get_sections, so an agent can place it among siblings without opening schemas.

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 when/when-not guidance: default is one file, followIncludes:true is for included files and requires filePath/sectionId/revision from get_sections; spansFiles sections are refused and must be edited per file with write_file instead; content must be read via get_section_content first. Real alternatives and preconditions are named rather than inferred.

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