@gram 2
doc portal-reference-mcp-tools
t MCP tools
d All 15 local and cloud gram_* tool names, inputs and source-grounded result forms.
view document
::rich
# MCP tools

Local and cloud MCP publish the same 15 public gram_* tools. Input schemas below come from the local MCP tools/list response; cloud schemas are parsed from the checked-in Go descriptor source and compared by SHA-256. Each request payload is a schema-validated actual fixture. Output evidence is captured from real Core/MCP operations. No public output JSON Schema is published.

## Tool contracts

### `gram_profile`

Local description: Write and read contract: the .gram vocabulary, the md body and its gram-rich/1 nodes, and how Thegram shows them. Read it before the first write.

Cloud description: Write and read contract: the .gram vocabulary, the md body and its gram-rich/1 nodes, and how Thegram shows them. Read it before the first write.

The cloud descriptor publishes the same input schema as the local descriptor; parity is recorded in the reference contract.

#### Actual input JSON Schema

```json
{
  "additionalProperties": false,
  "properties": {
    "task": {
      "enum": [
        "create",
        "edit",
        "rich",
        "read",
        "memory"
      ],
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}
```

#### Machine-readable request examples

Request: Actual local MCP request/output fixture

```json
{}
```

#### Actual operation output evidence

Operation: tools/call; source: [object Object]

```json
{
  "budget_bytes": 16384,
  "common": {
    "body": "Write the body as md: # headings, paragraphs, - or 1. lists (2-space nesting), | tables | with a |---| row and the same number of cells in every row (write a | inside a cell as \\|), > quotes, > [!note] on its own line followed by > text lines, code fences, $$ math, --- divider. [[record-id]] alone on a line places a record; [[*]]{type=task view=board} places the records matching type/status/tag; [label](@record-id) mentions a record inside a sentence.",
    "checklists": "A checklist is task records with x; there is no separate checkbox syntax.",
    "document": "One .gram file is one document: the doc owner, then records. Each owner has fields, links and blocks; the doc body is Markdown-like text (gram-rich/1 tree for rich changes). Core keeps every revision in the same file.",
    "links": "predicates related supports contradicts depends implements replaces derives blocks enables part-of; target is a record id here or document-id/entity-id in another document. Write a link as {predicate, target} or [predicate, target]. The doc owner has no links.",
    "numbers": "Do not copy a record's value into prose; mention the record instead, so the sentence follows the record.",
    "records": "type is one of task decision evidence knowledge context history goal blocker requirement risk assumption metric event artifact person agent project system service component source run asset. Fields: t title (required, one line), d description, x status (open active blocked completed accepted superseded ...), p priority (high medium low), owner, tag (repeat), source (repeat, a source record id), ref (URI or asset path), view, motion. metric: value unit observed. task: due (ISO date). event: at (ISO date or time). color: #RRGGBB. Values are kept as written.",
    "writes": "Pass the observed base_revision and expected_hash. One gram_create or gram_patch is one revision: add a record and place it in the body in the same patch. Reuse a request_id only to retry the same change; a lost answer is settled from the receipt."
  },
  "profile": "gram/2 md body + gram-rich/1 r2 changes",
  "read": {
    "gram_context": "Fields, links and the body as plain text in which mentions and items read as the records they point at; a decision also carries implemented, the date written on the earliest event in the same document that implements it.",
    "gram_get outline": "outline:true on the doc returns each top-level body block as [node id, node type, shown as, label]; use the ids to edit.",
    "gram_patch": "The answer carries diagnostics when something written cannot be shown as intended: unresolved_ref, unsupported_node, unparsed_value. The write itself is already committed."
  },
  "shown": {
    "collection": [
      "view is list; compact emoji, title and muted status rows → list",
      "view is table; plain table with bold header and wrapping cells → table",
      "no supported view and only tasks selected → list",
      "no supported view and any other or empty selection → table"
    ],
    "item": [
      "reference is unavailable → unresolved",
      "task; checkbox line with editable title and optional due, status and priority controls → task-row",
      "metric; inline title, value and unit fields → metric",
      "image asset; picture with muted title caption → image",
      "other record; emoji, editable semibold title, muted status and description (d or reason/summary/quote blocks); item view ignored → line"
    ]
  },
  "task": "read"
}
```

Output JSON Schema: absent from the public descriptors. The payload above is actual fixture evidence, not a schema.

### `gram_projects`

