mellos-mapping

Overview Schema Source Related Servers Discussions Admin

Record progress and revise the map

mmap_update

Update a Mellos map in one atomic batch: record node progress, move or relabel nodes, bands, groups, and lanes, and revise edges with evidence.

Instructions

The revision tool, all-or-nothing. Record progress on nodes: in-progress when starting a node (the pane spins), done with evidence when its verification passes, regressed with evidence when a done node breaks. Revise what the ghost design got wrong: move a node to another band, join or leave a group or lane, rename a band (or re-rank it, which reorders the whole map), relabel a group or a lane. Every clearable field takes null to empty it — that is how a field is cleared, never an empty string. Bands, groups and lanes are applied before the node updates, and within one node update layer moves the node before its other fields. The map is a ledger: report honestly, it never blocks you.

Input Schema

TableJSON Schema

Name	Required	Description
`kind`	No	diagram kind. dev (default) = the live progress ledger with status skins. The rest are documentation diagrams rendered neutrally: architecture (layered components; also fits call graphs and module dependencies), dataflow (source→transform→sink, stages as layers), behavior-tree (root on top, leaves at the bottom; also fits mind maps and WBS), sequence (classic call/return: rank = time step with rank 0 = EARLIEST, drawn top-down; declare lanes as participants and make every call AND every return its own event node in the acting participant's lane, edges labeled with the message). State machines are unsupported: cycles cannot enter a Mellos map.
`page`	No	page (parallel map) this call targets; omit for the default page. A new conversation is not a new effort. Read existing pages with mmap_read first; reuse the same page for continued work. Create a new page only for a distinct effort.
`edges`	No
`lanes`	No	relabel existing lanes; order and membership are untouched
`title`	No	Map title; null clears
`groups`	No	relabel or move a group; final membership must match its layer
`layers`	No	rename and/or re-rank existing bands; an item must carry a name, a rank, or both
`context`	No
`updates`	No
`laneOrder`	No	Every lane exactly once, in display order.
`expectedRevision`	No	Revision from mmap_read; absent requires a new page. A stale revision returns CONFLICT.

Schema Changelog

Changes observed during successful MCP inspections.

Changed33 schema fields changedv0.26.0Sep 19, 2026

addedInput schema / properties / context

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "next": {
+          "description": "Next actions for resuming this effort",
+          "maxLength": 2000,
+          "minLength": 1,
+          "pattern": "^[^\\u0000-\\u0008\\u000b-\\u001f\\u007f-\\u009f]*$",
+          "type": "string"
+        },
+        "summary": {
+          "description": "Concise purpose and confirmed decisions",
+          "maxLength": 2000,
+          "minLength": 1,
+          "pattern": "^[^\\u0000-\\u0008\\u000b-\\u001f\\u007f-\\u009f]*$",
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

addedInput schema / properties / edges

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "from": {
+        "description": "the node that USES the other (must live on a higher layer)",
+        "pattern": "^[a-z0-9][a-z0-9-]{0,63}$",
+        "type": "string"
+      },
+      "label": {
+        "anyOf": [
+          {
+            "description": "New edge label; null clears",
+            "maxLength": 80,
+            "minLength": 1,
+            "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]*$",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "New edge label; null clears"
+      },
+      "newFrom": {
+        "description": "replacement consumer",
+        "pattern": "^[a-z0-9][a-z0-9-]{0,63}$",
+        "type": "string"
+      },
+      "newTo": {
+        "description": "replacement dependency",
+        "pattern": "^[a-z0-9][a-z0-9-]{0,63}$",
+        "type": "string"
+      },
+      "to": {
+        "description": "the node being used (must live on a strictly lower layer)",
+        "pattern": "^[a-z0-9][a-z0-9-]{0,63}$",
+        "type": "string"
+      }
+    },
+    "required": [
+      "from",
+      "to"
+    ],
+    "type": "object"
+  },
+  "minItems": 1,
+  "type": "array"
+}

addedInput schema / properties / expectedRevision

Added value: +{
+  "description": "Revision from mmap_read; absent requires a new page. A stale revision returns CONFLICT.",
+  "pattern": "^(?:[a-f0-9]{64}|absent)$",
+  "type": "string"
+}

addedInput schema / properties / groups

Added value: +{
+  "description": "relabel or move a group; final membership must match its layer",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "id": {
+        "description": "id of the group to revise",
+        "pattern": "^[a-z0-9][a-z0-9-]{0,63}$",
+        "type": "string"
+      },
+      "label": {
+        "description": "new subsystem name",
+        "maxLength": 60,
+        "minLength": 1,
+        "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]*$",
+        "type": "string"
+      },
+      "layer": {
+        "description": "new layer; move members in the same batch",
+        "pattern": "^[a-z0-9][a-z0-9-]{0,63}$",
+        "type": "string"
+      }
+    },
+    "required": [
+      "id"
+    ],
+    "type": "object"
+  },
+  "minItems": 1,
+  "type": "array"
+}

addedInput schema / properties / kind

