Symbol

Delete a capsule Type (category). Identify the Type by UUID, name (e.g. "Debug"), or @type:slug (e.g. @type:debug). SAFE-BY-DEFAULT: call it FIRST without a `strategy`. If the Type is empty it is deleted outright. If it still contains capsules the call FAILS and reports how many capsules it holds (total, archived, shared) — nothing is deleted. Treat that failure as a decision point: confirm the user actually wants to destroy or move those capsules, then retry with an explicit strategy — `strategy: "cascade"` PERMANENTLY deletes the Type's capsules along with it, or `strategy: "migrate"` plus `migrate_to` (the target Type) moves the capsules into another Type before removing this one. The default "general" Type cannot be deleted. This is destructive and irreversible for cascaded capsules — a client permission prompt is the intended guard.

delete_type

Apply targeted anchor-based edits to a capsule without sending the full body. Use edit_capsule for surgical fixes — changing a single line, updating a value, correcting a section. For broad rewrites, use update_capsule instead. Each old_str must appear exactly once in the capsule — include enough surrounding context (typically a full sentence or line) to disambiguate. All edits apply atomically: every old_str must match uniquely or the entire call fails. Errors are structured so you can self-correct without a human in the loop.

edit_capsule

Find capsules with zero inbound references within a Type or project scope. At least one scope filter is required — never runs globally. Provide one of: `type_name` (preferred), `type_id`, `project_name` (preferred), or `project_id`. Examples: `{ type_name: "Prompts" }`, `{ project_name: "@project:onboarding" }`, `{ type_name: "Prompts", workspace: "Verdant Studio" }`. Use `workspace` to scope to a specific workspace — an org Type resolves by name and the scan returns that org's orphans (like every other workspace-aware tool). Omit it to search across your workspaces (a match is attributed to the workspace it came from). If no scope filter is provided, the call returns an error.

find_orphans

Get the authenticated user's account information: email, display name, and authentication method. Use this to confirm which Symbol account is connected.

get_account_info

