Octopad

List past sessions for a workspace, with optional date range and keyword filters on summaries. USE: when an agent needs to search session history (e.g. "what did we do last week", "find the session about billing"). Returns id, summary, status, client_app, and created_at. Key params: workspace_id (required), created_after, created_before (ISO dates), keyword (substring match on summary), limit (default 20, max 100).

list_sessions

List all members of a workspace with their roles, email addresses, and org membership info. USE to resolve assignee names for task assignment or check @mention targets. Shows both workspace role and org role. NOT a membership management tool — members are managed at the org level and added to workspaces from the org member pool. Key params: workspace_id. No active session required — callable before start_session (e.g. to resolve assignees).

list_members

List all active workspaces accessible to the current user. USE when you don't yet know the workspace_id needed for start_session or other tools — this is the entry point for workspace discovery. No session required. Key params: organization_id (optional, filter by org).

list_workspaces

Sign out of Octopad on the current MCP client. Revokes the access token used to make this call so the next tool call from this client triggers a fresh OAuth login — letting the user re-authenticate, optionally as a different Octopad account. Use this when the user asks to log out, sign out, switch accounts, or change Octopad identity. Takes no parameters; acts on the bearer token of the calling request. After calling, tell the user to send another message to start a fresh login.

logout

Manage CRM companies (accounts) in the active CRM workspace. Actions: create, get, list, update, archive (soft-delete), restore. `name` is required to create. `id` (get/update/archive/restore) accepts the company name or UUID. `get` ends with a source line when a source adapter binds the record: `Source: <source> · synced (last seen <time>)`, or `· missing since <date>` when the backend stopped reporting the identity (the record is untouched). Use `filter` on list for structured queries (e.g. by industry, country, employee_count, tag, or a custom field). Requires an active session.

crm_companies

Read and manage typed many-to-many links between CRM contacts and companies in the active CRM workspace. `list` accepts contact_ids to see every company for contacts, or company_ids to list company members; it receipts every requested id, uses one fail-closed message for empty/foreign/nonexistent ids, deduplicates per contact/company, and returns actionable association_ids plus every typed/source relation. `upsert` atomically creates or updates manual rows identified by contact_id + company_id + relationship_type; source is server-owned and cannot be supplied, so adapter namespaces remain capability-only. display_rank is optional presentation metadata and requires display_rank_source; it is presence-based, so OMITTING display_rank leaves any stored rank untouched and sending display_rank: null is how you clear one. It never chooses the primary. Set make_primary=true only for an explicit primary switch, which atomically updates the stable legacy contacts.company_id pointer. `remove` soft-deletes and receipts every association_id, and refuses to remove the final relation to the current primary until that pointer is explicitly cleared or switched. All calls are workspace-isolated. Requires an active session.

crm_contact_companies

Manage CRM contacts (people) in the active CRM workspace. Actions: create, get, list, update, archive (soft-delete), restore. A contact needs at least one of first_name / last_name / email. `company` controls the stable legacy primary company only; use crm_contact_companies for every membership, typed relation, rank, explicit primary switch, or company-member read. `id` accepts the contact name or UUID. `get` ends with a source line when a source adapter binds the record: `Source: octopad_backend · synced (last seen <time>)`, or `· missing since <date>` when the backend stopped reporting the identity — the record and its segments are untouched (segments stay a human choice). On list, filter company_association_id by company UUID to match any live company membership. Requires an active session.

crm_contacts

Manage the custom fields (the JSONB `custom_fields` schema) for one entity type in the active CRM workspace. Actions: list, add, remove. Every action takes an `entity_type` (contact/company/opportunity) — the catalog is per entity. A field has a `field_key` (a stable lowercase identifier matching ^[a-z][a-z0-9_]*$, e.g. "lead_score", stored under custom_fields and IMMUTABLE — a type change is remove + re-add), a `field_type` (text, number, boolean, date, datetime, select, multi_select, email, url, phone, currency, rating), a `label` (display name), and `is_filterable` (when true the tool builds an index so the field can be filtered/sorted in segments; a multi_select field is filtered by membership with has_tag / has_any_tag). `add` creates a field (a duplicate active key is rejected). `remove` hides a field and drops its index; by default it also purges the key from existing records (set purge_data=false to keep the stored values). Newly added filterable fields become available in the segment builder. Requires an active session.

