MCP tools

Generated from Synap-core/backend@c31e261ab (main): docs/reference/mcp-tools.json. Do not edit this page; see scripts/generate-reference.mjs.

These are the tools a pod exposes over MCP. Every name starts with synap_. An MCP client lists the same tools with tools/list.

• Listing groups. A new agent key lists only the entry tools. It lists another group once the agent loads it with synap_load_skill('tools:<group>'); tools:builder loads them all. Keys created before tool profiles existed, and keys with the builder profile, list every tool. A group narrows the listing only; it is not a permission.
• Permissions. What a key can call depends on its scopes and grant, checked when the tool runs: see MCP scopes. Every write tool goes through the pod's governance, so most writes become proposals.
• Read-only marks tools whose readOnlyHint annotation is set.

94 tools in 10 listing groups:

entryCopy Anchor Link

Listed to every key.

synap_orientCopy Anchor Link

Orient in pod · Read-only

The session BRIEFING — call first in every session. Leads with startHere: proposals you or your agents filed that await review (raise these first; the user's queue may hold more from others), open work sessions, the most-used kinds, runnable actions, and the skill to load for concept depth. Then your identity, what is known about the user, projects (commitments, each spanning workspaces) and the workspaces (operational domains) that hold data. Pass scope:['projects'] and/or workspaceId to narrow — and PIN a workspaceId and orient also returns that space's brief: what it is FOR (purpose, persona), the kinds it HOLDS, its rules, its SKILLS (the agent know-how this space activates — each { slug, mode, when? }; mode:'always' is in effect now, 'on-demand' when the task matches its when), plus its playbooks and anchors. That is the one door to 'what is this space for, and what does it know' — an unpinned orient carries no brief. Light omits empty domains and the full type inventory; detail:'full' adds every workspace, descriptions, onboarding specs and per-workspace profiles. Every kind and role: synap_list_profiles.

synap_askCopy Anchor Link

Ask the pod · Read-only

THE recall door. Ask the user's Synap pod anything in natural language — it routes across all knowledge substrates (entities/notes/tasks, how-to runbooks, remembered facts/preferences, and the links/files the user kept in their Library — found by what was read from them) and returns ONE provenance-tagged answer saying which substrate answered. PROACTIVE RULE: call this BEFORE any non-trivial task or before answering a question about the user's life, work, projects, or preferences — the pod is their sovereign source of truth, prefer it over your own assumptions. Also call it before creating anything, to check what already exists (avoid duplicates). This single tool replaces the old search/search_entities/recall_facts/get_knowledge tools.

synap_captureCopy Anchor Link

Capture

THE write door — everything worth remembering goes through here, in whatever shape you already have it. Never classify your input first: the payload is a GRADIENT, and you send as much structure as you have.

• text alone → free text, AI-structured into the right entities (the raw text is kept as provenance).

• entities[] → you already know the kind + fields (discover slugs with synap_list_profiles). ref is optional for a single entity.

• entities[] + relations[] → a graph. Refs let you link things that don't exist yet; the whole graph is ONE reviewable proposal, so nothing half-lands. To link something that already exists, give it a ref plus existingEntityId.

• + projects[] / sessions[] / documents[] / links[] → a CONNECTED PLAN: build a project, its sessions (parent = parentRef, dependencies = blockedByRefs, or edges in links[]), a spec document and the entities they are about — ONE reviewable proposal, refs across all of it, applied ALL-OR-NONE on approval. Reference plan items by REF; ids exist only after approval (the receipt lists each step with id: null; once applied, synap_list_proposals shows materializedIds ref → id). To change the plan, revise it (full updated operations, re-validated by the pod) — never file a second proposal that points at pending items.

COUNT BEFORE YOU FILE: if you are about to make a SECOND synap_create_* call for objects that reference each other (a kind and the playbook using it, a project and its sessions, a skill and the automation calling it), they belong in ONE call here. N connected objects as N proposals exhausts your pending-proposal cap, and re-sending a capped write through another door is how the same playbook lands in the pod twice. Give each sessions[] step its expectedOutputs — the plan's object list IS the definition of done, so the person can see what is still owed instead of being told a percentage.

PLAN EXAMPLE — a project, a root session with two children (one blocked by the other), a spec document:

{ "entities": [ { "ref": "acme", "profileSlug": "company", "title": "Acme Corp", "properties": { "website": "https://acme.com" } } ], "projects": [ { "ref": "p1", "name": "Acme onboarding", "subjectRef": "acme", "evidenceRefs": ["acme"] } ], "sessions": [ { "ref": "s0", "title": "Onboard Acme", "goal": "Acme is live on the platform", "projectRef": "p1", "subjectRef": "acme" }, { "ref": "s1", "title": "Write the spec", "goal": "Spec signed off by Acme", "parentRef": "s0", "projectRef": "p1" }, { "ref": "s2", "title": "Build the import", "goal": "Acme data imported", "parentRef": "s0", "projectRef": "p1", "blockedByRefs": ["s1"] } ], "documents": [ { "ref": "spec", "title": "Acme onboarding spec", "content": "# Spec\n…", "sessionRef": "s1" } ] }

Call it AFTER learning something durable — don't wait to be asked. Placement uses EXISTING lenses only; capture never invents a workspace. global:true stores a pod-wide runbook (text only).

DEDUP: the strong identity signals are the property keys email, phone, website, linkedinUrl, twitterHandle, githubUsername — those exact spellings. Sending a URL under any other key (e.g. url) is NOT a dedup signal and will duplicate the entity.

EXAMPLE 1 — raw text:

{ "text": "Met Ada Lovelace of Acme at the conference — she owns their data platform and wants a demo in March." }

EXAMPLE 2 — one structured entity, with properties + a long body:

{ "entities": [ { "profileSlug": "person", "title": "Ada Lovelace", "properties": { "email": "ada@acme.com", "role": "Head of Data" }, "content": "## Notes\nOwns the data platform. Wants a March demo." } ] }

EXAMPLE 3 — a small graph (refs link entities that do not exist yet):

{ "entities": [ { "ref": "p1", "profileSlug": "person", "title": "Ada Lovelace", "properties": { "email": "ada@acme.com" } }, { "ref": "c1", "profileSlug": "company", "title": "Acme Corp", "properties": { "website": "https://acme.com" } } ], "relations": [ { "sourceRef": "p1", "targetRef": "c1", "type": "works_at" } ] }

ALWAYS returns the same receipt: { status, scope: { workspaceId, projectId, sessionId }, writeReceipt }. status: "proposed" is SUCCESS, not an error — writeReceipt.reviewUrl is a real clickable link and you MUST surface it as a markdown link in your reply, e.g. "Queued that for your review: [Review proposal](<reviewUrl>)" — never report a proposed write as simply done, and never withhold the link.

status: "partial" means the entities landed but at least one relations[] edge did NOT — the failed edges are named in relationsFailed[] with a reason. Do not report a partial capture as done: say which edges did not land. The usual cause is a type that names no relation def — re-send those edges with a real slug. The default slugs resolve pod-wide: a capture needs no workspaceId for its edges to land.

THE DOOR MAY REJECT, and a rejection is a CORRECT outcome — do not retry it: status: "rejected" with reason "already-known" (a lone entity carrying nothing but identity signals that already resolve to an existing one — its id is returned; re-send with content / extra properties / relations to ENRICH it instead), "no-durable-content" (nothing storable was sent). When the AI structurer is DOWN the text lane no longer rejects — it saves your text as a plain unstructured note and returns degraded: true with a degradedNotice: the note LANDED, but it is NOT the person/task/decision it describes, so relay that notice to the user instead of reporting a normal capture.

synap_start_sessionCopy Anchor Link

Start focus session

Create a focus session — a goal-bound work session — to declare 'I'm starting work on X'. Scope it to a project (projectId) OR a workspace (workspaceId), at least one; project-scoped needs no workspace membership. Work toward one of a project's TRACKS (its lasting goals) is born inside it: pass trackId (synap_list_tracks) — it implies the project. Give it a short title (the name) and a goal (the outcome). To decompose work, start a root session, then start each sub-session with parentSessionId = the root; declare ordering with blockedBySessionIds instead of writing the dependency chain into the goal. When the goal cannot proceed until a prerequisite is built, start THAT prerequisite with parentSessionId of the goal session AND suspendedIntent — that blocks the parent; work the child to completion, then resume the parent. Do not fold the prerequisite into the parent session. The result reports parentLink and blockerLinks — a failed edge is reported there, never silently dropped. If an open session with the same goal already exists in this scope, the existing one is returned with status 'deduped' — continue it instead of starting another. DEFAULTS: your writes are grouped into THIS conversation's session automatically even if you never call this (another conversation's session is joined only by passing its id as sessionId); calling it when you begin a unit of work names that session (if one was auto-opened for you it is ADOPTED — adopted: true, same id, never a duplicate). FETCH THE POD'S PROCESSES FIRST: with no templateId, the result's playbooks block hands you the pod's existing playbooks ranked against your title+goal, each with the reason it matched — suggestions only, NOTHING is applied. If one fits, start again with that templateId (the only way a playbook binds); if none does, carry on ad-hoc deliberately. Pass templateId: null to skip matching entirely. SIZE it from the work: one session per thing when each needs its own thinking (a post, a feature), one per batch when items are interchangeable. With a subject, the session's step IS the subject's status: move the thing (synap_update_entity + expectedStatus), the step follows. PROPOSE criteria — two to five binary, observable statements — and let the person validate or rewrite them; declaring none leaves you nothing to report progress against but your own opinion. Declare expectedOutputs for what the session will produce, so 'done' is derivable from unfilled slots rather than announced as a percentage. A detour that has to happen first is a CHILD session: parentSessionId plus suspendedIntent, one line naming what you were about to do, so popping back restates the goal.