Fetch a single capsule by UUID or @type/ref. Accepts the same @slug/N references the user types in messages (e.g. @clients/1, @docker/3) — when the user provides one of these, call this tool or get_capsule_by_ref BEFORE answering from memory. Returns: id, ref_id, title, content_md, type_id, type_name, type_slug, type_guidance, is_encrypted, is_stale, archived_at, created_at, updated_at, workspace_id, project_id, is_prompt, prompt_name, is_agent, agent_meta (is_agent flags agent packaging; agent_meta is the stored packaging blob — both present on single-capsule reads so agent_meta can be read, one frontmatter key changed, and written back without dropping the rest), share_display (the capsule's own shared-display choice; null = inherit) and share_display_effective (the resolved value); tags and categories (structured { slug, name } classification chips, present on single-capsule reads); field_values and content_rendered (the body with {{field_name}} tokens substituted) for field-structured Types when present; a `content` envelope { format, source, text?, fields? } whose `format` (markdown|composed|structured) names the single representation to use and whose `source` (authored|borrowed) says whether the body is the capsule's own or its Type's output_template rendered live — a borrowing capsule returns content_md: null and content.source: "borrowed" — PREFER `content` (content_md/content_rendered/field_values remain only for back-compat); plus attachments, resolvedCrossRefs (and capsule_keys for encrypted capsules) when present. Also includes alsoAvailableAsSkill (the skill name) when this capsule is currently published as a skill. For a capsule packaged as a skill or an agent, includes a `packaging` object (issue #1943): { packaged_as, eligible, blockers: [{ code, message }], rendered_bytes, limit_bytes, warn_bytes, approaching_limit, published_state } — whether it can ship, every reason it cannot, the size the distributed artifact renders to, and the limit that applies, so you can tell it fits and how much room is left without publishing. Omitted for a capsule packaged as neither. Write-signal advisories on single-capsule reads (issue #1491): summary_stale (true when the summary predates the latest body edit), inbound_ref_count (the live, scope-correct count of capsules referencing this one) with unreferenced (true only when that count is 0 AND the Type does not suppress orphan warnings, is not log-structured, and the capsule is not archived), and skill_republish_needed (true when a published skill drifted in name or version and was not auto-republished — republish manually to update the served skill). Unfinished-capsule state (issue #1703): incomplete (true when the capsule was captured before its Type's required fields were satisfied) and, only on an incomplete capsule, a missing_required_fields advisory naming exactly the required fields still unmet, so a reader knows what work the capture-first capsule still owes. Includes a `log` object when the capsule owns a log or IS a log: { role: "owner"|"log", bound_type, owned_log_ref, append_via } — `append_via` is the exact append_log_entry call that targets this capsule's log, so appends are never mis-addressed (an OWNER capsule has owner_capsule_id: null by design; `log.role` disambiguates it). On a `log` capsule, `bound_type` is that log capsule's OWN Type and `owned_log_ref` is null; the owning capsule is reached via `owner_capsule_id`, not via `bound_type` (the field names the current capsule's Type on both sides). Omitted for a plain capsule. content_md is CANONICAL: byte-identical to stored content, with no inline expansion. Any @slug/N references it contains are resolved into a separate read-only `referenced_capsules` array (each entry: ref, title, content_md, is_encrypted, is_stale, available) — read those for context, but when editing, edit only content_md. Pass `workspace` to resolve an @type/ref that lives in an organization workspace; set include_type_guidance:false to omit the (repeated) Type guidance block.

get_capsule

Get inbound references (backlinks) to a capsule (1 hop), one size-budgeted page at a time. Works for both organization and personal capsules. Returns { items, hasMore, nextCursor, ... }: graph nodes for capsules that reference the target. When hasMore is true, pass nextCursor as `cursor` to fetch the next page (gap-free).

get_capsule_backlinks

Traverse the reference graph bidirectionally from a capsule up to a specified depth (1–3 hops). Works for both organization and personal capsules. Handles circular references gracefully via visited set. Returns nodes (id, title, type, ref, scope info) and edges (source_id, target_id, source_ref). Unresolved forward references are included with status "unresolved". Large graphs are capped at a node ceiling: when `truncated` is true, edges to omitted nodes are dropped (consistent subgraph) and `overflowRefs` lists unexpanded frontier refs to re-root from.

get_capsule_graph

Get outbound @type/ref references from a capsule (1 hop), one size-budgeted page at a time. Works for both organization and personal capsules. Returns { items, hasMore, nextCursor, ... }: graph nodes (id, title, type, ref, scope info). Unresolved forward references are included with status "unresolved". When hasMore is true, pass nextCursor as `cursor` to fetch the next page (gap-free).

get_capsule_references

MUST CALL when a user message contains an @slug/N reference (e.g. @clients/1, @docker/3, @debugging/14) or its emphatic form @@slug/N. These are Symbol capsule references — treat them like file paths the user pasted in. Do NOT answer from memory; fetch the capsule first. Pass the literal token as `ref` (e.g. ref="@clients/1"). The /N integer distinguishes capsule refs from npm scopes like @types/node. Alternatively use type_id + ref_id when you already have UUIDs. Returns: id, ref_id, title, content_md, type_id, type_name, type_slug, type_guidance, is_encrypted, is_stale, archived_at, created_at, updated_at, workspace_id, project_id, is_prompt, prompt_name, is_agent, agent_meta (is_agent flags agent packaging; agent_meta is the stored packaging blob — both present on single-capsule reads so agent_meta can be read, one frontmatter key changed, and written back without dropping the rest), share_display (the capsule's own shared-display choice; null = inherit) and share_display_effective (the resolved value); tags and categories (structured { slug, name } classification chips, present on single-capsule reads); field_values and content_rendered (the body with {{field_name}} tokens substituted) for field-structured Types when present; a `content` envelope { format, source, text?, fields? } whose `format` (markdown|composed|structured) names the single representation to use and whose `source` (authored|borrowed) says whether the body is the capsule's own or its Type's output_template rendered live — a borrowing capsule returns content_md: null and content.source: "borrowed" — PREFER `content` (content_md/content_rendered/field_values remain only for back-compat); plus attachments and resolvedCrossRefs (the pre-resolved cross-ref map for both body @type/N mentions and typed reference/multi_reference field values) when present. Also includes alsoAvailableAsSkill (the skill name) when this capsule is currently published as a skill. For a capsule packaged as a skill or an agent, includes a `packaging` object (issue #1943): { packaged_as, eligible, blockers: [{ code, message }], rendered_bytes, limit_bytes, warn_bytes, approaching_limit, published_state } — whether it can ship, every reason it cannot, the size the distributed artifact renders to, and the limit that applies, so you can tell it fits and how much room is left without publishing. Omitted for a capsule packaged as neither. Write-signal advisories on single-capsule reads (issue #1491): summary_stale (true when the summary predates the latest body edit), inbound_ref_count (the live, scope-correct count of capsules referencing this one) with unreferenced (true only when that count is 0 AND the Type does not suppress orphan warnings, is not log-structured, and the capsule is not archived), and skill_republish_needed (true when a published skill drifted in name or version and was not auto-republished — republish manually to update the served skill). Unfinished-capsule state (issue #1703): incomplete (true when the capsule was captured before its Type's required fields were satisfied) and, only on an incomplete capsule, a missing_required_fields advisory naming exactly the required fields still unmet, so a reader knows what work the capture-first capsule still owes. Includes a `log` object when the capsule owns a log or IS a log: { role: "owner"|"log", bound_type, owned_log_ref, append_via } — `append_via` is the exact append_log_entry call that targets this capsule's log, so appends are never mis-addressed (an OWNER capsule has owner_capsule_id: null by design; `log.role` disambiguates it). On a `log` capsule, `bound_type` is that log capsule's OWN Type and `owned_log_ref` is null; the owning capsule is reached via `owner_capsule_id`, not via `bound_type` (the field names the current capsule's Type on both sides). Omitted for a plain capsule. content_md is CANONICAL: byte-identical to stored content, with no inline expansion. Any @slug/N references it contains are resolved into a separate read-only `referenced_capsules` array (each entry: ref, title, content_md, is_encrypted, is_stale, available) — read those for context, but when editing, edit only content_md.

get_capsule_by_ref

Read a log's entries, newest-first and BOUNDED (default 20, max 100). Address EXACTLY ONE of: `capsule_id` (a log capsule directly, OR an OWNER capsule in a Type bound to a log Type — returns its owned log's entries, empty if none yet); or `type` (a period-mode log Type, read ACROSS all its dated buckets in one entry-time-ordered result — so a monthly log can be asked for "this week"). Narrow by when each entry happened with the entry_* window (a duration like 8h, a named period like this_week resolved in `timezone`, or explicit entry_after/entry_before ISO bounds). For a capsule read, page older entries with the returned nextCursor as `before`; for a Type read, pass the opaque nextCursor back as `cursor`. The capsule's prose frame comes from get_capsule.

get_log_entries

Read a Decision you sent (via send_decision), to check whether the human has answered. POLL this after send_decision, roughly every ~30 seconds for up to ~10 minutes, using the message id from the send_decision response. Returns { message, reply, answered, withdrawn, notes }: `message.decision` is the form you sent (sections/questions), `answered` flips true once every required question has a validated answer, and `reply.responses` then carries the answers (keyed by question field name). `notes` carries any free-form messages the user sent into this conversation that you have not yet received — read and act on them. Each note is delivered AT LEAST once (a note may reappear on a later poll if a delivery could not be confirmed), so DEDUPE by note `id` and prefer idempotent actions. When `answered` is true, read the answers from `reply.responses`. When `withdrawn` is true, YOU already withdrew this Decision (via withdraw_decision) — it is terminal and will never be answered, so STOP polling. A 404 means the user deleted the Decision — proceed with your best judgment and say so.

get_message

MUST CALL when a user message contains a #slug reference (e.g. #onboarding, #bloom-and-root) or @project:slug (e.g. @project:onboarding) — these are Symbol Project references. Projects group capsules across Types for organization sharing. By default returns full content for one page, packed to a byte budget; use content_level="metadata" for a cheaper metadata-only listing (titles, refs, dates). Supports cursor-based pagination. You MUST provide either project_name or project_id.

get_project_context

Retrieve a capsule via a share token or share URL. Requires API key auth and organization membership with MCP access enabled. Each call spends one view against the link's optional max-views limit, so re-resolving a limited link can exhaust it — resolve once and reuse the result.

get_shared_capsule

Get knowledge base statistics: total capsules, Types, capsules per Type, and recent entries.

get_stats

Get storage usage and list all attachments across all capsules. Shows used/quota/remaining storage and per-attachment details.

get_storage_info

MUST CALL when a user message contains a bare @slug reference (e.g. @clients, @debugging, @docker) or its emphatic form @@slug — these are Symbol Type references. SHOULD also call when the user says "load my X knowledge" or pastes domain language matching a Type name. Skip @slug only when it is clearly inside a code fence, a CSS at-rule (@media, @import), an npm scope (@types/node — has /letters, not /number), an email, or a social handle. Returns Type guidance + capsule content. By default returns full content for one page, packed to a byte budget; use content_level="metadata" for a cheaper metadata-only listing (titles, refs, dates). Use get_capsule with a specific @type/ref to load an individual capsule. Supports cursor-based pagination for Types with many capsules. You MUST provide either type_name or type_id.

get_type_context

List capsules from the Symbol knowledge base. Optionally filter by Type using EITHER type_name (preferred) OR type_id. By default returns metadata only (no content_md) for faster responses. Use content_level="full" to include full content. Every row carries the prompt facet flags is_prompt and prompt_name (plus share_display, the capsule's own shared-display choice; null = inherit) alongside the other lifecycle flags. Full rows ship content_md plus lean identity/lifecycle fields; internal columns stay omitted, and the redundant search excerpt is opt-in via `fields` (e.g. ["content_excerpt"]). Narrow by time window on the created, last-updated, or archived date (a relative <N>h/<N>d/<N>w window, a named calendar period like this_week resolved in `timezone`, or explicit *_after/*_before ISO bounds — combinable across columns), by tag, category, Skills (skill), unfinished capsules (incomplete), a Project (project_name/project_id), or staleness (stale), and choose the order with `sort`. State `timezone` when you use a named period, since the assistant is not in the viewer's browser; the archived_* windows require archived: true.

list_capsules

List all collections within a Type. Collections are named groupings of capsules within a Type for organization. Provide `type_name` (preferred — e.g. "Prompts" or "@type:prompts") or `type_id` (UUID). Examples: `{ type_name: "Prompts" }`, `{ type_name: "@type:prompts" }`, `{ type_id: "550e8400-e29b-41d4-a716-446655440000" }`. If both are provided, type_id takes precedence. If both are omitted, the call returns an error.

list_collections

List projects accessible to the authenticated user. Returns each project's id, slug, name, description, visibility, color, organization_id, created_at, and updated_at — enough to pick the right project_id for create/update/delete or for capsule association.

list_projects

List capsule Types (categories) accessible to the caller, sorted by most recent capsule activity. Default response is a lightweight per-Type row — id, name, slug, summary, is_encrypted, workspace_id, workspace_name, capsule_count, last_capsule_at — enough to pick the right Type. For a single Type's full `guidance` (required before creating/updating capsules), use get_type_context — do NOT pass detail="full" here just to read one guidance. Use detail="full" only when you need every Type's complete record (guidance, created_by, created_at, updated_at, lifecycle config) in one call. With detail="full" on a large tenant the response is paginated by size: when it does not all fit, a `delivery.nextCursor` is returned — pass it back as `cursor` to fetch the next page until `delivery.hasMore` is false.

list_types

List the WORKSPACES available to the authenticated user — the personal workspace plus every organization they belong to. A workspace is a top-level container that holds Types, capsules, and projects; it is NOT a Type (do not confuse the two). Call this when the user mentions a workspace by name (e.g. "in my Verdant workspace") and you need to disambiguate, when a previous tool call failed with a "workspace not found" or "ambiguous" error, or when you need to confirm which organizations the user belongs to before naming one. Returns each workspace's id (null for personal), name, type ("personal" or "organization"), and role. (To list Types instead, use list_types.)

list_workspaces

Create, update, or delete a collection within a Type. Collections group capsules within a Type for organization. To add/remove capsules from a collection, use add_capsules_to_collection and remove_capsules_from_collection.

manage_collection

Move one or more capsules from their current Type into a different Type — reorganize or migrate content between Types (e.g. move three capsules out of General into Standards). The capsule keeps its identity, share links, attachments, and project membership; it is assigned a fresh ref within the target Type, and its text alias travels along unless the target already uses that alias (then it is dropped). Old references keep working: a `@sourcetype/N` numeric ref or `@sourcetype/alias` written before the move still resolves to the moved capsule, so you do NOT need to edit the capsules that cite it. Reference capsules with @type/ref_id (numeric or alias) or a UUID, and the target Type by name or @type:slug. All capsules must live in the same workspace as the target Type; a target in a different workspace is refused. Returns, per capsule, its old ref, its new ref, and whether its alias travelled or was dropped.

move_capsules

Remove one or more capsules from a collection. The capsules remain in the Type. Provide a collection target: either `collection_id` (UUID) or `collection` (tenant-global alias).

remove_capsules_from_collection

Remove a capsule from a project — detach, unassign, or take a capsule out of a project (the inverse of add_capsules_to_project). Use this when the user asks to remove a capsule from a project, detach or unassign a capsule from a project, or take a capsule out of a project. The capsule itself is not deleted; only its membership in the project is removed. Use @project:slug, #slug, or plain name for the project, and @type/ref_id (or a UUID) to reference the capsules.

remove_capsules_from_project

MUST CALL when a user message contains 2+ Symbol references in any mix (e.g. "compare @clients/1 and @clients/2" or "load @debugging and check @docker/3"). Pass the raw user message as `prompt` — the server parses @slug/N capsule refs and bare @slug Type refs with the same skip rules as the inline syntax (skips CSS at-rules, npm scopes, code fences, emails). One round trip replaces multiple `get_capsule_by_ref` / `get_type_context` calls. You may pass explicit `mentions` arrays instead when the model has already extracted the references. Returns: capsules.{found, not_found, ambiguous}, types.{found, not_found, ambiguous}, projects.{found, not_found, ambiguous}, parsed, meta. Each found entry carries workspace attribution (`workspace_id`, `workspace_name`) naming the workspace it resolved in. A ref that matches the SAME slug in more than one accessible workspace still resolves (to the personal workspace by default) AND is listed in the matching `ambiguous` array (capsules/types/projects); when any `ambiguous` array is non-empty, retry with an explicit `workspace` to target the other. Pinning `workspace` scopes resolution to that one workspace and leaves `ambiguous` empty.

resolve_mentions

Revoke (disable) an existing share link so its URL no longer resolves. Use this when the user asks to unshare, revoke, disable, or turn off a share link for a capsule, Type, or Collection. Provide exactly one of: `share_url` (the full https://…/share/… link), `share_token` (the raw shr_… token), or `token_id` (the share row UUID). The underlying resource is NOT deleted — only the public link is revoked. Revoking an unknown or already-revoked link returns a clean "not found" refusal.

revoke_share_link

Turn an image attachment a quarter turn clockwise or anticlockwise, correcting a sideways or upside-down photo. The rotation rewrites the stored image so the correction holds everywhere it appears — the capsule view, downloads, and API reads all return upright bytes. Call again to keep turning; four turns in one direction return to the start. Only image attachments can be rotated (not SVG, BMP, or animated images); you must have edit permission on the owning capsule.

rotate_attachment

Search capsules using full-text search. Returns ranked results with highlighted snippets. structuredContent.results carries the ranked rows — each { ref, ref_id, title, snippet, rank, type_slug, type_name, is_encrypted } — alongside total/returned; the same rows are mirrored in the human-readable text block. Results are size-budgeted; when more remain, the notice gives the next `offset` to resume from (offset pagination is best-effort — gap-free within a stable result set).

search_capsules

Send a Decision — an interactive request for the HUMAN user to answer — delivered as a message in their Symbol Inbox. Use it when you need structured answers from the user (project intake, preferences, decision checklists) instead of free-form chat. Provide either `sections` (inline questions) or `from_type` (the slug of a PACKAGED Type) — never both. ALWAYS pass `agent.name` (STRONGLY match a capsule packaged as an agent so its featured image becomes your avatar) and `agent.task` (what you are working on right now) so the message threads under the right identity. CONCISENESS POLICY (server-enforced): each question must be 20 words or fewer and each choice option 10 words or fewer — the server rejects verbosity with a 422 naming the offending field. AFTER SENDING: the response includes a `url` — PASTE that url into your chat session so the human has a direct link to the Decision. Then POLL get_message with the returned message id roughly every ~30 seconds, for up to ~10 minutes, until its `answered` is true; then read the answers from `reply.responses` (keyed by question field name). You may attach `context` to a question (or to the Decision) — your own words on why you are asking (a changed value, a file path, a ref), shown to the user in the Context panel. For a real link target (a PR, a page), pass `links` — typed { label, href } anchors shown under the Decision — rather than pasting a URL into the title or a question; Decision prose is never turned into a link. The send response includes `notes` — any free-form messages the user sent you since your last interaction; read and act on them (each note is delivered AT LEAST once — dedupe by note `id`). The response also includes `personality` — apply its `instructions` to your ongoing tone. If the wait expires with no answer, call withdraw_decision with the message id to retract it (so it stops showing as waiting in the user's Inbox), then proceed with your best judgment and say you did so. If get_message 404s (the user deleted the Decision), just proceed. Requires the user to have experimental features enabled: a 404 on send means they have not — ask them to enable Settings → Experimental.

send_decision

Update an existing capsule by UUID or @type/ref. Only provided fields are changed. When updating content_md, follow the Type's guidance. To add attachments only, pass id with file_names/file_paths and no other fields. To attach a public file or image, pass its https:// URL in `urls` (fetched server-side). To attach a file you have the bytes for (e.g. an uploaded image on claude.ai), pass it in `attachments` as base64 ({ fileName, mimeType, data }) — for small files only (roughly ≤1MB decoded; the 6MB server cap is far above what one tool call can carry). This hosted server CANNOT read files from your computer's local disk; for seamless local-path uploads, install Symbol Bridge (https://symbol.chat/bridge) and use its create_capsule_with_attachments / update_capsule_with_attachments tools. Note: attachment bytes are NOT end-to-end encrypted — they are stored and served unencrypted even on an encrypted capsule, and are retrievable by anyone holding the attachment URL. Do not attach secrets you would not store in plaintext. Raster images above an optimization threshold are also resized and re-encoded server-side on ingest, so the stored bytes and reported size can differ from the file you submitted and the original is not preserved. All file types accepted. Limits: 25MB/file, 50MB/capsule, 200MB total, 10 files/request.

update_capsule

Update an existing project. Only provided fields are changed (PATCH semantics). Pass `color: null` to clear the display color. The workspace binding (organization_id) is immutable — to move a project, create a new one. Promoting visibility from "self" to "org_view" / "org_edit" requires the project to already live in an organization workspace.

update_project

Update an existing capsule Type (category). PATCH semantics: only the fields you pass are changed; omitted fields are left untouched. Identify the Type by UUID, name (e.g. "Debug"), or @type:slug (e.g. @type:debug). The slug is immutable (references and backlinks depend on it) and encryption cannot be toggled here — both are deliberately not editable. Guidance and summary edits are versioned automatically, so a prior version is always restorable from the Type's revision history; this makes correcting guidance safe. You can edit field_schema / output_template and the per-Type limits, but which of a Type's settings AI may change is governed per-Type: a change to a denied setting class is rejected with a clear reason. get_type_context reports the exact AI permissions for that Type. AI can never change a Type's AI-permission configuration itself. STRONGLY RECOMMENDED: pass updated_at (the Type's current updated_at, e.g. from get_type_context) so a concurrent edit is detected and reported instead of silently overwritten.

update_type

Withdraw a Decision you sent (via send_decision) that the human never answered. Call this when your get_message poll window expires with no answer and you are about to proceed on your own judgment: withdrawing retracts the Decision so it stops showing as waiting in the user's Inbox — the unread badge clears it, it is no longer named as pending, and the thread renders it as "Withdrawn" with no answer form. Nothing is deleted; the record of what you asked survives. Use the message id from the send_decision response. Withdrawing an already-withdrawn Decision succeeds again (idempotent — safe to retry). If the human answered in the meantime, withdraw returns a 409 and the answers are still readable with get_message — read them instead of proceeding blind. A 404 means the user deleted the Decision (or has not enabled experimental features) — proceed with your best judgment and say so.

withdraw_decision