crm_fields

Manage CRM deals / opportunities in the active CRM workspace. Actions: create, get, list, update, archive (soft-delete), restore. `name` is required to create. `stage` is free text until the workspace configures a pipeline, then it must be one of the configured stage keys. `company` and `point_of_contact` accept a name or UUID (set company_id / point_of_contact_id; "" unlinks). `id` (get/update/archive/restore) accepts the deal name or UUID. Use `filter` on list (e.g. by stage, amount, tag, or a custom field). Requires an active session.

crm_deals

Manage the configurable pipeline stages (the columns of the deal board) for the active CRM workspace. Actions: list, get, create, update, archive (soft-delete), reorder. A stage has a `key` (a short stable identifier like "qualified" that deals reference — set on create, IMMUTABLE after), a `label` (display name), a `display_order`, optional `is_won`/`is_lost` terminal flags, and an optional `color`. To rename a stage, `update` its label (the key never changes, so existing deals keep their stage). `archive` is blocked while deals still sit at that stage — move them first. `reorder` takes the full list of stage keys/UUIDs in the new order. `id` (get/update/archive) accepts a stage key, label, or UUID. A freshly-provisioned CRM workspace is seeded with new/qualified/proposal/negotiation/won/lost. Requires an active session.

crm_pipeline_stages

Manage and run saved CRM segments (saved views / email lists) in the active CRM workspace. A segment is a named, saved filter over one entity type (contact/company/opportunity). Actions: create, get, list, update, archive (soft-delete), restore, run. `run` executes the saved filter and returns the matching rows. `id` accepts the segment name or UUID. Contact segments can filter virtual field company_association_id by company UUID to match any live company membership, not just the legacy primary. The `filter` tree uses the same shape as the entity tools. Requires an active session.

crm_segments

Binary and document storage — PDFs, images, spreadsheets, and other non-markdown files, stored in cloud storage with metadata tracked in the workspace. USE when the user shares a document or artifact to preserve for the team (specs, exported reports, design assets); link files to tasks (file_ids) or knowledge items for discoverability. To upload: do NOT read the file contents — call init_upload with just the filename + mime_type, then follow the instructions it returns (a curl command if you can run a shell, or a frontend link to share with the user otherwise). NOT for structured text content (→ pages), atomic facts (→ knowledge), or searching file contents (→ search with types:["file"]). Requires an active session.

files

Manage company goals — the strategic layer above work streams. Goals define "what" and "why"; work streams handle "how". USE to create goals, update status, and link work streams to goals (primary + secondary contribution). link_stream: only time-bound streams can link to goals — ongoing streams must NOT be linked (they represent permanent areas of work, not goal-bound efforts). NOT for goal progress or contributing tasks → build_context(mode: "goal") returns richer data. **Goal closure (status="achieved"):** pick `closure_method`: "draft_page" requires `post_mortem_content` (body-only markdown, ≥200 chars — DO NOT include YAML frontmatter or an H1 title, the server prepends the standardized header) and optional `post_mortem_page_title` (defaults to "<Goal Title> — Post-Mortem"). The post-mortem page lands automatically in the workspace's system Archive folder alongside archived stream trackers — no folder argument is needed or accepted. "skip" requires `skip_post_mortem_rationale` (≥20 chars) — only when the user explicitly accepts no post-mortem artifact. Before drafting, read each linked stream's Rationale, Definition of Success, Scope, Closing Report, and Activity Log via pages; plus completed tasks' completion comments. The tool runs the full close lifecycle atomically: goal flip + post-mortem page + linked-completed-stream cascade (archive + task archive + audit comments). Fails if any time-bound linked stream is still active, if the goal already has a post-mortem page (re-close fence), or on any mid-transaction error (rolls back everything). **Goal reopen (status="active" from achieved):** requires `reopen_rationale` (≥20 chars). Appends a "### Re-opened" section AND a "### Superseded" marker to the existing post-mortem page (fail-closed), then unlinks the page from the goal (sets `page_id` to NULL). Each close cycle files a fresh post-mortem page; prior post-mortems stay on disk as workspace artifacts. Flips status, cascade-unarchives streams that were auto-archived by this goal's closure (via the archived_by_goal_id FK — not text matching). Optional `reopen_streams="all"` flips those streams further from completed back to active. **Org goals (task ⑦):** create with scope="organization" for a company-wide goal shared across the org (org admins only; default "workspace"); share_to_org / unshare_from_org move an existing goal between this workspace and the org in place (org admins only, intra-org); parent_goal ladders a goal under a parent (optional, same-org guarded — clear with an empty string on update). Closing/reopening an ORG goal works like a workspace goal but is org-admin-gated: the post-mortem is filed as an org-scoped page (no folder) and closure blocks on, then cascade-archives, the org goal's contributing streams across ALL workspaces in the org (reopen un-cascades them). Key params: action (list|get|create|update|delete|restore|link_stream|unlink_stream|share_to_org|unshare_from_org), goal_id, title, scope, parent_goal, closure_method + post_mortem_content/skip_post_mortem_rationale (achieved), reopen_rationale + reopen_streams (reopen), work_stream_id + primary_goal_id + secondary_goal_ids (link_stream). Requires an active session.