Added value: +{
+  "description": "diagram kind. dev (default) = the live progress ledger with status skins. The rest are documentation diagrams rendered neutrally: architecture (layered components; also fits call graphs and module dependencies), dataflow (source→transform→sink, stages as layers), behavior-tree (root on top, leaves at the bottom; also fits mind maps and WBS), sequence (classic call/return: rank = time step with rank 0 = EARLIEST, drawn top-down; declare lanes as participants and make every call AND every return its own event node in the acting participant's lane, edges labeled with the message). State machines are unsupported: cycles cannot enter a Mellos map.",
+  "enum": [
+    "dev",
+    "architecture",
+    "dataflow",
+    "behavior-tree",
+    "sequence"
+  ],
+  "type": "string"
+}

addedInput schema / properties / laneOrder

Added value: +{
+  "description": "Every lane exactly once, in display order.",
+  "items": {
+    "description": "existing lane id",
+    "pattern": "^[a-z0-9][a-z0-9-]{0,63}$",
+    "type": "string"
+  },
+  "maxItems": 100,
+  "type": "array"
+}

addedInput schema / properties / lanes

Added value: +{
+  "description": "relabel existing lanes; order and membership are untouched",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "id": {
+        "description": "id of the lane to relabel",
+        "pattern": "^[a-z0-9][a-z0-9-]{0,63}$",
+        "type": "string"
+      },
+      "label": {
+        "description": "new column name",
+        "maxLength": 60,
+        "minLength": 1,
+        "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]*$",
+        "type": "string"
+      }
+    },
+    "required": [
+      "id",
+      "label"
+    ],
+    "type": "object"
+  },
+  "minItems": 1,
+  "type": "array"
+}

addedInput schema / properties / layers

Added value: +{
+  "description": "rename and/or re-rank existing bands; an item must carry a name, a rank, or both",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "id": {
+        "description": "id of the band to revise",
+        "pattern": "^[a-z0-9][a-z0-9-]{0,63}$",
+        "type": "string"
+      },
+      "name": {
+        "description": "new display name of the band",
+        "maxLength": 60,
+        "minLength": 1,
+        "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]*$",
+        "type": "string"
+      },
+      "rank": {
+        "description": "an integer in 0..99, 0 = bottom / most primitive; must be unique among the map's bands",
+        "maximum": 99,
+        "minimum": 0,
+        "type": "integer"
+      }
+    },
+    "required": [
+      "id"
+    ],
+    "type": "object"
+  },
+  "minItems": 1,
+  "type": "array"
+}

changedInput schema / properties / page / description

Previous value: -"page (parallel map) this call targets; omit for the default page. One effort = one page: start a NEW effort on its own page named after the effort, so concurrent sessions never write over each other and the pane can switch between pages."New value: +"page (parallel map) this call targets; omit for the default page. A new conversation is not a new effort. Read existing pages with mmap_read first; reuse the same page for continued work. Create a new page only for a distinct effort."

addedInput schema / properties / title

