Skip to main content
Glama

Anima MCP Server

by io.github.AnimaApp
OverviewDiscussionsAdmin

Edit Artifact Files

artifact-edit
Destructive

Change the files of an EXISTING artifact and commit them, without git or a shell. Never creates a new artifact — the sessionId keeps pointing at the same one, and its playground URL does not change. If a Canvas draft exists, this refuses unless acknowledgeCanvasDraftRevision matches the draft you reviewed and the user explicitly chose to edit committed files. It does not edit, promote or discard the draft. All the changes you pass land as ONE commit: either every operation applies or none does. Read the files first with artifact-explore and pass the revision it returned as baseRevision; if someone else changed the artifact meanwhile the edit is rejected with REVISION_CONFLICT, which lists what changed so you can re-read those files and retry. Prefer op "str_replace" for edits to existing files (send the exact snippet), "write" to create a file or replace one wholesale, "delete", and "move" to rename. move does NOT rewrite imports — neither in the files that import the moved module, nor the relative imports INSIDE the moved file, which now resolve from its new folder, so read it first and add the str_replace operations that fix them. The live preview updates from the new commit immediately. To rename an artifact or change its visibility use artifact-update_metadata; for very large repositories or full git workflows (branches, history rewriting) use artifact-get_git_token.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
changesYesUp to 20 operations, applied IN ORDER and committed together as one commit. Each path resolves against the result of the operations before it, so a str_replace listed after a move of the same file must use the new path.
sessionIdYesThe artifact session id — the last path segment of the artifact URL (e.g. "mr25vsjppVtbMx" from https://app.agentgrid.io/artifacts/mr25vsjppVtbMx), or the id from artifact-create.
baseRevisionYesThe full commit id from your most recent artifact-explore response — exact, not "HEAD" or an abbreviation, since it is what the edit is checked against. If the artifact has changed since, the edit is rejected with REVISION_CONFLICT instead of overwriting the other change.
commitMessageYesCommit message describing the change, e.g. "Change pill color to blue". Keep the first line short. Plain text only: do not add attribution trailers (Co-Authored-By, Agent-Id, Anima-Actor-*) — the server stamps those itself and rejects the edit if the message contains them.
acknowledgeCanvasDraftRevisionNoOnly after explicitly choosing to edit committed files despite a Canvas draft: pass the draft revision reported by artifact-explore. A draft based on the previous head is superseded by this commit. This does not edit or promote it.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / acknowledgeCanvasDraftRevision / description
      Previous value: -"Only after explicitly choosing to edit committed files despite a Canvas draft: pass the draft revision reported by artifact-explore. The draft is preserved and may become outdated. This does not edit or promote it."New value: +"Only after explicitly choosing to edit committed files despite a Canvas draft: pass the draft revision reported by artifact-explore. A draft based on the previous head is superseded by this commit. This does not edit or promote it."
  2. Changed1 schema field changed
    • addedInput schema / properties / acknowledgeCanvasDraftRevision
      Added value: +{
+  "description": "Only after explicitly choosing to edit committed files despite a Canvas draft: pass the draft revision reported by artifact-explore. The draft is preserved and may become outdated. This does not edit or promote it.",
+  "exclusiveMinimum": 0,
+  "maximum": 9007199254740991,
+  "type": "integer"
+}
  3. Added

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already state destructiveHint=true and readOnlyHint=false, but the description adds substantial behavior: operations are committed atomically as ONE commit, REVISION_CONFLICT occurs on staleness, the artifact URL remains unchanged, drafts are never edited/promoted/discarded, and move does not rewrite imports. It also notes the live preview updates immediately. This goes well beyond the annotations without contradicting them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but dense; every sentence addresses a distinct failure mode or usage rule (atomicity, draft handling, baseRevision conflicts, op choice, move caveat, alternatives). It front-loads the core function and scoping before diving into conditions, and there is no filler or repetition.

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?

For a complex mutation tool, the description covers inputs, ordering, atomicity, conflict handling, draft behavior, and alternatives remarkably well. The only gap is that there is no output schema and the description does not state what the successful response contains (e.g., new commit id), leaving the agent to guess the return shape. Otherwise complete.

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 100%, so the schema already documents all parameters thoroughly. The description nevertheless adds valuable operational guidance: prefer str_replace for existing files, send exact snippets, and be aware that move does not fix import paths. This is complementary but largely reinforces rather than replacing the schema's already-rich parameter documentation.

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 uses a specific verb-resource pair ('Change the files of an EXISTING artifact and commit them') and immediately scopes itself by stating it never creates a new artifact. It also names sibling tools like artifact-update_metadata and artifact-get_git_token to route away from non-file-edit operations, making it easy to distinguish from the many artifact siblings.

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?

The description explicitly says when to use this tool (editing existing artifact files without git/shell) and when not to (renaming/visibility changes → artifact-update_metadata; huge repos/full git workflows → artifact-get_git_token). It also gives a critical precondition: read files first with artifact-explore and pass the returned revision as baseRevision, plus the Canvas draft condition for acknowledgeCanvasDraftRevision. This is fully explicit guidance.

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

All Anima MCP Server toolsInspect
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