goals

Manages Key Information — the four atomic kinds of durable workspace knowledge: Key Fact (neutral truth), Decision (choice + rationale), Question (open item), Risk (threat + severity), selected via the type param. Each item is ONE discrete, durable truth — not a document or a collection. USE create to capture information that should outlive the current session; USE get for full item details with linked files/pages — reading several KNOWN items by title/id → get with entity_ids, never one get per item. Body fields are capped (~600 chars each, enforced) — put longer or structured content in a page and link it via page_ids. NOT for long-form content like specs, plans, or guides (→ pages), file storage (→ files), or broad cross-type retrieval (→ search). Duplicate detection runs on create; override with force_create when genuinely distinct. Key Facts carry a freshness anchor: editing content re-verifies a fact automatically, and re-confirming one still holds without any edit → update it with mark_verified: true to reset its staleness clock (read surfaces flag facts unverified past a per-category age window). Requires an active session.

knowledge

Organize pages into folders with icons and sort order. USE to create, rename, reorder, or delete folders that group related pages. NOT for page content — creating, reading, or editing pages themselves (→ pages). **Folder routing**: Before creating a page, call page_folders(action="list") to see available folders and their descriptions. Use the description to pick the right folder — each description defines what belongs there. When in doubt, match on the folder's core purpose, not keywords. If no folder fits, the page may need a new folder or should remain uncategorized. **System folders**: Each workspace has one system-managed folder — Archive (closed work artifacts: archived stream trackers, goal post-mortems). Organizations also have one system-managed Archive folder (org-goal post-mortems). System folders are flagged `is_system = true`, are read-only, and cannot be renamed or deleted via this tool — they are managed automatically; do not create or target them by hand. Cosmetic edits (icon, ordering, description) are allowed. Trying to create a folder with a name that collides with an existing system folder is rejected with a friendly hint. Key params: action (list/create/update/delete), folder_id (name or UUID — fuzzy-resolved), folder_name (plain text — no emoji), folder_icon (single emoji character), folder_ordering (lower = first). Requires an active session.

page_folders