Local description: The Thegram folder shared with agents plus mounted collections: local project folders and mounts as {key, id, kind, name, count, access}. Use the exact mount key from this list as a path prefix, e.g. @mounts/<mount-id>/proj/notes.gram. The @mounts namespace is reserved so mount paths never shadow local projects. Mount access never exceeds existing agent approval.

Cloud description: The Thegram folder shared with agents plus mounted collections: local project folders and mounts as {key, id, kind, name, count, access}. Use the exact mount key from this list as a path prefix, e.g. @mounts/<mount-id>/proj/notes.gram. The @mounts namespace is reserved so mount paths never shadow local projects. Mount access never exceeds existing agent approval.

The cloud descriptor publishes the same input schema as the local descriptor; parity is recorded in the reference contract.

#### Actual input JSON Schema

```json
{
  "additionalProperties": false,
  "properties": {},
  "required": [],
  "type": "object"
}
```

#### Machine-readable request examples

Request: Actual local MCP request/output fixture

```json
{}
```

#### Actual operation output evidence

Operation: tools/call; source: [object Object]

```json
{
  "access": "write",
  "mounts": [],
  "projects": [
    [
      "descriptor-fixture",
      1
    ]
  ],
  "vault": "descriptor-fixture"
}
```

Output JSON Schema: absent from the public descriptors. The payload above is actual fixture evidence, not a schema.

### `gram_capabilities`

Local description: Tools, whether semantic search actually works now, and the folder's index state.

Cloud description: Tools, whether semantic search actually works now, and the folder's index state.

The cloud descriptor publishes the same input schema as the local descriptor; parity is recorded in the reference contract.

#### Actual input JSON Schema

```json
{
  "additionalProperties": false,
  "properties": {},
  "required": [],
  "type": "object"
}
```

#### Machine-readable request examples

Request: Actual local MCP request/output fixture

```json
{}
```

#### Actual operation output evidence

Operation: tools/call; source: [object Object]

```json
{
  "budget_bytes": 16384,
  "index": {
    "embeddedChunks": 0,
    "failedFiles": 0,
    "indexedFiles": 0,
    "pendingFiles": 0
  },
  "semantic": {
    "status": "available"
  },
  "tools": [
    "gram_profile",
    "gram_capabilities",
    "gram_projects",
    "gram_brief",
    "gram_read",
    "gram_changes",
    "gram_recall",
    "gram_list",
    "gram_get",
    "gram_context",
    "gram_relations",
    "gram_range",
    "gram_state",
    "gram_create",
    "gram_patch"
  ]
}
```

Output JSON Schema: absent from the public descriptors. The payload above is actual fixture evidence, not a schema.

### `gram_recall`

Local description: Search by relevance. Inclusive from/to filter record dates; date-only to includes the day, and YYYY-MM/YYYY mean a span; date selects a field. Defaults are event at, metric observed, task due, otherwise at. A date/month/year query in keyword, exact or auto matches record dates. scope means exact s-tag membership only (not section or type); type filters record type. Filters refill top_k from further candidates. When available, the final hit value is cosine similarity; compare only for the same query and model, not against a universal floor. Prefer hybrid or keyword when semantic hits are loose.

Cloud description: Search by relevance. Inclusive from/to filter record dates; date-only to includes the day, and YYYY-MM/YYYY mean a span; date selects a field. Defaults are event at, metric observed, task due, otherwise at. A date/month/year query in keyword, exact or auto matches record dates. scope means exact s-tag membership only (not section or type); type filters record type. Filters refill top_k from further candidates. When available, the final hit value is cosine similarity; compare only for the same query and model, not against a universal floor. Prefer hybrid or keyword when semantic hits are loose.

The cloud descriptor publishes the same input schema as the local descriptor; parity is recorded in the reference contract.

#### Actual input JSON Schema

```json
{
  "additionalProperties": false,
  "properties": {
    "cursor": {
      "type": "string"
    },
    "date": {
      "type": "string"
    },
    "documents": {
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "folder": {
      "type": "string"
    },
    "from": {
      "type": "string"
    },
    "mode": {
      "enum": [
        "exact",
        "keyword",
        "semantic",
        "hybrid",
        "auto"
      ],
      "type": "string"
    },
    "query": {
      "type": "string"
    },
    "scope": {
      "type": "string"
    },
    "to": {
      "type": "string"
    },
    "top_k": {
      "minimum": 1,
      "type": "integer"
    },
    "type": {
      "type": "string"
    }
  },
  "required": [
    "query"
  ],
  "type": "object"
}
```

