MCP tools

@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.
::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/<mount-id>/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/<id>/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:"<observed 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
SRC format-history6
t Current History/6 specification
ref https://github.com/clab-one/thegram-format/blob/main/spec/source-history-render.md