aggregate_tasks
ChatGPTSummarize 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.
batch_search
ChatGPTMulti-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 (required), optional label, types, and methods. Returns results grouped by query label. By default archived tasks/comments are excluded — pass include_archived:true to include them. NOT for single lookups (→ search). Requires an active session.
batch_tasks
ChatGPTCreate multiple tasks in one call with optional parent-child wiring via parent_ref "@N". USE when a planning session produces 3+ related tasks — avoids round-trips and preserves hierarchy in one atomic operation. NOT for single task creation (use tasks), bulk field overrides (use bulk_tasks), or commenting (use task_comments). NOT for personal reminders, calendar alerts, or shopping/grocery lists — those are out of scope for Octopad. Key params: tasks[] array — each item supports title, description, work_stream_id, priority, parent_ref or parent_task_id. LIMITS: max 20 tasks per call, max 30,000 chars total across all titles + descriptions. If the payload is too large, split into smaller batches — do not shorten descriptions. If a batch times out, DO NOT retry blindly — check if tasks were created first, as the server may have processed the request despite the timeout. DEPENDENCIES: When creating 2+ tasks, every task MUST include depends_on_refs — use [] for independent tasks, ["@N"] for a dependency on task at index N in this batch, or the name or UUID of an existing task to depend on it. This wires task_dependencies rows automatically. Requires an active session.
build_context
ChatGPTFetch deeper workspace context mid-session — call after start_session when you need richer data for a specific entity or are switching focus. USE by mode: - "task" → full task data: status, deps, subtasks, linked pages, related knowledge, stream tracker. Call before starting any WORK task. Accepts task_name (fuzzy-matched). Also accepts work_stream_name as an entry point — auto-resolves to the next task in that stream for you. If the resolved task has pending subtasks, auto-drills to the next actionable subtask. Resolution priority: task_name > work_stream_name. - "work_stream" → tracker content, activity log, tasks by status, stream knowledge. USE for stream status checks and project updates. Stream-selection rule, most-specific-first: when the user names 2+ streams, ALWAYS use work_stream_names: ["A","B","C"] (one targeted call). When they name one, use work_stream_name. Only omit BOTH when the user explicitly asks for a workspace-wide view of EVERY active stream — that path returns all streams unfiltered, is the most expensive shape, and should be reserved for genuine "what is everything in flight" questions; do NOT default to it when the user named specific streams. NEVER call this tool in parallel with different work_stream_name values to survey multiple streams. If the user implied resuming or continuing work on a stream, re-call with mode="task" + work_stream_name instead — this mode does not select the next task. - "goal" → goal details, contributing streams, task progress. USE for goal-progress reviews. Accepts goal_name. NOT for: to-do list / priorities → use todo_list(action:"generate"). Knowledge search → use search. Workspace orientation → use start_session. Key params: workspace_id, mode (task|work_stream|goal), task_name (mode=task), work_stream_name / work_stream_names (mode=task or work_stream), goal_name (mode=goal). Requires an active session (call start_session first).
bulk_tasks
ChatGPTApply the same field override to multiple tasks at once — status, assignee, work stream, priority, or archive flag. USE when closing a sprint, reassigning a block of work, or archiving completed tasks in bulk. NOT for creating tasks (use batch_tasks), per-task changes (use tasks), or comments (use task_comments). Key params: action (update/archive, default: update), task_ids (array of titles or UUIDs), then any shared field — status, assigned_to, work_stream_id, is_archived + archive_rationale. For archive: archive_rationale is required. MOVING A SUBTREE TO ANOTHER WORK STREAM: a subtask always lives in its parent's work stream, so move the PARENT task(s) and the subtasks follow automatically — do NOT list subtasks to move them. A subtask whose parent is not in the move is left where it is and reported back (it is not counted as moved). Requires an active session.
crm_companies
ChatGPTManage 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_contact_companies
ChatGPTRead 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_contacts
ChatGPTManage 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_deals
ChatGPTManage 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_fields
ChatGPTManage 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_interventions
ChatGPTGive the connected AI the bounded context needed to choose a useful intervention on a CRM contact, and record what happened, without sending anything. Works for ANY source adapter this workspace has registered, not only Octopad's own backend: source names the adapter and may be omitted when the workspace has exactly one, in which case an ambiguous workspace is refused rather than guessed. get_context reads 1–100 CRM contact UUIDs and returns contact identity, every company ordered by member count, facts projected from that adapter's own declared field ownership, known contactability, positively allowlisted product-signal facts, the intervention phases already recorded, bounded Card/Brief context, Entries, freshness and next action. The complete receipt has a 1 MiB budget; split an oversized batch. Generic Entry prose and arbitrary signal payload fields are never projected. record atomically writes one phase to the CRM intervention store, one CRM signal and one bounded Entry under a shared idempotency key; the store's unique key decides duplicates, so an exact replay is a no-op and returns the first receipt, while divergent content under the same key fails. For the Octopad backend adapter the write is also mirrored to the product nudge ledger, exactly once and never on a replay, and that ledger's opt-out verdict is honoured before anything is written. It accepts contact_id only: the adapter, the bound source identity and the recorder are all derived server-side, and an adapter belonging to another workspace can never be reached. This tool never sends an email and never accepts a sender identity or message body/subject. reconcile_history is a zero-mutation dry run over explicit provider_message_id+intervention id+contact_id records; it classifies matched/unattributed/ambiguous and never matches on email or subject. Requires an active CRM session.
crm_pipeline_stages
ChatGPTManage 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_search
ChatGPTSearch 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). Use when looking for contacts, companies or deals by name, words or meaning. Not for tasks, pages or knowledge (→ search). 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_segments
ChatGPTManage 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_signals
ChatGPTAppend a batch of behavioral signals to the CRM signal firehose in the active CRM workspace — the agent batch-WRITE hot path. Use when recording what contacts did (opened, replied, booked a meeting), many at once. Not for a note or hand-off on a record (→ crm_record). Pass signals: an array where each entry has a required signal_type (e.g. "email_open", "linkedin_reply", "meeting_booked") and optionally contact_id / company_id (name or UUID, resolved within this workspace), source, occurred_at (ISO 8601, defaults to now; must be within the last 12 months and not in the future), and a payload JSON object. Append-only firehose: each signal is stored as an immutable raw event; the batch is then folded into each referenced contact's distilled card non-destructively — the card's signal count is incremented and a rollup updated, and any existing human summary/attributes are preserved (never overwritten or deleted). Read cards back via build_context contact mode. The whole batch is rejected if any signal references a contact/company that is not in this workspace, or has an out-of-window occurred_at. Use ONE call to write many signals (campaign scale) rather than one call per signal. Requires an active session.
crm_status
ChatGPTCheck that the CRM is active for this workspace. Use when unsure whether this workspace has the CRM. Not for workspace orientation (→ start_session). Returns ok when the active workspace has the CRM enabled and you are a member of it (the CRM tools operate only on workspaces where the CRM module is on and you are a member; in any other workspace they refuse). Requires an active session (call start_session first).
end_session
ChatGPTEnd the current session and persist a summary for future context — auto-generates from activity log if none provided, but an explicit summary is richer. USE: at the end of every session. Pass a brief plain-text recap of what was accomplished so future sessions can pick up without losing context. NOT required to keep the session alive — sessions auto-expire — but calling explicitly stores a better summary and triggers the session scribe. Key params: workspace_id (omit to auto-close the most recent active session), summary (plain-text recap of session work), session_id (omit to auto-close the most recent active session).
feedback
ChatGPTCapture 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.
files
ChatGPTBinary 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.
followup
ChatGPTFollow a task, a work stream, a page or a set of tags for yourself, with what matters to you, or stop. subscribe: exactly one of task_id, work_stream_id, page_id or tags (with tag_mode all or any, and tag_scope organization to follow them in every workspace), plus interest in your own words. Following the same target again with another interest or tag_mode starts a new revision, checked against the situation as it is now: earlier changes are not replayed. unsubscribe: the same target, or subscription_id. You follow as yourself only, and a follow reaches you only while you can open its target. Assignments, reviews and requests addressed to you need no follow. context: read your changes and the current report; with work_stream_id, that stream's changes and report. contribute: for a work stream, rewrite its whole report from that version, naming it as base, or stamp it still valid with text null; explain other subjects in common. Interests are optional; declare every free comment in questions ([] when it asks nothing). read: the explained situation of a task, work stream or page now; without one, your requests, follows and recent reports for streams and explanations elsewhere. Earlier report revisions: history_offset with work_stream_id. Requires an active session.
github
ChatGPTBridge Octopad tasks to GitHub issues — create issues, check status, post comments, list linked tasks, or unlink. USE when the user wants to track a task externally in GitHub. Requires workspace github_repo and github_token configured by an admin. NOT for general task management → use tasks. Key params: action (send_to_github|get_status|post_comment|list_linked|unlink), workspace_id, task_id (required except list_linked), comment (post_comment only). Requires an active session.
goals
ChatGPTManage 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.
knowledge
ChatGPTManages 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. 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. Requires an active session.
list_members
ChatGPTList 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_organizations
ChatGPTList all organizations the current user belongs to — with member counts and role. USE to discover org IDs or verify membership before workspace operations. No session required.
list_sessions
ChatGPTList 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_workspaces
ChatGPTList 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).
logout
ChatGPTSign 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.
manage_tags
ChatGPTManage 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.
notepad_purge
ChatGPTPermanently deletes your own Private Notepad history snapshots below before_revision, or all of them without it. Cannot be undone; the document itself stays. Call it only when the user asks to erase old private text, and after they confirm. Read-only keys cannot purge.
notifications
ChatGPTThe user's unread notifications in this organization: work they own, created or wait on that moved, comments, mentions and requests. Once you have acted on them or told the user, mark_handled moves them to History everywhere, the bell included: pass ids, or all: true. Handling one never changes its task.
page_folders
ChatGPTOrganize 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.
pages
ChatGPTLong-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. 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 user-only action in the Octopad UI — there is no MCP action for it. 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). 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.
search
ChatGPTCross-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. Requires an active session.
skill_opened
ChatGPTRecord that you opened an Octopad plugin skill. Call it once per skill, with the skill's folder name.
start_session
ChatGPTREQUIRED 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. To-do list / priorities → use todo_list(action:"generate"). Knowledge search → use search. Already in a session → use build_context instead. Key params: workspace_name (fuzzy-matched), agent_type.
task_statuses
ChatGPTDefine the workspace's task sub-statuses; assign one to a task through tasks (sub_status). Each sits under one master status, with a label in English, French and Spanish and a definition of when to use it; at most 5 active per master. list (default) shows them by master, retired ones included. create, update, retire and merge are for workspace admins. A sub-status never restates a task field (date, assignee, priority, tags) and never tracks a record's pipeline: CRM deal stages are crm_pipeline_stages. Requires an active session.
tasks
ChatGPTIndividual task operations — get, create, update, delete, restore, list. 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"). The action param also covers approval-gated completions and dependency edges. NOT for batch creation (→ batch_tasks), bulk field overrides across many tasks (→ bulk_tasks), standalone comments (→ task_comments), or work prioritization / daily to-do lists (→ todo_list). NOT for personal reminders, calendar alerts, or shopping/grocery lists — out of scope for Octopad. Requires an active session.
todo_list
ChatGPTYour personal daily to-do list — the rolling, per-user queue of what YOU are working on today or this week (items due this week or sooner). USE when the user asks about their list or today's priorities with NO named entity (e.g. "what should I work on", "show my to-do list", "reorder my list"). If the user names a task, stream, or goal — or says resume/continue/pick up X — use build_context instead. Actions (see the action param for behavior): next, get, generate, add, reorder, remove, defer. NOT for multi-week or multi-phase planning → use the task tree (tasks + task_dependencies), never this tool. NOT for task status updates → tasks. NOT for stream health → build_context(mode: "work_stream"). NOT for personal reminders, calendar alerts, or shopping/grocery lists — out of scope for Octopad. Requires an active session.
work_streams
ChatGPTManage 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. Call list_types before creating — reuse existing org types. 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). Requires an active session.
workspace_health
ChatGPTCheck 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.
