Skip to main content
Glama

edit

Destructive

Replace exact text in a file on a remote machine, using a unique match or replacing all occurrences, with guarded fleets requiring the user's explicit agreement first.

Instructions

Replace exact text in a file on the remote machine. old_string must be unique unless replace_all is set. On a guarded fleet you must first ask the user and get their explicit agreement; only then set confirm to the fleet name.

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": {
      "path": "<path>",
      "old_string": "<old_string>",
      "new_string": "<new_string>"
    },
    "name": "edit"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathYesFile path on the remote machine: absolute, or relative to the workspace directory.
fleetNoFleet name. Omit to use the default.
confirmNoGuarded fleets only: the fleet name, set only after the user explicitly agreed. Never set it on your own.
contextNoContext name. Omit to use the default.
workspaceNoWorkspace id. Omit to use this session's workspace on the fleet.
new_stringYesReplacement text (may be empty to delete).
old_stringYesExact text to replace. Must be unique in the file unless replace_all is set.
replace_allNoReplace every occurrence.

Output Schema

NameRequiredDescriptionDefault
kindYes
mimeNo
noteNo
pathNo
sizeNo
countNo
linesNo
whereYes
sha256No
contentNo
entriesNo
new_fileNo
warningsNo
truncatedNo
workspaceYes
next_offsetNo
total_linesNo
omitted_bytesNo
written_bytesNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the danger profile is known. The description adds the non-obvious approval workflow for guarded fleets and the uniqueness precondition, which are real behavioral facts not encoded in annotations. It does not describe post-edit effects or failure modes, keeping it below a 5.

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

Conciseness5/5

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

Three short sentences, front-loaded with the core action and followed by the two constraints that matter most. No filler and nothing redundant.

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 destructive 8-parameter mutation tool, the description covers the destructive-safety concern and the uniqueness constraint, and an output schema exists so return values need no exposition. The main omission is when to choose this over the other editing siblings.

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 100% and every parameter is already documented, so the baseline is 3. The description restates the old_string/replace_all relationship and clarifies that confirm takes the fleet name only after explicit consent, but adds little beyond the schema text.

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?

States a specific verb and resource: 'Replace exact text in a file on the remote machine,' with the exact-match semantics that separate it from a wholesale write. It does not explicitly differentiate itself from siblings like write_file or multi_edit, so an agent must infer the boundary.

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?

Gives a clear conditional rule for the guarded-fleet case (ask the user first, then set confirm), which is solid usage guidance for that branch. However, it never says when to prefer this tool over write_file, multi_edit, or bash-based editing, and gives no guidance on when replace_all is appropriate beyond the schema's own wording.

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