Skip to main content
Glama
Sign In
PatchLoop

PatchLoop

by varad-oss
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

str_replace

Replace one exact, unique occurrence of old text with new text in a file; returns an error with match counts if the old text is missing or ambiguous.

Instructions

Edit a file by replacing one exact occurrence of old_str with new_str. old_str must match the file exactly (including indentation and whitespace) and must occur exactly once; otherwise the tool returns an error with the number of matches, and you should include more surrounding lines to make it unique. On success it shows the edited region. Test files are read-only and cannot be edited.

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_str": "<old_str>",
      "new_str": "<new_str>"
    },
    "name": "str_replace"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathYes
new_strYes
old_strYes

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.4/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does so well: it discloses the exact-match and uniqueness preconditions, the failure mode (error plus number of matches), the success signal (edited region shown), and a read-only file constraint. It omits whether the write is atomic or whether the target file must already exist, leaving a minor 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.

Conciseness5/5

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

Three tight sentences: the action first, then the precondition and failure recovery, then the success and constraint. Every sentence earns its place and nothing is repeated from structured fields.

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?

An output schema exists, so return structure need not be spelled out, and the description still notes the on-success view and the error payload. What remains missing for a write tool with no annotations is a note on whether edits are atomic, whether the file must exist, or any path-format expectations.

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 description coverage is 0%, so the description must compensate; it does for the two non-obvious parameters by specifying that old_str must match exactly including indentation/whitespace and must be unique, and that new_str is the replacement. Only path is left implicit, which is acceptable for an obvious filesystem argument.

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 and resource ("Edit a file by replacing one exact occurrence of old_str with new_str") and the semantics of the operation (exact single-occurrence substitution). This is unmistakably distinct from siblings like view_file, search, diff, and bash, so an agent can route to it without opening the 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 concrete recovery guidance when the precondition fails ("include more surrounding lines to make it unique") and an explicit exclusion (test files are read-only). It does not name an alternative tool for cases where a non-unique replacement is needed (e.g., bash), so it falls short of full when/when-not/alternative coverage.

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