Added value: +{
+  "anyOf": [
+    {
+      "description": "Map title; null clears",
+      "maxLength": 120,
+      "minLength": 1,
+      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]*$",
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Map title; null clears"
+}

addedInput schema / properties / updates / items / properties / detail / anyOf

Added value: +[
+  {
+    "description": "design notes shown in the pane detail panel: responsibility, contract, key decisions; null clears them",
+    "maxLength": 600,
+    "minLength": 1,
+    "pattern": "^[^\\u0000-\\u0008\\u000b-\\u001f\\u007f-\\u009f]*$",
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / updates / items / properties / detail / description

Previous value: -"design notes shown in the pane detail panel: responsibility, contract, key decisions"New value: +"design notes shown in the pane detail panel: responsibility, contract, key decisions; null clears them"

removedInput schema / properties / updates / items / properties / detail / maxLength
```
Removed value: -600
```
removedInput schema / properties / updates / items / properties / detail / type
```
Removed value: -"string"
```

addedInput schema / properties / updates / items / properties / evidence / anyOf

Added value: +[
+  {
+    "description": "for done: how it was verified; for regressed: what broke; null clears it",
+    "maxLength": 200,
+    "minLength": 1,
+    "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]*$",
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / updates / items / properties / evidence / description

Previous value: -"for done: how it was verified; for regressed: what broke"New value: +"for done: how it was verified; for regressed: what broke; null clears it"

removedInput schema / properties / updates / items / properties / evidence / maxLength
```
Removed value: -200
```
removedInput schema / properties / updates / items / properties / evidence / type
```
Removed value: -"string"
```

changedInput schema / properties / updates / items / properties / group / anyOf

Previous value: -[
-  {
-    "$ref": "#/properties/page"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "description": "join this same-band group; null leaves the current group",
+    "pattern": "^[a-z0-9][a-z0-9-]{0,63}$",
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

removedInput schema / properties / updates / items / properties / id / $ref
```
Removed value: -"#/properties/page"
```
addedInput schema / properties / updates / items / properties / id / description
```
Added value: +"id of the node to update"
```
addedInput schema / properties / updates / items / properties / id / pattern
```
Added value: +"^[a-z0-9][a-z0-9-]{0,63}$"
```
addedInput schema / properties / updates / items / properties / id / type
```
Added value: +"string"
```

changedInput schema / properties / updates / items / properties / kind / description

Previous value: -"set the node kind; null clears it"New value: +"node kind rendered as a glyph prefix. Known: selector | sequence | parallel | decorator | condition | action (behavior trees); source | transform | sink (dataflow); service | db | queue | ui (architecture). Unknown kinds are kept and shown in the detail panel."

addedInput schema / properties / updates / items / properties / label / description
```
Added value: +"new display label inside the box"
```
addedInput schema / properties / updates / items / properties / label / pattern
```
Added value: +"^[^\\u0000-\\u001f\\u007f-\\u009f]*$"
```

changedInput schema / properties / updates / items / properties / lane / anyOf

Previous value: -[
-  {
-    "$ref": "#/properties/page"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "description": "join this lane; null leaves the current lane",
+    "pattern": "^[a-z0-9][a-z0-9-]{0,63}$",
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / updates / items / properties / layer

Added value: +{
+  "description": "move the node to this band; applied before this item's other fields, so a node can move and join a group on the new band in one item. Every edge touching it must still point strictly downward, and a grouped node may only move to its group's band.",
+  "pattern": "^[a-z0-9][a-z0-9-]{0,63}$",
+  "type": "string"
+}

addedInput schema / properties / updates / items / properties / sources

Added value: +{
+  "anyOf": [
+    {
+      "description": "Optional source files and verified SHA256 baselines. mmap_read changes checks them without rescanning the repository.",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "path": {
+            "maxLength": 1024,
+            "type": "string"
+          },
+          "sha256": {
+            "pattern": "^[a-f0-9]{64}$",
+            "type": "string"
+          }
+        },
+        "required": [
+          "path"
+        ],
+        "type": "object"
+      },
+      "maxItems": 100,
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Optional source files and verified SHA256 baselines. mmap_read changes checks them without rescanning the repository."
+}

changedInput schema / properties / updates / items / properties / status / description

Previous value: -"planned = ghost on the map; in-progress = spinner; done = verified; regressed = was done, now broken"New value: +"the status to record. planned = ghost on the map; in-progress = spinner; done = verified; regressed = was done, now broken"

changedInput schema / properties / updates / items / properties / submap / anyOf

Previous value: -[
-  {
-    "$ref": "#/properties/page"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "description": "link a child map page by slug; null unlinks it",
+    "pattern": "^[a-z0-9][a-z0-9-]{0,63}$",
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / updates / items / properties / submap / description

Previous value: -"link a child map page; null unlinks it"New value: +"link a child map page by slug; null unlinks it"

removedInput schema / required
```
Removed value: -[
-  "updates"
-]
```

First observedv0.12.0Aug 13, 2026

TDQS

A4.3/5.0

Behavior4/5

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

With no annotations provided, the description carries the full burden, and it does substantial work: it discloses the all-or-nothing transactional nature, the ordering semantics ('Bands, groups and lanes are applied before the node updates', 'layer moves the node before its other fields'), the null-clears convention, the ledger honesty principle, and the fact that the map never blocks the reporter. It also discloses that unknown kinds are kept and shown in the detail panel. This is rich behavioral context beyond the schema.

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?

The description is dense but well-structured: it front-loads the tool's identity and core purpose, then enumerates operations in a logical order (progress, revision, structural moves, clearing, ordering, ledger principle). Every sentence carries information; there is no filler. It is longer than the ideal, but the tool is genuinely complex with 11 parameters and multiple operation families, so the length is justified.

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 complex 11-parameter mutation tool with no annotations and no output schema, the description covers a great deal: the all-or-nothing behavior, ordering semantics, null-clearing, the ledger principle, and the unsupported state-machine case. It does not explicitly describe return values or error behavior beyond the schema's CONFLICT mention, and it does not enumerate every parameter's purpose, but the schema covers 73% of parameters and the description adds the cross-cutting semantics that matter most.

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 73%, so the schema already documents most parameters. The description adds meaningful semantics beyond the schema: the null-clears convention for every clearable field, the ordering of band/group/lane application before node updates, the layer-moves-first rule within a node update, and the 'never an empty string' rule. These are exactly the kind of cross-parameter semantics that the schema's per-field descriptions cannot convey. It does not fully compensate for the 27% undocumented gap, but the added value is substantial.

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 description opens with a clear verb and resource ('revision tool, all-or-nothing') and enumerates the full scope: recording node progress, revising ghost-design mistakes, moving/renaming bands/groups/lanes, and clearing fields with null. It distinguishes itself from siblings by framing itself as the revision/update counterpart to mmap_declare and mmap_read, and the 'all-or-nothing' transactional note adds a specific behavioral identity.

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?

The description gives strong context for when to use this tool: record progress, revise ghost design, move/rename bands/groups/lanes, clear fields. It also gives an explicit exclusion ('State machines are unsupported') and a strong directive ('Read existing pages with mmap_read first; reuse the same page for continued work'). It does not explicitly name sibling alternatives like mmap_declare or mmap_remove, but the usage context is clear enough that an agent can route correctly.

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

Deploy Server

Record progress and revise the map

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools