wisp-mcp

safe_write_file

DestructiveIdempotent

Overwrite an existing text file only when its current SHA-256 matches the expected hash, then verify the stored result to prevent accidental or conflicting changes.

Instructions

Overwrite an existing text file only when its current SHA-256 matches expected_sha256, then verify the stored result. Prefer this over write_file for existing files; requires WISP_ALLOW_FILE_WRITES.

Input Schema

Name	Required	Description
`path`	Yes	Path in the selected server filesystem, starting from its root.
`content`	Yes	Complete replacement UTF-8 text content.
`server_id`	No	Wisp server ID. Omit to use the configured WISP_SERVER_ID default.
`expected_sha256`	Yes	64-character SHA-256 from the most recent read or fingerprint of the same file.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv1.4.2Nov 4, 2026

addedInput schema / properties / content / description

Added value: +"Complete replacement UTF-8 text content."

addedInput schema / properties / expected_sha256 / description

Added value: +"64-character SHA-256 from the most recent read or fingerprint of the same file."

addedInput schema / properties / path / description

Added value: +"Path in the selected server filesystem, starting from its root."

addedInput schema / properties / server_id / description

Added value: +"Wisp server ID. Omit to use the configured WISP_SERVER_ID default."

First observedv1.4.1Aug 17, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Beyond the write/destructive annotations, it discloses the optimistic-concurrency guard, verification of the stored result, and the WISP_ALLOW_FILE_WRITES requirement. These details explain both the safety mechanism and an operational prerequisite, and they do not conflict with the annotations.

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?

Two compact sentences front-load the operation and guard, then provide selection and configuration guidance. There is no filler or redundant enumeration of schema 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?

Together with the complete input schema, output schema, and annotations, the description supplies nearly everything needed for safe selection and invocation. Naming read_file or file_fingerprint as concrete hash sources and stating how mismatch or verification failures are reported would make the workflow slightly more complete.

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 coverage is 100%, so parameter formats, sources, and defaults are already documented. The description adds meaningful context by explaining that expected_sha256 is checked against the file's current hash as a write precondition, rather than merely being a 64-character value from a prior read or fingerprint.

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?

The description specifies the operation and resource—overwriting an existing text file—and identifies its defining SHA-256 precondition and post-write verification. It also distinguishes the tool from its closest sibling, write_file.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Prefer this over write_file for existing files" gives explicit when-to-use guidance and names the alternative. Limiting the operation to existing files also signals that this is not the general choice for creating a new file.

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