#### Machine-readable request examples

Request: Actual local MCP request/output fixture

```json
{
  "query": "descriptor tool evidence"
}
```

#### Actual operation output evidence

Operation: tools/call; source: [object Object]

```json
{
  "docs": [],
  "hits": [],
  "mode": "keyword",
  "reason": "SEMANTIC_INDEX_STALE"
}
```

Output JSON Schema: absent from the public descriptors. The payload above is actual fixture evidence, not a schema.

### `gram_list`

Local description: No path: every document as [path, title, rev]; path of a folder: the documents in it. With select {type?, status?, tag?, from?, to?, date?}: matching records as [path#id, type, title, status|null, date?], filtered by inclusive date span, sorted by the selected date; date-only to includes that day and YYYY-MM / YYYY are shorthand. Date defaults by record type: event at, metric observed, task due, otherwise at; date names another field. Path of a .gram: its entity ids in source order, optionally at a past revision.

Cloud description: No path: every document as [path, title, rev]; path of a folder: the documents in it. With select {type?, status?, tag?, from?, to?, date?}: matching records as [path#id, type, title, status|null, date?], filtered by inclusive date span, sorted by the selected date; date-only to includes that day and YYYY-MM / YYYY are shorthand. Date defaults by record type: event at, metric observed, task due, otherwise at; date names another field. Path of a .gram: its entity ids in source order, optionally at a past revision.

The cloud descriptor publishes the same input schema as the local descriptor; parity is recorded in the reference contract.

#### Actual input JSON Schema

```json
{
  "additionalProperties": false,
  "properties": {
    "cursor": {
      "type": "string"
    },
    "effective_at": {
      "type": "string"
    },
    "limit": {
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    },
    "path": {
      "type": "string"
    },
    "recorded_at": {
      "type": "string"
    },
    "revision": {
      "minimum": 0,
      "type": "integer"
    },
    "select": {
      "additionalProperties": false,
      "properties": {
        "date": {
          "type": "string"
        },
        "from": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "tag": {
          "type": "string"
        },
        "to": {
          "type": "string"
        },
        "type": {
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "required": [],
  "type": "object"
}
```

#### Machine-readable request examples

Request: Actual local MCP request/output fixture

```json
{
  "path": "descriptor-fixture/doc.gram"
}
```

#### Actual operation output evidence

Operation: tools/call; source: [object Object]

```json
{
  "doc": {
    "hash": "0d8a4b16c7d77a03",
    "path": "descriptor-fixture/doc.gram",
    "rev": 0
  },
  "entities": [
    [
      "d1",
      "decision"
    ]
  ]
}
```

Output JSON Schema: absent from the public descriptors. The payload above is actual fixture evidence, not a schema.

### `gram_get`

Local description: One entity's selected fields/blocks/links, optionally at a past revision. outline:true lists the body's top-level blocks as [node id, type, shown as, label]. For several entities use gram_context.

Cloud description: One entity's selected fields/blocks/links, optionally at a past revision. outline:true lists the body's top-level blocks as [node id, type, shown as, label]. For several entities use gram_context.

The cloud descriptor publishes the same input schema as the local descriptor; parity is recorded in the reference contract.

#### Actual input JSON Schema

```json
{
  "additionalProperties": false,
  "properties": {
    "blocks": {
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "effective_at": {
      "type": "string"
    },
    "entity": {
      "type": "string"
    },
    "fields": {
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "links": {
      "type": "boolean"
    },
    "outline": {
      "type": "boolean"
    },
    "path": {
      "type": "string"
    },
    "recorded_at": {
      "type": "string"
    },
    "revision": {
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "path",
    "entity"
  ],
  "type": "object"
}
```

#### Machine-readable request examples

Request: Actual local MCP request/output fixture

```json
{
  "path": "descriptor-fixture/doc.gram",
  "entity": "d1"
}
```

#### Actual operation output evidence

Operation: tools/call; source: [object Object]

```json
{
  "doc": {
    "hash": "0d8a4b16c7d77a03",
    "path": "descriptor-fixture/doc.gram",
    "rev": 0
  },
  "entity": {
    "fields": {
      "t": [
        "Task-scoped descriptor fixture"
      ]
    },
    "id": "d1",
    "type": "decision"
  }
}
```

Output JSON Schema: absent from the public descriptors. The payload above is actual fixture evidence, not a schema.

### `gram_context`

Local description: Read many entities in one call: fields (default t d x p owner tag due at value unit source ref), links and bounded rich text for each {path, entity}; a decision adds implemented, the date of its earliest implementing event. Prefer this to repeated gram_get.

Cloud description: Read many entities in one call: fields (default t d x p owner tag due at value unit source ref), links and bounded rich text for each {path, entity}; a decision adds implemented, the date of its earliest implementing event. Prefer this to repeated gram_get.

The cloud descriptor publishes the same input schema as the local descriptor; parity is recorded in the reference contract.

#### Actual input JSON Schema

```json
{
  "additionalProperties": false,
  "properties": {
    "cursor": {
      "type": "string"
    },
    "fields": {
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "ids": {
      "items": {
        "properties": {
          "effective_at": {
            "type": "string"
          },
          "entity": {
            "type": "string"
          },
          "path": {
            "type": "string"
          },
          "recorded_at": {
            "type": "string"
          },
          "revision": {
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "path",
          "entity"
        ],
        "type": "object"
      },
      "minItems": 1,
      "type": "array"
    }
  },
  "required": [
    "ids"
  ],
  "type": "object"
}
```

#### Machine-readable request examples

Request: Actual local MCP request/output fixture

```json
{
  "ids": [
    {
      "path": "descriptor-fixture/doc.gram",
      "entity": "d1"
    }
  ]
}
```

#### Actual operation output evidence

Operation: tools/call; source: [object Object]

```json
{
  "docs": [
    {
      "hash": "0d8a4b16c7d77a03",
      "path": "descriptor-fixture/doc.gram",
      "rev": 0
    }
  ],
  "items": [
    {
      "fields": {
        "t": [
          "Task-scoped descriptor fixture"
        ]
      },
      "id": "d1",
      "type": "decision"
    }
  ]
}
```

Output JSON Schema: absent from the public descriptors. The payload above is actual fixture evidence, not a schema.

### `gram_relations`

Local description: Explicit links and REL edges from one entity; defaults to its project documents.

Cloud description: Explicit links and REL edges from one entity; defaults to its project documents.

The cloud descriptor publishes the same input schema as the local descriptor; parity is recorded in the reference contract.

#### Actual input JSON Schema

```json
{
  "additionalProperties": false,
  "properties": {
    "cursor": {
      "type": "string"
    },
    "depth": {
      "maximum": 3,
      "minimum": 1,
      "type": "integer"
    },
    "direction": {
      "enum": [
        "out",
        "in",
        "both"
      ],
      "type": "string"
    },
    "from": {
      "properties": {
        "entity": {
          "type": "string"
        },
        "path": {
          "type": "string"
        }
      },
      "required": [
        "path",
        "entity"
      ],
      "type": "object"
    },
    "limit": {
      "minimum": 1,
      "type": "integer"
    },
    "paths": {
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "predicates": {
      "items": {
        "type": "string"
      },
      "type": "array"
    }
  },
  "required": [
    "from"
  ],
  "type": "object"
}
```

#### Machine-readable request examples

Request: Actual local MCP request/output fixture

```json
{
  "from": {
    "path": "descriptor-fixture/doc.gram",
    "entity": "d1"
  }
}
```

#### Actual operation output evidence

Operation: tools/call; source: [object Object]

```json
{
  "docs": [],
  "edges": []
}
```

Output JSON Schema: absent from the public descriptors. The payload above is actual fixture evidence, not a schema.

### `gram_brief`

Local description: Start here. One call orients you in a project folder (folder) or one memory document (path): docs [path, title, rev, hash, last recorded, last effective] (rev and hash are the CAS pair for gram_patch), counts by type, open records [path#id, type, title, status, priority] (work types only, blockers and risks first; proposed and finished ones left out), recent revisions [path, rev, recorded, effective, by, "+added ~changed -removed"], and next: keep it and pass it to gram_changes since on your next visit.

Cloud description: Start here. One call orients you in a project folder (folder) or one memory document (path): docs [path, title, rev, hash, last recorded, last effective] (rev and hash are the CAS pair for gram_patch), counts by type, open records [path#id, type, title, status, priority] (work types only, blockers and risks first; proposed and finished ones left out), recent revisions [path, rev, recorded, effective, by, "+added ~changed -removed"], and next: keep it and pass it to gram_changes since on your next visit.

The cloud descriptor publishes the same input schema as the local descriptor; parity is recorded in the reference contract.

#### Actual input JSON Schema

```json
{
  "additionalProperties": false,
  "properties": {
    "folder": {
      "type": "string"
    },
    "limit": {
      "maximum": 50,
      "minimum": 1,
      "type": "integer"
    },
    "path": {
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}
```

#### Machine-readable request examples

Request: Actual local MCP request/output fixture

```json
{}
```

#### Actual operation output evidence

Operation: tools/call; source: [object Object]

```json
{
  "counts": {
    "decision": 1
  },
  "docs": [
    [
      "descriptor-fixture/doc.gram",
      "Descriptor fixture",
      0,
      "0d8a4b16c7d77a03",
      "2026-10-12T13:41:21.161Z",
      null
    ]
  ],
  "next": "2026-10-12T13:41:21.161Z",
  "open": [],
  "recent": [
    [
      "descriptor-fixture/doc.gram",
      0,
      "2026-10-12T13:41:21.161Z",
      null,
      "thegram-descriptor-fixture",
      "+2 ~0 -0"
    ]
  ],
  "scope": "."
}
```

Output JSON Schema: absent from the public descriptors. The payload above is actual fixture evidence, not a schema.

### `gram_read`

Local description: Read one document a section at a time. Without section: the heading outline [level, heading, node id, chars]. With section: {doc, section, level, md, more?}; historical reads also include at. Agent record lines include id and raw type/x/p; at, due, the first value and optional unit/observed; non-empty d on the next line; and replaces links. at/observed dates beginning YYYY-MM-DD are shortened to 10 characters; a decision without at shows its earliest implementing event's date. Other fields (owner/tag/source/ref), other links, and extra values require gram_context. Collections use raw-type headings and id-bearing bullets; images use Markdown image refs. No separate records index is returned. A long section continues with cursor = more.

Cloud description: Read one document a section at a time. Without section: the heading outline [level, heading, node id, chars]. With section: {doc, section, level, md, more?}; historical reads also include at. Agent record lines include id and raw type/x/p; at, due, the first value and optional unit/observed; non-empty d on the next line; and replaces links. at/observed dates beginning YYYY-MM-DD are shortened to 10 characters; a decision without at shows its earliest implementing event's date. Other fields (owner/tag/source/ref), other links, and extra values require gram_context. Collections use raw-type headings and id-bearing bullets; images use Markdown image refs. No separate records index is returned. A long section continues with cursor = more.

The cloud descriptor publishes the same input schema as the local descriptor; parity is recorded in the reference contract.

#### Actual input JSON Schema

```json
{
  "additionalProperties": false,
  "properties": {
    "cursor": {
      "type": "string"
    },
    "effective_at": {
      "type": "string"
    },
    "path": {
      "type": "string"
    },
    "recorded_at": {
      "type": "string"
    },
    "revision": {
      "minimum": 0,
      "type": "integer"
    },
    "section": {
      "type": "string"
    }
  },
  "required": [
    "path"
  ],
  "type": "object"
}
```

#### Machine-readable request examples

Request: Actual local MCP request/output fixture

```json
{
  "path": "descriptor-fixture/doc.gram"
}
```

#### Actual operation output evidence

Operation: tools/call; source: [object Object]

```json
{
  "doc": {
    "hash": "0d8a4b16c7d77a03",
    "path": "descriptor-fixture/doc.gram",
    "rev": 0
  },
  "outline": [],
  "title": "Descriptor fixture"
}
```

Output JSON Schema: absent from the public descriptors. The payload above is actual fixture evidence, not a schema.

### `gram_changes`

Local description: What changed after since (ISO time, exclusive) in a folder or document, or after since_revision in one document: each revision with add [id, type, title], set [id, title, changed keys], del [id, title]; the document owner is doc. next is the time to pass as since later; more continues the page.

Cloud description: What changed after since (ISO time, exclusive) in a folder or document, or after since_revision in one document: each revision with add [id, type, title], set [id, title, changed keys], del [id, title]; the document owner is doc. next is the time to pass as since later; more continues the page.

The cloud descriptor publishes the same input schema as the local descriptor; parity is recorded in the reference contract.

#### Actual input JSON Schema

```json
{
  "additionalProperties": false,
  "properties": {
    "cursor": {
      "type": "string"
    },
    "folder": {
      "type": "string"
    },
    "limit": {
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    },
    "path": {
      "type": "string"
    },
    "since": {
      "type": "string"
    },
    "since_revision": {
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [],
  "type": "object"
}
```

#### Machine-readable request examples

Request: Actual local MCP request/output fixture

```json
{
  "path": "descriptor-fixture/doc.gram",
  "since_revision": 0
}
```

#### Actual operation output evidence

Operation: tools/call; source: [object Object]

```json
{
  "changes": [],
  "docs": [],
  "next": "2026-10-12T13:41:21.161Z"
}
```

Output JSON Schema: absent from the public descriptors. The payload above is actual fixture evidence, not a schema.

### `gram_range`

Local description: History events of one document; with query, only changes relevant to it.

Cloud description: History events of one document; with query, only changes relevant to it.

The cloud descriptor publishes the same input schema as the local descriptor; parity is recorded in the reference contract.

#### Actual input JSON Schema

```json
{
  "additionalProperties": false,
  "properties": {
    "expected_hash": {
      "type": "string"
    },
    "limit": {
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    },
    "path": {
      "type": "string"
    },
    "query": {
      "type": "string"
    },
    "start": {
      "minimum": 0,
      "type": "integer"
    },
    "top_k": {
      "minimum": 1,
      "type": "integer"
    }
  },
  "required": [
    "path"
  ],
  "type": "object"
}
```

#### Machine-readable request examples

Request: Actual local MCP request/output fixture

```json
{
  "path": "descriptor-fixture/doc.gram"
}
```

#### Actual operation output evidence

Operation: tools/call; source: [object Object]

```json
{
  "doc": {
    "hash": "0d8a4b16c7d77a03",
    "path": "descriptor-fixture/doc.gram",
    "rev": 0
  },
  "events": [
    {
      "actor": "agent",
      "agent": "thegram-descriptor-fixture",
      "recorded_at": "2026-10-12T13:41:21.161Z",
      "revision": 0
    }
  ]
}
```

Output JSON Schema: absent from the public descriptors. The payload above is actual fixture evidence, not a schema.

### `gram_state`

Local description: One document as it was at a revision, at a write time (recorded_at), or at the time its facts happened (effective_at).

Cloud description: One document as it was at a revision, at a write time (recorded_at), or at the time its facts happened (effective_at).

The cloud descriptor publishes the same input schema as the local descriptor; parity is recorded in the reference contract.

#### Actual input JSON Schema

```json
{
  "additionalProperties": false,
  "properties": {
    "cursor": {
      "type": "string"
    },
    "entity": {
      "type": "string"
    },
    "path": {
      "type": "string"
    },
    "selector": {
      "properties": {
        "effective_at": {
          "type": "string"
        },
        "recorded_at": {
          "type": "string"
        },
        "revision": {
          "minimum": 0,
          "type": "integer"
        }
      },
      "type": "object"
    }
  },
  "required": [
    "path",
    "selector"
  ],
  "type": "object"
}
```

#### Machine-readable request examples

Request: Actual local MCP request/output fixture

```json
{
  "path": "descriptor-fixture/doc.gram",
  "selector": {
    "revision": 0
  }
}
```

#### Actual operation output evidence

Operation: tools/call; source: [object Object]

```json
{
  "at": {
    "at": "2026-10-12T13:41:21.161Z",
    "eff": null,
    "rev": 0
  },
  "doc": {
    "hash": "0d8a4b16c7d77a03",
    "path": "descriptor-fixture/doc.gram",
    "rev": 0
  },
  "entities": [
    [
      "d1",
      "decision",
      "Task-scoped descriptor fixture"
    ]
  ],
  "title": "Descriptor fixture"
}
```

Output JSON Schema: absent from the public descriptors. The payload above is actual fixture evidence, not a schema.

### `gram_create`

Local description: Create a .gram document; a new folder in the path becomes a new project folder. content is the body as md text, or {text|rich, records, fields, blocks} to write structure in one revision. effective_at (ISO time) records when the written facts happened.

Cloud description: Create a .gram document; a new folder in the path becomes a new project folder. content is the body as md text, or {text|rich, records, fields, blocks} to write structure in one revision. effective_at (ISO time) records when the written facts happened.

The cloud descriptor publishes the same input schema as the local descriptor; parity is recorded in the reference contract.

#### Actual input JSON Schema

```json
{
  "additionalProperties": false,
  "properties": {
    "base_revision": {
      "type": "null"
    },
    "content": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "additionalProperties": false,
          "properties": {
            "blocks": {
              "items": {
                "type": "object"
              },
              "type": "array"
            },
            "fields": {
              "type": "object"
            },
            "records": {
              "items": {
                "type": "object"
              },
              "type": "array"
            },
            "rich": {
              "type": "object"
            },
            "text": {
              "type": "string"
            }
          },
          "type": "object"
        }
      ]
    },
    "effective_at": {
      "type": "string"
    },
    "path": {
      "type": "string"
    },
    "title": {
      "type": "string"
    }
  },
  "required": [
    "path",
    "base_revision",
    "title",
    "content"
  ],
  "type": "object"
}
```

#### Machine-readable request examples

Request: Actual local MCP request/output fixture

```json
{
  "path": "descriptor-fixture/doc.gram",
  "base_revision": null,
  "title": "Descriptor fixture",
  "content": {
    "records": [
      {
        "type": "decision",
        "id": "d1",
        "fields": {
          "t": [
            "Task-scoped descriptor fixture"
          ]
        }
      }
    ]
  }
}
```

#### Actual operation output evidence

Operation: tools/call; source: [object Object]

```json
{
  "created": [
    "d1"
  ],
  "doc": {
    "hash": "0d8a4b16c7d77a03",
    "path": "descriptor-fixture/doc.gram",
    "rev": 0
  },
  "receipt": {
    "revision": 0,
    "status": "success"
  }
}
```

Output JSON Schema: absent from the public descriptors. The payload above is actual fixture evidence, not a schema.

### `gram_patch`

Local description: Change a document against the observed rev/hash. Resending the same request_id returns the original receipt. An add operation may carry place: "end", {after: record or node id} or {section: heading text or node id} to put the new record in the body in the same revision. effective_at (ISO time) records when the change happened.

Cloud description: Change a document against the observed rev/hash. Resending the same request_id returns the original receipt. An add operation may carry place: "end", {after: record or node id} or {section: heading text or node id} to put the new record in the body in the same patch. effective_at (ISO time) records when the change happened.

The cloud descriptor publishes the same input schema as the local descriptor; parity is recorded in the reference contract.

#### Actual input JSON Schema

```json
{
  "additionalProperties": false,
  "properties": {
    "base_revision": {
      "minimum": 0,
      "type": "integer"
    },
    "effective_at": {
      "type": "string"
    },
    "expected_hash": {
      "minLength": 1,
      "type": "string"
    },
    "operations": {
      "items": {
        "type": "object"
      },
      "minItems": 1,
      "type": "array"
    },
    "path": {
      "type": "string"
    },
    "request_id": {
      "description": "Stable per intended change; reuse only to retry the same change.",
      "maxLength": 128,
      "minLength": 1,
      "type": "string"
    }
  },
  "required": [
    "path",
    "base_revision",
    "expected_hash",
    "request_id",
    "operations"
  ],
  "type": "object"
}
```

#### Machine-readable request examples

Request: Actual local MCP request/output fixture

```json
{
  "path": "descriptor-fixture/doc.gram",
  "base_revision": 0,
  "expected_hash": "0d8a4b16c7d77a03",
  "request_id": "descriptor-evidence-patch",
  "operations": [
    {
      "op": "set",
      "entity": "d1",
      "key": "x",
      "value": "Core MCP fixture"
    }
  ]
}
```

#### Actual operation output evidence

Operation: tools/call; source: [object Object]

```json
{
  "doc": {
    "hash": "940f584dce3e48c5",
    "path": "descriptor-fixture/doc.gram",
    "rev": 1
  },
  "receipt": {
    "request_id": "descriptor-evidence-patch",
    "revision": 1,
    "status": "success"
  }
}
```

Output JSON Schema: absent from the public descriptors. The payload above is actual fixture evidence, not a schema.
::end

SRC format-language
t .gram language specification
ref https://github.com/clab-one/thegram-format/blob/main/spec/language.md
SRC format-rich
t Current rich document specification
ref https://github.com/clab-one/thegram-format/blob/main/spec/rich-document.md
SRC format-history6
t Current History/6 specification
ref https://github.com/clab-one/thegram-format/blob/main/spec/source-history-render.md