Skills MCP Server

Overview Schema Source Related Servers Discussions Admin

a11y_edit_file

Edit a project file by replacing exact text or creating a new one. Ensures JSON/Python validity, keeps a backup, and requires approval.

Instructions

Edit a file of the person's project by replacing an EXACT piece of text (old_string must appear once, or use replace_all), or create a new file (old_string empty). Read the file first with a11y_read_file and copy the piece exactly. A JSON or Python file that was valid cannot become invalid. A backup is kept before every write (undo with a11y_undo_edit). With approval ON (default, A11Y_MCP_EDIT_APPROVAL) the edit is HELD and shown as a diff until the person answers: show them the diff and then call a11y_approve_edit with THEIR answer, never on your own. With approval OFF the edit is applied at once.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "path": "<path>",
      "old_string": "<old_string>",
      "new_string": "<new_string>"
    },
    "name": "a11y_edit_file"
  }
}

Input Schema

Name	Required	Description	Default
`path`	Yes
`new_string`	Yes
`old_string`	Yes
`replace_all`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv2.1.0Oct 19, 2026

TDQS

A4.8/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: it discloses the write-time backup and undo path, the JSON/Python validity invariant ('a valid file cannot become invalid'), and the two-mode approval behavior (edit HELD as a diff by default vs applied immediately when off). These are exactly the non-obvious traits an agent cannot infer from schema.

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?

Front-loads the primary action and mode split in the first sentence, then adds prerequisites, safety and approval flow. Sentence count is high and the approval instructions are dense, but each sentence carries operational value; little is wasted.

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, so return values need no explanation. Given a 4-parameter mutation tool with zero annotation coverage, the description covers preconditions, uniqueness constraint, create-vs-edit, backup/undo, validity guarantee and approval gating — nothing an agent needs to invoke it correctly is missing.

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 0%, so the description must compensate, and it does for the critical parameters: old_string must appear exactly once (or use replace_all) and an empty old_string means create-file, which is genuinely non-obvious semantics. new_string is only implied by the replacement phrasing and path is not described, but both are near-self-evident.

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?

Specific verb (edit) plus resource (file of the person's project) with two clearly stated modes: replace an exact piece of text or create a new file via empty old_string. It is unmistakably distinct from siblings a11y_read_file (read) and a11y_undo_edit (revert), both of which it explicitly references.

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?

Explicitly prescribes reading first with a11y_read_file and copying the text exactly, tells the caller to use replace_all when the string appears more than once, and routes undo to a11y_undo_edit. The approval workflow is spelled out as a procedure (show the diff, then call a11y_approve_edit with the person's answer, never on your own).

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