Skip to main content
Glama
patchloom

Patchloom

Official
by patchloom
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Rust
Local

batch_replace

Destructive

Replace the same text across multiple files in one atomic call, with optional fuzzy matching and per-file match counts to reveal hits or misses.

Instructions

Replace the same text across multiple files in one call. Engine staging is atomic for applied writes (all written files succeed or none change). Pattern misses are soft by default: matching files still apply and total misses appear in refused[]; set require_change=true to fail the whole batch if any file has no match. Canonical field is files (array); singular file is accepted as an alias for one path. Optional fuzzy enables similarity fallback; when exact old is absent, refuse by default unless allow_absent_old=true (#1758). JSON reports match_mode (exact/fuzzy/anchored), optional match_score, optional matched_text, match_count per change and aggregate (#1674). Example: {"files": ["Cargo.toml", "README.md"], "old": "0.1.0", "new": "0.2.0"}

Input Schema

NameRequiredDescriptionDefault
newYesText to replace with. Alias `to` accepted because agents often emit that name (LLM prior).
oldYesText to find in each file. Alias `from` accepted because agents often emit that name (LLM prior).
fileNoSingle file (LLM prior). Equivalent to `files: [file]` when `files` is empty. If both are set, `files` wins. Alias `path` matches replace_text priors.
filesNoFile paths to apply the replacement to (relative to working directory). Canonical multi-file form.
fuzzyNoWhen exact match fails, try fuzzy/similarity fallback (#1668).
regexNoUse regex mode for the `old` pattern.
strictNoRoll back all writes when format/validate lifecycle steps fail.
if_existsNoIf true, silently succeed when a file does not contain the pattern instead of returning an error. Useful for idempotent batch replacements.
multilineNoEnable multiline matching (dot matches newlines in regex mode).
word_boundaryNoMatch only at word boundaries. Prevents 'SetupFile' from matching inside 'BenchSetupFile'. Auto-escapes regex metacharacters.
require_changeNoFail when a file has zero matches (fail closed). Softened when if_exists is true.
min_fuzzy_scoreNoReject fuzzy matches below this similarity floor (#1687). `None` = no floor.
allow_absent_oldNoAllow fuzzy apply when exact `old` is absent (#1758). Default false (fail closed; report best candidate without writing).
case_insensitiveNoCase-insensitive matching.
command_positionNoOnly rewrite shell command-position tokens (not arguments / longer words). Peels wrappers like sudo, timeout, busybox, flock, runuser, setsid.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.32.0

TDQS

A4.1/5.0
Behavior5/5

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

Annotations only say this is a destructive, non-read-only write; the description adds the substantive traits an agent needs: engine staging is atomic for applied writes (all succeed or none change), misses are soft by default, absent `old` refuses by default, and the JSON report shape (match_mode, match_score, matched_text, match_count, refused[]). That is real disclosure beyond the annotation layer.

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-loaded with purpose and the atomicity guarantee, then behavior, then example — good ordering with no filler sentences. The inline issue references (#1758, #1674, #1668, #1687) are clutter that costs tokens without helping the agent.

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?

For a 15-parameter destructive tool with no output schema, the description covers the essentials: atomicity semantics, default failure policy, opt-in flags, alias precedence, and the shape of the returned JSON including the refused[] miss channel. An agent has enough to call it correctly without opening the schema.

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 baseline is 3, and most description content (files vs file alias, fuzzy, allow_absent_old, require_change) restates what the schema already documents. The one genuine addition is the worked example showing a minimal valid call, which alone does not lift it above baseline.

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?

Opens with a specific verb + resource + scope: 'Replace the same text across multiple files in one call,' which immediately separates it from single-file replace_text and from patch-style siblings. It never names the alternative tool explicitly, so the distinction is inferred from 'multiple files' rather than stated.

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 conditional guidance for the important switches: soft-miss default with require_change=true to fail the whole batch, and refuse-by-default when exact `old` is absent unless allow_absent_old=true. It does not, however, tell the agent when to pick batch_replace over replace_text or apply_patch, so tool selection is left implicit.

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