Long-form markdown documents — specs, plans, reference guides, meeting notes. Unlike knowledge (atomic facts), a page is a living document that evolves over time. USE to create or maintain structured content: project briefs, architecture docs, stream tracker pages, research write-ups. Use "append" to add entries to a page (e.g., activity logs on stream trackers). Use "update" with content_updates for targeted search-and-replace edits. USE "list" (optionally `folder_id`-scoped) as the DIRECTORY for coverage questions — "all pages about X", "what do we have in this folder" — its titles, tags, and AI summaries are enough to build the full set without opening anything; a summary can point at candidates but never proves a phrase or fact is ABSENT from the page's actual content (→ search for that). **Before creating a page**, call `page_folders(action: "list")` to see existing folders, pick the best match, then call `pages(action: "prepare", folder_id: "FolderName")` to load that folder's best practices. `folder_id` is required on create/batch_create whenever the workspace has any folders — uncategorized pages are refused (pass `folder_override: true` only when leaving uncategorized is genuinely intended). NOT for atomic facts or decisions (→ knowledge), file storage (→ files), folder management (→ page_folders), or cross-type search (→ search with types=["page"]). Pinning a page into AI context is a human-only action in the Octopad UI — there is no MCP action for it (this is about human-vs-agent, not which human: org-level pinning is further restricted to org admins, see scope param). **Org-wide pages**: in a multi-workspace organization, a page can live at ORG scope (shared across every workspace in the org) — pass `scope: "organization"` on create for a company-wide page (SOP, policy, shared reference), or use `share_to_org` to move an existing workspace page org-wide (and `unshare_from_org` to bring it back). Org create / share / unshare — and editing or deleting an org page (update/append/delete/restore) — require org-admin rights; any org member can READ an org page. get/update/append/delete by name transparently resolve an org page when no workspace page shares the title; `list` also surfaces this organization's org-wide pages in a separate "Organization-wide Pages" sub-block (and any org page is still reachable by exact title or UUID). Reading several KNOWN pages by title/id → get with page_ids, never one get per page. Key params: action (create/update/append/get/list/delete/restore/batch_create/prepare/share_to_org/unshare_from_org), scope (create: workspace|organization), page_id (title or UUID — for get/update/delete/share_to_org/unshare_from_org), folder_id (organize into folders, or target folder for prepare). Requires an active session.

pages

Manage the organization-wide tag vocabulary — the shared labels applied across tasks, pages, key information, and files. USE list to browse the vocabulary (most-used first, optional query filter) before creating, so you REUSE an existing tag instead of spawning a near-duplicate. Minting a genuinely new label requires a one-line `justification` — if you cannot name a second item that could carry the tag, reuse instead. USE get for one tag's details. USE create to mint a tag (idempotent — returns the existing tag if the label already exists). USE update to rename or describe, merge to fold one tag into another, alias to add synonyms, unalias to remove a synonym a merge/rename/alias left behind (an alias silently redirects every future mint of that label, so a wrong one needs a way out), delete to soft-remove, restore to bring one back. Tags are shared across the whole organization, so update/merge/alias/unalias/delete/restore require org admin or owner. To APPLY a tag to a task/page/knowledge item/file, pass the `tags` array on that entity's own tool — not here. Key params: action, tag (name or UUID), label, query, winner/loser (merge), aliases. Requires an active session.

manage_tags

Add, list, or redact comments on a task. USE to log progress, decisions, or handoff context mid-task — these are the audit trail a future session reads. The same note for several tasks → ONE add_comment with task_ids (max 10), never one call per task; a different note per task stays one call each. Keep comments under 1500 characters — session plans, research, and detailed reports belong in the task description or a linked page, not here. NOT for one-off notes alongside a status change — use the comment param on tasks(action: "update") instead. Use #entity-name and @username in content for clickable cross-references and notifications. Key params: action (add_comment/list_comments/redact_comment), task_id (title or UUID) or task_ids (several tasks, one shared body), content (add_comment: min 10 chars, write as a handoff note). Requires an active session. Notes, findings and hand-offs on a CRM contact, company or deal go to crm_record, not here.

task_comments

