Skip to main content
Glama
Sign In
sangingeum

filekeeper-mcp

by sangingeum
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

file_replace_text

Destructive

Replace literal text in files with staged exact or normalized matching, first/all replacement, and an undoable operation ID.

Instructions

Replace literal text and return operation_id, undo_available and the match stage.

    Matching is staged and the result always names the stage: exact first,
    then normalised (indentation and trailing whitespace tolerated, the
    replacement re-based onto the matched indentation), then a NO_MATCH
    refusal carrying the nearest candidate lines. match is required and is
    either first or all; there is no default policy. match_count reports the
    matches found, expected_match_count refuses a different number, and
    expected_content pins the exact text of one region.

Input Schema

NameRequiredDescriptionDefault
newYes
oldYes
pathYes
matchYesreplacement policy: 'first' or 'all'
dry_runNo
expected_hashNo
expected_contentNo
expected_match_countNo
i_accept_secret_write_riskNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.8

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already flag destructiveHint=true and idempotentHint=false, and the description adds real value on top: the staged exact-then-normalised matching ladder, the re-basing of replacement onto matched indentation, and the NO_MATCH refusal that returns nearest candidate lines. It omits any mention of the i_accept_secret_write_risk gate, which is a meaningful behavioral precondition an agent should know about before calling.

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?

The first sentence front-loads purpose and return values, then the staged-matching and guard-parameter details follow in a compact block. No filler sentences and no repetition of what the schema already declares.

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?

For a 9-parameter destructive write tool with no output schema, the description covers matching semantics and the return fields well. It falls short on the safety-relevant parameters (dry_run, expected_hash, i_accept_secret_write_risk) that an agent would need in order to invoke this tool responsibly.

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 only 11% across 9 parameters, so the description carries most of the burden. It explains match (required, first/all, no default), match_count, expected_match_count and expected_content, but leaves dry_run, expected_hash and especially i_accept_secret_write_risk entirely undefined even though their names are not self-explanatory in a destructive context.

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 and resource ('Replace literal text') and names the return payload (operation_id, undo_available, match stage). It does not explicitly distinguish itself from the sibling file_replace_lines or file_apply_patch, so an agent must infer that this tool operates on literal strings rather than line numbers or patches.

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?

It states that match is required with no default policy and enumerates the two policies, which is genuinely useful selection guidance. However, it never says when to choose this over file_replace_lines or file_apply_patch, nor when to prefer dry_run before committing a destructive edit.

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