Reference

MCP tools

All 15 local and cloud gram_* tool names, inputs and source-grounded result forms.

Explore as .gram

DocumentDashboard

Document

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.

Actual local request/output fixtures were captured at 2026-10-12T23:10:32.456Z from development producer 0.9.8 (33). Compiled MCP app inputs: source commit ac7bbad5c868510309b7666db7c16504f8724b52, digest sha256:2dcaeacf5e759eddc0bf1af41ee23b1a9a642e0d731bc2f1f027dfe2bc9d7fd3 (93 files); Whole-app checkout context recorded when the immutable producer proof was sealed: commit ac7bbad5c868510309b7666db7c16504f8724b52, full app-input digest sha256:cfcae64c10be5aadcac58993b637c78f1b718ce57f56bcd5794c674c7f7b0cb8 (99 files); this is not a live UI conformance claim. At contract load, freshness is asserted for the exact 47-file MCP/Core source closure, whose compiled, captured and current hashes match, with Core ABI v1 and cloud schema source thegram-vault/internal/mcp/gateway.go#335359731a3724bb0bf7a02093e3d7e1bbd93ccda3bbdff143b6178eec98a436. Immutable descriptor, matching-runtime build proof and completion receipt were independently verified by the descriptor loader.

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

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

Machine-readable request examples

Request: Actual request sent to the source-matched local MCP helper; not a generated schema-only example

{}

Actual operation output evidence

Operation: tools/call; source: thegram-desktop/App/Sources/AgentGateway.swift, thegram-desktop/Helper/ThegramMCP.swift, thegram-format/verification/native-core.mjs; fixture paths: undefined -> undefined

{
  "content": [
    {
      "text": "{\"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\"}",
      "type": "text"
    }
  ],
  "resultType": "complete",
  "structuredContent": {
    "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"
  }
}

Source-backed tool errors

Code: E_ARGUMENT; message: Unknown argument <key>

Sources: thegram-vault/internal/mcp/gateway.go#335359731a3724bb0bf7a02093e3d7e1bbd93ccda3bbdff143b6178eec98a436

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

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

Machine-readable request examples

Request: Actual request sent to the source-matched local MCP helper; not a generated schema-only example

{}

Actual operation output evidence

{
  "content": [
    {
      "text": "{\"access\":\"write\",\"mounts\":[],\"projects\":[[\"descriptor-fixture\",1]],\"vault\":\"descriptor-fixture\"}",
      "type": "text"
    }
  ],
  "resultType": "complete",
  "structuredContent": {
    "access": "write",
    "mounts": [],
    "projects": [
      [
        "descriptor-fixture",
        1
      ]
    ],
    "vault": "descriptor-fixture"
  }
}

Source-backed tool errors

Code: E_ARGUMENT; message: Unknown argument <key>

Sources: thegram-vault/internal/mcp/gateway.go#335359731a3724bb0bf7a02093e3d7e1bbd93ccda3bbdff143b6178eec98a436

Code: E_STORAGE; message: workspace storage is not configured

Sources: thegram-vault/internal/mcp/workspace.go#9de8ccbfe796301fd9406f7b78d775da520dfb77127aea2a3caf499391143ad9

Code: PROVIDER_AUTH_REQUIRED; message: Google Drive must be reconnected

Sources: thegram-vault/internal/mcp/workspace.go#9de8ccbfe796301fd9406f7b78d775da520dfb77127aea2a3caf499391143ad9

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

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

Machine-readable request examples

Request: Actual request sent to the source-matched local MCP helper; not a generated schema-only example

{}

Actual operation output evidence

{
  "content": [
    {
      "text": "{\"budget_bytes\":16384,\"index\":{\"embeddedChunks\":0,\"failedFiles\":0,\"indexedFiles\":0,\"pendingFiles\":0},\"semantic\":{\"reason\":\"EMBEDDING_UNAVAILABLE: missing model/embeddinggemma-2/tokenizer.json\",\"status\":\"unavailable\"},\"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\"]}",
      "type": "text"
    }
  ],
  "resultType": "complete",
  "structuredContent": {
    "budget_bytes": 16384,
    "index": {
      "embeddedChunks": 0,
      "failedFiles": 0,
      "indexedFiles": 0,
      "pendingFiles": 0
    },
    "semantic": {
      "reason": "EMBEDDING_UNAVAILABLE: missing model/embeddinggemma-2/tokenizer.json",
      "status": "unavailable"
    },
    "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"
    ]
  }
}

Source-backed tool errors

Code: E_ARGUMENT; message: Unknown argument <key>

