PaperDock

Edit a text project file

edit_file

Destructive

Immediately edit one existing editable text file and record the applied change in PaperDock's Review changes UI. Provide exactly one target (fileId or path) and exactly one payload: operations, content, or rangeToken with insert. Read the relevant current text first and pass its baseRevision. For a long replacement covering every line returned by an exact read_file.lineRange call, pass its rangeToken with insert; the token is connection-, file-, revision-, range-, and content-bound and expires after 10 minutes. For other focused edits, use sequential UTF-16 operations and copy expectedText exactly from read_file without retyping, normalization, spelling correction, or manual Unicode escaping; insertions use expectedText: "". On a target or history conflict, read again and retry once. Use content only when broadly rewriting most of the file. This tool cannot create, rename, or delete files. Supply a stable requestId for each logical edit and reuse it with the identical payload after a timeout or response loss. Use a new ID after rereading and changing the edit. When apply sessions are enabled, unrelated intervening edits may merge within this call; overlaps, ambiguous insertion order, or unavailable history require a new read. FILE_APPLY_BUSY, FILE_APPLY_LOCKED, and FILE_APPLY_DRAIN_TIMEOUT are temporary deferrals; retry the identical request after synchronization. FILE_APPLY_OUTCOME_UNKNOWN or FILE_APPLY_IN_PROGRESS means the result is being checked, not that nothing was saved: retry with the same requestId. AGENT_REVIEW_RELOAD_REQUIRED needs the user to save or finish earlier Keep/Revert decisions; do not repeatedly retry. FILE_APPLY_DISABLED temporarily stops new AI edits while existing request outcomes remain available. Keep retries bounded. Legacy clients without requestId use a deterministic payload ID. Full rewrites and history replay have bounded sizes and may require a smaller edit or a fresh read.

Input Schema

Name	Required	Description
`path`	No
`fileId`	No
`insert`	No
`content`	No
`projectId`	Yes
`requestId`	No	Stable identifier for this logical edit; reuse unchanged on transport retries.
`operations`	No
`rangeToken`	No
`baseRevision`	Yes
`expectedUpdatedAt`	No

Output Schema

Name	Required	Description	Default
`file`	Yes
`merged`	No
`requestId`	No
`duplicateCommit`	No
`applicationStatus`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedNov 3, 2026

addedInput schema / properties / requestId

Added value: +{
+  "description": "Stable identifier for this logical edit; reuse unchanged on transport retries.",
+  "maxLength": 128,
+  "minLength": 1,
+  "pattern": "^[A-Za-z0-9._:-]+$",
+  "type": "string"
+}

addedOutput schema / properties / duplicateCommit
```
Added value: +{
+  "type": "boolean"
+}
```
addedOutput schema / properties / merged
```
Added value: +{
+  "type": "boolean"
+}
```
addedOutput schema / properties / requestId
```
Added value: +{
+  "type": "string"
+}
```

First observedSep 8, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Beyond the annotations, the description discloses substantial behavior: the edit is applied immediately, the change is recorded for review, rangeTokens are bound to connection/file/revision/range/content and expire after 10 minutes, apply sessions can merge unrelated edits, and specific error codes indicate temporary deferral versus unknown outcomes. This is unusually rich behavioral disclosure for a destructive mutation tool.

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 definition is front-loaded and nearly every sentence carries operational meaning, including retry and error-handling rules. However, the single dense paragraph, long error-code sequence, and compressed terminology make it harder to scan than it could be with lighter structure.

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 complex destructive edit tool with ten parameters and many failure modes, the description covers the critical workflow, conflict handling, idempotency, review integration, and retry semantics. An output schema exists, so return-value explanation is not required, and the remaining gaps are minor relative to the complexity addressed.

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 description coverage is only 10%, so the description has to carry most parameter meaning. It successfully explains the exactly-one target rule for fileId or path, the exactly-one payload rule for operations, content, or rangeToken with insert, the role of baseRevision, exact expectedText copying, empty expectedText for insertions, and stable requestId reuse. It leaves projectId, expectedUpdatedAt, and precise from/to boundary semantics unstated.

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 opens with a specific verb and resource: immediately edit one existing editable text file. It also states the side effect of recording the change in PaperDock's Review changes UI, and it explicitly excludes create, rename, and delete, which distinguishes it from sibling tools such as create_file and rename_file.

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?

It gives explicit selection rules among the payload alternatives: use rangeToken with insert for a long replacement from an exact read_file.lineRange call, operations for other focused edits, and content only when broadly rewriting most of the file. It also tells the agent to read first and pass baseRevision, and it explains when to reread instead of retrying blindly.

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

All PaperDock tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?