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_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.
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).
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.
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.
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).
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.
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.
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.
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.
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.
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.
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_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_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_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).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
