cmdshellmcp

Overview Schema Source Related Servers Discussions Admin

Editfile

editFile

Edits existing local text files with sed expressions while creating numbered backups and returning unified diffs. Restricts changes to the configured directory and removes the backup if sed fails.

Instructions

Edits an existing local text file using a sed expression/program.

Args: file: Local path of the file to edit, limited to the configured current directory and its descendants. script: The authoritative sed editing expression/program. args: Optional safe sed arguments. Options that enable in-place editing, supply another expression or program file, select other files, or execute commands are not allowed.

Before editing, the tool creates the next available numbered backup (.bk1, .bk2, .bk3, and so on), and never overwrites an existing backup. The source file is replaced only after sandboxed sed completes successfully. On success, the response contains a diff -u unified diff from the backup/original version to the edited file. If sed fails while the original is unchanged, the newly created backup is removed. When --editdelbk or config editdelbk is enabled, a successful edit's backup is deleted only after the unified diff response has been composed.

Example: file="src/example.py", script="s/old_name/new_name/g". The resulting backup might be src/example.py.bk1.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`args`	No
`file`	Yes
`script`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.1Oct 12, 2026

TDQS

A4.3/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and does so thoroughly: numbered backup creation (.bk1, .bk2) that never overwrites, source replaced only after sandboxed sed succeeds, backup rolled back on failure, unified diff output on success, and the conditional backup deletion under --editdelbk. These are exactly the destructive-operation details an agent needs.

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?

The tool's operation is front-loaded in the first sentence and every following block (args constraints, backup lifecycle, example) carries real information. It is dense and somewhat long, but the length is justified by the mutation semantics rather than padding.

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?

An output schema exists, yet the description still flags the diff -u return format, and it covers constraints, failure handling, and backup lifecycle for a destructive, annotation-free, zero-coverage-schema tool. Nothing essential to calling it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate, and it does: file is defined as a path confined to the configured current directory, script is described as the authoritative sed program, and args is bounded by an explicit list of disallowed option classes (in-place, extra expressions/program files, other files, command execution). The example clarifies script syntax.

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 and resource with the operative mechanism: 'Edits an existing local text file using a sed expression/program.' The word 'existing' usefully distinguishes it from a whole-file creator like writeFile, but no sibling is named explicitly, so an agent must infer the boundary with writeFile/applyPatch.

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?

'Edits an existing local text file' plus the note that file is 'limited to the configured current directory and its descendants' implies scope constraints, so usage is partly implied. However, there is no explicit when-to-use vs writeFile, applyPatch, or cmdshell, and no stated prerequisites beyond existence.

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

Deploy Server