Actual Zen MCP tools

Discover the installed tool inventory first; a host can prefix these names. These are the current tools, not hypothetical APIs. Do not load the whole workspace into the model to answer a narrow question.

Tool	Input	Result and limits
`zen_state`	`{workspaceId?}`	Workspaces, metadata, capabilities and runs. Record bodies omitted.
`zen_record_get`	`{id, offset?, limit?}`	UUID or returned human ref. Default body limit 12000 characters, maximum 20000. Follow `nextOffset` until the relevant body is complete.
`zen_record_history`	`{id}`	Historical revisions; may be large. Request only when history is needed.
`zen_research_search`	`{workspaceId, query, type?}`	At most 20 substring matches, bodies truncated to 1500 characters. Search is not semantic and includes proposed entries: inspect their status/scope.
`zen_record_write`	`{operation,payload,idempotencyKey}`	The five operations below. Agent credentials do not carry owner authority.
`zen_run_events`	`{runId,after?}`	Real event sequence after a cursor; do not fabricate absent commands or checks.
`zen_milestone_inspect`	`{workspaceId,ref?}`	Records a milestone from Git evidence. This mutates records; it does not commit/push and is not a read-only dry run.

Writes

record.create payload: {workspaceId,type,title,body?,status?,tags?,links?,visibility?,data?,parentId?}. Omit id/ref/revision/timestamps: the writer allocates them. Use DOC plus data.kind: "spec", "adr", "glossary" or "handoff"; there is no SPEC/ADR record type. SRT requires parentId of its ART collection in the same workspace.

record.update payload: {id,expectedRevision,patch}. Allowed patch fields: title, body, status, tags, links, visibility, data. Supplying data replaces that object; merge the current fields explicitly. Supplying links/tags also replaces those arrays. Do not erase unrelated relationships.

task.transition payload: {id,expectedRevision,status}. Status is backlog/review for ordinary agent preparation; working comes from owner dispatch and Done is owner-controlled. Changing status alone does not execute code.

artifact.select payload: {id,variantId,expectedRevision}. id is the ART collection, variantId is its SRT child. The writer validates the relationship and records selectedVariantId, selectedVariantRevision and selectedRef. Resolve a copied sub-reference through its collection and the selected historical revision, not blindly through the latest file. For runnable files pin an explicit source manifest/hash/snapshot before selection; MCP does not provide a snapshot tool. Use authorized host file IO outside managed record files, then record.update with a merged data object. Detect source drift before implementation.

feedback.apply payload: {id,expectedRevision,lesson?} for FDK/MEM. Only bounded, recognized low-risk scoped preferences can be applied by the agent. Sensitive, uncertain or personal changes require the owner's approval path. An API rejection is not permission to edit the file directly.

Example: creating research, with actual workspace UUID supplied by discovery:

{"operation":"record.create","idempotencyKey":"research-upload-retry-01","payload":{"workspaceId":"<discovered-workspace-uuid>","type":"RDT","title":"Upload retry semantics","body":"## Finding\nThe observed retry reuses its command identity.\n\n## Evidence\nLocal trace and source locations are linked below.","tags":["uploads","retry"],"visibility":"private","data":{"confidence":"medium"}}}

Angle-bracket values in examples are input slots, not valid UUIDs to submit. After a successful create, use the returned id/ref/revision. Persist one operation key for the exact request and reuse it only for that retry. New intent gets a new key. On conflict fetch current revision, compare content, obtain/perform the appropriate resolution and submit a new operation. A failed/ambiguous side effect may require review rather than automatic retry.

Capability limits

There is no MCP workspace-create/run/schedule/Git/append-event tool in this build. Use the installed companion CLI or owner interface for initialization/dispatch. Submit external execution evidence in a linked LOG or DOC review report; do not invent an append-events call. local records can be read by a local model and are not cloud-synced; never-copy is unavailable to the agent. No tool makes private content public automatically.