wisp-mcp

replace_in_file

DestructiveIdempotent

Replace an exact text snippet in a file only after verifying the expected SHA-256 and match count, then confirm the edit succeeded.

Instructions

Replace an exact text snippet only when the file SHA-256 and match count are exactly as expected, then verify the result. Prefer for small edits to existing files; requires WISP_ALLOW_FILE_WRITES.

Input Schema

Name	Required	Description
`new`	Yes	Replacement text.
`old`	Yes	Exact existing text to replace.
`path`	Yes	Path in the selected server filesystem, starting from its root.
`server_id`	No	Wisp server ID. Omit to use the configured WISP_SERVER_ID default.
`expected_count`	No	Exact number of old-text matches required before editing.
`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.

Changed9 schema fields changedv1.4.2Nov 4, 2026
- addedInput schema / properties / expected_count / description
```
Added value: +"Exact number of old-text matches required before editing."
```
- addedInput schema / properties / expected_count / maximum
```
Added value: +100
```
- addedInput schema / properties / expected_count / minimum
```
Added value: +1
```
- 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 / new / description
```
Added value: +"Replacement text."
```
- addedInput schema / properties / old / description
```
Added value: +"Exact existing text to replace."
```
- addedInput schema / properties / old / minLength
```
Added value: +1
```
- 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/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=false, so the mutation profile is known. The description adds real value on top: the edit is conditional on an exact SHA-256 and match-count check, the result is verified afterward, and an environment permission (WISP_ALLOW_FILE_WRITES) gates the call.

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 sentences, zero filler. The safety precondition comes first and the use-case preference plus permission requirement follow, so the agent gets the critical constraint immediately.

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 destructive edit tool with an output schema and full annotation coverage, the definition supplies the guard conditions, the permission prerequisite, and the intended use case. It leaves mismatch behavior (error vs. no-op) implicit, but the verify-and-guard framing plus the output schema covers most of what an agent needs.

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 every parameter is already documented, including expected_sha256's provenance and expected_count's exact-match requirement. The description restates the guard semantics at a high level rather than adding new per-parameter meaning, so baseline 3 applies.

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?

States a specific verb ('Replace') plus resource ('exact text snippet') and the atomic precondition (SHA-256 + match count must match exactly). It hints at the sibling distinction with 'Prefer for small edits to existing files', which implicitly contrasts with whole-file writes, but never names write_file or safe_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 Guidelines4/5

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

'Prefer for small edits to existing files' gives a clear selection context versus full-file write tools, and 'requires WISP_ALLOW_FILE_WRITES' states a hard prerequisite. It stops short of naming alternatives or saying when not to use it (e.g. multi-match or large rewrites).

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