Workspace and team task management — get, create, update, delete, restore, list. Pick the action: reviewing 2+ tasks → list once, never get them one by one; full detail of a single task → get; reading several KNOWN tasks by title/id → get with task_ids, never one get per item; editing one task → update, heterogeneous edits per row → batch_update with updates, the same edit across several → bulk_tasks not one update each; creating several → batch_tasks. USE create to start work, update for status changes, list to browse the backlog. USE get for full details of a single task (description, dependencies, subtasks, linked files/pages); for surrounding context — comments, related knowledge, activity — use build_context(mode: "task"). Need every subtask's full spec too, not just titles/status → build_context(mode: "task", subtask_detail: "full") in one call — never loop get once per subtask. Approval loop: a requires_approval task marked done by a non-creator enters pending review, cleared with action confirm_completion or reject_completion. The action param also covers dependency edges. NOT for batch creation (→ batch_tasks), bulk field overrides across many tasks (→ bulk_tasks), standalone comments (→ task_comments), unscoped assigned-work retrieval (→ aggregate_tasks with assigned_to:"me") or named task/stream context (→ build_context). NOT for personal reminders, calendar alerts, or shopping/grocery lists — those are out of scope for Octopad. Requires an active session.

tasks

Manage work streams — parallel initiatives (e.g. "Frontend", "Infrastructure") that group tasks under company goals. USE get for structural metadata (goals, task counts, dependencies, config) — for activity, tracker content, and progress use build_context(mode: "work_stream"). USE list to browse all streams. USE create/update/delete for structural changes. Categorize a stream with `tags` (org-wide labels shared across every entity — browse the vocabulary with the `manage_tags` tool first to reuse an existing label). Time-bound streams (cadence wire value: "finite") require rationale, definition_of_success, and goal linking at creation. New trackers land in the workspace's system Trackers folder; on archive of a time-bound stream the tracker moves to the system Archive folder (alongside goal post-mortems) and on unarchive it returns to Trackers. If the tracker was deleted while archived, re-opening the stream lazy-recreates a fresh skeleton tracker. Key params: action, work_stream_id (name or UUID — for get/update/delete/restore), name, cadence (ongoing|finite), tags. Requires an active session. Free organizations have a page cap (trackers count); a cap error must be relayed to the user verbatim, never retried, and the content never saved elsewhere.

work_streams

Search the active CRM workspace for contacts, companies, or deals — the dedicated CRM search lane (separate from the global `search` tool, which does NOT index CRM data). Hybrid ranked: keyword (full-text + substring + typo-tolerant fuzzy over names, titles, descriptions, and the distilled contact card narrative; contact searches also match the linked company name) PLUS, for contacts, semantic similarity over the card embedding. Narrow with `filter` and/or a saved `segment` by name. Contact filters support virtual field company_association_id with company UUIDs to match any live membership, not just the legacy primary. Pass a `query`, a `filter`, and/or a `segment`. Requires an active session.

crm_search

