Datacron

Overview Schema Source Related Servers Discussions Admin

Revert note to exact history

revert_note

DestructiveIdempotent

Undo a bad note write by restoring exact prior content-addressed bytes, passing expected_hash for compare-and-swap. The rollback remains reversible and logged.

Instructions

Use this to undo a bad write by restoring exact prior bytes. Restore a note to exact content-addressed history bytes. Pass the current content_hash as expected_hash for CAS. The revert is itself durable, reversible, indexed, and operation-logged.

Input Schema

Name	Required	Description	Default
`note`	Yes
`to_hash`	Yes
`request_id`	No
`expected_hash`	No

Output Schema

Name	Required	Description	Default
`indexed`	Yes
`rel_path`	No
`replayed`	No
`reverted`	No
`committed`	No
`content_hash`	Yes
`operation_id`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedv0.1.17Oct 17, 2026
- addedOutput schema / description
```
Added value: +"Successful ``revert_note`` payload."
```
- removedOutput schema / properties / committed / default
```
Removed value: -null
```
- removedOutput schema / properties / operation_id / default
```
Removed value: -null
```
- removedOutput schema / properties / rel_path / default
```
Removed value: -null
```
- removedOutput schema / properties / replayed / default
```
Removed value: -null
```
- removedOutput schema / properties / reverted / default
```
Removed value: -null
```

Changed9 schema fields changedv0.1.5Sep 5, 2026

addedInput schema / properties / request_id

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Request Id"
+}

addedOutput schema / properties / committed

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Committed"
+}

addedOutput schema / properties / operation_id

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Operation Id"
+}

addedOutput schema / properties / rel_path

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Rel Path"
+}

addedOutput schema / properties / replayed

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Replayed"
+}

removedOutput schema / properties / reverted / $ref
```
Removed value: -"#/$defs/RevertedNoteOutput"
```

addedOutput schema / properties / reverted / anyOf

Added value: +[
+  {
+    "$ref": "#/$defs/RevertedNoteOutput"
+  },
+  {
+    "type": "null"
+  }
+]

addedOutput schema / properties / reverted / default
```
Added value: +null
```

changedOutput schema / required

Previous value: -[
-  "reverted",
-  "content_hash",
-  "indexed"
-]New value: +[
+  "content_hash",
+  "indexed"
+]

First observedv0.1.0Jul 31, 2026

TDQS

A4.1/5.0

Behavior4/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 real value beyond that: the revert is 'durable, reversible, indexed, and operation-logged,' and it explains the CAS precondition. No contradiction with destructiveHint=true, since overwriting current bytes is itself destructive.

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?

Four short sentences, front-loaded with the purpose before the CAS mechanics and behavioral traits. Slight redundancy between the first two sentences ('restoring exact prior bytes' vs 'restore a note to exact content-addressed history bytes'), but nothing is wasted.

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, so return values need not be described. The description covers when to use it, the CAS guard, and post-write behavior; the remaining gaps are the semantics of request_id and the note identifier, which are minor for a 4-parameter tool.

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 0%, so the description must carry parameter meaning. It does explain expected_hash explicitly (current content_hash for CAS) and implies to_hash (target history bytes), but leaves request_id and the note identifier undocumented, so it only partially compensates for the coverage gap.

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 and resource: 'undo a bad write by restoring exact prior bytes' / 'Restore a note to exact content-addressed history bytes.' The content-addressed/bytes framing distinguishes it from sibling write tools (patch_note_section, append_journal) and from read-only history tools like get_note_history.

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 a clear triggering condition ('Use this to undo a bad write') and invocation guidance ('Pass the current content_hash as expected_hash for CAS'). It does not name alternatives (e.g., when to prefer patching a section instead of reverting the whole note), so it stops short of full when/when-not routing.

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