Skip to main content
Glama

fs_patch_file

Idempotent

Atomically replace an exact text block in a workspace file, with optional SHA-256 concurrency checks and idempotency keys to prevent conflicting or duplicate edits.

Instructions

Atomically replace an exact target text block inside a workspace file with optional SHA-256 Optimistic Concurrency Control (expected_sha256) and idempotency_key.

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>",
      "target": "<target>",
      "replacement": "<replacement>"
    },
    "name": "fs_patch_file"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathYesRelative file path inside the workspace root.
targetYesExact contiguous block of existing text to replace (must appear exactly once).
replacementYesReplacement text block.
expected_sha256NoOptional SHA-256 hex digest of the existing file for Optimistic Concurrency Control (CAS).
idempotency_keyNoOptional unique key to guarantee idempotent replay protection on retries.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.6/5.0
Behavior4/5

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

Annotations already declare idempotentHint=true and destructiveHint=false, so the description earns credit for adding atomicity and CAS/OCC semantics plus replay-protection behavior. It stops short of describing what happens on hash mismatch or non-unique target (error vs. no-op), which is a meaningful gap for a mutation tool.

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?

A single dense sentence with the operation front-loaded and no filler. Slightly jargon-heavy ('Optimistic Concurrency Control (CAS)'), but every clause carries information.

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?

With no output schema, the description should cover outcomes, yet it never states the return value or failure modes (target not found, target appears multiple times, SHA-256 mismatch). Adequate for calling the tool, incomplete for predicting its behavior.

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 description coverage is 100%, so the schema already documents every parameter, including expected_sha256 and idempotency_key. The description only restates those parameter names with a gloss on their purpose, adding no format or edge-case detail beyond the schema.

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+resource: 'atomically replace an exact target text block inside a workspace file'. The 'exact target text block' wording implicitly distinguishes it from a whole-file write, but no sibling (e.g. fs_write_file) is named, so differentiation is inferential rather than explicit.

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 only implied: the surgical block-replacement framing suggests a targeted edit rather than a full rewrite, but there is no explicit when-to-use/when-not guidance or prerequisite statement (e.g. file must exist, target must be unique).

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