Cross-type retrieval — find anything in the workspace by meaning or exact phrase. Combines keyword (ILIKE), semantic (embedding), and section (page-heading) search into one relevance-ranked result set. USE to discover information without knowing which content type holds it, or for broad questions ("what do we know about X?"). Narrow with methods[] (keyword/semantic/sections) and types[] (decision, key_fact, question, risk, page, file, task, chunk, task_comment, section) — see those params, including the section/sections coupling. NOT for creating or editing content (→ knowledge, pages, files) or loading structured entity context (→ build_context). For 2+ independent queries, use batch_search (parallel). Archived tasks/comments are excluded unless include_archived:true. Each hit lists the org tags on it (a chunk/section/comment lists its parent page/file/task's), so you can see what a tag-filtered set was narrowed by — for the full vocabulary use manage_tags(action:"list"). THIS IS ALSO THE TAG-FILTERED ENTRY POINT for pages, knowledge and files, whose own tools can only APPLY tags: pass `tags` with NO `query` to browse everything carrying one (work streams and goals are not search result types — read their tag lines from work_streams/goals list instead). A tag-only call uses the keyword method, returns at most 10 per content type ordered by type then id (not recency), and is capped by `limit` (default 10, max 50) — treat it as "show me what is tagged X", not an exhaustive listing. A ranked result set is proof of relevant matches, never proof that nothing else qualifies — before concluding "no other page has X", weigh the result count and confidence against what the corpus should hold (e.g. via `pages`/`page_folders`), not just the top scores shown. Requires an active session.

search

Multi-query parallel search — run 2–10 independent searches in one call. USE when you need to check multiple topics before acting: refreshing a page across domains, verifying decisions before a plan, finding pages to link to a new task. Pass an array of query objects, each with `query`, optional `label`, `types`, and `methods`. Returns results grouped by query label, each hit listing the org tags on it. By default archived tasks/comments are excluded — pass include_archived:true to include them. `query` may be omitted on an entry ONLY when the batch sets `tags`/`exclude_tags` — that entry then browses by tag alone (keyword method, ≤10 per content type, not an exhaustive listing). NOT for single lookups (→ `search`). Requires an active session.

batch_search

Capture user sentiment about the product — complaints and praise logged against the workspace. USE immediately when the user expresses positive or negative sentiment mid-session. NOT for task blockers or session notes → use task_comments instead. ⚠️ PRIVACY RULE (hard stop): content must describe Octopad UX/behavior only. NEVER include the user's name, task titles, project names, session data, UUIDs, email addresses, or anything that belongs to the user. Describe the product behavior, not the specific user instance. Server-side validation will reject UUIDs and email patterns. ✅ DO: "Task save action sometimes fails silently — user noticed after submit" ❌ DON'T: "David complained that his task 'Fix login flow' won't save" (leaks name + task title) Redact action: call ONLY when the user explicitly asks to redact a specific feedback entry — never on your own initiative. Key params: action (create|list|redact), sentiment (complaint|praise, required for create), content (create: max 500 chars), category (free-text tag e.g. "ux", "onboarding"), feedback_id (redact: UUID of the entry to mask). Requires an active session.

feedback

REQUIRED FIRST CALL — authenticates the user, creates a session, and returns workspace orientation context (methodology, strategy, team, recent sessions). Call before any other workspace tool. Returns orientation only — use build_context after for entity-specific context (tasks, streams, goals). Read the methodology first, then make an informed build_context call. NOT for: entity-specific context → use build_context. Unscoped assigned work / priorities → use aggregate_tasks(assigned_to:"me", view:"list") and keep the result descriptive, not prescriptive. Knowledge search → use search. Already in a session → use build_context instead. Key params: workspace_name (fuzzy-matched), agent_type.

start_session

Summarize OR list tasks across the workspaces of ONE organization in a single call — no session required. USE for "what is on my plate" (assigned_to:"me") in an org, an overview across that org's workspaces, OR a cross-workspace activity summary for one person ("what did David do this week" → assigned_to + updated_after). Scopes to a SINGLE organization: pass organization_id, or a workspace_id (which pins one org); if you belong to several orgs and give neither, the tool asks you to pick one — it never spans every org at once. An org-scoped agent key is bound to its own org automatically. Summary-first by default: returns a roll-up (total + per-status counts + overdue, grouped org → workspace) so it stays compact on large accounts. Pass view:"list" (or a limit/offset) to instead NAME the actual tasks — at most 50 bounded, paginated rows per call, sorted earliest-due-first, each tagged with its workspace and work stream. Note the deliberate divergence: the summary counts ALL statuses by default, while the list defaults to OPEN tasks only (todo/in_progress/blocked) unless you pass status_filter. Narrow further with workspace_id (one workspace); filter by assigned_to or created_by (a person, or "me"), status (one or several), priority, due-date bucket, and created/updated date range. DOES NOT filter by tag, deliberately — there is no cross-workspace tag filter anywhere. For "every task tagged X", call tasks(action:"list", filter_tags:["X"]) once per workspace and merge; within a single workspace that is the complete answer. Read-only.

aggregate_tasks

Check the health of this workspace's Key Information — a lint pass that surfaces stale facts (unverified past their freshness window) and bloated facts (grown into a multi-sentence paragraph that should be split or moved to a page). USE run (default) for periodic hygiene, or before trusting an old fact, to sweep for new issues and see the open queue. USE list_findings to read the queue without re-running the sweep. Propose-only: findings are never auto-fixed. Remediation loop: fix the underlying fact first — knowledge `update` with `mark_verified: true`, or archive it — THEN call resolve_finding with resolution: "resolved" to clear it, or resolution: "dismissed" to stop flagging this specific item going forward. Key params: action, status (list_findings), finding_id + resolution (resolve_finding). Requires an active session.

workspace_health