Skip to main content
Glama
Sign In
sangingeum

filekeeper-mcp

by sangingeum
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

file_write

Destructive

Replace an entire file atomically with new content, using expected hash and dry-run checks to prevent conflicts. Returns an operation ID and undo availability.

Instructions

Replace a whole file with new content and return operation_id and undo_available.

    The replacement is atomic: a crash leaves the complete previous content.
    expected_hash guards against clobbering a file that changed since it was
    read; a mismatch is CONTENT_CONFLICT and nothing is written. The file's
    encoding and byte-order mark are inherited unless encoding is named.
    Credential-shaped targets are refused unless i_accept_secret_write_risk
    is true. dry_run validates and writes nothing. Otherwise the operation is
    recorded and undoable. Not idempotent: each successful call adds a
    history record.

Input Schema

NameRequiredDescriptionDefault
pathYes
contentYes
dry_runNo
encodingNo
expected_hashNo
i_accept_secret_write_riskNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.8

TDQS

A4.1/5.0
Behavior5/5

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

The description adds substantial behavioral context beyond annotations: atomic replacement, CONTENT_CONFLICT behavior on hash mismatch, encoding/BOM inheritance, credential-shaped target refusal, dry-run semantics, undoability, and non-idempotence with history records. It is fully consistent with destructiveHint=true and idempotentHint=false.

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 description is front-loaded with the core action, then layers in atomicity, conflict handling, encoding, secret refusal, dry-run, undo, and idempotence. Each sentence adds useful operational detail without repetition or fluff.

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?

For a complex destructive write operation with no output schema, the description is substantially complete: it describes the return values (operation_id and undo_available), safety behavior, and conflict handling. The main remaining gap is lack of explicit sibling routing and path-creation semantics.

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?

With 0% schema description coverage, the description carries the burden and explains the non-obvious parameters: expected_hash, encoding, dry_run, and i_accept_secret_write_risk. It does not add details for path or content, such as whether the target must already exist or whether parent directories are created, but the main behavioral parameters are well covered.

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?

The description states a specific verb and resource: 'Replace a whole file with new content.' The word 'whole' distinguishes it from partial-edit siblings such as file_replace_text and file_apply_patch, though it does not explicitly name those alternatives.

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 explains key operating conditions, including expected_hash for conflict avoidance, dry_run validation, and secret-target refusal. However, it does not explicitly say when to use file_write instead of file_create, file_replace_text, or file_apply_patch, so the agent must infer the boundary from the phrase 'whole file.'

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