ClearPolicy

Publish Document Revision Tool

publish-document-revision-tool

Destructive

Publish a draft document revision so it can be sent for electronic signature. Generates a PDF and document hash. Confirm with the user before publishing. After publishing, use send-signing-request to distribute it.

Input Schema

Name	Required	Description
`revision_id`	Yes	The ULID of the draft revision to publish.
`base_version`	Yes	The lock_version of the exact draft state reviewed and approved for publication. Read and review again if it changed.
`allow_unfilled_fields`	No	Only set true after telling the user which template fields are unfinished and getting explicit approval to publish with those labels still visible.

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
`latest_published_revision_pdf_uri`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 22, 2026

addedInput schema / properties / allow_unfilled_fields

Added value: +{
+  "description": "Only set true after telling the user which template fields are unfinished and getting explicit approval to publish with those labels still visible.",
+  "type": "boolean"
+}

Changed4 schema fields changedOct 13, 2026

addedInput schema / properties / base_version

Added value: +{
+  "description": "The lock_version of the exact draft state reviewed and approved for publication. Read and review again if it changed.",
+  "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/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true, non-idempotent, non-readOnly, so the safety profile is covered; the description adds real value by saying a PDF and document hash are produced and that user confirmation is required first. It stops short of saying the publish is irreversible or what happens to the draft state afterward.

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?

Four short sentences, front-loaded with the action, then the side effects, the safety gate, and the next tool. No repeated or filler content.

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?

Annotations carry the destructive/non-idempotent profile, the output schema covers return values, and the schema documents parameters. The description supplies the workflow context (confirm → publish → send) that the structured fields cannot express.

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 coverage is 100%, so revision_id, base_version, and allow_unfilled_fields are each fully documented in the schema, including the concurrency and approval caveats. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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?

Specific verb+resource ('Publish a draft document revision') with the concrete outcome stated (PDF and document hash generated). It clearly distinguishes itself from create-document-revision-tool and update-document-revision-tool by describing the publish transition into the signing workflow.

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?

Explicitly states the precondition (confirm with the user before publishing) and the follow-up tool (send-signing-request to distribute it), which routes the agent correctly among 19 siblings. The when and the next step are both given, not inferred.

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?