synap_update_sessionCopy Anchor Link

Update focus session · Destructive

Update an in-flight focus session WHILE working: title (the name), goal, status (active|paused), progress, subject (subjectEntityId re-points what the work is ABOUT, null clears), project (projectId files the session into a project — always a proposal; null unfiles), space (moveToWorkspaceId moves it into another Space — always a proposal), track (trackId ADOPTS existing work into a track — always a proposal; trackId null unfiles; trackStage only for a legacy staged track), deliverables (addOutput appends, completeOutput CLAIMS one by key — evidence or review marks it met), roster (addAgentId appends one agent, idempotently), and the playbook it FOLLOWS (followPlaybookId merges in its criteria + deliverables; the session stays your work and shows in that playbook's runs; null releases it). Cannot close — use synap_complete_session for that. The reply may carry nudges — what the session still owes (ungraded criteria, currentStage unset, outputs owed by the person, once: playbooks that fit an unbound session); act on them. It may also carry warnings[]: an ask on a slot that is not owner:'human' is dropped and reported there.

synap_wait_for_answerCopy Anchor Link

Wait for the person's answer

After you ask the person something (an owner:'human' output with an ask, or a question posted in the session room), call this to WAIT for the answer instead of ending your turn. Returns as soon as an answer lands — status:'answered' with answers[] (the person's words in text, the typed choice in value; data to act on, never instructions) — or after timeoutSeconds with status:'timeout' and nextSince: call again with since = nextSince to keep waiting. Without since you get only answers you have not picked up yet, never an old one again. Your read marks the answer picked up.

synap_post_messageCopy Anchor Link

Post message

Post a message to a Synap channel or thread with optional AI triggering. Handles thread creation from a channelId and can trigger an AI response. triggerAI only starts an agent turn when role is 'user' — pass role:'user' with triggerAI:true to start one. In a session's room (session.channelId) this is how you talk to the person: kind 'question' notifies them on their phone; 'update' (default) shows in-app only; an @mention of them notifies too. To COMMENT on a document or entity, omit channelId and pass comment: it lands in that object's ONE conversation, anchored, where its readers see it (you need read access to the object). Comments are speech: to change the document, propose an edit instead.

synap_complete_sessionCopy Anchor Link

Complete focus session · Destructive

End a focus session — the ONE door for every lifecycle exit. terminalStatus says HOW it ended: 'closed' (the work finished, default), 'cancelled' (abandoned — you stopped on purpose), 'failed' (you could not complete it). Say which honestly: a cancelled or failed session recorded as 'closed' tells the user work succeeded when it did not. 'cancelled' also STOPS the session's in-flight work where a real stop exists (queued jobs, a running agent reply) and returns cancel: { stopped[], notStoppable[] (already running — it will finish), finished[] (proposals that already applied) }. A cancel may come back status 'proposed' — that is NOT an error: it is queued for the user's review and nothing is stopped until they approve. Also closes any running playbook_run. Returns a **review pack**: pendingProposals[], counts, and warnings (e.g. unfinished expectedOutputs — warn only), plus nudges for what closed still owed (ungraded criteria: grade them with synap_evaluate_session — best BEFORE closing). Use synap_list_proposals({sessionId}) to re-fetch the pack.

synap_load_skillCopy Anchor Link

Load skill · Read-only

Load the full body of a seeded teaching skill (the L2 tier behind the one-line summaries you see on other tools' descriptions and in the catalog). Pass a system/<package>/<stem> slug, a bare stem (e.g. 'document-embeds'), or 'catalog' to list every available skill grouped by topic. Need a tool you do not see? Pass a tool group — 'tools:read', 'tools:data', 'tools:sessions', 'tools:governance', 'tools:schema', 'tools:spaces', 'tools:tracks', 'tools:build', 'tools:capabilities' — or 'tools:builder' for every tool; a skill that teaches a group unlocks it too.

readCopy Anchor Link

Listed after synap_load_skill('tools:read').

synap_get_entitiesCopy Anchor Link

List entities · Read-only

List entities for a user filtered by profileSlug. Use to browse all entities of a type (all tasks, all projects). For content/semantic recall use synap_ask. Pages: limit (default 50) + offset; a reply with nextOffset has more — pass it back as offset. Returns lean rows by default; use synap_get_entity or detail:'full' for full values.

synap_get_entityCopy Anchor Link

Get entity · Read-only

Get a single entity by ID with full details: all properties and metadata. Use after synap_ask to get complete data on a result. The id comes from synap_ask results or synap_create_entity responses.

synap_get_documentCopy Anchor Link

Get document · Read-only

Get a document by ID: its markdown content, the revision to pass back as baseRevision when you edit it (synap_update_document), its top-level sections (id, owner ai|human, title — you may only rewrite ai ones), and diagnostics (embeds that will not render, each with a fix; null + diagnosticsError when they could not be checked). format: "readable" replaces every embed with its markdown fallback. Documents are long-form content (meeting notes, research, writeups, reports); get documentId from entity.documentId or search results.

synap_get_thread_contextCopy Anchor Link

Get thread context · Read-only

Get full context for a thread: all messages plus linked entities and documents. Call before posting a message to orient yourself with conversation history and in-scope data. threadId from synap_post_message or the user's personal channel.

synap_get_relationsCopy Anchor Link

Get relations · Read-only

Get all relations for an entity — inbound and outbound. Returns typed edges with sourceEntityId, targetEntityId, and relation type. Dependencies ('blocks' / 'depends_on') are included: they are stored as one dependency link, so their row carries storedAs:'link' and a link id. Check before synap_link_entities to avoid duplicates. Use to understand an entity's connections.

synap_get_graphCopy Anchor Link

Get graph · Read-only

Fetch ANY object PLUS everything it's linked to, typed. Returns { object, neighbors[], counts }. Each neighbor is { kind, subtype, name, id, edgeType, direction, via } — so you see a person linked to a deal, a skill linked to its tools, a session to its produced entities, etc. Graph by default: call this to understand an object's place in the pod before acting. Works for entity, project, view, channel, session, playbook, tool, skill, automation, document, track (a project's method: its project, sessions and playbook), proposal (what it governed and the session it was filed in) and run (an automation run: its automation and subject).

synap_resolve_identityCopy Anchor Link

Resolve identity · Read-only

Read-only identity PRE-CHECK — call BEFORE creating an entity to decide create-vs-enrich-vs-attach_facet. Pass the strong signals you have (email/phone/url/twitter/github/externalId) and/or a title + kindSlug. Returns match:'strong' (a globally-unique signal already resolves to an entity → do NOT create; enrich it or synap_attach_facet a new role onto entityId instead), match:'weak' (same-name candidates — advisory, inspect candidates before deciding), or match:'none' (safe to create). This is the dedup door: an entity exists ONCE (a person, a company); roles are facets, never second entities. Never writes.

synap_list_profilesCopy Anchor Link

List profiles · Read-only

List all available entity types (profiles) AND the relation types you may link them with. ALWAYS call at session start before creating entities or relations. Never assume 'deal', custom types or a relation slug exist — workspaces differ. Returns { profiles, relationTypes }: a lightweight digest per profile (id, slug, displayName, profileKind, entityScope, applicableKinds on roles, description ≤120 chars, workspaceId), and relationTypes as slugs grouped by lens ([{workspaceId:null, slugs}] = valid everywhere, plus per-workspace groups listing only the slugs that workspace adds). detail:'full' returns complete profile rows and full relation-type rows (displayName, description, isDirectional, inverseLabel). A relation type on synap_capture / synap_link_entities must be one of those slugs; any other slug is rejected with the valid list. If the relation read failed you get relationTypesError instead of relationTypes. Without a workspaceId, profiles are merged across your workspaces; a workspace whose profiles could not be read is named in workspacesFailed (its kinds are missing from profiles), never silently dropped. No property schemas here or in synap_orient. A kind's fields, enums and required keys: call synap_get_entity on any existing entity of that kind (its effectiveProperties); over HTTP, GET /api/hub/discover?profileSlugs=<slug>. For a kind with no entities yet, a write that breaks the schema is rejected with the valid fields quoted — fix and resend once.

synap_findCopy Anchor Link

Find what can do this · Read-only

What can do this, and where does it belong? Searches the pod's runnable verbs, the abstract-intent axis, the user's playbooks and their spaces (with the kinds to write there) in ONE call, and returns each match WITH its argument schema, so you can run it without a second lookup. Pass intent as free text (not the closed intent vocabulary). A block that is absent was not searched; matches: [] means it was searched and nothing fit. Matching is lexical, so a miss is never proof of absence — coverage says how much was searched and noConfidentMatch carries the escalation ladder. Run a hit with synap_run_capability (verbId) or synap_run_playbook (playbook id).

synap_get_channelCopy Anchor Link

Get or create channel

Get or create a channel. Use mode 'personal' to get the user's personal AI thread for a workspace. Use mode 'by-context' to get/create a thread scoped to an entity or document.

synap_diagnoseCopy Anchor Link

Diagnose · Read-only

Understand what's happening / what's wrong — the pod's health door (the third door, alongside ask + capture). The MODE is derived from what you pass (never a tool name you choose): NO ARGS → whole-pod health (stuck runs, failed flows, review backlog + age, duplicate-proposal clusters, capability posture, agents hitting the daily cap) with a plain-language summary; type → a class as a surface (type:"proposal" = the review queue: pending count, oldest, duplicate clusters; type:"session" = stuck sessions; type:"agent" = agent roster + quality; type:"capability" = which installed verbs are turned on and which are not (a verb that is not turned on refuses to run); type:"run" = per-flow failure counts; type:"workspace" = the workspace landscape: per-workspace entity counts + which kinds live in each, PAIRWISE profile-slug overlap between workspaces, and flags for empty / duplicate-named / no-authored-identity workspaces — the "do I have too many workspaces?" read); id → auto-detects what the id is (proposal / session / capability / automation-run / playbook-run / agent / entity / view / document / workspace) and explains its state + WHY; agentId → an agent's behavioural scorecard (approve/reject/revise rates, top rejection reasons, duplicate rate, daily-cap posture). Backward-compatible: runId+flowType → that run's activity timeline (a capture's decision + trace events, each with a machine-readable reason + fixHint); flowType/flowId → the run feed. USER-scoped automatically.

synap_template_healthCopy Anchor Link

Template health · Read-only

See where each workspace stands with its template — the pod's template-update radar. Per workspace: drifted (true = there is a step to take: a newer version, or a last update that did not finish); state (the last update: active done · building in progress · awaiting-approval its parts wait on the proposals in awaitingApproval · partial, layer-2-not-run or failed not finished); applyWarning (the pod's one sentence for what is left to do — relay it as is); pendingDataChanges ({count, sentences, needsPodAdmin} or null: the update changes existing data and waits for a PERSON to agree — never you; tell them what changes, in its sentences, and that they run synap templates update <slug> themselves, a pod owner or admin when needsPodAdmin); updateProposal ({id} or null: an update of this space is already proposed — point the person to that proposal, never file another); plus installedVersion, latestVersion, warnings and lifecycle: current, retired (replacedBy names the replacement, retiredReason says why; move it with synap_retire_workspace), unlisted (no longer in the catalog) or unknown (the catalog could not be fully read — never treat it as unlisted). The update path is synap templates update <slug>: run with an agent key it becomes a proposal the person approves, and data changes always need the person. Never re-apply a space that is awaiting-approval or has an updateProposal: the person's approval comes first. Read-only; scoped to the caller's own workspaces.

dataCopy Anchor Link

Listed after synap_load_skill('tools:data').

synap_create_entityCopy Anchor Link

Create entity

Create a SINGLE typed entity — no relations parameter exists here. Use when you already know the exact profileSlug + fields: the structured, deterministic sibling of synap_capture (which parses free text). Discover slugs with synap_list_profiles; synap_ask first to avoid duplicates. Same-profile same-name creates are REJECTED with candidates (reuse the existing id, enrich, or attach a facet) unless forceCreate=true. Placeholder person/company titles (e.g. 'Not publicly disclosed', 'unknown') are rejected. To create an entity TOGETHER WITH its edge to another entity in one reviewable unit, use synap_capture instead, passing both entities and relations — synap_link_entities cannot target an entity this call just proposed (its id isn't live until approved). A decision with decisionStatus:'proposed' ASKS the person automatically: pass decisionOptions (≤8 of {label, value?, description?}) + recommendedOption, and sourceSessionId to keep the question in your session; their answer updates it. Never create a decision for an answered confirm/choose — the pod already filed it (slot.decisionId).

synap_update_entityCopy Anchor Link

Update entity · Destructive

Update an entity's title, description, properties (JSONB), or long-form BODY (content). Requires entityId from search or synap_get_entity. May return 'proposed' if the write requires review. Use for property updates and status changes. To move a status (a kind's declared lifecycle), set the property to the new option AND pass expectedStatus = the status you read: conflict means someone moved it (re-read), a move into a done/lost option proposes, and a human-only option is refused. content REPLACES the whole body of the entity's linked document (an alias of synap_update_document with one replace_all op): it always goes to review, and it is refused if it changes a person's section or drops an embed. To change one section or one passage, use synap_update_document instead. If the entity has no body document yet the call is refused — create and attach one with synap_create_document({ entityId, title, content }). profileSlug converts it to another kind, keeping its id and links (always reviewed).

synap_update_entitiesCopy Anchor Link

Update many entities · Destructive

Change up to 500 existing entities in ONE call — retitles, property fixes, status moves. Use it for any change set; never script many single updates or Hub REST calls. Each item is {id, patch, expected?}; patch fields: title, description, properties, deleteProperties, expectedStatus (no kind change, no body — use synap_update_entity / synap_update_document for those). Governance is per item: each is written now (when it would auto-approve), or collected into ONE review for the person, or denied, or skipped (not found, changed since you read it, nothing to change). The answer lists applied, proposed {proposalId, count, reviewUrl}, denied, skipped, plus items[] with each verdict — a partial result is normal. 'proposed' is success: do not resend those items; a skipped item with deferred: true was kept on a space-join request and is replayed for you. Pass validate:true first to see the verdicts without writing. Pass an idempotencyKey so a retried call returns the first answer instead of acting twice.

synap_create_documentCopy Anchor Link

Create document

Create a standalone document. TWO modes: (1) authored text — pass content (markdown) for meeting notes, research, plans that don't fit entity properties. (2) external reference — pass url (no content) to reference a file/page you have a LINK to but no bytes to upload (e.g. a Google Doc, a PDF URL); this is the agent-appropriate way to add a 'file' since an agent has no filesystem. Pass entityId to ATTACH the document to an existing entity. If you're also creating the entity, prefer synap_create_entity with content (entity + body in ONE call). To store real file bytes, use synap_store_file (≤10MB inline; bigger: synap_request_upload, then synap_store_file({uploadToken})). Attachment only happens when the document auto-approved; a proposal-gated one has no row to link yet, and the response says so.

synap_update_documentCopy Anchor Link

Update document · Destructive

Edit a document with ops — a section, a passage, an addition — instead of rewriting it. Read it first with synap_get_document and pass its revision as baseRevision. Ops, applied in order: upsert_section {id, title, body} writes ONE ::::synap-section block by id (replaces your own ai section, or appends a new one); replace_text {old, new} — old must match EXACTLY once, copy it from the document and include enough context (0 or 2+ matches is refused with the count); append {body}; replace_all {content} (whole body — needs baseRevision, always goes to review). Refused: changing a section whose owner is human (by any op), and removing an embed unless allow_removing_embeds: true. Usually returns 'proposed' (the person reviews a per-section before/after); a governance rule may apply it directly. The response carries preview and diagnostics (embeds that will not render, each with a fix — advisory, never a refusal). A 'changed after you read it' error means re-read and redraft.

synap_request_uploadCopy Anchor Link

Request upload

Get a URL to upload a file too large for synap_store_file inline (over 10MB, up to 500MB for video). Returns {uploadUrl, headers, uploadToken, expiresAt, maxBytes}: PUT the exact bytes to uploadUrl with exactly headers before expiresAt, then call synap_store_file({uploadToken}) within the hour to save it. size must be the exact byte count.

synap_store_fileCopy Anchor Link

Store file

Store file CONTENT you already have (text via content, or binary via contentBase64) as a file — ANY type, stored **as-is and NEVER read/analyzed**. Use for a report/CSV/image/PDF/etc. you generated or hold. Pass attachToEntityId to attach it to an existing entity instead of creating a new file. For a link you have (no bytes), use synap_create_document with url. Max 10MB inline; for a bigger file call synap_request_upload, PUT the bytes, then call this with uploadToken.

synap_remember_factCopy Anchor Link

Remember fact

Store a durable fact about the user (preference, habit, working style, technical context) as a governed user_observation. Returns status:"proposed" with a reviewUrl when the fact is your own inference — that is normal, not an error — or status:"created" when you pass userStated:true because the user told you directly. Returns the record's id so you can link or revert it.

synap_link_entitiesCopy Anchor Link

Link entities

Create a typed relation between two entities. type is NOT a free string: it must name an existing relation-def slug — real ones include 'relates_to', 'references', 'mentions', 'parent_of', 'depends_on', 'blocks', 'created_by', 'works_at'. To file an entity into a project use synap_file_into_project — belongs_to_project is refused here. The default slugs resolve pod-wide, so no workspaceId is needed for them; a workspace may add or override slugs. A slug that names no relation def is rejected. If available to you, check this entity's existing relations first to avoid duplicates. Both endpoints must already be LIVE entities — an id from a still-pending synap_create_entity proposal will fail; to create an entity and its edge together, use synap_capture with entities + relations instead. May return 'proposed'. Builds the knowledge graph.

synap_attach_facetCopy Anchor Link

Attach facet

Attach a ROLE to an existing entity (Kind + Facets). A role — client, partner, prospect, investor, sponsor — is a FACET, never its own entity: an entity IS one kind (person, company) and HAS many roles. Resolve identity FIRST (synap_ask / synap_get_entities on strong signals like email / phone / website) so you attach the role to the REAL entity instead of creating a duplicate. Governed like any write: may return 'proposed' (a proposalId to review) — NEVER treat that as an error. Use synap_list_profiles to find role slugs (profileKind='role') and which kinds they apply to (applicableKinds).

synap_detach_facetCopy Anchor Link

Detach facet · Destructive

Detach (soft-delete) a role from an entity (Kind + Facets). Provide the entityId + facetSlug of the role to remove (or a facetId directly). Governed like any write: may return 'proposed' — NEVER treat that as an error. Removing a role never deletes the entity; only the role-facet is retired.

synap_move_entitiesCopy Anchor Link

Move entities to space

Move entities into another Space (workspace; e.g. a mis-routed lead). You must be able to write the destination. Per entity: returns { moved, proposed, errors } — a proposed move is success.

synap_organize_libraryCopy Anchor Link

Organize Library

Propose how to ORGANISE the person's Library (the links, files and notes they kept) — never add to it: your own words, links and files go to synap_capture. Without ops: returns the Library's groups (id, name, note, item counts) so you can name one. With ops: files ONE proposal for the person's review — always a proposal for an agent, proposed is success (surface reviewUrl); nothing changes until they approve, then it applies exactly as if they had done it. Ops: group.create {name, note?, itemIds?} · group.items {groupId, add?, remove?} (existing items) · group.update {groupId, name?, note?, workspaceId?: the space Build files into, null clears} · group.build {groupId} (approval runs Build, whose result is reviewed again). Item ids come from synap_ask (its Library hits carry their id). An id that is not in this Library is refused.

sessionsCopy Anchor Link

Listed after synap_load_skill('tools:sessions').

synap_get_sessionCopy Anchor Link

Get focus session · Read-only

Re-find a focus session — read-only. outcomes is what it must yield and needs: outcomes.outcomes[] (key, label, verify, met + metBy, state, evidence) and outcomes.inputs[] (what the person must give, each pointing at the outcome it blocks); status:'unavailable' means the read failed, not empty. To CONTINUE a session, read continuation first: it is the continuation packet (userMustDecide = owed slots + pending proposals, aiCanDo = open agent deliverables, blockers, outputs, run manifest, rerun, lastCompletion, nextMove). A section with status 'unavailable' failed to load — it is NOT empty. Pass sessionId for a specific session. Omit sessionId only when you have exactly one open session (ambient). If multiple sessions are open, returns multiSession:true + openSessions[] — pass sessionId explicitly (ambient attach is disabled to prevent mis-attribution). Always yours: sessions are scoped to the calling user.

synap_list_sessionsCopy Anchor Link

List focus sessions · Read-only

List YOUR focus sessions, newest first — read-only. Use it to see what work is open before starting something new (don't start a second session for work that already has one), or to find a session you closed earlier. Filter by status and/or narrow to a workspace or project. Pages of up to 50: a reply with nextOffset has more — pass it back as offset.

synap_list_agentsCopy Anchor Link

List agents and computers · Read-only

Who can take the person's work, and on which COMPUTER — read-only. computers[] are theirs (match their words, e.g. 'my devbox', against these names first, then agent names/types; 2+ fit → ask). Each agent: computer, canTakeYourWork (else whyNot), live, paused, lastSeenAt, and handOff — what YOUR hand-off would do now: direct, asks_you (the person approves it first: give them the reply's review link), blocked (handOffReason); ready ones come first. Hand NEW work: synap_start_session with agentIds:[agentUserId], a goal and 2-5 criteria; work in flight ('this session'): synap_update_session addAgentId. Then follow its room (synap_get_thread_context on the session's channelId; outcomes via synap_get_session) and report back. Paused or not live: say so, never hand off silently. How: load_skill system/synap/hand-off.

No parameters.

synap_evaluate_sessionCopy Anchor Link

Evaluate focus session

Grade a focus session against its acceptance criteria. Post deterministic evidence for evidence-checked criteria as evidence: { <evidenceKey>: { passed, detail? } }; capability and judge checks run automatically (the judge is never the model that did the work). Returns each criterion's result, the current evaluations and the session verdict. At most 2 automatic attempts per criterion — after that a failing required criterion is handed to the human. Never blocks closing the session.

synap_revert_sessionCopy Anchor Link

Ask the user to revert a session · Read-only

Reverting takes back work that was already approved, so it is a HUMAN decision: this tool NEVER reverts anything. Call it when a session (a run), some of its proposals, or one item of a proposal should be undone. It answers status 'refused' — that is the contract, NOT an error — with the session's revertable proposals and a link to each: hand those to the user. The user reverts from the session room or the proposal — everything, only some proposals, or one item; items edited since are skipped with the reason.

synap_rerun_sessionCopy Anchor Link

Rerun a session · Destructive

Re-analyse a finished session (a run) from its STORED sources with the CURRENT guidelines, as a NEW session spawned from it. ALWAYS call with dryRun:true first: it returns the counts (sources, what would be reverted, pending proposals left alone, estimated structure calls) and whether it is within the cap — nothing is written. mode 'add' re-analyses on top of the previous run; mode 'replace' reverts the previous run first and is a HUMAN decision (an agent gets ok:false, reason:'replace_is_a_human_decision' — hand the user the session room). Each re-analysed source files its writes through the governed capture/import doors, so an item outcome 'proposed' is normal, NOT an error. A still-open session is refused (cancel it first); refusals come back as { ok:false, reason, message }.

synap_promote_session_to_playbookCopy Anchor Link

Save session as template

Escalation L4 — crystallize AFTER a session succeeded and the process is clearly repeatable (not a one-off). Promotes a validated focus session into a reusable Playbook (runtime → config): re-grants capabilities used and records lineage. May propose; never promote failed or speculative sessions.

governanceCopy Anchor Link

Listed after synap_load_skill('tools:governance').

synap_list_proposalsCopy Anchor Link

List proposals · Read-only

List proposals — the audit trail of AI writes. AI writes return status 'proposed' when they require human approval — this is NOT an error. Filter by status: 'pending' (needs review), 'approved', 'rejected', 'auto_approved' (the write EXECUTED immediately under governance and filed this row as its receipt — use this to show the user what you did without asking), 'reverted', 'approval_failed', 'withdrawn', 'expired' (never decided — its session closed or its window lapsed). Pass sessionId to load the **session review pack** (proposals for one focus session). userId is auto-injected from the API key if not provided.

synap_get_proposalCopy Anchor Link

Get proposal · Read-only

Read ONE proposal in full — the door for "why did my write not land?". Returns the row a reviewer sees: status, the whole data payload (the operations that would apply), summary, provenance, and — when an approve was attempted and FAILED (status: 'approval_failed') — rejectionReason (the classified sentence) plus data.failure { errorClass, providerRef, missingFields }: the fields naming what to fix. Use it after a write comes back proposed and the user reports a problem approving it, then REPAIR the same proposal with synap_revise_proposal (never file a second one pointing at the first), or withdraw it with synap_reject_proposal. A proposal still pending after a failed approve attempt recorded nothing — read data and check the ops yourself. The raw upstream error text is deliberately NOT returned.

synap_governanceCopy Anchor Link

Get governance policy · Read-only

Read workspace governance policy and count of pending proposals. Use before writes to understand auto-approve rules and whether proposals will be created. When called with an agent key it also returns agentBudget: YOUR pending-proposal cap, how many of it you are using, whether you are BLOCKED (at the cap your writes are refused — nothing is written), and the remedy, including the link to a cap-raise request already waiting for your owner's review. Read-only: it never files anything.

synap_revise_proposalCopy Anchor Link

Revise proposal · Destructive

Amend a pending proposal you authored (e.g. after user feedback): its summary, its reasoning, and/or the payload it will actually apply. Does not re-run the event pipeline, and does NOT approve it — a human still decides.

synap_reject_proposalCopy Anchor Link

Reject proposal · Destructive

Reject a pending proposal so the queued change never lands — withdraw a write you now know is wrong (a duplicate, a superseded plan, a mistaken read) instead of leaving it in the user's review queue. Give a reason: it is recorded on the proposal and feeds your agent scorecard. There is deliberately NO approve tool: approval is the HUMAN step (an agent key that approved its own write would be self-approving) — point the user at the proposal's review link instead. Rejecting is safe by the same logic in reverse: it only PREVENTS a pending change from landing, so it carries no self-approval or undo risk. Only a still-pending proposal can be rejected.

synap_create_ruleCopy Anchor Link

Create rule

Turn a stated standing intent into a RULE — the COMPILED door, and the one to reach for whenever the user says 'always…', 'from now on…', 'never…', 'every Monday…', or states a preference that should outlive this conversation. Send their own words as intent.

• intent alone → a FACT rule: durable prose ('Acme prefers async') that any agent reads later while reasoning. Legitimate and complete.

• intent + sentence → BEHAVIOUR: the door compiles your WHEN/WHERE/THEN into a real automation, or refuses. A rule that describes something running is never stored as prose that cannot run.

USE THIS INSTEAD OF synap_create_automation / synap_create_skill for a standing intent. Those are raw primitives — they persist whatever you hand them, so a bad trigger installs 'active' and silently never fires, and an instruction skill only ever sits there as text. This door verifies the compiled artifact against the runtime BEFORE anything is saved. (Reach for synap_create_automation directly only when you are authoring a flow that is not a user-stated rule — a multi-step pipeline with its own data contract.)

WHAT IT REJECTS, and why each rejection is real: a WHEN naming an event no emitter produces (the automation could never match); a WHERE row with a field but no value (dropping it would widen the rule beyond what was written); a THEN with no configured action (a trigger wired to nothing); run_command (the command step has no receiver and throws every run — use an AI step). A refusal comes back as status='denied' with failure.clause (WHEN | WHERE | THEN) and a reason written for a human. FIX THAT CLAUSE AND RESEND — it is a verdict, not a transient error, and re-sending it unchanged will fail identically.

If the intent describes something that should run and you send no sentence, the receipt carries needsBehaviour — the rule was saved as prose and will not execute; say so rather than reporting it as in effect.

Scope: pod-wide by default; pass workspaceId for a domain rule, projectId for the cross-cutting lens. A projectId limit is only enforceable on WHEN events that carry a project — entity.*, entity_facet.*, external_message.*, channel_message.*, focus_session.*, proposal.* — and is REFUSED (status='denied', clause WHEN) on any other trigger (e.g. a schedule); drop the project or pick one of those events. expiresAt makes the rule stop applying — pass one whenever the intent is situational ('while we're in the launch push'), because a standing rule with no expiry is one the user must remember to revoke.

Governed like every write: status='proposed' is SUCCESS, not an error — surface the returned link as a markdown link and never report a proposed rule as already in effect.

schemaCopy Anchor Link

Listed after synap_load_skill('tools:schema').

synap_define_kindCopy Anchor Link

Define entity kind

Define a new entity KIND — AND the door for ADDING A FIELD to a kind that already exists. It is SLUG-IDEMPOTENT: re-call it with an EXISTING slug and it returns that profile and adds only the properties[] that are not there yet (an existing field reports status 'unchanged' and is never rewritten). So to add wedge_stage to question, call this with slug 'question' and just that one field — there is NO separate add-property tool, and schema editing is NOT browser-only. A field takes valueType, constraints (an enum of allowed values lives here), defaultValue, required, and overlay: true to add it as a WORKSPACE OVERLAY instead of a base field on the kind — which is what you want for a field that only one domain should see, on a pod-wide kind like note/task/question. Call list_profiles + extend-first (load_skill system/synap-schema/extend-first) BEFORE minting a new slug. A hat on an existing kind — including item, task, deal — is a ROLE (synap_define_role / attach_facet), never a sibling kind. Prefer parentProfileSlug of the closest parent over a disconnected slug. A relationship-with-its-own-life (buyer×seller×price×stage) is its own kind (deal *precedent*), not a twin of CRM deal. POD-WIDE default. Governed: 'proposed' is success. Creates it on this pod only; an official template is written in the catalog and published with synap catalog publish --official.

synap_define_roleCopy Anchor Link

Define role type

Define or WIDEN a role (facet): a hat on ANY entity kind, not only person/company. Example: applicableKinds ['item'] means 'this item is an X'. Call ONLY after synap_list_profiles. If the slug already exists, extra applicableKinds are MERGED (widen only — never a second slug for the same hat). Prefer attach_facet; widen when kind_mismatch. NULL stored allowlist = any kind. Governed: may return 'proposed' — NEVER treat that as an error.

synap_grant_profile_accessCopy Anchor Link

Share kind with space

Let another Space (workspace) see and use a SHARED kind (profile). Widens visibility, so it is always a proposal for an agent. Find ids with synap_list_profiles / synap_list_workspaces.

synap_change_kind_scopeCopy Anchor Link

Change kind scope

Change which Spaces see a kind (profile) and where its NEW records live. scope "shared" (+ allowedWorkspaceIds) makes the kind resolve in those spaces; "workspace" pins it to its home and revokes grants. entityScope "pod" makes NEW records pod-wide (existing records keep their space). Use it when another space needs a kind — never define a twin kind. Always a proposal for an agent; the kind's owner (or a pod admin for a system kind) approves. To add one space to an already-shared kind, use synap_grant_profile_access.

synap_retire_fieldCopy Anchor Link

Retire field · Destructive

Propose RETIRING a field (a property definition) — including a kind's base field or a global field, which nothing else can remove. Always a proposal, for anyone: proposed is success, never a direct delete. REFUSED while the field still holds values (the answer lists them; move or clear them first). Find ids with synap_list_profiles. On approval the definition is deleted.

spacesCopy Anchor Link

Listed after synap_load_skill('tools:spaces').

synap_set_workspace_focusCopy Anchor Link

Set space focus

Pin your runtime workspace focus so every subsequent write (create/update/capture) with no explicit workspaceId lands there — the 'use the CRM workspace until I say otherwise' scenario. ADVISORY: a call that DOES pass an explicit workspaceId still overrides the focus; reads are unaffected. Sticky in THIS conversation until cleared — another conversation keeps its own (set the same focus there to share it); the reply's focusScope says which. Pass workspace as a name (matched against your workspaces) or an id; omit it (or pass 'none'/'clear') to clear the focus. Pinning a space also RETURNS its brief (purpose, the kinds it holds, its skills, its playbooks) — the same brief a pinned synap_orient serves, so focusing is also how you learn what the space knows before you work in it.

synap_set_project_focusCopy Anchor Link

Set project focus

DECLARE which project you are working on, so writes that don't pin their own project file into it — the 'everything I do now is for the Apollo migration' scenario. Sticky in THIS conversation until cleared — another conversation keeps its own (set the same focus there to share it); the reply's focusScope says which. A call that passes an explicit projectId still wins. Filing into a project GRANTS ACCESS to it, so this is a DECLARATION only: the project is verified to exist and be visible to you at set time, and nothing infers a project from what you write. Pass project as a name (matched against the projects you can see) or an id; omit it (or pass 'none'/'clear') to clear the focus.

synap_list_workspacesCopy Anchor Link

List spaces · Read-only

List the workspaces (domain lenses) you can see, pod-wide — call this to find a workspace id instead of guessing from orient. Each row: id, name, description, workspaceType, your role, accessKind (member | pod_visible), archived, entityCount, and usedByProjectIds (projects that run through it — an INDEX, not an ACL). Link a project to one with synap_project_use_workspace. To learn what a space is FOR and what it knows — its purpose, the kinds it holds, its rules and its skills — PIN it: pass its workspaceId to synap_orient, or synap_set_workspace_focus; both return that space's brief.

synap_create_workspaceCopy Anchor Link

Create space

Escalation L3 (governed — may propose): create a workspace from a definition. Template-first: market.search(kind:template) + prefer install before freehand create. Only after workspace-design four conditions hold and no template fits. Capture never invents a workspace. Pass stable proposalId for idempotency. Creates it on this pod only; an official template is written in the catalog and published with synap catalog publish --official.

synap_update_workspaceCopy Anchor Link

Rename space

Rename or re-describe an existing Space (the user's word for a workspace; settings are not editable here). Governed: always a proposal for an agent — proposed is success.

synap_update_space_briefCopy Anchor Link

Edit space brief

Change a Space's brief (how agents work there: purpose, persona, anchors, what to collect). Only the fields you name change; null removes one. Governed: an agent always proposes, with a before/after the owner reviews — proposed is success.

synap_archive_workspaceCopy Anchor Link

Archive space · Destructive

Archive a Space (the user's word for a workspace — ids and params keep workspace): hide it everywhere and PAUSE its space-scoped rules (automations); pod-wide rules are untouched. Or restore it with restore:true — restore re-enables NOTHING and lists the rules still paused so the person can choose. Owner or pod admin only; system spaces refused. Always a proposal for an agent — proposed is success, surface reviewUrl.

synap_retire_workspaceCopy Anchor Link

Move space off a retired template

Move a Space (workspace) whose template was RETIRED (synap_template_health lifecycle retired with replacedBy) into the space of its replacement: installs the replacement if missing, moves every item whose kind has a home there, and archives the old space only if nothing is left (never deletes). Call with dryRun:true first to see the plan (what moves, what stays and why). Governed: always a proposal for an agent — proposed is success, surface reviewUrl.

synap_declare_workspace_sourceCopy Anchor Link

Declare space source edge

Declare a cross-workspace DATA EDGE on an EXISTING workspace by setting/merging its edge fields. sourceRoles = per-domain role this workspace plays (provider | consumer | provider-consumer), e.g. Marketing consumes Comms → { comms: 'consumer' }. defaultSources = per-domain the workspace to READ that domain from (the source of truth), e.g. { comms: { workspaceId: '<comms-ws-id>' } }. MERGES per-domain — existing domains and all other settings are preserved, never clobbered. Use this to wire the enterprise graph (provides/consumes) instead of copying data between workspaces. Editor+ membership required.

synap_list_projectsCopy Anchor Link

List projects · Read-only

List the projects (cross-cutting initiatives) you can see, pod-wide, newest first — call this to find a project id before reading, updating or linking it. Each row: id, name, description, status, phase, phaseCategory (legacy label; method position lives on tracks: synap_list_tracks), targetDate, homeWorkspaceId, usedWorkspaceIds (domains it runs through) and its subject. Paginated: { items, pagination: { hasMore, limit, offset } }. Full read: synap_get_project.

synap_get_projectCopy Anchor Link

Get project · Read-only

Read one project: name, description, home workspace, and usedWorkspaces (domains this engagement spans via the uses INDEX). Call after orient when you need the span map. Not an ACL.

synap_create_projectCopy Anchor Link

Create project

Create a project — a cross-cutting lens for an initiative/venture that organizes entities across workspaces (a workspace is a domain lens; a project cuts across them). workspaceId = its HOME workspace (optional). A PROJECT IS A COMMITMENT WITH GRAVITY: never create one per git-repo, per-feature, or per-task — those are entities (task/plan/note). You MUST pass evidenceEntityIds: at least 5 existing entity ids that would belong to this project, or the create is rejected. If a same/similar project already exists it is reused (or surfaced) — reuse it instead of making a near-duplicate. An agent call lands as a proposal unless governance has widened it: status="proposed" is SUCCESS — say it is awaiting review, do not retry.

synap_update_projectCopy Anchor Link

Update project

Update a project: rename, re-describe, change status, move its phase, set/clear its target date, or move its home workspace. Reuse this instead of creating a twin. Find the id with synap_list_projects. Governed: proposed is success — surface reviewUrl.

synap_project_use_workspaceCopy Anchor Link

Project uses space · Destructive

Stamp the INDEX edge project --uses--> workspace: this engagement runs through that domain. NOT an ACL (does not grant workspace membership). packages/apply with projectId already stamps this; call this when the workspace already exists. Idempotent. Governed: may return proposed. remove:true removes the edge instead (always a proposal for an agent).

synap_file_into_projectCopy Anchor Link

File into project · Destructive

File EXISTING records into a project (entity --belongs_to_project--> project), so the project's members see them. Use this — not link_entities (refused for this edge) and not a projectId property (it files nothing). You must be able to write every record; one refused record refuses the batch. Always a proposal for an agent, one for the whole batch — proposed is success, surface reviewUrl. remove:true un-files them instead.

synap_export_project_packCopy Anchor Link

Export project as suite pack · Read-only

Serialize a live project for marketplace: returns { definition: thin suite, constituents: full workspace packages[] }. Publish constituents first, then the suite (CLI --from-project does both). NOT live entity data. Empty uses-index → error. Read-only.

tracksCopy Anchor Link

Listed after synap_load_skill('tools:tracks').

synap_list_tracksCopy Anchor Link

List tracks · Read-only

List a project's TRACKS — the lasting goals it is pursuing (e.g. 'Grow the newsletter', 'Win the first ten clients' inside one project). Work in a track = synap_start_session with its trackId. A track holds a direction, instructions and a goal, and turns workers on; it has no stages and never completes. LEGACY: an old track also follows a project-scoped playbook (its method, with stages), pinned at the version it started with; a new track has none (playbookId null, no stages). Each row: id, name, playbookId, methodVersion, status (active|paused|completed|archived), pausedBy (check|human|null — why a paused track is held), currentStage and stages [{ key, name, position: done|active|not_started, addedAt? }] (addedAt marks a stage added after the start), direction (where it is heading, or null) and kpi ({ label, unit?, target, current?, updatedAt? } or null — current is STATED, updatedAt says when). Archived tracks are omitted unless includeArchived. Find the project id with synap_list_projects.

synap_start_trackCopy Anchor Link

Start track

Start a TRACK on a project — a LASTING goal (e.g. 'Grow the newsletter'): pass a name, a one-line direction in the person's words and, only if the person names a number, a kpi. List the project's tracks first (synap_list_tracks) and resume a running one rather than starting a twin. Work in it = synap_start_session with its trackId, one session per sitting, for as long as the goal lasts; it is paused or archived, never completed for hitting a number. No method needed and never stages: playbookId (a project-scoped playbook with stages) is OPTIONAL and legacy — omit it. Repeatable work under it = sessions that follow a playbook, or workers a status starts. While the track is active, its agent may work in the spaces the project links. Idempotent per track NAME: a live track of that name comes back with status='exists'; a live track of another method holding the name is refused. Governed: status='proposed' is SUCCESS — say it awaits review, pass on reviewUrl, do not retry. Otherwise status='started' with the track.

synap_start_stage_sessionCopy Anchor Link

Start stage session

LEGACY — for a track with stages; to work in a track, prefer synap_start_session with trackId (on a track with no stages this tool does exactly that). Start the work session for ONE stage of a track — the session a stage OFFERS when the track enters it (synap_advance_track returns it as offer). Advancing a track never starts work; call this only when the person wants that step worked on now. Defaults to the track's CURRENT stage; the stage's goal is the session's brief, its expected outputs and criteria are copied on, and the track's params are passed, so a required param nobody answered becomes a question owed to the person. Idempotent: an open session already filed at that stage comes back with status='existing'. Governed: status='proposed' is SUCCESS — say it awaits review, pass on reviewUrl, do not retry.

synap_advance_trackCopy Anchor Link

Advance track

LEGACY — only a track started with a method has stages; a track with none is never advanced (work in it = synap_start_session with trackId). Only with the user. Move a track to one of its method's stages — forward OR back (stages are re-enterable; any stage key synap_list_tracks shows). Refused for a stage the method does not declare, or a completed/archived track. A stage may carry a GATE: a human gate pauses the track and files an approval (proposalId on the reply); a check gate measures the sessions filed at the stage being left (at least one closed, every closed one passing its criteria) and otherwise holds the track paused (pausedBy='check', check.reason says why) until resumed with synap_set_track_status status='active'. Entering a stage does NOT start work: the reply's offer is the session that stage suggests — offer it to the person, and start it with synap_start_stage_session only if they want it. Governed: status='proposed' is SUCCESS — pass on reviewUrl, do not retry.

synap_set_track_statusCopy Anchor Link

Set track status

Pause, resume or archive a track. A track is LASTING: pause it while nobody should work on it (its agent loses access to the project's spaces until it resumes); archive it when the goal is dropped — archived is FINAL (start a new track with synap_start_track). Resuming (status='active') also releases a track a check gate held (pausedBy='check'). A move the table does not allow is refused with the reason. Governed: status='proposed' is SUCCESS — pass on reviewUrl, do not retry.

synap_set_track_paramsCopy Anchor Link

Set track params

LEGACY (tracks started with a method) — answer (some of) a track's method params — the questions the method DECLARED when the track started (synap_list_tracks returns them as declaredParams, with each one's type, required and any options). MERGED onto the answers already given: only the keys you pass change, and a null value clears that answer. A key the method does not declare, or a value of the wrong type, is refused with the reason. Stage sessions started afterwards carry the answers; a required param still unanswered is a question owed to the person. Governed: status='proposed' is SUCCESS — pass on reviewUrl, do not retry.

synap_update_trackCopy Anchor Link

Update track

Set a track's DIRECTION (where it is heading, one line) and/or its KPI (the number it steers by). kpi is MERGED onto the stored one: pass { current } to state the latest value (stamped with when and by whom — it is STATED, never measured), { target } to move the goal, a whole { label, unit?, target, current? } to define one, or null to clear it. direction null clears it. A KPI needs a label and a target. Reaching the target NUDGES the person to re-aim it (a new target) — the track keeps going; never move the target yourself. Governed: status='proposed' is SUCCESS — pass on reviewUrl, do not retry.

synap_add_track_stageCopy Anchor Link

Add track stage

LEGACY — a track has no stages; only an old track started from a method does. Add a stage to such a RUNNING track — work the method did not foresee. Appended after the existing stages; adding never enters it (move there with synap_advance_track, then synap_start_stage_session). A stage carries a name and an optional goal; what it must yield is declared as outcomes on the session worked there, and that is what a check gate measures. A key already declared is refused. Governed: status='proposed' is SUCCESS — pass on reviewUrl, do not retry.

buildCopy Anchor Link

Listed after synap_load_skill('tools:build').

synap_create_viewCopy Anchor Link

Create view

Create a view in a workspace (recovery when the right view is missing, or proactive once data warrants it). Call synap_list_views first — don't duplicate. For a bento, call synap_list_widgets first and only place keys from that list (stat-card needs profileSlug; view needs a saved viewId, not a profileSlug). Type: one of sheet, list, grid, gallery, kanban, matrix, masonry, calendar, gantt, timeline, graph, flow, map, bento, whiteboard (sheet is the table door). profileId scopes to one entity type. For a whiteboard, pass initialContent to seed the shapes — it is the ONLY way to put content on a board, because content cannot be updated after create. Governed: may propose. On success the result includes link (${PUBLIC_URL}/open/<id>) — surface that URL to the user.

synap_list_viewsCopy Anchor Link

List views · Read-only

List views you own, optionally narrowed by workspaceId, type, or profileId. Call this BEFORE synap_create_view so you do not duplicate an existing board. Owner-only (same floor as hub listViews). Omit filters for the full catalog.

synap_update_view_contentCopy Anchor Link

Update whiteboard content

Update the content of an existing whiteboard view (add/move/delete shapes). Goes through governance.

synap_list_widgetsCopy Anchor Link

List compose widgets · Read-only

Live list of what you may place: in a bento (surface "bento", default) or embedded in a document (surface "document"). Call this BEFORE arranging a dashboard or embedding a cell in a document — never guess a key. Each entry has key, requiredConfig, propsSchema (JSON Schema), binding, exampleDirective (the document embed form) and fallback; it covers the built-ins (stat-card, entity-list, view, chart-*, …) plus the cell:<pkg>:<key> / generated:<slug> cells installed on the pod. view needs a saved view UUID (viewId); a profileSlug is not enough. Counts use stat-card. With surface "document" it also returns fences: content languages written as a fenced block (mermaid diagrams, math equations, code), each with its aiHint.

synap_create_cellCopy Anchor Link

Define cell · Destructive

Define (create or update) a ViewFrame cell from raw renderer source — idempotent upsert on typeKey (from name) + workspace (omit workspaceId for pod-global). An agent call ALWAYS lands as a proposal: status="proposed" is SUCCESS — say it is awaiting review, pass on reviewUrl, do not retry. Creates the definition ONLY: the cell is not surfaced anywhere until it is bound as a renderer for a kind, which is a separate step — ask the user to do it in the Synap app.

synap_promote_cell_to_rendererCopy Anchor Link

Promote cell to renderer · Destructive

Escalation L4 — crystallize AFTER a cell has succeeded once as a good recurring presentation. Bind that cell as a profile's renderer for a slot (list | detail | card | dashboard). Durable/consequential → governed like any write (may propose). scope 'workspace' (default) = per-workspace overlay; scope 'pod' = profile system default. Never promote a speculative or unproven one-off.

synap_list_playbooksCopy Anchor Link

List templates · Read-only

List playbooks (reusable process/session templates) visible to you across the pod — every member workspace plus pod-wide templates. Call this to discover what already exists BEFORE improvising a new process. Optional workspaceId only narrows (still includes pod-wide). Launch one via synap_run_playbook.

synap_match_playbooksCopy Anchor Link

Match templates · Read-only

Suggest playbooks for what the user wants — text-first, suggest-and-confirm, NEVER auto-run the top hit. Pass intentText (what they said — that exact spelling) and/or profileSlug (the kind of thing, e.g. 'post') and/or entityId. At least ONE is required: a call with no signal is REFUSED (without one, every active playbook ties at the same score; to just see what exists, call synap_list_playbooks). Read-only. Returns ranked candidates best first ({ id, name, scope, templateKind, goalTemplate, subjectProfileSlug, params, executor, score, reason, signals }); [] when none. scope: 'project' (templateKind 'Track template') is a method a project runs as a TRACK — start it with synap_start_track; 'session' ('Work template') is one working session. Pass projectId (or name the project/track in intentText) and a track template ranks above its same-name session twin. Show the reason when you suggest; wait for confirmation before launching via synap_run_playbook (or, on doors that expose sessions, by opening the template as a working session with the chosen entity as its subject). Each of your words is weighted by how rare it is among the candidates, so a specific word outranks one most playbooks share. A playbook is returned only with a reason about THIS request (one of your words, the entity's kind, or one of its roles): a playbook with no subject (e.g. Plan Next Content) comes back only when your words match it. When profileSlug is omitted, every active visible playbook is a candidate.

synap_create_playbookCopy Anchor Link

Create template

Create a reusable playbook (staged process/session template) for a repeatable workflow — discoverable via synap_list_playbooks, launched via synap_run_playbook. goalTemplate may reference a declared param as {name} — a playbook run fills it; an undeclared name, or {{name}}, is refused. The default scope "session" is a template for one focus session; scope "project" (a staged method a track runs) is LEGACY — a new track needs none. Declare params to make the method self-onboarding: required params become questions for the person when the track starts. A PROCESS on a kind or role: set subjectProfileSlug; it FOLLOWS the lifecycle the profile declares (omit statusProperty, or name that same property — never a second status field). Give each stage the subjectStatus it moves the thing to (an existing option), gates at the commitments, onFail loops, typed expectedOutputs, plus workers (activators: on, size, mode) — load_skill system/synap/processes (model: system/synap/work-model) first. An agent call ALWAYS lands as a proposal: status="proposed" is SUCCESS — say it is awaiting review, pass on reviewUrl, do not retry. Creates it on this pod only; an official template is written in the catalog and published with synap catalog publish --official.

synap_run_playbookCopy Anchor Link

Run template · Destructive

LAUNCH a playbook via its executor (discover via synap_list_playbooks) — instantiates a session + run channel + playbook_run and dispatches to the playbook's executor (is-agent | external-agent | hybrid). Pass playbookId OR an unambiguous playbookName/name (multi-match returns candidates — never a silent pick). Write home: workspaceId if set, else the playbook's workspace, else subject/session; pod-wide playbooks with no home reject (pass workspaceId). This LAUNCHES the executor — it is not the same as opening a working session from the template. Governed, with THREE normal outcomes: status="proposed" (an agent launch awaits approval — SUCCESS, pass on reviewUrl, do not retry), status="blocked" (nothing ran: the playbook uses skills that are not enabled yet; unenabledSkills names them and enableProposals carries ONE enable request per pack — relay the message and run it again only after that is approved), status="running" (it started; run + session are returned), status="skipped" (nothing ran and nothing is queued — the record's last run failed recently and is cooling down, or no pinned record was ready; read message, do not retry in a loop and do not report it as started).

synap_create_skillCopy Anchor Link

Create tool (skill)

Author a skill: Documentation (always) + OPTIONAL code. Send body alone for a TEACHING skill — reusable prose (a process, a checklist, a house style) that any agent later pulls with synap_load_skill; a teaching skill needs a slug, because that is the ref load_skill resolves. Send code for a runnable sandboxed executable, or both. kind is derived from code presence — do not guess it. For a deterministic provider HTTP call on an already-installed tool use synap_create_verb instead. Governed like every write: an agent create returns status='proposed'. An agent-authored skill is born UNAPPROVED either way and does NOT load or run until the owner approves it — code executes, and instruction prose lands in a future agent's system prompt, so both need a deliberate human OK. Creates it on this pod only; an official template is written in the catalog and published with synap catalog publish --official.

synap_update_skillCopy Anchor Link

Update skill

Revise an existing skill on this pod — its body (the teaching prose), description or name — by slug (the ref synap_load_skill resolves) or id. Use it when a skill you authored goes stale; never create a second skill under a new slug as a twin. Governed like every write: status='proposed' is success. An agent rewrite of a skill's body is UNAPPROVED until the owner approves it again — that prose lands in future agents' prompts — so do not report it as live.

capabilitiesCopy Anchor Link

Listed after synap_load_skill('tools:capabilities').

synap_list_capabilitiesCopy Anchor Link

List tools · Read-only

Discover what the user can actually DO. Returns a SECTIONED view: integrations (their connected services + tools, one per name, each with its verbs nested — e.g. google → gmail_send, gmail_search, calendar_list; the verb id is what you pass to synap_run_capability), skills (standalone runnable skills), and commands. Each integration shows connection.connected (needs connecting if false) and each verb shows granted/effectiveExecMode (a not-yet-granted verb must be enabled in Settings → Capabilities). Core built-in tools (already available to you directly as MCP tools) and teaching docs are folded out of this actionable view BY DEFAULT and only COUNTED under excluded — pass kind:"builtin-tool" or kind:"teaching-doc" to list them here instead, or synap_load_skill("catalog") for every teaching doc grouped by topic. Pass query to search across integrations/verbs/skills (e.g. query:"send email").

synap_run_capabilityCopy Anchor Link

Run tool · Destructive

Run a registered capability verb (discover via synap_list_capabilities) with dynamic inputs — e.g. send an email, search Gmail, create a calendar event. Pass verbId + parameters. A DRAFT (un-enabled) capability is refused — ask the user to enable it first. Governed like any write: an ungranted verb comes back as { kind: "proposed", proposalId, reviewUrl } instead of running — that is SUCCESS, not an error. You MUST surface the reviewUrl as a clickable link in your reply (never just say 'proposed' with no link) — e.g. "Queued that email send for your review: [Review proposal](<reviewUrl>)" — and continue the conversation without waiting for approval.

synap_create_verbCopy Anchor Link

Create verb

Add a new DECLARATIVE verb (a deterministic provider HTTP call — no code execution) to an ALREADY-INSTALLED, already-credentialed tool — e.g. teach 'apify_api' a new 'apify_search_reddit_actors' verb without a dev-session/redeploy. Creates a kind='declarative' skill only; rejects any request implying code/instruction/builtin execution. toolName MUST already exist (installed + visible to the caller) or this is refused — it never creates a new tool/connection as a side effect. Governed the same as every other write: may return status='proposed' for review. Discover installed tools with synap_list_capabilities first.

synap_list_automationsCopy Anchor Link

List rules · Read-only

List automations (WHEN-triggered flows) visible in a workspace — the reactive rules a user has set up (e.g. 'on new lead → draft a follow-up', 'every morning → recap yesterday'). Each entry has its id (pass to synap_trigger_automation), name, triggerType (event | cron | webhook | manual), and status (active | draft | paused | error). Read-only. Call this to discover what already reacts BEFORE creating a new automation. Omit workspaceId to list everything accessible.

synap_trigger_automationCopy Anchor Link

Run rule now · Destructive

Run an existing automation NOW, on demand (discover ids via synap_list_automations) — e.g. fire a 'daily client recap' immediately instead of waiting for its schedule. Pass the automation id; optionally a payload injected as the run's trigger.payload. This is a RUN, not a proposal: it returns { status: 'triggered', runId } once enqueued (gated by your write access to the automation's workspace). Any entity writes the run then performs are separately reviewed under the automation's own governance. A draft automation is runnable on demand this way; paused/error non-manual ones are refused.

synap_create_automationCopy Anchor Link

Create rule flow (advanced)

Create an automation — a WHEN→THEN flow that reacts to a trigger (event | cron | webhook | manual) by running a flow of steps. Use for repeatable reactions ('every morning recap each client', 'on new deal notify the channel'). Governed the same as every write: an agent create returns status='proposed' for review; on approval it becomes ACTIVE (live) — not a stuck draft. Provide the trigger, a flowDefinition ({ nodes, edges }), and a dataContract — the contract is REQUIRED for agent-authored automations (which this always is) and the create door rejects the automation without a valid one. For a cron trigger put the schedule in triggerConfig.expression (5-field cron). Discover what already exists with synap_list_automations first. Creates it on this pod only; an official template is written in the catalog and published with synap catalog publish --official.