ClearPolicy

Update Document Revision Tool

update-document-revision-tool

DestructiveIdempotent

Update a draft document revision body (Markdown) and/or summary. Published revisions cannot be edited — create a new draft revision first. Prefer rich-text drafts created via create-document.

Input Schema

Name	Required	Description
`summary`	No	Optional short summary of this draft (max 255 characters). Pass empty string to clear.
`revision_id`	Yes	The ULID of the draft document revision to update.
`base_version`	Yes	The lock_version returned when you last read this revision. A stale version is rejected; read and review the latest content before trying again.
`body_markdown`	No	Full Markdown body to store (replaces existing content). Required unless only updating summary.

Output Schema

Name	Required	Description	Default
`id`	Yes
`status`	Yes
`app_url`	Yes
`summary`	No
`edit_url`	No
`is_empty`	Yes
`document_id`	Yes
`source_type`	Yes
`content_text`	Yes
`lock_version`	Yes
`published_at`	No
`resource_uri`	Yes
`document_name`	No
`content_markdown`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedOct 13, 2026

addedInput schema / properties / base_version

Added value: +{
+  "description": "The lock_version returned when you last read this revision. A stale version is rejected; read and review the latest content before trying again.",
+  "type": "integer"
+}

changedInput schema / required

Previous value: -[
-  "revision_id"
-]New value: +[
+  "revision_id",
+  "base_version"
+]

addedOutput schema / properties / lock_version
```
Added value: +{
+  "type": "integer"
+}
```

changedOutput schema / required

Previous value: -[
-  "id",
-  "document_id",
-  "status",
-  "source_type",
-  "content_markdown",
-  "content_text",
-  "is_empty",
-  "resource_uri",
-  "app_url"
-]New value: +[
+  "id",
+  "lock_version",
+  "document_id",
+  "status",
+  "source_type",
+  "content_markdown",
+  "content_text",
+  "is_empty",
+  "resource_uri",
+  "app_url"
+]

AddedJul 17, 2026

TDQS

A4/5.0

Behavior3/5

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful context that only drafts are editable and that a published revision must be superseded by a new draft, but the replacement semantics of body_markdown and the lock_version staleness behavior live in the schema rather than the description.

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?

Three short sentences, front-loaded with the action, then the key constraint, then the preference. Every sentence carries distinct information with no filler.

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?

With a full output schema, complete parameter docs, and annotations covering destructive/idempotent behavior, the remaining description burden is small. It covers the draft-only constraint and preferred authoring path, leaving little an agent would need to infer.

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 100%, so revision_id, base_version, summary, and body_markdown are all fully documented in the schema, including the max-255 limit and clear-on-empty rule. The description adds no parameter detail beyond that baseline.

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 (update) and resource (draft document revision), plus the exact fields affected (body Markdown and/or summary). This clearly separates it from create-document-revision-tool and publish-document-revision-tool without the agent needing to open 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 Guidelines4/5

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

Explicitly states the when-not condition (published revisions cannot be edited; create a new draft first) and steers toward the preferred path (rich-text drafts via create-document). It names the sibling alternatives but doesn't spell out every route, so slightly short of fully explicit routing.

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

All ClearPolicy 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?