Skip to main content
Glama
ng-galien

Maket

by ng-galien
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

maket_state

Attach a JSON Schema, durable data, and immutable revision history to one living document; then initialize, update, patch, validate, restore, or set retention.

Instructions

When to use: attach durable data and immutable snapshot history to one living document.

Document state is separate from collections and mail merge. A state-backed document renders Mustache variables, sections, inverted sections, and loops from its latest revision. Every mutation stores a complete validated schema + data snapshot. History is unbounded unless the document has a revision retention. The page interface is HTML/CSS, a JSON Forms template, or HTML embedding the current form at . Configure the form with maket_page set_form. HTML uses display-only Mustache plus explicit data-maket-bind controls. JSON Forms uses the document-state JSON Schema and data, with an optional UI schema. Both formats resolve to the same JSON Pointer patches and revisioned store. init — attach a schema and initial data to a static document (revision 1; no expected_revision). get — read the schema, the revision retention (retention, null when unbounded), and the current revision. update — append a complete state snapshot; expected_revision is required. patch — apply RFC 6902 JSON Patch operations; expected_revision is required. validate_schema — validate a proposed schema against current or supplied data without saving. change_schema — atomically replace the schema and append compatible data; expected_revision is required. history — list immutable revisions newest first. revision — read one revision. restore — append a new revision containing an older schema + data snapshot; expected_revision is required. set_retention — keep retention previous revisions besides the current one and delete older ones now and after every later write; 0 keeps only the current state, null restores unbounded history. Applies to Workspace items and collection projections too.

Input Schema

NameRequiredDescriptionDefault
docYesTarget document name.
dataNoComplete state object required by init/update; optional compatible data for schema validation/change.
patchNoRFC 6902 operations required by action=patch.
actionYesDocument-state operation to perform.
schemaNoJSON Schema required by init, validate_schema, and change_schema.
revisionNoHistorical revision required by revision and restore.
retentionNoFor set_retention: number of previous revisions kept besides the current one (0 keeps only the current state); null keeps the full history again.
expected_revisionNoCurrent revision required by update, patch, change_schema, and restore; not used by init.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv2.2.0
    • changedInput schema / properties / action / enum
      Previous value: -[
-  "init",
-  "get",
-  "update",
-  "patch",
-  "validate_schema",
-  "change_schema",
-  "history",
-  "revision",
-  "restore"
-]New value: +[
+  "init",
+  "get",
+  "update",
+  "patch",
+  "validate_schema",
+  "change_schema",
+  "history",
+  "revision",
+  "restore",
+  "set_retention"
+]
    • addedInput schema / properties / retention
      Added value: +{
+  "anyOf": [
+    {
+      "maximum": 9007199254740991,
+      "minimum": 0,
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "For set_retention: number of previous revisions kept besides the current one (0 keeps only the current state); null keeps the full history again."
+}
  2. Changed1 schema field changedv1.7.0
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
  3. Addedv1.5.0

TDQS

A4.5/5.0
Behavior4/5

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

With no annotations, the description carries full burden and does well: it discloses that every mutation stores a complete validated snapshot, that history is unbounded unless retention is set, that set_retention deletes older revisions immediately and after every later write, and that it also affects Workspace items and collection projections. It does not describe optimistic-concurrency failure behavior when expected_revision is stale, nor permissions/auth, which keeps it short of 5.

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 use case and alternative tools, then a compact action reference table where each line earns its place. The HTML/JSON Forms page-interface paragraph is longer and more tangential than the rest, and is the one section that could be trimmed, otherwise dense and well-organized.

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 an 8-parameter action-dispatch tool with no output schema and no annotations, the description is thorough: it defines all actions, mutation preconditions, and retention side effects. It leaves return shapes partially implicit (e.g., what history/revision return) and omits failure modes, but is otherwise complete enough to call the tool correctly.

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 schema already documents all 8 parameters (baseline 3). The description adds real meaning on top: which actions require expected_revision, which require a complete data object vs optional data, and the exact semantics of retention (0 vs null). It stops short of explaining JSON Pointer/patch path conventions, so 4 rather than 5.

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+resource: 'attach durable data and immutable snapshot history to one living document.' It explicitly distinguishes itself from collections and mail merge, and enumerates all ten actions with a one-line meaning each, so an agent can identify the tool and the operation without opening the 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?

Leads with 'When to use:' and names the alternatives it is not (collections, mail merge). Per-action notes state preconditions (expected_revision required by update/patch/change_schema/restore; init uses revision 1 with no expected_revision), which is exactly the when-to-use detail an agent needs to pick correctly.

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