Reference for the 17 MCP tools that manage boards, members, activity, mentions, and guidelines. Of the 198 Pulse MCP tools, these are the first your agent should call at the start of every session.
These 17 MCP tools cover everything an agent needs to find its board, identify itself, see who else is on the board, catch up on activity since last session, and read the guidelines that govern its work. They are the session-start surface of Pulse — agents typically call okto_pulse_list_my_boards and okto_pulse_get_board_guidelines before doing any other work.
Board CRUD is REST-only. There is no MCP tool to create, update, or delete a board, and there are no MCP tools to manage board share links. Those operations live on the REST API at POST /api/v1/boards, PATCH /api/v1/boards/{id}, DELETE /api/v1/boards/{id}, and POST /api/v1/boards/{id}/shares (inventory:559–571). Agents work within boards; humans set them up.
For the protocol, transport, and authentication shared by all 198 tools, see MCP reference. For storage paths backing every call here, see Storage paths.
Every Pulse MCP tool returns a JSON-encoded str (inventory:235). Errors come back as a JSON object with at least an error field; success bodies are tool-specific.
ok → {"key": ..., "items": [...]}auth → {"error": "Authentication failed"}perm → {"error": "Permission denied: <flag>"}notfound→ {"error": "Board not found"} | {"error": "Agent not found"}
The auth/perm errors above come from _auth_error() / _perm_error() in server.py. Permission flags are listed in 80-pulse-feature-inventory.md:798–877.Multi-value parameters (lists) accept three input shapes per helpers.coerce_to_list_str — native list, JSON array, or pipe-separated string. Comma-only strings are rejected.
These two tools operate on the authenticated agent itself, not on any board. The API key in the MCP connection identifies the agent — no board_id parameter is required.
Common errors:Authentication failed if the API key is missing or revoked.When to use: at session start, to confirm your identity and the permission flags you carry. Agents that ignore their own permissions issue tool calls that the server then rejects — wasted round-trips.
role_summary is computed by generate_role_summary in core/infra/permissions.py:1175. The format is Role: <preset> | Owns: <a, b> | Cannot: <x> | KG: <caps>, with empty sections omitted. Legacy agents (permissions=null) get Role: Full Control (legacy) | Owns: unrestricted (permissions=null grants all).
Source: server.py:753 (inventory:246)Update your own description and/or objective. Both arguments are optional; an empty string leaves the field unchanged.
Common errors:Authentication failed; Permission denied: self:update.Permission required:self:update.When to use: rare; objectives are usually set by the human operator at agent provisioning time. An agent might update its description after a meaningful skill change (“Now also writes Cypher for the KG”).
Source: server.py:804 (inventory:247)List every board this agent has access to. No parameters — the agent identity in the MCP connection scopes the result.
Common errors:Authentication failed.When to use: the first call of any session. Most other board-scoped tools require a board_id; this is how you discover yours. Pair with okto_pulse_get_unseen_summary for a quick status read on each board.
Source: server.py:1295 (inventory:251)Get full board detail: metadata, ideations, specs, cards, and agents. This is a heavy bundle — use the lighter list_my_boards when you only need IDs and names.
Common errors:Authentication failed; Permission denied: board:read; Board not found.Permission required:board:read.When to use: when you need a single round-trip overview of everything on a board. For per-domain detail prefer the focused tools — list_specs, list_cards_by_status, list_agents — which return only what they own.
This tool returns all cards in the board’s response. On large boards (hundreds of cards) the payload is sizeable. Use okto_pulse_list_cards_by_status with filters when you only need a subset.
Source: server.py:1390 (inventory:252)List every agent registered on a board with full per-agent metadata, including the human-readable role_summary derived from each agent’s permissions.
Common errors:Authentication failed; Permission denied: board:read.Permission required:board:read.When to use: before mentioning another agent in a comment (use the name field as @<name>), or when picking a reviewer for submit_task_validation — the validator must be an independent agent, distinct from the implementer. See Card validation.
Source: server.py:1436 (inventory:253)List all members — owner (a human user) plus every agent — in a single call. Use this when you need to distinguish the human owner from agents.
Common errors:Authentication failed; Permission denied: board:read; Board not found.Permission required:board:read.When to use: when you need to attribute work or ping the human owner explicitly (the owner is not an agent and cannot be @-mentioned in comments — owner contact is out-of-band). For agent-only listings, prefer list_agents.
Source: server.py:1147 (inventory:250)Lightweight counts of unseen mentions and recent activity. Cheaper than list_my_mentions — call this every session start to decide whether you need the full mention list.
The recent_activity_24h count is the number of ActivityLog rows in the last 24 hours, regardless of who performed them. unseen_mentions is total_mentions - seen_count, floored at 0.Common errors:Authentication failed.When to use: every session start, before doing anything else. If unseen_mentions == 0, skip list_my_mentions.
Source: server.py:839 (inventory:248)Return every comment or Q&A item on the board where this agent is mentioned via @<agent_name>. Searches across cards, specs, ideations, and refinements. By default returns only unseen mentions.
Common errors:Authentication failed.When to use: when get_unseen_summary reports unseen_mentions > 0. Call once, process each mention, then batch-call mark_as_seen with the collected item_id values to avoid re-processing.
Source: server.py:1031 (inventory:249)Mark one or more mention items as seen so they stop appearing in list_my_mentions and stop counting toward unseen_mentions.
The item_id values from list_my_mentions. Native list preferred (["comment_01H...", "qa_01H..."]); JSON-array string and pipe-separated string also accepted. Comma-only strings are rejected — see helpers.coerce_to_list_str
Returns:
{ "success": true, "marked": 2 }
Common errors:Authentication failed; rejection of comma-only item_ids strings.When to use: immediately after processing the result of list_my_mentions. If you skip this step, every subsequent session will re-surface the same mentions.
Common errors:Authentication failed; Permission denied: board:read.Permission required:board:read.When to use: for forensic “what happened to this card” lookups (card_id=...) or to reconstruct the recent timeline (limit=100). Don’t use it for unread-mention tracking — list_my_mentions is targeted, this is a firehose.
Source: server.py:9712 (inventory:438)Return every guideline visible on this board — linked global guidelines and inline ones — merged and sorted by priority (highest first).
Common errors:Authentication failed; Permission denied: board:read.Permission required:board:read.When to use:the second call of every session, right after list_my_boards. The guidelines tell you the rules of the road: phrasing constraints, validation gates, citation requirements. The docstring on the tool itself says: “This is the PRIMARY tool for reading board guidelines — call it BEFORE doing any work on a board.”
Source: server.py:9742 (inventory:439)Browse the global guideline catalog owned by this board’s owner — guidelines that can be linked but are not necessarily linked yet.
Common errors:Authentication failed; Permission denied: board:read; Board not found.Permission required:board:read.When to use: to discover global guidelines before linking them. For “what governs work on this board right now”, use get_board_guidelines instead.
Source: server.py:9801 (inventory:440)Create a new guideline. scope="global" puts it in the catalog (linkable to any board); scope="inline" makes it board-specific.
Common errors:Authentication failed; Permission denied: board:read.Permission required:board:read.When to use: to formalize a recurring instruction. If you find yourself repeating the same correction in card comments, capture it as a global guideline and link it to the board.
Common errors:Authentication failed; Permission denied: board:read; guideline not found.Permission required:board:read.When to use: to revise a long-running guideline. Note that updates are not versioned — keep an external log if you need a change history.
Common errors:Authentication failed; Permission denied: board:read; guideline not found.Permission required:board:read.When to use: when a guideline is genuinely retired. Prefer unlink_guideline_from_board if the guideline is still useful on some boards.
Deletion cascades to all board links. There is no undo.
Common errors:Authentication failed; Permission denied: board:read; guideline already linked.Permission required:board:read.When to use: to apply a global rule to this specific board. Set higher priorities for non-negotiables (validation gates, security constraints) so they sort first in get_board_guidelines.
Common errors:Authentication failed; Permission denied: board:read; link not found.Permission required:board:read.When to use: when a guideline no longer applies to a particular board (e.g. a board moves from internal-tools to public-product and the “no public-API breaking changes” rule kicks in elsewhere).
This is the canonical opener every Pulse-connected agent should run.
# 1. Identify yourselfprofile = json.loads(await okto_pulse_get_my_profile())# 2. Find your boardsresult = json.loads(await okto_pulse_list_my_boards())board_id = result["boards"][0]["id"]# 3. Read the rulesguidelines = json.loads(await okto_pulse_get_board_guidelines(board_id))for g in guidelines["guidelines"]: print(f"[{g['priority']}] {g['title']}")# 4. Catch up on what changedsummary = json.loads(await okto_pulse_get_unseen_summary(board_id))if summary["unseen_mentions"]: mentions = json.loads(await okto_pulse_list_my_mentions(board_id)) item_ids = [m["item_id"] for m in mentions["mentions"]] # ... process each mention ... await okto_pulse_mark_as_seen(board_id, item_ids)# 5. Now you're ready to do work
The full SDLC pipeline — ideations → refinements → specs → cards → validations — picks up from there. See SDLC flow for the end-to-end loop, MCP setup to connect your agent in the first place, and the rest of the MCP reference for tools beyond board management.
