Skip to main content
Glama

Typebar (formerly SuperDocs)

revert_session_to_message

Rewinds a chat session, document and conversation, to just before a specific user message. The reverted message's text comes back as compose_text, to edit and resend. Messages from the reverted turn forward are soft-archived: hidden but kept (redo_revert restores them). Pass the turn_index a chat reply returned. Rejects with 409 while a chat job is in progress or awaiting approval. Returns 422 (code 'turn_has_no_restore_point') when the turn recorded no restore point (usually the message before it did not finish); the response lists revertable_turns (possibly empty) that can be rewound to.

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": {
      "session_id": "<session_id>",
      "turn_index": "<turn_index>"
    },
    "name": "revert_session_to_message"
  }
}

Input Schema

NameRequiredDescriptionDefault
dry_runNoWhen true, compute the per-document revert diff WITHOUT committing or archiving anything — used to render a preview before the user confirms.
session_idYes
turn_indexYesTurn index of the user message to revert. The text of that message is returned in compose_text so the caller can re-edit and resend it. Every chat row at this turn or later is soft-archived (hidden from active reads but retained for audit).
response_modeNo'summary': no HTML; counts, conflicts, the redo handle.full

Output Schema

NameRequiredDescriptionDefault
dry_runNoEchoes the request's dry_run: when true nothing was committed/archived — this is a preview only.
session_idYesSession identifier.
compose_textYesThe text of the user message that was reverted. Clients should pre-fill the compose box with this so the user can edit and resend.
change_countsNoresponse_mode 'summary' only (absent otherwise): per document (slug), how many sections the revert restores, by operation (edit, create, delete). Summary carries this in place of revert_changes, which is null there.
editor_actionNoClient instruction: 'update' to load the restored document, or 'clear' to reset the editor to empty.update
document_stateNoRestored document state. Null when the session is reset to empty.
revert_changesNoPer-document (slug -> change-set) revert diff. Applying these merges the revert onto any concurrent live edits — a conflicting section is surfaced for you to resolve rather than replacing the whole document. On dry_run this is the preview; on a real revert it is what was committed.
revert_conflictsNoPer-document (slug -> entries) sections whose restore did NOT fully land. TWO classes, told apart by the 'displaced' flag. (1) NOT LANDED ('displaced' absent/false): content another writer committed was preserved instead (reason 'concurrent_edit_preserved' / 'lineage_unknown'), or a removal could not be resolved against the live document; the matching revert_changes entry is annotated 'conflict': true and carries the preserved bytes as new_html (the honest committed state) plus the un-landed restore as restore_html. (2) LANDED IN THE WRONG PLACE ('displaced': true): the content WAS restored but not at its original position — reason 'restored_elsewhere' (it was added at the end of the document because the section it anchors to is gone) or 'position_not_restored' (a concurrent writer's placement won). These carry an empty their_html (nothing of another writer's was preserved, so there is nothing to adopt) plus the raw 'resolution' token, and the matching revert_changes entry is annotated 'displaced': true — never 'conflict', because new_html is still the restored content. (3) NOT SAVED AT ALL ('write_failed': true, operation 'write', chunk_id null): the document's recovery write did not commit — reason 'document_deleted' (archived mid-revert), 'storage_paused' (durable saving paused for this account) or 'write_failed'. Document-level, so there is no matching revert_changes entry; storage still holds the pre-revert content while document_state shows the reverted document, so a client MUST re-read the document before saving again. Null/absent when the revert landed cleanly everywhere.
reverted_to_turnYesTurn index that the active conversation now ends at (the AI reply preceding the reverted user message). -1 when the session is reset to its initial empty state (revert from the very first user message).
redo_checkpoint_idNoThe identifier of the pre-revert state. Revert is non-destructive — passing this back to POST /sessions/{id}/redo (with the same turn_index) restores it and un-archives the rolled-back turns, undoing the revert. Null on a dry-run, and null when the pre-revert state could not be captured — in that case redo_unavailable_reason says which, so absence by design and absence by failure are never the same value.
archived_turn_countYesNumber of chat rows soft-archived by this revert (turns hidden from the UI but retained for audit).
redo_unavailable_reasonNoPresent ONLY when redo_checkpoint_id is null because the pre-revert state could not be captured (never on a dry-run, where null is by design). The revert itself succeeded and is durable; what is unavailable is the one-step undo of it. Treat a non-null value as: do not attempt redo_revert for this revert — it has no argument to pass.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.7/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and mostly delivers: it discloses that data is soft-archived rather than destroyed, that redo_revert restores it, and the exact failure codes and payloads (409, 422 with revertable_turns). Missing is any statement about permissions/authorization or whether concurrent calls to the same session are safe, which is a real gap for a mutation tool.

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?

Front-loads the operation, then the return value, then archival semantics, then failure conditions — each sentence adds a distinct fact with no repetition. Dense and efficient for the amount of behavior conveyed.

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?

An output schema exists so return values needn't be enumerated, yet the description still calls out the two payloads an agent must act on (compose_text, revertable_turns). Error codes, archival behavior, and the recovery path are all covered, leaving nothing material missing for correct invocation.

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 75%, so baseline is ~3, but the description adds genuine meaning beyond the schema for the critical parameter: turn_index must be one obtained from a chat reply and identifies a user message whose text is returned. It says nothing about dry_run or response_mode, but those are well documented in the schema itself.

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?

Opens with a specific verb and resource plus scope: rewind a chat session/document/conversation to just before a specific user message. It immediately distinguishes itself from redo_revert by naming the inverse operation, so an agent can tell the two apart without opening schemas.

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?

States where turn_index comes from ('the turn_index a chat reply returned'), what the call is for (edit and resend via compose_text), the restoration alternative (redo_revert), and two explicit when-not conditions: 409 while a chat job is in progress or awaiting approval, and 422 'turn_has_no_restore_point'.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.