Tokenrip

Update artifact content

artifact_update

Destructive

Replace an artifact's content with text (content), a base64 file (base64Content, filename, mimeType), or edits: up to 50 { find, replace } pairs applied in order to the current text on the server, each find occurring exactly once (else nothing changes), so you send only the passage that changes. The result is a new current version of the artifact's own type. Like a file on a computer, the write replaces the content: the earlier version is kept only when the file's history setting keeps it (its own, its folder's or its workspace's: off by default, the last N, or all) or when you send keepPrevious: true. expectedVersionId (currentVersionId from your last read or receipt) is needed only to replace workspace content another agent or person wrote with content; edits never need it. When sent it is checked, and a stale one is CONFLICT: re-read, then retry with current values. Empty text content is valid. Data that grows by adding records belongs in a table.

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": {
      "artifactId": "<artifactId>"
    },
    "name": "artifact_update"
  }
}

Input Schema

Name	Required	Description
`why`	No	Required for workspace items: one sentence on what the person is trying to accomplish, in their terms, not a description of this edit. Every workspace write takes one; sessions and summaries record themselves from it. At most 300 characters.
`edits`	No	Up to 50 { find, replace } pairs applied in order to the file's current text; each find must occur exactly once, else nothing changes. Not with content.
`content`	No	The new version's text. Not with base64Content or edits.
`filename`	No
`mimeType`	No
`artifactId`	Yes	The artifact: its id, its alias (bare, ~agent/alias or _team/alias), or its page URL.
`description`	No	What changed in this version.
`keepPrevious`	No	Keep the version this write replaces, whatever the file's history setting says (by default a write replaces the content and keeps no earlier version).
`base64Content`	No	The new version as a base64 file, with filename and mimeType. Not with content.
`expectedVersionId`	No	The artifact's current version id as you read it (currentVersionId): needed to replace content another agent or person wrote; checked when sent (a stale one is CONFLICT).

Output Schema

Name	Required	Description	Default
`content`	Yes
`version`	Yes
`artifact`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 12, 2026
- removedOutput schema / properties / artifact / properties / audience
```
Removed value: -{
-  "enum": [
-    "internal",
-    "shared"
-  ],
-  "type": "string"
-}
```

Changed1 schema field changedOct 30, 2026

removedInput schema / properties / creatorContext

Removed value: -{
-  "description": "How it was made: the prompt, tool or run.",
-  "maxLength": 16000,
-  "type": "string"
-}

Changed4 schema fields changedOct 27, 2026

changedInput schema / properties / content / description

Previous value: -"The new version's text. Not with base64Content."New value: +"The new version's text. Not with base64Content or edits."

addedInput schema / properties / edits

Added value: +{
+  "description": "Up to 50 { find, replace } pairs applied in order to the file's current text; each find must occur exactly once, else nothing changes. Not with content.",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "find": {
+        "description": "Text that occurs exactly once in the file as the earlier edits left it.",
+        "maxLength": 1000000,
+        "minLength": 1,
+        "type": "string"
+      },
+      "replace": {
+        "description": "What replaces it (may be empty).",
+        "maxLength": 1000000,
+        "type": "string"
+      }
+    },
+    "required": [
+      "find",
+      "replace"
+    ],
+    "type": "object"
+  },
+  "maxItems": 50,
+  "minItems": 1,
+  "type": "array"
+}

changedInput schema / properties / expectedVersionId / description

Previous value: -"The artifact's current version id as you read it (currentVersionId): required for a workspace artifact (a stale one is CONFLICT), optional otherwise."New value: +"The artifact's current version id as you read it (currentVersionId): needed to replace content another agent or person wrote; checked when sent (a stale one is CONFLICT)."

addedInput schema / properties / keepPrevious

Added value: +{
+  "description": "Keep the version this write replaces, whatever the file's history setting says (by default a write replaces the content and keeps no earlier version).",
+  "type": "boolean"
+}

Changed5 schema fields changedOct 27, 2026

addedOutput schema / properties / artifact / properties / alias

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

addedOutput schema / properties / artifact / properties / folder

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "format": "uuid",
+          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+          "type": "string"
+        },
+        "slug": {
+          "type": "string"
+        },
+        "teamSlug": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "id",
+        "slug"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

addedOutput schema / properties / artifact / properties / rawUrl

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

addedOutput schema / properties / artifact / properties / title

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

changedOutput schema / properties / artifact / required

Previous value: -[
-  "id",
-  "url",
-  "type",
-  "currentVersionId"
-]New value: +[
+  "id",
+  "url",
+  "rawUrl",
+  "type",
+  "currentVersionId",
+  "alias",
+  "title",
+  "folder"
+]

First observedOct 23, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Beyond the annotations (destructiveHint=true, idempotentHint=false), it discloses that the write replaces content outright, that the prior version survives only under the file/folder/workspace history setting or keepPrevious, that edits are atomic (each find must occur exactly once, else nothing changes), and that a stale expectedVersionId yields CONFLICT followed by re-read-and-retry. This is exactly the extra context the annotations cannot convey.

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?

It is front-loaded with the input-mode choice and the destructive-replace behavior before the versioning nuances, and nearly every clause carries information. It is a dense single paragraph, however, with a somewhat run-on history clause and a file analogy that could be compressed.

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 10-parameter destructive mutation with an output schema, the description covers the mode contract, the destructive/replace semantics, version retention, conflict handling, and empty-content validity. Return shape is covered by the output schema and the remaining parameter text sits in the schema, so nothing an agent needs to call this safely is missing.

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

Parameters5/5

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

Schema coverage is already 80%, yet the description still adds meaning: mutual exclusivity of content/base64Content/edits, the ordering and exactly-once semantics of find/replace pairs, what expectedVersionId is checked against and when it can be omitted, and the effect of keepPrevious versus the history setting. Only the 'why' parameter is left entirely to its schema text.

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 opening sentence states a specific verb (Replace) and resource (an artifact's content) and immediately enumerates the three mutually exclusive input modes: text via content, a base64 file via base64Content/filename/mimeType, or find/replace edits. An agent can tell this apart from read/append/patch siblings without opening the schema.

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?

It gives clear mode-selection guidance (edits when you want to send only the changed passage; expectedVersionId only when overwriting content another agent or person wrote) and a partial exclusion ('Data that grows by adding records belongs in a table'). It never distinguishes this tool from close siblings like artifact_append or artifact_patch, so a little routing is left to inference.

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

All Tokenrip 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.