Alcoven

Change documents

edit_document

Destructive

Changes, fixes or rewrites passages in documents and text files (a typo, a sentence, a paragraph, a figure), up to eight edits at once: each edit names a passage copied exactly (without line numbers), found there exactly once, what it becomes, and one line on why. The person sees every edit and confirms it in this AI tool before anything changes. Clients that cannot show that confirmation get a preview and a proposal id instead, and nothing changes until the proposal is confirmed. Files that are not text are not changed here: they get a new version by upload in Alcoven.

Input Schema

Name	Required	Description
`did`	No	What the person did themselves in this work, in a few words they agree with: what they chose or decided, what they corrected, rewrote or wrote, what they checked and against what. Start with the verb, in the past tense, in their language: "Chose the three-step plan; fixed the March totals; rewrote the opening". Say nothing of what you did, what they did not do, how long it took, or a share of the work. Pass no did when their part was the request and the yes. Everyone who sees the change reads it, people outside the team included. At most 300 characters.
`read`	No	The § addresses you read for this work, kept with asked. Alcoven adds what it saw you read on this project since you last wrote on it, going back two hours at most.
`asked`	No	What the person asked for, in their own words, as they said it: their request only, never the rest of the conversation, and left out when they do not want it shared. It goes on the project with the change, so everyone who sees the change, and their AIs, see why it was made.
`edits`	Yes
`project`	No	The project's slug, from open_project, like acme. Not needed when a § address names the project, or when the person is on one project.
`summaries`	No	For a document whose meaning changed: its new summary in one or two sentences.
`asked_from`	No	Where the request came from, when the person says so, in a few words: "Tuesday's call with the bank", "Ines's email".

Output Schema

Name	Required	Description	Default
`writes`	No
`applied`	Yes
`preview`	No
`proposal`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 26, 2026

addedInput schema / properties / did

Added value: +{
+  "description": "What the person did themselves in this work, in a few words they agree with: what they chose or decided, what they corrected, rewrote or wrote, what they checked and against what. Start with the verb, in the past tense, in their language: \"Chose the three-step plan; fixed the March totals; rewrote the opening\". Say nothing of what you did, what they did not do, how long it took, or a share of the work. Pass no did when their part was the request and the yes. Everyone who sees the change reads it, people outside the team included. At most 300 characters.",
+  "maxLength": 300,
+  "type": "string"
+}

First observedOct 22, 2026

TDQS

A4.1/5.0

Behavior5/5

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

Annotations declare destructiveHint=true and readOnlyHint=false, so the agent already knows this mutates data; the description adds the crucial qualifier that the mutation is human-gated — 'The person sees every edit and confirms it in this AI tool before anything changes.' It also discloses the degraded path (preview plus proposal id, nothing changes until confirmed) and the exact-match-once constraint on find. That is behavior an agent cannot infer from the annotations.

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 operation and scale ('up to eight edits at once') and closes with the non-text exclusion, so the important routing information sits at both ends. The middle sentences are dense and slightly run-on, and the restatement of the edits sub-fields duplicates schema content that could have been cut.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists and the input schema is rich, so the description needn't explain return values — and it doesn't. It correctly covers the mutation-confirmation model and the text-only scope, which are the two things an agent could get wrong. The attribution parameters (did, asked, asked_from, read) carry elaborate schema prose but get no framing in the description at all.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 86%, so the schema already documents all seven parameters thoroughly, including the did/read/asked attribution fields. The description paraphrases the edits object's four sub-fields (find copied exactly without line numbers, appearing once, the replacement, a one-line why) but adds no guidance for the other parameters. Baseline 3 applies when structured fields do the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Changes, fixes or rewrites passages in documents and text files') and enumerates the granularity (typo, sentence, paragraph, figure). The final sentence carves out a distinct resource boundary — non-text files are not changed here. What it doesn't do is differentiate from the sibling apply_edits, which reads like the same operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete operating conditions: up to eight edits at once, and a clear exclusion for non-text files, which are routed elsewhere ('they get a new version by upload in Alcoven'). The confirmation path is spelled out for both capable and incapable clients. It stops short of naming apply_edits or explaining when an agent should prefer that sibling over this one.

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

All Alcoven tools Inspect

Try in Browser

Pay for results, not tokens.Fund a bounty. Let AI agents compete and collaborate to solve your problems.agentbounties.appAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?