Skip to main content
Glama

fs_replace

Idempotent

Find-and-replace text in a single file, server-side. No read-modify-write cycle from the client. Archives the current contents as a new version before writing (same retention as fs_write), so fs_restore can roll back.

Literal string match (not regex). Only works on text files. A single find that matches nothing returns replacements: 0 and writes nothing.

Several edits to one file: pass edits, an ordered array of { "find", "replace", "expect"? } (at most 200), instead of top-level find/replace. They apply in order (a later edit sees the earlier ones) and save as ONE new version. In the array every edit must match: the first that does not returns FIND_NOT_FOUND with zero-based data.edit_index and writes nothing; expect: n requires exactly n matches, else FIND_COUNT_MISMATCH with data.expected and data.actual. One call edits one file.

Example:

{ "project_id": "my-saas", "path": "/src/config.ts", "find": "API_URL = 'https://staging...'", "replace": "API_URL = 'https://api...'" }
// Returns: { "ok": true, "replacements": 1, "version": 4 }
{ "project_id": "my-saas", "path": "/notes/todo.md", "edits": [{ "find": "- [ ] ship", "replace": "- [x] ship", "expect": 1 }, { "find": "Status: draft", "replace": "Status: done" }] }
// Returns: { "ok": true, "replacements": 2, "edits": [{ "edit_index": 0, "replacements": 1 }, { "edit_index": 1, "replacements": 1 }], "version": 5 }

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": {
      "project_id": "<project_id>",
      "path": "<path>"
    },
    "name": "fs_replace"
  }
}

Input Schema

NameRequiredDescriptionDefault
findNoExact string to find (non-empty). Omitted when `edits` is sent.
pathYesFull path to the file with leading slash.
editsNoOrdered edits to this one file, saved as one new version. Every edit must match or nothing is written (FIND_NOT_FOUND with data.edit_index). Exclusive with top-level find/replace.
replaceNoReplacement string (may be empty to delete matches). Omitted when `edits` is sent.
project_idYesProject ID (UUID), subdomain, or slug — resolved server-side, no UUID lookup needed. 'default' also works when the account has exactly one project; multi-project accounts must name one (the error lists them).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Goes well beyond the annotations by disclosing that current contents are archived as a new version before writing (same retention as fs_write) with rollback via fs_restore, that a no-match find writes nothing, that an `edits` array is all-or-nothing and saves as one version, and by naming exact error codes with their data payloads (FIND_NOT_FOUND/data.edit_index, FIND_COUNT_MISMATCH/data.expected/actual). That is the mutation-safety context an agent needs and the annotations alone do not convey.

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?

Front-loaded with the core purpose and the server-side/no-read-modify-write rationale, then the rollback guarantee, then the multi-edit mode with examples. Every sentence carries operational information: literal-not-regex, text-only, no-write-on-no-match, ordering, atomicity, and error contracts.

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 compensates by showing concrete success payloads (`replacements`, `version`, per-edit results) and error codes with data fields. Combined with the archival/rollback behavior, an agent has everything needed to invoke it correctly and interpret failures.

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 100%, so the baseline is 3; the description still adds value by explaining that `edits` applies in order with later edits seeing earlier ones, that it is exclusive with top-level find/replace, and by showing two concrete request/response examples. It reinforces rather than merely repeats the schema's documented fields.

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 precise verb+resource ("Find-and-replace text in a single file, server-side") and immediately differentiates from a client-side read-modify-write cycle, which is exactly what sibling tools like fs_read plus fs_write would require. An agent can tell this apart from fs_write without opening either schema.

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

Usage Guidelines4/5

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

Gives clear selection conditions: literal string only (not regex), text files only, one file per call, and use the `edits` array rather than repeated calls when making several changes to one file. It does not explicitly route the regex or full-rewrite case to another tool (fs_write is only mentioned for retention semantics), so it stops short of full when/when-not guidance.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources