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`

All listed inputs are optional. `task`: string (create|edit|rich|read|memory).

### `gram_capabilities`

All listed inputs are optional. .

### `gram_projects`

All listed inputs are optional. .

### `gram_brief`

All listed inputs are optional. `folder`: string; `path`: string; `limit`: integer (min 1, max 50).

### `gram_read`

Required: `path`. `path`: string; `section`: string; `revision`: integer (min 0); `recorded_at`: string; `effective_at`: string; `cursor`: string.

### `gram_changes`

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`

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`

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`

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`

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`

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`

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`

Required: `path`, `selector`. `path`: string; `entity`: string; `selector`: object {revision, recorded_at, effective_at}; `cursor`: string.

### `gram_create`

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`

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
ref https://github.com/clab-one/thegram-format/blob/main/spec/language.md
t .gram language specification

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