Skip to main content
Glama
dreamforgestudiollc

EMET

by dreamforgestudiollc
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Hybrid

retire_doc

Idempotent

Mark a continuity document obsolete without deleting it: it stays readable and recoverable, but leaves working lists and startup scans unless include_retired is true. Use for test scratch.

Instructions

Mark a continuity document OBSOLETE. Nothing is deleted: the document keeps its id, its full content, its version and its digest, and read_doc still returns it - flagged retired, with the reason - so it can never be silently lost. What changes is visibility: list_docs stops returning it unless include_retired is true, so retired documents leave the working view and the startup scans. This is document control as ISO 7.5.3 describes it - issue the revision, mark the prior copy obsolete, retain it, prevent its unintended use - and it is the document-store counterpart of revise_memory superseding a layer entry. THE STORE HAS NO DELETE, BY DESIGN. Use for genuine litter: tombstones, merged staging documents, test scratch. Reversible: write_doc on the same id brings it back into the working view.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
doc_idYesDocument id to mark obsolete.
reasonYesWhy it is obsolete. Required, at least 10 characters. Drops only.
sourceNoSource tag - which host produced this write. One name on every write since 2026-09-27.
exchangeNoThe exchange (turn) this write belongs to, counting from 1. A write for exchange n while exchange n-1 was never appended is refused by the session graph until n-1 is appended.
retired_byNoAlias of `source` (the older name, kept one release). Prefer `source`.
session_idNoTranscript session id.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.2.2
    • changedInput schema / properties / exchange / description
      Previous value: -"The exchange (turn) this write belongs to, counting from 1. A write for exchange n while exchange n-1 was never appended is flagged by the session graph."New value: +"The exchange (turn) this write belongs to, counting from 1. A write for exchange n while exchange n-1 was never appended is refused by the session graph until n-1 is appended."
    • changedInput schema / properties / reason / description
      Previous value: -"Why it is obsolete, e.g. 'merged into threads/income-transition.md'. Recorded on the document and shown by read_doc."New value: +"Why it is obsolete. Required, at least 10 characters. Drops only."
    • changedInput schema / properties / session_id / description
      Previous value: -"Your transcript session id from emet_session_open. The session graph reads this session's state before the write and returns `session_graph.next` - the next step."New value: +"Transcript session id."
    • changedInput schema / required
      Previous value: -[
-  "doc_id"
-]New value: +[
+  "doc_id",
+  "reason"
+]
  2. First observedv0.1.0

TDQS

A4.4/5.0
Behavior5/5

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

Annotations already declare destructiveHint=false and idempotentHint=true, but the description goes far beyond them: it states nothing is deleted, the id/content/version/digest are retained, read_doc still returns it flagged retired, and list_docs hides it unless include_retired is true. It also discloses reversibility via write_doc and that the store has no delete by design.

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?

Front-loaded with the core action, and each sentence carries information (retention, visibility, reversibility). The ISO 7.5.3 exposition and the revise_memory analogy are slightly discursive but still earn their place by anchoring intent.

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 non-destructive mutation with annotations covering the safety profile, the description supplies everything an agent needs: what changes, what is preserved, effect on list_docs and startup scans, and how to undo it. No output schema is needed since the visibility behavior is fully explained.

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 every parameter including doc_id, reason, source, exchange and retired_by is already documented in the schema. The description adds no format or syntax detail about parameters, so the baseline 3 for a fully-covered schema 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?

States a precise verb+resource ("Mark a continuity document OBSOLETE") and immediately scopes what that means versus deletion. It distinguishes itself from siblings by naming read_doc, list_docs, write_doc and revise_memory and describing how each relates to a retired document.

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?

"Use for genuine litter: tombstones, merged staging documents, test scratch" gives clear positive guidance, and the revise_memory comparison situates it among alternatives. It stops short of explicit when-not-to-use exclusions beyond the implicit "not for live documents," so it falls just shy of a 5.

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

Deploy Server

Other Tools