mnema

Official

Overview Schema Source Related Servers Discussions Admin

Retract a link

retract_link

Retract a mistakenly recorded link by naming its exact subject, target, and relation, appending a signed reason so reads stop applying the edge while references mark it retracted.

Instructions

Take back a link that was recorded by mistake: a governs on the wrong path, a relation that does not hold. Name the edge exactly as link_knowledge took it. The link is NOT erased: a signed retraction carrying the reason is appended, and every read that applies a link stops seeing the edge when nobody else asserts it, so a rule it addressed at a path stops acting there; references still shows it, marked retracted. It follows the link to the first tree that holds that edge. Only the identity that recorded a link retracts it; a link of another identity, or one already retracted, is refused. RECORDING IS PERMANENT: mnema is append-only and nothing deletes a fact. A record in the public scope is committed to the repository and reaches every machine that clones it (published, if that repository is public). So do NOT record credentials here. Values in a recognized format (cloud keys, API tokens, private keys, a password inside a URL) are replaced with a typed placeholder before anything is written and the reply says what was replaced, but a format mnema does not recognize is written verbatim and cannot be taken back. Do not record personal data either: an email address is replaced with and reported, and the mnid already says who wrote. Each text field holds at most 65536 bytes; a longer one is refused, not truncated.

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": {
      "subject": "<subject>",
      "target": "<target>",
      "rel": "<rel>",
      "reason": "<reason>"
    },
    "name": "retract_link"
  }
}

Input Schema

Name	Required	Description
`rel`	Yes	The relation, as it was linked.
`reason`	Yes	Why it is taken back.
`target`	Yes	What the link points at, as it was linked.
`subject`	Yes	The entity the link originates from.

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 9, 2026

TDQS

A4/5.0

Behavior3/5

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

There is a lot of behavioral content: the link is not erased but a signed retraction is appended, readers stop seeing the edge when no one else asserts it, `references` still shows it marked retracted, the operation 'follows the link to the first tree that holds that edge', and oversize text is refused rather than truncated. That is consistent with destructiveHint=false and idempotentHint=false. Most of the remainder, however, restates the append-only recording policy (credential redaction, `<email>` substitution, public-scope publication) that is really about `link_knowledge`, and nothing is said about what this call itself returns or whether a retraction can be undone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The retraction mechanics are front-loaded and well ordered, but roughly half the text is a recording policy about credentials, personal data and byte limits that mostly concerns the linking tool, and several clauses ('published, if that repository is public', 'the mnid already says who wrote') are decorative. The core instruction could be carried in half the length without losing anything an agent needs to invoke this call.

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?

For a four-parameter mutation with no output schema, the definition covers the essentials: permanence of the appended retraction, ownership restriction, refusal on already-retracted edges, cross-tree lookup, and size limits. The gap is the return shape of a successful retraction, since only the redaction notice is described.

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 description coverage is 100%, so the baseline is 3, and the description earns a point above it by adding a stricter matching rule the schema does not convey: the edge must be named exactly as it was linked, which tells the agent that `subject`, `target` and `rel` are identity fields, not fuzzy lookups. It also characterizes `reason` as being carried inside the signed retraction, making it part of the permanent record rather than a transient comment.

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?

The definition opens with a specific verb and resource, 'Take back a link that was recorded by mistake', and immediately gives concrete instances ('a `governs` on the wrong path, a relation that does not hold'). It also ties itself to the sibling that creates such links by requiring the edge be named 'exactly as `link_knowledge` took it', so an agent can tell the two apart without reading 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?

Usage is made explicit through concrete failure cases that warrant retraction and through hard prerequisites: only the identity that recorded the link may retract it, and an already-retracted link is refused. What is missing is an explicit statement of when to prefer a sibling such as retract_note, or when to leave a stale-but-true edge alone; the extensive 'do not record' guidance concerns the write side more than this call.

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