Skip to main content
Glama

Revise a neuron

crbro_revise
Idempotent

Revise a stored neuron without deleting it: retire outdated or false facts via status, reactivate or verify items, edit metadata, and move entries to another neuron while keeping dates.

Instructions

Write: change what a neuron says without deleting anything — for what stopped being true, or never was, with nothing replacing it (a replacement is crbro_learn with supersedes; what must not exist on disk, crbro_forget). facts and entries take a status: superseded or retracted retire them (kept in the file, gone from recall), active reactivates, and status verified records a check against the source. summary, domain, tags and name edit metadata in the same call; the id never changes. move_to splits: the listed entries go to another neuron with their dates. Anything in unmatched is STILL LIVE: fix and re-run.

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": {
      "neuron": "<neuron>"
    },
    "name": "crbro_revise"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameNoRename; id, file and links stay.
noteNoWhy; stored with the retirement.
tagsNoReplaces the WHOLE tag list; on protocol neurons re-send priority: and source:.
factsNoFact ids (entry_id from crbro_recall) or exact text.
domainNoNew domain.
neuronYesNeuron id or name.
statusNosuperseded (default: newer truth exists), retracted (never true), active (reactivate) or verified (still holds at its source).
entriesNoDecisions, patterns, errors or debts by exact text (or id with verified and move_to).
move_toNoSplit: move the listed facts/entries to this neuron id or name (created if missing), dates kept. Refused on a shared neuron.
summaryNoNew neuron summary; credentials are redacted.
evidenceNoWith verified: source = you checked the reference; user = the user confirmed.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed11 schema fields changedv2.12.0
    • changedInput schema / properties / domain / description
      Previous value: -"Replace the neuron domain unconditionally, e.g. \"proyectos-web\"."New value: +"New domain."
    • changedInput schema / properties / entries / description
      Previous value: -"Exact texts of decisions, patterns, errors or debts to move to `status`. Retired entries stay in the file (entry_status) but leave recall like a superseded fact. With status verified: decisions or patterns, by exact text or entry id."New value: +"Decisions, patterns, errors or debts by exact text (or id with verified and move_to)."
    • changedInput schema / properties / evidence / description
      Previous value: -"With verified: source means the caller actually checked the reference (required); user means the user confirmed it. Omitted remains an unspecified explicit check for older clients. Never inferred from repeating a fact."New value: +"With verified: source = you checked the reference; user = the user confirmed."
    • changedInput schema / properties / facts / description
      Previous value: -"Facts to move to `status`: their ids (from crbro_recall) or exact text (trimmed, case-insensitive). For superseded/retracted only active facts match; for active only retired ones do."New value: +"Fact ids (entry_id from crbro_recall) or exact text."
    • changedInput schema / properties / move_to / description
      Previous value: -"Split: move the entries listed in facts/entries (ids from crbro_inspect, or exact text; any kind) to this neuron — id or name, created if missing with the same type and domain. They keep their dates, keys and retirement; the source is quarantined first and the two neurons are linked. status and note are ignored. Refused while `neuron` is shared."New value: +"Split: move the listed facts/entries to this neuron id or name (created if missing), dates kept. Refused on a shared neuron."
    • changedInput schema / properties / name / description
      Previous value: -"Rename the neuron. Its id, file, synapses and shared state stay the same."New value: +"Rename; id, file and links stay."
    • changedInput schema / properties / neuron / description
      Previous value: -"Neuron id or name holding what to revise, e.g. \"project_octochat\"."New value: +"Neuron id or name."
    • changedInput schema / properties / note / description
      Previous value: -"Why. Stored as revision_note on facts and entry_status.note on entries. The next reader will wonder. Ignored with status verified."New value: +"Why; stored with the retirement."
    • changedInput schema / properties / status / description
      Previous value: -"superseded = a newer truth exists (default); retracted = it was never true; active = reactivate a retired fact or entry (local only on a shared neuron: the next sync re-applies the retirement; shared_warning says so). verified = you checked these active facts, or live decisions or patterns, against their source and they still hold: their last verification becomes now and they leave possibly_stale. A retired target is not verifiable: it comes back in unmatched and retired_targets."New value: +"superseded (default: newer truth exists), retracted (never true), active (reactivate) or verified (still holds at its source)."
    • changedInput schema / properties / summary / description
      Previous value: -"Replace the neuron summary. Credentials are redacted and listed in redacted."New value: +"New neuron summary; credentials are redacted."
    • changedInput schema / properties / tags / description
      Previous value: -"Replace the WHOLE tag list (trimmed, deduplicated). On protocol neurons re-send the priority: and source: tags or they are gone."New value: +"Replaces the WHOLE tag list; on protocol neurons re-send priority: and source:."
  2. Changed1 schema field changedv2.10.0
    • addedInput schema / properties / evidence
      Added value: +{
      +  "description": "With verified: source means the caller actually checked the reference (required); user means the user confirmed it. Omitted remains an unspecified explicit check for older clients. Never inferred from repeating a fact.",
      +  "properties": {
      +    "method": {
      +      "enum": [
      +        "source",
      +        "user"
      +      ],
      +      "type": "string"
      +    },
      +    "reference": {
      +      "properties": {
      +        "field": {
      +          "maxLength": 256,
      +          "type": "string"
      +        },
      +        "kind": {
      +          "enum": [
      +            "file",
      +            "url",
      +            "person"
      +          ],
      +          "type": "string"
      +        },
      +        "project": {
      +          "maxLength": 256,
      +          "type": "string"
      +        },
      +        "value": {
      +          "maxLength": 2048,
      +          "minLength": 1,
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "kind",
      +        "value"
      +      ],
      +      "type": "object"
      +    }
      +  },
      +  "required": [
      +    "method"
      +  ],
      +  "type": "object"
      +}
  3. Changed4 schema fields changedv2.9.1
    • changedInput schema / properties / entries / description
      Previous value: -"Exact texts of decisions, patterns, errors or debts to move to `status`. Retired entries stay in the file (entry_status) but leave recall like a superseded fact."New value: +"Exact texts of decisions, patterns, errors or debts to move to `status`. Retired entries stay in the file (entry_status) but leave recall like a superseded fact. With status verified: decisions or patterns, by exact text or entry id."
    • changedInput schema / properties / note / description
      Previous value: -"Why. Stored as revision_note on facts and entry_status.note on entries. The next reader will wonder."New value: +"Why. Stored as revision_note on facts and entry_status.note on entries. The next reader will wonder. Ignored with status verified."
    • changedInput schema / properties / status / description
      Previous value: -"superseded = a newer truth exists (default); retracted = it was never true; active = reactivate a retired fact or entry. Reactivation is local: on a shared neuron the next sync re-applies the retirement (the response carries shared_warning)."New value: +"superseded = a newer truth exists (default); retracted = it was never true; active = reactivate a retired fact or entry (local only on a shared neuron: the next sync re-applies the retirement; shared_warning says so). verified = you checked these active facts, or live decisions or patterns, against their source and they still hold: their last verification becomes now and they leave possibly_stale. A retired target is not verifiable: it comes back in unmatched and retired_targets."
    • changedInput schema / properties / status / enum
      Previous value: -[
      -  "superseded",
      -  "retracted",
      -  "active"
      -]New value: +[
      +  "superseded",
      +  "retracted",
      +  "active",
      +  "verified"
      +]
  4. Changed1 schema field changedv2.5.1
    • addedInput schema / properties / move_to
      Added value: +{
      +  "description": "Split: move the entries listed in facts/entries (ids from crbro_inspect, or exact text; any kind) to this neuron — id or name, created if missing with the same type and domain. They keep their dates, keys and retirement; the source is quarantined first and the two neurons are linked. status and note are ignored. Refused while `neuron` is shared.",
      +  "type": "string"
      +}
  5. Changed1 schema field changedv2.4.0
    • removedInput schema / $schema
      Removed value: -"http://json-schema.org/draft-07/schema#"
  6. Changed11 schema fields changedv2.0.0
    • addedInput schema / properties / domain
      Added value: +{
      +  "description": "Replace the neuron domain unconditionally, e.g. \"proyectos-web\".",
      +  "type": "string"
      +}
    • addedInput schema / properties / entries
      Added value: +{
      +  "description": "Exact texts of decisions, patterns, errors or debts to move to `status`. Retired entries stay in the file (entry_status) but leave recall like a superseded fact.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • changedInput schema / properties / facts / description
      Previous value: -"Facts to retire: their ids (from crbro_recall) or exact text (trimmed, case-insensitive). Already-retired facts never match."New value: +"Facts to move to `status`: their ids (from crbro_recall) or exact text (trimmed, case-insensitive). For superseded/retracted only active facts match; for active only retired ones do."
    • addedInput schema / properties / name
      Added value: +{
      +  "description": "Rename the neuron. Its id, file, synapses and shared state stay the same.",
      +  "type": "string"
      +}
    • changedInput schema / properties / neuron / description
      Previous value: -"Neuron id or name holding the facts, e.g. \"project_octochat\"."New value: +"Neuron id or name holding what to revise, e.g. \"project_octochat\"."
    • changedInput schema / properties / note / description
      Previous value: -"Why it stopped being true. The next reader will wonder."New value: +"Why. Stored as revision_note on facts and entry_status.note on entries. The next reader will wonder."
    • changedInput schema / properties / status / description
      Previous value: -"superseded = there is a newer truth (default); retracted = it was never true."New value: +"superseded = a newer truth exists (default); retracted = it was never true; active = reactivate a retired fact or entry. Reactivation is local: on a shared neuron the next sync re-applies the retirement (the response carries shared_warning)."
    • changedInput schema / properties / status / enum
      Previous value: -[
      -  "superseded",
      -  "retracted"
      -]New value: +[
      +  "superseded",
      +  "retracted",
      +  "active"
      +]
    • addedInput schema / properties / summary
      Added value: +{
      +  "description": "Replace the neuron summary. Credentials are redacted and listed in redacted.",
      +  "type": "string"
      +}
    • addedInput schema / properties / tags
      Added value: +{
      +  "description": "Replace the WHOLE tag list (trimmed, deduplicated). On protocol neurons re-send the priority: and source: tags or they are gone.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • changedInput schema / required
      Previous value: -[
      -  "neuron",
      -  "facts"
      -]New value: +[
      +  "neuron"
      +]
  7. Addedv1.14.0

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare destructiveHint=false and idempotentHint=true, yet the description goes well beyond them: retirement keeps content 'in the file, gone from recall', the id never changes on rename, and move_to is refused on shared neurons. Most valuable is the partial-failure contract ('Anything in unmatched is STILL LIVE: fix and re-run'), which is the only disclosure of that return field since no output schema exists. It stops short of saying what a successful response looks like overall.

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 operation type and dense with signal; there is almost no filler sentence. It is a single unbroken paragraph with heavy parenthetical nesting, which costs some scannability for an 11-parameter tool, but nothing meaningful could be cut without losing routing information.

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?

Covers the hard parts of a complex 11-parameter mutation tool: retirement semantics, metadata editing, split behaviour, and the unmatched recovery loop. With no output schema, the description could say more about the success payload (what a revise returns besides unmatched), which is the main remaining gap.

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 100%, so the baseline is 3, but the prose adds real cross-parameter meaning the schema cannot express: which fields accept a status, that tags replaces the WHOLE list (and that protocol neurons need priority:/source: resent), and that move_to splits entries out to another neuron with dates preserved. Only evidence/reference semantics are left largely to the schema.

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 verb-plus-resource statement plus an explicit scope limit: 'Write: change what a neuron says without deleting anything.' It then distinguishes the exact sibling cases (replacement -> crbro_learn with supersedes; removal -> crbro_forget), so an agent can separate it from all three neighbours without opening a schema.

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 the selecting condition ('for what stopped being true, or never was, with nothing replacing it') and names both alternatives with the condition that favours each. It also gives per-field guidance (status values, metadata editing vs. move_to splitting) and a recovery instruction for the unmatched case.

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