@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. 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 ```json { "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 ```json {} ``` #### 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 ```json { "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 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//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//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 request sent to the source-matched local MCP helper; not a generated schema-only example ```json {} ``` #### 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 ```json { "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 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 ```json { "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 ```json {} ``` #### 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 ```json { "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 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 ```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 request sent to the source-matched local MCP helper; not a generated schema-only example ```json { "query": "lunar migration evidence", "mode": "keyword" } ``` #### 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 ```json { "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 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 ```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 request sent to the source-matched local MCP helper; not a generated schema-only example ```json { "path": "descriptor-fixture/doc.gram" } ``` #### 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 ```json { "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 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 Sources: thegram-vault/internal/mcp/tools_common.go#f243590ff0ab46a241c752ae104c538e5064c869525209dfc7219572d6d5523c 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_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 request sent to the source-matched local MCP helper; not a generated schema-only example ```json { "path": "descriptor-fixture/doc.gram", "entity": "d1", "fields": [ "t", "d" ], "links": true } ``` #### 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 ```json { "content": [ { "text": "{\"doc\":{\"hash\":\"d4344a16bec94a0a\",\"path\":\"descriptor-fixture/doc.gram\",\"rev\":1},\"entity\":{\"fields\":{\"d\":[\"Description updated by a real CAS patch.\"],\"t\":[\"Lunar migration decision\"]},\"id\":\"d1\",\"type\":\"decision\"}}", "type": "text" } ], "resultType": "complete", "structuredContent": { "doc": { "hash": "d4344a16bec94a0a", "path": "descriptor-fixture/doc.gram", "rev": 1 }, "entity": { "fields": { "d": [ "Description updated by a real CAS patch." ], "t": [ "Lunar migration decision" ] }, "id": "d1", "type": "decision" } } } ``` #### Source-backed tool errors Code: E_ARGUMENT; message: Unknown argument Sources: thegram-vault/internal/mcp/gateway.go#335359731a3724bb0bf7a02093e3d7e1bbd93ccda3bbdff143b6178eec98a436 Code: STALE_READ; message: The document changed while it was read; read again Sources: thegram-vault/internal/mcp/tools_common.go#f243590ff0ab46a241c752ae104c538e5064c869525209dfc7219572d6d5523c 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_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 request sent to the source-matched local MCP helper; not a generated schema-only example ```json { "ids": [ { "path": "descriptor-fixture/doc.gram", "entity": "d1" }, { "path": "descriptor-fixture/doc.gram", "entity": "e1" } ], "fields": [ "t", "d" ] } ``` #### 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 ```json { "content": [ { "text": "{\"docs\":[{\"hash\":\"d4344a16bec94a0a\",\"path\":\"descriptor-fixture/doc.gram\",\"rev\":1}],\"items\":[{\"fields\":{\"d\":[\"Description updated by a real CAS patch.\"],\"t\":[\"Lunar migration decision\"]},\"id\":\"d1\",\"type\":\"decision\"},{\"fields\":{\"t\":[\"Lunar migration evidence\"]},\"id\":\"e1\",\"links\":[[\"supports\",\"d1\"]],\"type\":\"evidence\"}]}", "type": "text" } ], "resultType": "complete", "structuredContent": { "docs": [ { "hash": "d4344a16bec94a0a", "path": "descriptor-fixture/doc.gram", "rev": 1 } ], "items": [ { "fields": { "d": [ "Description updated by a real CAS patch." ], "t": [ "Lunar migration decision" ] }, "id": "d1", "type": "decision" }, { "fields": { "t": [ "Lunar migration evidence" ] }, "id": "e1", "links": [ [ "supports", "d1" ] ], "type": "evidence" } ] } } ``` #### Source-backed tool errors Code: E_ARGUMENT; message: Unknown argument Sources: thegram-vault/internal/mcp/gateway.go#335359731a3724bb0bf7a02093e3d7e1bbd93ccda3bbdff143b6178eec98a436 Code: E_CURSOR; message: Invalid context cursor Sources: thegram-vault/internal/mcp/tools_entity.go#04d41ed2634d5904fa812be53c92c70a06403d78334890b9791c168b8f89c9f0 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_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 request sent to the source-matched local MCP helper; not a generated schema-only example ```json { "from": { "path": "descriptor-fixture/doc.gram", "entity": "e1" }, "depth": 1 } ``` #### 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 ```json { "content": [ { "text": "{\"docs\":[{\"hash\":\"d4344a16bec94a0a\",\"path\":\"descriptor-fixture/doc.gram\",\"rev\":1}],\"edges\":[[\"e1\",\"supports\",\"d1\"]]}", "type": "text" } ], "resultType": "complete", "structuredContent": { "docs": [ { "hash": "d4344a16bec94a0a", "path": "descriptor-fixture/doc.gram", "rev": 1 } ], "edges": [ [ "e1", "supports", "d1" ] ] } } ``` #### Source-backed tool errors Code: E_ARGUMENT; message: Unknown argument 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_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 request sent to the source-matched local MCP helper; not a generated schema-only example ```json { "path": "descriptor-fixture/doc.gram" } ``` #### 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 ```json { "content": [ { "text": "{\"counts\":{\"decision\":1,\"evidence\":1},\"docs\":[[\"descriptor-fixture/doc.gram\",\"Lunar migration decision\",1,\"d4344a16bec94a0a\",\"2026-10-12T23:10:31.898Z\",null]],\"next\":\"2026-10-12T23:10:31.898Z\",\"open\":[],\"recent\":[[\"descriptor-fixture/doc.gram\",1,\"2026-10-12T23:10:31.898Z\",null,\"thegram-descriptor-fixture\",\"+1 ~2 -0\"],[\"descriptor-fixture/doc.gram\",0,\"2026-10-12T23:10:31.884Z\",null,\"thegram-descriptor-fixture\",\"+2 ~0 -0\"]],\"scope\":\"descriptor-fixture/doc.gram\"}", "type": "text" } ], "resultType": "complete", "structuredContent": { "counts": { "decision": 1, "evidence": 1 }, "docs": [ [ "descriptor-fixture/doc.gram", "Lunar migration decision", 1, "d4344a16bec94a0a", "2026-10-12T23:10:31.898Z", null ] ], "next": "2026-10-12T23:10:31.898Z", "open": [], "recent": [ [ "descriptor-fixture/doc.gram", 1, "2026-10-12T23:10:31.898Z", null, "thegram-descriptor-fixture", "+1 ~2 -0" ], [ "descriptor-fixture/doc.gram", 0, "2026-10-12T23:10:31.884Z", null, "thegram-descriptor-fixture", "+2 ~0 -0" ] ], "scope": "descriptor-fixture/doc.gram" } } ``` #### Source-backed tool errors Code: E_ARGUMENT; message: Unknown argument 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_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 request sent to the source-matched local MCP helper; not a generated schema-only example ```json { "path": "descriptor-fixture/doc.gram", "section": "Descriptor fixture" } ``` #### 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 ```json { "content": [ { "text": "{\"doc\":{\"hash\":\"d4344a16bec94a0a\",\"path\":\"descriptor-fixture/doc.gram\",\"rev\":1},\"level\":1,\"md\":\"# Descriptor fixture\\n\\nLunar migration evidence tracks the migration decision.\\n\\n**Lunar migration evidence** · evidence `e1`\",\"section\":\"Descriptor fixture\"}", "type": "text" } ], "resultType": "complete", "structuredContent": { "doc": { "hash": "d4344a16bec94a0a", "path": "descriptor-fixture/doc.gram", "rev": 1 }, "level": 1, "md": "# Descriptor fixture\n\nLunar migration evidence tracks the migration decision.\n\n**Lunar migration evidence** · evidence `e1`", "section": "Descriptor fixture" } } ``` #### Source-backed tool errors Code: E_ARGUMENT; message: Unknown argument Sources: thegram-vault/internal/mcp/gateway.go#335359731a3724bb0bf7a02093e3d7e1bbd93ccda3bbdff143b6178eec98a436 Code: E_CURSOR; message: Invalid section cursor Sources: thegram-vault/internal/mcp/memory.go#cf97b451501c97d5db3c43836171a65ce221b9105d1b3c75ae58ccefc93e72e1 Code: STALE_CURSOR; message: The cursor belongs to another document, revision or section Sources: thegram-vault/internal/mcp/memory.go#cf97b451501c97d5db3c43836171a65ce221b9105d1b3c75ae58ccefc93e72e1 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_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 request sent to the source-matched local MCP helper; not a generated schema-only example ```json { "path": "descriptor-fixture/doc.gram", "since_revision": 0 } ``` #### 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 ```json { "content": [ { "text": "{\"changes\":[{\"add\":[[\"e1\",\"evidence\",\"Lunar migration evidence\"]],\"at\":\"2026-10-12T23:10:31.898Z\",\"by\":\"thegram-descriptor-fixture\",\"path\":\"descriptor-fixture/doc.gram\",\"rev\":1,\"set\":[[\"doc\",\"Lunar migration decision\",[\"body\"]],[\"d1\",\"Lunar migration decision\",[\"d\"]]]}],\"docs\":[{\"hash\":\"d4344a16bec94a0a\",\"path\":\"descriptor-fixture/doc.gram\",\"rev\":1}],\"next\":\"2026-10-12T23:10:31.898Z\"}", "type": "text" } ], "resultType": "complete", "structuredContent": { "changes": [ { "add": [ [ "e1", "evidence", "Lunar migration evidence" ] ], "at": "2026-10-12T23:10:31.898Z", "by": "thegram-descriptor-fixture", "path": "descriptor-fixture/doc.gram", "rev": 1, "set": [ [ "doc", "Lunar migration decision", [ "body" ] ], [ "d1", "Lunar migration decision", [ "d" ] ] ] } ], "docs": [ { "hash": "d4344a16bec94a0a", "path": "descriptor-fixture/doc.gram", "rev": 1 } ], "next": "2026-10-12T23:10:31.898Z" } } ``` #### Source-backed tool errors Code: E_ARGUMENT; message: Unknown argument Sources: thegram-vault/internal/mcp/gateway.go#335359731a3724bb0bf7a02093e3d7e1bbd93ccda3bbdff143b6178eec98a436 Code: E_CURSOR; message: Invalid changes cursor Sources: thegram-vault/internal/mcp/memory.go#cf97b451501c97d5db3c43836171a65ce221b9105d1b3c75ae58ccefc93e72e1 Code: STALE_CURSOR; message: The documents changed since this cursor; ask again without cursor Sources: thegram-vault/internal/mcp/memory.go#cf97b451501c97d5db3c43836171a65ce221b9105d1b3c75ae58ccefc93e72e1 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_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 request sent to the source-matched local MCP helper; not a generated schema-only example ```json { "path": "descriptor-fixture/doc.gram" } ``` #### 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 ```json { "content": [ { "text": "{\"doc\":{\"hash\":\"d4344a16bec94a0a\",\"path\":\"descriptor-fixture/doc.gram\",\"rev\":1},\"events\":[{\"actor\":\"agent\",\"agent\":\"thegram-descriptor-fixture\",\"recorded_at\":\"2026-10-12T23:10:31.884Z\",\"revision\":0},{\"actor\":\"agent\",\"agent\":\"thegram-descriptor-fixture\",\"recorded_at\":\"2026-10-12T23:10:31.898Z\",\"request_digest\":\"7c6ef8e1baaffce1\",\"request_id\":\"descriptor-evidence-patch\",\"revision\":1}]}", "type": "text" } ], "resultType": "complete", "structuredContent": { "doc": { "hash": "d4344a16bec94a0a", "path": "descriptor-fixture/doc.gram", "rev": 1 }, "events": [ { "actor": "agent", "agent": "thegram-descriptor-fixture", "recorded_at": "2026-10-12T23:10:31.884Z", "revision": 0 }, { "actor": "agent", "agent": "thegram-descriptor-fixture", "recorded_at": "2026-10-12T23:10:31.898Z", "request_digest": "7c6ef8e1baaffce1", "request_id": "descriptor-evidence-patch", "revision": 1 } ] } } ``` #### Source-backed tool errors Code: E_ARGUMENT; message: Unknown argument 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_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 request sent to the source-matched local MCP helper; not a generated schema-only example ```json { "path": "descriptor-fixture/doc.gram", "selector": { "revision": 0 } } ``` #### 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 ```json { "content": [ { "text": "{\"at\":{\"at\":\"2026-10-12T23:10:31.884Z\",\"eff\":null,\"rev\":0},\"doc\":{\"hash\":\"d4344a16bec94a0a\",\"path\":\"descriptor-fixture/doc.gram\",\"rev\":1},\"entities\":[[\"d1\",\"decision\",\"Lunar migration decision\"]],\"title\":\"Lunar migration decision\"}", "type": "text" } ], "resultType": "complete", "structuredContent": { "at": { "at": "2026-10-12T23:10:31.884Z", "eff": null, "rev": 0 }, "doc": { "hash": "d4344a16bec94a0a", "path": "descriptor-fixture/doc.gram", "rev": 1 }, "entities": [ [ "d1", "decision", "Lunar migration decision" ] ], "title": "Lunar migration decision" } } ``` #### Source-backed tool errors Code: E_ARGUMENT; message: Unknown argument Sources: thegram-vault/internal/mcp/gateway.go#335359731a3724bb0bf7a02093e3d7e1bbd93ccda3bbdff143b6178eec98a436 Code: E_CURSOR; message: Invalid state cursor Sources: thegram-vault/internal/mcp/tools_history.go#c2d2b98e94a1cebbc9aadae0e931500c109b61fe44e90ad2f9e1bc6b76e499c8 Code: STALE_READ; message: The document was replaced while it was read Sources: thegram-vault/internal/mcp/tools_history.go#c2d2b98e94a1cebbc9aadae0e931500c109b61fe44e90ad2f9e1bc6b76e499c8 Code: STALE_CURSOR; message: Cursor belongs to another document or revision Sources: thegram-vault/internal/mcp/tools_history.go#c2d2b98e94a1cebbc9aadae0e931500c109b61fe44e90ad2f9e1bc6b76e499c8 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_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 request sent to the source-matched local MCP helper; not a generated schema-only example ```json { "path": "descriptor-fixture/doc.gram", "base_revision": null, "title": "Lunar migration decision", "content": { "text": "# Descriptor fixture\n\nLunar migration evidence tracks the migration decision.", "records": [ { "type": "decision", "id": "d1", "fields": { "t": [ "Lunar migration decision" ], "d": [ "Initial decision description" ] } } ] } } ``` #### 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 ```json { "content": [ { "text": "{\"created\":[\"d1\"],\"doc\":{\"hash\":\"51faf6ac85ea9bb8\",\"path\":\"descriptor-fixture/doc.gram\",\"rev\":0},\"receipt\":{\"revision\":0,\"status\":\"success\"}}", "type": "text" } ], "resultType": "complete", "structuredContent": { "created": [ "d1" ], "doc": { "hash": "51faf6ac85ea9bb8", "path": "descriptor-fixture/doc.gram", "rev": 0 }, "receipt": { "revision": 0, "status": "success" } } } ``` #### Source-backed tool errors Code: E_ARGUMENT; message: Unknown argument Sources: thegram-vault/internal/mcp/gateway.go#335359731a3724bb0bf7a02093e3d7e1bbd93ccda3bbdff143b6178eec98a436 Code: E_CAS_REQUIRED; message: base_revision required Sources: thegram-format/native/api.rs#a7e13ec4b422ae4907c7d7eac481267103f9b4b86248e706a82251cc597a5e02 Code: E_CAS_REQUIRED; message: Create requires explicit null base_revision Sources: thegram-format/native/api.rs#a7e13ec4b422ae4907c7d7eac481267103f9b4b86248e706a82251cc597a5e02 Code: STALE_REVISION; message: Artifact changed during transaction Sources: thegram-format/native/store.rs#3bd54253eeee764c2cdf1d3dc1e9c0f4f1d9f96fbd75c66171d96b19a342addc Code: STALE_REVISION; message: Create target already exists Sources: thegram-format/native/store.rs#3bd54253eeee764c2cdf1d3dc1e9c0f4f1d9f96fbd75c66171d96b19a342addc Code: COMMIT_UNKNOWN; message: Replacement published but durability is uncertain: {e} Sources: thegram-format/native/store.rs#3bd54253eeee764c2cdf1d3dc1e9c0f4f1d9f96fbd75c66171d96b19a342addc Code: COMMIT_UNKNOWN; message: Marker observed but durability not confirmed: {e} Sources: thegram-format/native/store.rs#3bd54253eeee764c2cdf1d3dc1e9c0f4f1d9f96fbd75c66171d96b19a342addc Code: STORAGE_CONFLICT; message: remote file changed since it was read Sources: thegram-vault/internal/mcp/workspace.go#9de8ccbfe796301fd9406f7b78d775da520dfb77127aea2a3caf499391143ad9 Code: STORAGE_CONFLICT; message: remote file changed and local restoration failed Sources: thegram-vault/internal/mcp/workspace.go#9de8ccbfe796301fd9406f7b78d775da520dfb77127aea2a3caf499391143ad9 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 Code: E_PATH; message: Vault mounts support writes only to top-level documents Sources: thegram-vault/internal/mcp/paths.go#754797578ba9858e6db8707f17ca9ceed82914215e83e00e437a05e925bff936 Code: E_READ_ONLY; message: This mounted folder is read-only to agents 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_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 request sent to the source-matched local MCP helper; not a generated schema-only example ```json { "path": "descriptor-fixture/doc.gram", "base_revision": 0, "expected_hash": "51faf6ac85ea9bb8", "request_id": "descriptor-evidence-patch", "operations": [ { "op": "add", "record": { "type": "evidence", "id": "e1", "fields": { "t": [ "Lunar migration evidence" ] }, "links": [ { "predicate": "supports", "target": "d1" } ] }, "place": "end" }, { "op": "set", "entity": "d1", "key": "d", "value": "Description updated by a real CAS patch." } ] } ``` #### 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 ```json { "content": [ { "text": "{\"created\":[\"e1\"],\"doc\":{\"hash\":\"d4344a16bec94a0a\",\"path\":\"descriptor-fixture/doc.gram\",\"rev\":1},\"receipt\":{\"request_id\":\"descriptor-evidence-patch\",\"revision\":1,\"status\":\"success\"}}", "type": "text" } ], "resultType": "complete", "structuredContent": { "created": [ "e1" ], "doc": { "hash": "d4344a16bec94a0a", "path": "descriptor-fixture/doc.gram", "rev": 1 }, "receipt": { "request_id": "descriptor-evidence-patch", "revision": 1, "status": "success" } } } ``` #### Source-backed tool errors Code: E_ARGUMENT; message: Unknown argument Sources: thegram-vault/internal/mcp/gateway.go#335359731a3724bb0bf7a02093e3d7e1bbd93ccda3bbdff143b6178eec98a436 Code: E_REQUEST_REUSE; message: request_id belongs to another intent Sources: thegram-format/native/api.rs#a7e13ec4b422ae4907c7d7eac481267103f9b4b86248e706a82251cc597a5e02 Code: E_REQUEST_ID; message: Nonempty request_id required Sources: thegram-format/native/api.rs#a7e13ec4b422ae4907c7d7eac481267103f9b4b86248e706a82251cc597a5e02 Code: E_CAS_REQUIRED; message: base_revision required Sources: thegram-format/native/api.rs#a7e13ec4b422ae4907c7d7eac481267103f9b4b86248e706a82251cc597a5e02 Code: E_CAS_REQUIRED; message: Create requires explicit null base_revision Sources: thegram-format/native/api.rs#a7e13ec4b422ae4907c7d7eac481267103f9b4b86248e706a82251cc597a5e02 Code: STALE_REVISION; message: Accepted revision or hash changed Sources: thegram-format/native/temporal.rs#a143cc67c4518c4599f96af9565ae765c1dcdc770d694b13a8fdc08a03c69c0e Code: STALE_REVISION; message: Artifact changed during transaction Sources: thegram-format/native/store.rs#3bd54253eeee764c2cdf1d3dc1e9c0f4f1d9f96fbd75c66171d96b19a342addc Code: COMMIT_UNKNOWN; message: Replacement published but durability is uncertain: {e} Sources: thegram-format/native/store.rs#3bd54253eeee764c2cdf1d3dc1e9c0f4f1d9f96fbd75c66171d96b19a342addc Code: COMMIT_UNKNOWN; message: Marker observed but durability not confirmed: {e} Sources: thegram-format/native/store.rs#3bd54253eeee764c2cdf1d3dc1e9c0f4f1d9f96fbd75c66171d96b19a342addc Code: STORAGE_CONFLICT; message: remote file changed since it was read Sources: thegram-vault/internal/mcp/workspace.go#9de8ccbfe796301fd9406f7b78d775da520dfb77127aea2a3caf499391143ad9 Code: STORAGE_CONFLICT; message: remote file changed and local restoration failed Sources: thegram-vault/internal/mcp/workspace.go#9de8ccbfe796301fd9406f7b78d775da520dfb77127aea2a3caf499391143ad9 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 Code: E_PATH; message: Vault mounts support writes only to top-level documents Sources: thegram-vault/internal/mcp/paths.go#754797578ba9858e6db8707f17ca9ceed82914215e83e00e437a05e925bff936 Code: E_READ_ONLY; message: This mounted folder is read-only to agents 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. ::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 @gram-history 6 @rev 0 2026-10-12T13:11:21.917Z - b039c40cfa10d43a906d58b3b286e77862008eb35fc41dd674f4432797aee2dc @rev 1 2026-10-12T13:11:21.917Z portal-reference-contracts agent=developer-doc-generator req=portal-reference-mcp-tools-0ff3467636a98a1ad01d2d4c dig=19fd277f90b4aa40 kind=SourceImported 53bff8be48ac873a9cc3b141d63346bfd8c3b8cf5c70a9f981e8003002a36ad8 @@ 108 1 0 @@ 110 0 2 t .gram language specification @@ 111 1 0 @@ 113 0 1 t Current History/6 specification @rev 2 2026-10-12T13:16:27.369Z portal-reference-contracts agent=developer-doc-generator req=portal-reference-mcp-tools-582729b115fb21c595fa0324 dig=38199155c6a4cdc0 kind=SourceImported 05068247b4baa1e473cc55c53571a2c947280030e564a088e2c8857460f7db5a @@ 13 2 0 @@ 19 2 0 @@ 25 2 0 @@ 31 2 0 @@ 37 2 0 @@ 43 2 0 @@ 49 2 0 @@ 55 2 0 @@ 61 2 0 @@ 67 2 0 @@ 73 2 0 @@ 79 2 0 @@ 85 2 0 @@ 91 2 0 @@ 96 4 0 @rev 3 2026-10-12T13:42:23.441Z portal-reference-finalize agent=developer-doc-generator req=portal-reference-mcp-tools-1a652c201294659a8676e7b7 dig=e44bdb22605008cb kind=SourceImported 4acf52061e7d883d6d589ff655a8a89df75a6a21415eabaef4e4acf4f3ddec12 @@ 4 1280 138 ::body # MCP tools Local and cloud MCP publish the same 15 `gram_*` names and matching descriptions/input fields. Both reject undeclared top-level arguments. The public descriptors publish input schemas, not output schemas; there is intentionally no invented JSON output schema below. Result shapes are concise behavioral contracts, and optional values depend on data/runtime. ## Inputs ### `gram_profile` 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. All listed inputs are optional. `task`: string (create|edit|rich|read|memory). ### `gram_capabilities` Tools, whether semantic search actually works now, and the folder's index state. All listed inputs are optional. . ### `gram_projects` 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//proj/notes.gram. The @mounts namespace is reserved so mount paths never shadow local projects. Mount access never exceeds existing agent approval. All listed inputs are optional. . ### `gram_brief` 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. All listed inputs are optional. `folder`: string; `path`: string; `limit`: integer (min 1, max 50). ### `gram_read` 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. Required: `path`. `path`: string; `section`: string; `revision`: integer (min 0); `recorded_at`: string; `effective_at`: string; `cursor`: string. ### `gram_changes` 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. All listed inputs are optional. `folder`: string; `path`: string; `since`: string; `since_revision`: integer (min 0); `limit`: integer (min 1, max 100); `cursor`: string. ### `gram_recall` 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. Required: `query`. `query`: string; `mode`: string (exact|keyword|semantic|hybrid|auto); `folder`: string; `scope`: string; `type`: string; `documents`: array of string; `top_k`: integer (min 1); `from`: string; `to`: string; `date`: string; `cursor`: string. ### `gram_list` 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. All listed inputs are optional. `path`: string; `select`: object {type, status, tag, from, to, date}; `limit`: integer (min 1, max 100); `cursor`: string; `revision`: integer (min 0); `recorded_at`: string; `effective_at`: string. ### `gram_get` 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. Required: `path`, `entity`. `path`: string; `entity`: string; `fields`: array of string; `blocks`: array of string; `links`: boolean; `outline`: boolean; `revision`: integer (min 0); `recorded_at`: string; `effective_at`: string. ### `gram_context` 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. Required: `ids`. `ids`: array of object {path, entity, revision, recorded_at, effective_at}; required path, entity (min 1); `fields`: array of string; `cursor`: string. ### `gram_relations` Explicit links and REL edges from one entity; defaults to its project documents. Required: `from`. `paths`: array of string; `from`: object {path, entity}; required path, entity; `direction`: string (out|in|both); `predicates`: array of string; `depth`: integer (min 1, max 3); `limit`: integer (min 1); `cursor`: string. ### `gram_range` History events of one document; with query, only changes relevant to it. Required: `path`. `path`: string; `start`: integer (min 0); `limit`: integer (min 1, max 100); `query`: string; `top_k`: integer (min 1); `expected_hash`: string. ### `gram_state` One document as it was at a revision, at a write time (recorded_at), or at the time its facts happened (effective_at). Required: `path`, `selector`. `path`: string; `entity`: string; `selector`: object {revision, recorded_at, effective_at}; `cursor`: string. ### `gram_create` 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. Required: `path`, `base_revision`, `title`, `content`. `path`: string; `base_revision`: null; `title`: string; `content`: string or object {text, rich, records, fields, blocks}; `effective_at`: string. ### `gram_patch` Local: 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: 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. Required: `path`, `base_revision`, `expected_hash`, `request_id`, `operations`. `path`: string; `base_revision`: integer (min 0); `expected_hash`: string (length 1–undefined); `request_id`: string (length 1–128); `effective_at`: string; `operations`: array of object {} (min 1). A selector consists of at most one of `revision` (non-negative integer), `recorded_at` (string) or `effective_at` (ISO timestamp with zone). The top-level selector appears on read/get/list; state takes a nested selector. An object schema's required keys are shown where specified. The public patch descriptor types `operations` as object array, but does not define operation members; consult the Core patch contract rather than assume one fixed operation shape. ## Source-grounded result contracts and examples - `gram_projects`: mounts are `{key,id,kind,name,count,access}`; use exact `key` as prefix, for example `@mounts//proj/notes.gram`. - `gram_list({path:"project"})`: documents are `[path,title,rev]`; on a document path, entity rows are `[id,type]`. - `gram_get({path:"project/notes.gram",entity:"doc",fields:["t"],links:true})`: returns a document citation and an entity with requested fields/links. - `gram_context({ids:[{path:"project/notes.gram",entity:"decision-id"}]})`: one bounded context item per requested entity. - `gram_read({path:"project/notes.gram"})`: heading outline; add `section` to get `{doc,section,level,md,more?}`. - `gram_state({path:"project/notes.gram",selector:{revision:0}})`: selected historical state. - `gram_create({path:"project/notes.gram",base_revision:null,title:"Notes",content:"# Notes\n\nReadable body."})`: one new @gram 2 + History/6 document. Create does not accept request_id. - `gram_patch({path:"project/notes.gram",base_revision:0,expected_hash:"",request_id:"notes-edit-1",operations:[{op:"set",entity:"doc",key:"t",value:"Notes"}]})`: one CAS-protected change. Returns may include pagination fields, citations, warnings, created IDs, diagnostics and index/sync state. Treat the actual returned payload as authoritative; examples omit optional fields. ## Tool result shapes - `gram_profile`: Returns the requested contract/profile object; no output JSON Schema is published. - `gram_projects`: Returns projects and mounts. Mount entries expose key, id, kind, name, count, and access; use key, not display name, as path prefix. - `gram_capabilities`: Returns tool names, index counters and current semantic-search status; availability is runtime-dependent. - `gram_brief`: Returns docs, type counts, open work records, recent revisions and a continuation hint. Document hashes are the CAS token supplied to gram_patch. - `gram_read`: Without section returns heading outline; with section returns {doc,section,level,md,more?}; a historical read also returns at. Section cursors are bound to document, revision and section. - `gram_changes`: Returns revisions with add [id,type,title], set [id,title,changed keys], del [id,title]; document owner is doc. next and more support continuation. - `gram_recall`: Returns matching document/record hits with source path and entity identity, selected fields and relevance metadata; results depend on the runtime index/provider. - `gram_list`: Returns document tuples [path,title,rev], selected record tuples [path#id,type,title,status,date?], or entity tuples [id,type] for a document path. - `gram_get`: Returns {doc,entity}; entity includes id/type and requested fields, links, blocks. outline:true adds rendered top-level body-block rows. - `gram_context`: Returns one context item per requested {path,entity}, with selected/default fields, links and bounded rich text; decisions may add implemented and implementation date. - `gram_relations`: Returns directional explicit links and REL edges from the source entity, with traversal and paging metadata. - `gram_range`: Returns current document CAS identity plus a bounded slice of history events, or keyword-relevant events when query is supplied. - `gram_state`: Returns selected historical document/entity state and selector provenance; no output schema is published. - `gram_create`: Returns doc:{path,rev,hash}, receipt status/revision, sync state, and optional created IDs, warnings, indexing warning, or write diagnostics. Local-folder sync differs from cloud mounts. - `gram_patch`: Returns doc:{path,rev,hash}, receipt:{request_id,status,revision,replayed?}, sync state, and optional created IDs/warnings/diagnostics. Cloud successful commits report sync.state=synced. Cloud adds read-only/destructive/open-world annotations in its descriptors; local descriptors do not. Cloud success marks mounted writes synced. Neither service publishes per-tool output JSON Schema. ::end SRC format-language t .gram language specification ref https://github.com/clab-one/thegram-format/blob/main/spec/language.md @rev 4 2026-10-12T13:50:17.306Z portal-reference-finalize agent=developer-doc-generator req=portal-reference-mcp-tools-86a8ee6c2c693db69a332193 dig=bd27c3e87331e571 kind=SourceImported 7d6fc86956c45d51969006e4c6942a900fdcd7bd2cb768c61e12d6fc0ca97f9a @@ 52 1 1 Operation: tools/call; source: [object Object] @@ 122 1 1 Operation: tools/call; source: [object Object] @@ 169 1 1 Operation: tools/call; source: [object Object] @@ 283 1 1 Operation: tools/call; source: [object Object] @@ 373 1 1 Operation: tools/call; source: [object Object] @@ 378 1 1 "hash": "0d8a4b16c7d77a03", @@ 463 1 1 Operation: tools/call; source: [object Object] @@ 468 1 1 "hash": "0d8a4b16c7d77a03", @@ 563 1 1 Operation: tools/call; source: [object Object] @@ 569 1 1 "hash": "0d8a4b16c7d77a03", @@ 674 1 1 Operation: tools/call; source: [object Object] @@ 726 1 1 Operation: tools/call; source: [object Object] @@ 738 2 2 "0d8a4b16c7d77a03", "2026-10-12T13:41:21.161Z", @@ 743 1 1 "next": "2026-10-12T13:41:21.161Z", @@ 749 1 1 "2026-10-12T13:41:21.161Z", @@ 814 1 1 Operation: tools/call; source: [object Object] @@ 819 1 1 "hash": "0d8a4b16c7d77a03", @@ 884 1 1 Operation: tools/call; source: [object Object] @@ 890 1 1 "next": "2026-10-12T13:41:21.161Z" @@ 952 1 1 Operation: tools/call; source: [object Object] @@ 957 1 1 "hash": "0d8a4b16c7d77a03", @@ 965 1 1 "recorded_at": "2026-10-12T13:41:21.161Z", @@ 1036 1 1 Operation: tools/call; source: [object Object] @@ 1041 1 1 "at": "2026-10-12T13:41:21.161Z", @@ 1046 1 1 "hash": "0d8a4b16c7d77a03", @@ 1161 1 1 Operation: tools/call; source: [object Object] @@ 1169 1 1 "hash": "0d8a4b16c7d77a03", @@ 1243 1 1 "expected_hash": "0d8a4b16c7d77a03", @@ 1258 1 1 Operation: tools/call; source: [object Object] @@ 1263 1 1 "hash": "940f584dce3e48c5", @rev 5 2026-10-12T23:17:38.039Z portal-reference-finalize agent=developer-doc-generator req=portal-reference-mcp-tools-r4-ffdb124fdbb30bde15e544bf dig=687497c12039c4ec kind=SourceImported 42cdc270655ca8d134ee83118fffa73372c5a3e8bb50cf45d38c67c0cffe7677 @@ 10 2077 1264 ## 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: thegram-desktop/App/Sources/AgentGateway.swift, thegram-format/verification/native-core.mjs; fixture paths: temporary task-owned fixture vault -> descriptor-fixture/ ```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//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//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: thegram-desktop/App/Sources/AgentGateway.swift, thegram-format/verification/native-core.mjs; fixture paths: temporary task-owned fixture vault -> descriptor-fixture/ ```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: thegram-desktop/App/Sources/AgentGateway.swift, thegram-format/verification/native-core.mjs; fixture paths: temporary task-owned fixture vault -> descriptor-fixture/ ```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: thegram-desktop/App/Sources/AgentGateway.swift, thegram-format/verification/native-core.mjs; fixture paths: temporary task-owned fixture vault -> descriptor-fixture/ ```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: thegram-desktop/App/Sources/AgentGateway.swift, thegram-format/verification/native-core.mjs; fixture paths: temporary task-owned fixture vault -> descriptor-fixture/ ```json { "doc": { "hash": "5d206ba664b99795", "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: thegram-desktop/App/Sources/AgentGateway.swift, thegram-format/verification/native-core.mjs; fixture paths: temporary task-owned fixture vault -> descriptor-fixture/ ```json { "doc": { "hash": "5d206ba664b99795", "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: thegram-desktop/App/Sources/AgentGateway.swift, thegram-format/verification/native-core.mjs; fixture paths: temporary task-owned fixture vault -> descriptor-fixture/ ```json { "docs": [ { "hash": "5d206ba664b99795", "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: thegram-desktop/App/Sources/AgentGateway.swift, thegram-format/verification/native-core.mjs; fixture paths: temporary task-owned fixture vault -> descriptor-fixture/ ```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: thegram-desktop/App/Sources/AgentGateway.swift, thegram-format/verification/native-core.mjs; fixture paths: temporary task-owned fixture vault -> descriptor-fixture/ ```json { "counts": { "decision": 1 }, "docs": [ [ "descriptor-fixture/doc.gram", "Descriptor fixture", 0, "5d206ba664b99795", "2026-10-12T13:42:50.404Z", null ] ], "next": "2026-10-12T13:42:50.404Z", "open": [], "recent": [ [ "descriptor-fixture/doc.gram", 0, "2026-10-12T13:42:50.404Z", 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: thegram-desktop/App/Sources/AgentGateway.swift, thegram-format/verification/native-core.mjs; fixture paths: temporary task-owned fixture vault -> descriptor-fixture/ ```json { "doc": { "hash": "5d206ba664b99795", "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: thegram-desktop/App/Sources/AgentGateway.swift, thegram-format/verification/native-core.mjs; fixture paths: temporary task-owned fixture vault -> descriptor-fixture/ ```json { "changes": [], "docs": [], "next": "2026-10-12T13:42:50.404Z" } ``` 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: thegram-desktop/App/Sources/AgentGateway.swift, thegram-format/verification/native-core.mjs; fixture paths: temporary task-owned fixture vault -> descriptor-fixture/ ```json { "doc": { "hash": "5d206ba664b99795", "path": "descriptor-fixture/doc.gram", "rev": 0 }, "events": [ { "actor": "agent", "agent": "thegram-descriptor-fixture", "recorded_at": "2026-10-12T13:42:50.404Z", "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: thegram-desktop/App/Sources/AgentGateway.swift, thegram-format/verification/native-core.mjs; fixture paths: temporary task-owned fixture vault -> descriptor-fixture/ ```json { "at": { "at": "2026-10-12T13:42:50.404Z", "eff": null, "rev": 0 }, "doc": { "hash": "5d206ba664b99795", "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: thegram-desktop/App/Sources/AgentGateway.swift, thegram-format/verification/native-core.mjs; fixture paths: temporary task-owned fixture vault -> descriptor-fixture/ ```json { "created": [ "d1" ], "doc": { "hash": "5d206ba664b99795", "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": "5d206ba664b99795", "request_id": "descriptor-evidence-patch", "operations": [ { "op": "set", "entity": "d1", "key": "x", "value": "Core MCP fixture" } ] } ``` #### Actual operation output evidence Operation: tools/call; source: thegram-desktop/App/Sources/AgentGateway.swift, thegram-format/verification/native-core.mjs; fixture paths: temporary task-owned fixture vault -> descriptor-fixture/ ```json { "doc": { "hash": "8bb0f0480b3ee685", "path": "descriptor-fixture/doc.gram", "rev": 1 }, "receipt": { "request_id": "descriptor-evidence-patch", "revision": 1, "status": "success" } } ```