Skip to main content
Glama
Negm-Ahmed

Desktop Commander

by Negm-Ahmed
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

edit_block

Apply surgical text replacements to files with precision. Replace specific text strings within a file path to modify content at exact locations.

Instructions

                    Apply surgical text replacements to files.
                    
                    BEST PRACTICE: Make multiple small, focused edits rather than one large edit.
                    Each edit_block call should change only what needs to be changed - include just enough 
                    context to uniquely identify the text being modified.
                    
                    Takes:
                    - file_path: Path to the file to edit
                    - old_string: Text to replace
                    - new_string: Replacement text
                    - expected_replacements: Optional parameter for number of replacements
                    
                    By default, replaces only ONE occurrence of the search text.
                    To replace multiple occurrences, provide the expected_replacements parameter with
                    the exact number of matches expected.
                    
                    UNIQUENESS REQUIREMENT: When expected_replacements=1 (default), include the minimal
                    amount of context necessary (typically 1-3 lines) before and after the change point,
                    with exact whitespace and indentation.
                    
                    When editing multiple sections, make separate edit_block calls for each distinct change
                    rather than one large replacement.
                    
                    When a close but non-exact match is found, a character-level diff is shown in the format:
                    common_prefix{-removed-}{+added+}common_suffix to help you identify what's different.
                    
                    Similar to write_file, there is a configurable line limit (fileWriteLineLimit) that warns
                    if the edited file exceeds this limit. If this happens, consider breaking your edits into
                    smaller, more focused changes.
                    
                    IMPORTANT: Always use absolute paths for reliability. Paths are automatically normalized regardless of slash direction. Relative paths may fail as they depend on the current working directory. Tilde paths (~/...) might not work in all contexts. Unless the user explicitly asks for relative paths, use absolute paths.
                    This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.

Input Schema

NameRequiredDescriptionDefault
file_pathYes
new_stringYes
old_stringYes
expected_replacementsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.3

TDQS

A4.9/5.0
Behavior5/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure and does so comprehensively. It explains the default behavior (replaces only ONE occurrence), how to replace multiple occurrences, the uniqueness requirement for context, what happens with non-exact matches (character-level diff shown), line limit warnings similar to write_file, and path handling requirements. This provides rich behavioral context beyond basic parameter documentation.

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 description is well-structured with clear sections and front-loaded information, but could be slightly more concise. The core purpose is stated immediately, followed by best practices, parameter explanations, behavioral details, and important notes. While every sentence adds value, some redundancy exists (e.g., path guidance appears in multiple places). Overall, it's efficiently organized but not maximally concise.

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?

Given the tool's complexity (file editing with precise text replacement), lack of annotations, and no output schema, the description provides complete contextual information. It covers purpose, usage guidelines, all parameters, behavioral characteristics, error conditions, best practices, and even references to related tools. This gives the AI agent everything needed to select and invoke this tool correctly for surgical text replacements.

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?

With 0% schema description coverage, the description fully compensates by explaining all parameters in detail. It clearly defines file_path, old_string, new_string, and expected_replacements with their meanings, default values, and usage implications. The description adds significant value beyond the bare schema by explaining how these parameters interact (e.g., how expected_replacements affects the replacement behavior) and providing practical guidance on their use.

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 clearly states the tool's purpose: 'Apply surgical text replacements to files.' This is a specific verb ('apply surgical text replacements') + resource ('files') combination that distinguishes it from sibling tools like write_file (which creates/overwrites entire files) or read_file (which only reads). The description effectively communicates this is for targeted modifications rather than wholesale file operations.

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?

The description provides explicit guidance on when to use this tool versus alternatives. It states: 'When editing multiple sections, make separate edit_block calls for each distinct change rather than one large replacement' and references write_file as a similar tool with line limit warnings. It also gives clear 'BEST PRACTICE' recommendations for making small, focused edits and distinguishes this from broader file operations available in the sibling toolset.

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