Tools for agents: Guarded text edit application

Apply multiple checked replacements to text with stale-content guards, overlap rejection and result offsets.

Connect with MCP

{
  "mcpServers": {
    "super-agent-tools": {
      "url": "https://app.getsupers.com/sites/agent-text-edits/mcp"
    }
  }
}
Streamable HTTP · No API key · Stateless

Use this URL in any client supporting remote Streamable HTTP MCP. Calls return structured JSON; inputs are processed without persistence.

Call apply_guarded_text_edits

All start/end offsets refer to the original document, use zero-based Unicode code points, and are half-open. Inputs may arrive in any order; edits are applied in increasing original offset order. expected must equal the complete original slice exactly, including whitespace. Any mismatch, invalid range or overlap fails the entire call without a partial result. Insertions use start=end and expected empty. Two edits sharing a start are rejected as ambiguous, including insertion plus replacement; an insertion at the preceding replacement end is permitted when starts differ. Adjacent replacements are permitted. No Unicode normalization, newline conversion, fuzzy matching or file access occurs. Empty edits return the unchanged text. applied gives each original input index and its result span, in application order. SHA-256 values hash UTF-8 text without a BOM added by the tool. This returns transformed text; it does not edit a repository or file. Use the Unicode span tool to convert UTF-8/UTF-16 offsets first.

Input and output schemas
{
  "name": "apply_guarded_text_edits",
  "title": "Guarded text edit application",
  "description": "Apply nonoverlapping half-open replacements after validating every original-text guard. Offsets are Unicode code points, all relative to the original text. No filesystem writes.",
  "inputSchema": {
    "$defs": {
      "TextEdit": {
        "properties": {
          "start": {
            "title": "Start",
            "type": "integer"
          },
          "end": {
            "title": "End",
            "type": "integer"
          },
          "expected": {
            "title": "Expected",
            "type": "string"
          },
          "replacement": {
            "title": "Replacement",
            "type": "string"
          }
        },
        "required": [
          "start",
          "end",
          "expected",
          "replacement"
        ],
        "title": "TextEdit",
        "type": "object"
      }
    },
    "properties": {
      "text": {
        "title": "Text",
        "type": "string"
      },
      "edits": {
        "items": {
          "$ref": "#/$defs/TextEdit"
        },
        "title": "Edits",
        "type": "array"
      }
    },
    "required": [
      "text",
      "edits"
    ],
    "title": "apply_guarded_text_editsArguments",
    "type": "object"
  },
  "outputSchema": {
    "additionalProperties": true,
    "title": "apply_guarded_text_editsDictOutput",
    "type": "object"
  },
  "icons": null,
  "annotations": {
    "title": null,
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "meta": null,
  "execution": null
}

Run the example to see the actual result.

HTTP alternative

POST https://app.getsupers.com/sites/agent-text-edits/call
Content-Type: application/json

{
  "text": "alpha beta gamma",
  "edits": [
    {
      "start": 0,
      "end": 5,
      "expected": "alpha",
      "replacement": "A"
    },
    {
      "start": 11,
      "end": 16,
      "expected": "gamma",
      "replacement": "G"
    }
  ]
}

The HTTP and MCP interfaces execute the same implementation. Validation errors are returned explicitly. See the tool notes above for its supported inputs and behavior.

Guarded replacements use original Unicode positions

Read the explanation

The documented example starts with alpha, beta, gamma separated by spaces: sixteen Unicode code points. It targets alpha at zero through five, and gamma at eleven through sixteen. Ends are excluded. Every expected string must equal its full original slice, including whitespace. All ranges refer to the original document, even when inputs arrive out of order. This explanation follows the exposed contract; the offline preview does not execute the remote tool. Replace alpha with A and gamma with G. Each substitution removes four code points, so sixteen becomes eight. The first result span is zero through one. After that four-point shift, the second original span eleven through sixteen becomes result span seven through eight. The reported application order follows increasing original offset and retains the original input index. No file is written; transformed text is returned. A stale guard, invalid range or overlapping edit fails the entire call. Two edits with the same start are ambiguous, including an insertion sharing a replacement start. Adjacent replacements are permitted, and an insertion at a preceding replacement end is permitted when starts differ. Insertions have equal start and end with empty expected text. No normalization or fuzzy matching occurs. Returned hashes cover UTF eight text without an added byte order mark; they do not authorize a repository change.

Understanding Guarded Text Edit Application

How does guarded text editing guarantee safe simultaneous replacements across original document offsets?

The apply_guarded_text_edits tool takes an original string alongside a list of proposed replacements, each defined by half-open Unicode code point offsets [start, end) and an expected original slice. Before changing any text, it verifies every expected guard against the original text, rejects unpaired surrogates, sorts edits into ascending offset order, and ensures no two edits overlap or start at identical positions. If every guard passes, it reconstructs the string sequentially and outputs the transformed text, SHA-256 hashes, and mapped result spans without modifying files or repositories.

All offsets must be measured in 0-indexed Unicode code points (scalar values) relative strictly to the original input string. The tool performs exact binary string equality without newline normalization, fuzzy matching, case folding, or repository write capabilities. Overlapping ranges or conflicting simultaneous insertions at the same start index abort the entire call without returning partial modifications.

Try a worked example

Leaving the preset arguments unchanged ("alpha beta gamma" with edits replacing [0, 5) "alpha" with "A" and [11, 16) "gamma" with "G"), clicking 'Run tool' executes the validation pass. Because both slices match exactly and neither overlaps, the Structured result panel populates with transformed text "A beta G", original_length 16, result_length 8, and an applied array detailing input_index 0 mapped to result span [0, 1) and input_index 1 mapped to result span [7, 8).

All-or-Nothing Guard Validation

Before concatenating chunks, the engine verifies that each start and end boundary satisfies 0 <= start <= end <= len(text). It inspects each slice text[start:end] to ensure byte-for-byte and character-for-character equality with the expected string. Any mismatch triggers an immediate error, protecting agents against applying edits to stale file states.

Insertions are represented by setting start equal to end with an empty expected string. While multiple edits can be adjacent, two edits sharing an identical start offset are rejected as ambiguous, preventing undefined ordering between consecutive insertions.

Application Order and Result Offset Tracking

Edits can be submitted in arbitrary order within the input array. The routine preserves the original input_index while sorting operations by (start, end). As replacement slices expand or shrink text length, it tracks cumulative length offsets and returns result_start and result_end for each applied edit.