Agent Workstation

Overview Schema Source Related Servers Discussions Admin

Apply changes

apply_changes

Destructive

Apply line-addressed file changes atomically by naming each action and path, using read_file revisions to safely create, edit, delete, move, or copy files.

Instructions

Apply line-addressed file changes atomically. Prefer this over apply_patch when you know the line numbers: nothing has to match. Each change names an action (create, write, edit, delete, move, copy), and a path. write is an upsert: it needs the revision read_file reported when the path exists, but may omit it when creating a missing path. edit, delete, move, and copy always need that revision; create rejects it and asserts absence. edit takes line operations (replace, delete, insert_after, insert_before) whose numbers all refer to the file as read, not to the result of earlier edits in the same call. content is whole lines: "" is zero lines and a trailing newline adds a blank line. One path per call; use apply_patch to chain several edits onto one file. Example: {"changes":[{"action":"edit","path":"app.py","revision":"","edits":[{"op":"replace","start_line":10,"end_line":12,"content":"new line"}]}]}

Input Schema

TableJSON Schema

Name	Required	Description
`changes`	Yes	One entry per file, at least one. A path may appear once per call; use apply_patch to chain several edits onto one file. The whole request must fit in 1 MiB, so keep it to roughly 20 files per call.
`dry_run`	No
`idempotency_key`	No	Names this exact request so a retry after a lost response replays the recorded result (flagged idempotent_replay) instead of doing the work twice. Use a new key for new work: the key is bound to the arguments that first used it, and reusing it with any other argument — including a different dry_run — is refused with IDEMPOTENCY_KEY_REUSED. Only a successful non-dry-run result is recorded, and only the 64 most recently used keys are kept across all tools.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`ok`	Yes
`clean`	No
`error`	No
`dry_run`	No
`summary`	No
`removals`	No
`warnings`	No
`additions`	No
`affected_files`	No
`already_applied`	No
`idempotent_replay`	No
`revision_algorithm`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.1Sep 13, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only supply destructiveHint/idempotentHint flags; the description goes well beyond them with atomicity, per-action revision requirements, the REVISION_MISMATCH refusal for stale files, the create-asserts-absence rule, and the fact that a path may appear only once per call. It correctly aligns with destructiveHint=true (write/edit/delete/move operations) and does not contradict idempotentHint=false (the idempotency_key is an opt-in replay mechanism, not inherent idempotence).

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-loaded with the core purpose and the sibling routing decision, then dense per-action rules, and it closes with a concrete example. Efficient overall, though some sentences restate revision rules already carried in the schema property descriptions.

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?

For a 3-parameter, nested, destructive multi-file mutation tool with annotations and an output schema, the description covers atomicity, revision/auth preconditions, error codes, per-action semantics, and the request-size envelope. An agent has everything needed to call it correctly.

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 moderate (67%), and the description compensates by explaining which actions require vs. reject revision, that create asserts absence, and the whole-lines semantics of content ('' is zero lines, trailing newline adds a blank line). It also duplicates some schema text (line numbers refer to file as read) and provides a worked example, so it adds value but is partly redundant with the schema.

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?

States a specific verb+resource ('Apply line-addressed file changes atomically') and immediately distinguishes itself from the sibling apply_patch by naming the selection condition (when you know the line numbers). An agent can pick between the two without opening either schema.

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?

Explicit when-to-use ('prefer this over apply_patch when you know the line numbers') and when-not ('use apply_patch to chain several edits onto one file'), plus the constraint that paths appear once per call. Both the alternative and the switching condition are named.

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