Sources: thegram-vault/internal/mcp/gateway.go#335359731a3724bb0bf7a02093e3d7e1bbd93ccda3bbdff143b6178eec98a436

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

{
  "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 request sent to the source-matched local MCP helper; not a generated schema-only example

{
  "query": "lunar migration evidence",
  "mode": "keyword"
}

Actual operation output evidence

{
  "content": [
    {
      "text": "{\"docs\":[{\"hash\":\"d4344a16bec94a0a\",\"path\":\"descriptor-fixture/doc.gram\",\"rev\":1}],\"hits\":[[\"descriptor-fixture/doc.gram#d_51779bca8dd74f53afe256c4bc8fbe2d\",\"document\",\"Lunar migration decision\",null,\"section: Descriptor fixture\"],[\"descriptor-fixture/doc.gram#e1\",\"evidence\",\"Lunar migration evidence\",null]]}",
      "type": "text"
    }
  ],
  "resultType": "complete",
  "structuredContent": {
    "docs": [
      {
        "hash": "d4344a16bec94a0a",
        "path": "descriptor-fixture/doc.gram",
        "rev": 1
      }
    ],
    "hits": [
      [
        "descriptor-fixture/doc.gram#d_51779bca8dd74f53afe256c4bc8fbe2d",
        "document",
        "Lunar migration decision",
        null,
        "section: Descriptor fixture"
      ],
      [
        "descriptor-fixture/doc.gram#e1",
        "evidence",
        "Lunar migration evidence",
        null
      ]
    ]
  }
}

Source-backed tool errors

Code: E_ARGUMENT; message: Unknown argument <key>

Sources: thegram-vault/internal/mcp/gateway.go#335359731a3724bb0bf7a02093e3d7e1bbd93ccda3bbdff143b6178eec98a436

Code: E_STORAGE; message: workspace storage is not configured

Sources: thegram-vault/internal/mcp/workspace.go#9de8ccbfe796301fd9406f7b78d775da520dfb77127aea2a3caf499391143ad9

Code: PROVIDER_AUTH_REQUIRED; message: Google Drive must be reconnected

Sources: thegram-vault/internal/mcp/workspace.go#9de8ccbfe796301fd9406f7b78d775da520dfb77127aea2a3caf499391143ad9

Code: E_PATH; message: Absolute paths are outside the approved folder

Sources: thegram-vault/internal/mcp/paths.go#754797578ba9858e6db8707f17ca9ceed82914215e83e00e437a05e925bff936

Code: E_PATH; message: Path does not start with a mounted collection

Sources: thegram-vault/internal/mcp/paths.go#754797578ba9858e6db8707f17ca9ceed82914215e83e00e437a05e925bff936

Code: E_PATH; message: Path is outside the approved folders

Sources: thegram-vault/internal/mcp/paths.go#754797578ba9858e6db8707f17ca9ceed82914215e83e00e437a05e925bff936

Code: E_PATH; message: Path is outside an approved folder or hidden

Sources: thegram-vault/internal/mcp/paths.go#754797578ba9858e6db8707f17ca9ceed82914215e83e00e437a05e925bff936

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

{
  "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 request sent to the source-matched local MCP helper; not a generated schema-only example

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

Actual operation output evidence

{
  "content": [
    {
      "text": "{\"doc\":{\"hash\":\"d4344a16bec94a0a\",\"path\":\"descriptor-fixture/doc.gram\",\"rev\":1},\"entities\":[[\"d1\",\"decision\"],[\"e1\",\"evidence\"]]}",
      "type": "text"
    }
  ],
  "resultType": "complete",
  "structuredContent": {
    "doc": {
      "hash": "d4344a16bec94a0a",
      "path": "descriptor-fixture/doc.gram",
      "rev": 1
    },
    "entities": [
      [
        "d1",
        "decision"
      ],
      [
        "e1",
        "evidence"
      ]
    ]
  }
}

Source-backed tool errors

Code: E_ARGUMENT; message: Unknown argument <key>

Sources: thegram-vault/internal/mcp/gateway.go#335359731a3724bb0bf7a02093e3d7e1bbd93ccda3bbdff143b6178eec98a436

Code: E_CURSOR; message: Invalid list cursor

Sources: thegram-vault/internal/mcp/tools_common.go#f243590ff0ab46a241c752ae104c538e5064c869525209dfc7219572d6d5523c

Code: STALE_READ; message: The document changed while it was read; read again

Sources: thegram-vault/internal/mcp/tools_common.go#f243590ff0ab46a241c752ae104c538e5064c869525209dfc7219572d6d5523c

Code: STALE_CURSOR; message: The documents changed since this cursor; list again