Skip to main content
Glama
nucleusv

Linux MCP daemon

by nucleusv
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Go
Local

files/update

Destructive

Edit an existing file in place by appending text or replacing a line range. Use absolute path, specify start/end lines or append flag.

Instructions

Edits part of an EXISTING file in place: appends text or replaces an inclusive line range. Mutating and not atomic; the file keeps its mode and owner. To write a whole file use files/create; to see the lines first use files/read with start_line/end_line. With append: true exactly content is added at the end (no newline is added, include your own) and the file is created if missing, though not its parent directories; append wins over any line range. Otherwise start_line AND end_line are both required (1-indexed, end_line >= start_line), the file must exist, and those lines are replaced by content (one trailing newline of content is ignored; an end_line past the end is clamped; a start_line past the end adds content as a new last line). There is no insert or delete mode: replacing with empty content leaves one empty line. Returns Successfully appended to PATH or Successfully updated lines A-B in PATH, no diff. path must be absolute; privileged: true (a grant, and for root a paths: entry) edits files you cannot write.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
pathYesAbsolute path of the file to edit
appendNoIf true, append content at the end (creates the file if missing); takes precedence over start_line/end_line
contentYesText to append, or to replace the line range with (no newline is added when appending)
end_lineNoLast line to replace (inclusive, >= start_line; past the end of the file is clamped)
privilegedNoRun as root. Needs a grant for this tool in mcp-sudo.yaml and a `paths:` entry covering the path, otherwise refused
start_lineNoFirst line to replace (1-indexed); required together with end_line unless append is true

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changedv0.4.1
    • changedInput schema / properties / append / description
      Previous value: -"If true, appends the content to the end of the file"New value: +"If true, append content at the end (creates the file if missing); takes precedence over start_line/end_line"
    • changedInput schema / properties / content / description
      Previous value: -"Text content to insert or append"New value: +"Text to append, or to replace the line range with (no newline is added when appending)"
    • changedInput schema / properties / end_line / description
      Previous value: -"End of the line range to replace (inclusive)"New value: +"Last line to replace (inclusive, >= start_line; past the end of the file is clamped)"
    • changedInput schema / properties / path / description
      Previous value: -"Path to the file to edit"New value: +"Absolute path of the file to edit"
    • changedInput schema / properties / privileged / description
      Previous value: -"Set to true to edit as root"New value: +"Run as root. Needs a grant for this tool in mcp-sudo.yaml and a `paths:` entry covering the path, otherwise refused"
    • changedInput schema / properties / start_line / description
      Previous value: -"Start of the line range to replace (1-indexed)"New value: +"First line to replace (1-indexed); required together with end_line unless append is true"
  2. First observed

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds non-atomicity, that mode and owner are preserved, the exact return strings, the absence of a diff, and the privileged-grant requirement. It also discloses subtle behavioral edge cases (trailing newline ignored, end_line clamped, start_line past end appends) that no annotation covers.

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-loads purpose and alternatives before edge cases, and nearly every sentence carries essential semantics. It is on the long side, but the density of non-obvious behavior (clamping, newline rules, no insert/delete mode) justifies most of the length.

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?

With no output schema, the description supplies the return values directly and covers preconditions (file must exist, path absolute, parent dirs not created), mode/owner preservation, and failure modes for privileged edits. Nothing an agent needs to invoke it correctly appears 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?

Schema coverage is already 100%, yet the description still adds semantics the schema lacks: append precedence over line ranges, that start_line AND end_line are jointly required and 1-indexed with end_line >= start_line, the newline handling on append, and the privileged grant mechanics. This meaningfully exceeds the schema text.

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 (Edits), resource (file), and the two distinct modes (append vs. replace line range) in the first sentence. Explicitly contrasts itself with `files/create` for whole-file writes and `files/read` for inspecting lines, so an agent can distinguish it from siblings 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?

Names both alternatives and the condition that selects each ('To write a whole file use files/create; to see the lines first use files/read with start_line/end_line'). It also spells out when append mode applies versus line-range mode, including that append wins over a supplied range.

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

Deploy Server

Other Tools