Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.oktolabs.ai/llms.txt

Use this file to discover all available pages before exploring further.

Comments & questions

Pulse exposes 29 of its 198 MCP tools for back-and-forth communication on pipeline entities:
  • Q&A on every entity type — open and choice questions, with answer-or-select responses. 22 tools spanning ideation, refinement, spec, card, and sprint.
  • Free-form comments on cards — text comments and choice “polls”. 7 tools.
Source-of-truth citations: okto-pulse-feature-inventory.md:272–289 (card Q&A + comments + attachments), :290–314 (ideation), :315–332 (refinement), :353–370 (spec Q&A), :457–475 (sprint Q&A), :476–484 (delete-Q&A across stages).

Two patterns, one shape

Q&AComments
Lives onentity.qa_items (JSONB on parent)Dedicated comments table linked by card_id
Attached toIdeation, refinement, spec, card, sprintCard only
Question typesOpen (free-text answer) and choice (single- or multi-select, optional free-text)Text comments and choice “polls” (single/multi-select)
Lifecycleask → answer → optional deleteadd → optional update / respond → delete
PermissionsPermissions.QA_CREATE, _ANSWER, _DELETEPermissions.COMMENTS_CREATE, _UPDATE, _DELETE
Use Q&A when you need a structured, reviewable trail of decisions (“did the agent confirm X before advancing?”). Use comments for ad-hoc collaboration on a specific card. The ambiguity-killer protocol (an ideation-stage best practice) leans heavily on okto_pulse_ask_ideation_choice_question: asking the user to pick between options is faster and less ambiguous than asking an open question.

Q&A reference (22 tools)

The shape is identical across entity types — only the noun changes. Per parent: ask_*_question (open), ask_*_choice_question (structured), answer_*_question, list_*_qa, delete_*_question.

Ideation (server.py:4282–4538)

ToolLinePurpose
okto_pulse_ask_ideation_question4282Ask an open-ended question.
okto_pulse_ask_ideation_choice_question4331Ask a structured question with options (the ambiguity-killer entry point).
okto_pulse_answer_ideation_question4418Answer a Q&A item — pass answer for open, selected for choice.
okto_pulse_list_ideation_qa4485List Q&A items on an ideation.
okto_pulse_delete_ideation_question12011Delete a Q&A item.

Refinement (server.py:5204–5460)

ToolLinePurpose
okto_pulse_ask_refinement_question5204Ask an open question.
okto_pulse_ask_refinement_choice_question5253Ask a structured choice question.
okto_pulse_answer_refinement_question5340Answer.
okto_pulse_list_refinement_qa5407List Q&A.
okto_pulse_delete_refinement_question12050Delete.

Spec (server.py:10413–10974)

ToolLinePurpose
okto_pulse_ask_spec_question10413Ask an open question.
okto_pulse_ask_spec_choice_question10464Ask a structured choice question.
okto_pulse_answer_spec_question10552Answer.
okto_pulse_list_spec_qa10619List Q&A.
okto_pulse_delete_spec_question11973Delete.

Card (server.py:2638–2777)

ToolLinePurpose
okto_pulse_ask_question2639Ask an open question on a card.
okto_pulse_answer_question2689Answer a card Q&A.
okto_pulse_delete_question2742Delete a card Q&A.
Cards do not have a ask_choice_question tool — choice flows on cards use the comment system below (okto_pulse_add_choice_comment), which lives in the same file area and is richer (multi-responder support, response history).

Sprint (server.py:11903–11972)

ToolLinePurpose
okto_pulse_ask_sprint_question11903Ask an open question on a sprint.
okto_pulse_answer_sprint_question11937Answer a sprint Q&A.
okto_pulse_delete_sprint_question12089Delete a sprint Q&A.

Cross-stage carry-over

ToolLinePurpose
okto_pulse_copy_qa_to_card7838Copy answered Q&A items from a spec into a card as a single consolidated comment. Unanswered Q&As are skipped.
This is the bridge that makes spec-level decisions visible to an implementer working a card without forcing them to chase pointers back to the spec.
Input to okto_pulse_copy_qa_to_card:
  board_id: "brd_abc123"
  spec_id:  "spec_XYZ"
  card_id:  "card_001"

Output:
{
  "success": true,
  "copied":  4
}
The card receives a new comment whose body is a Markdown summary:
## Spec Q&A Context

**Q:** Should retries be exponential or fixed?
**A:** Exponential with jitter — 3, 6, 12 seconds.

**Q:** Cap retries per webhook event?
**A:** Yes, 5 attempts then dead-letter.
...

Open vs. choice questions

Open

Open questions are free-text in, free-text out. They’re the right pick when the answer space isn’t enumerable.
Input to okto_pulse_ask_spec_question:
  board_id: "brd_abc123"
  spec_id:  "spec_XYZ"
  question: "What's the maximum acceptable end-to-end latency for the checkout submission?"

Output:
{
  "success": true,
  "qa": {
    "id":       "qa_a1b2c3",
    "question": "What's the maximum acceptable end-to-end latency for the checkout submission?",
    "asked_by": "agent_pm"
  }
}

Choice — the ambiguity-killer

Choice questions force a pick from a set. They are the preferred shape when the answer is closed-form (yes/no, A/B/C, library X vs Y) — the agent gets a structured response instead of paraphrased prose.
Input to okto_pulse_ask_ideation_choice_question:
  board_id:        "brd_abc123"
  ideation_id:     "id_M1"
  question:        "Which diagram tool should we standardize on?"
  options:         ["Mermaid (text-based, lightweight)", "Excalidraw (rich, manual)", "draw.io (export-only)"]
  question_type:   "choice"
  allow_free_text: "false"

Output:
{
  "success": true,
  "qa": {
    "id":              "qa_d4e5f6",
    "question":        "Which diagram tool should we standardize on?",
    "question_type":   "choice",
    "choices": [
      { "id": "opt_0", "label": "Mermaid (text-based, lightweight)" },
      { "id": "opt_1", "label": "Excalidraw (rich, manual)" },
      { "id": "opt_2", "label": "draw.io (export-only)" }
    ],
    "allow_free_text": false,
    "asked_by":        "agent_lead"
  }
}

Multi-value options parsing

Both ask_*_choice_question and add_choice_comment accept options in three formats. The same selected rules apply when answering / responding.
FormatExampleWhen
JSON array (preferred)'["Option A (with, commas)", "Option B"]'Always safe — labels can contain commas, pipes, anything.
Pipe-separated"Option A|Option B|Option C"Labels contain commas but no pipes.
Comma-separated"Option A,Option B,Option C"Legacy — fragile if any label contains a comma.
See okto_pulse.core.mcp.helpers.parse_multi_value for the canonical parser. The same rules govern selected when answering choice questions.

Answering

answer_*_question takes either answer (open) or selected (choice) — provide the one that matches the question’s question_type.
Input to okto_pulse_answer_ideation_question:
  board_id:    "brd_abc123"
  ideation_id: "id_M1"
  qa_id:       "qa_d4e5f6"
  selected:    "opt_0"

Output:
{
  "success": true,
  "qa": {
    "id":            "qa_d4e5f6",
    "question_type": "choice",
    "selected":      ["opt_0"],
    "answered_by":   "agent_user_proxy"
  }
}
For multi-select (question_type="multi_choice"), pass the same multi-value format used for options: ["opt_0", "opt_2"], "opt_0|opt_2", or legacy comma-separated.

Card comments (7 tools)

Comments are card-scoped, free-form, and mutable. Two flavors: text and choice (the latter is a richer “poll” that can collect responses from multiple agents).

Tool reference (server.py:2778–3164)

ToolLinePurpose
okto_pulse_add_comment2778Add a text comment to a card.
okto_pulse_add_choice_comment2829Add a choice “poll” — comment_typechoice / multi_choice, optional allow_free_text.
okto_pulse_respond_to_choice2914Respond to a poll. selected accepts the same multi-value formats as options.
okto_pulse_get_choice_responses2975Get all responses (per-responder, with optional free-text).
okto_pulse_list_comments3013List all comments on a card (text + choice, in order).
okto_pulse_update_comment3059Edit an existing comment’s body.
okto_pulse_delete_comment3119Delete a comment.

Choice comment lifecycle

A choice comment is the right tool when several agents need to weigh in on the same card-level decision (sprint review polls, technique selection, prioritization). Compared to a card Q&A, it captures multiple distinct responses with attribution.
Input to okto_pulse_add_choice_comment:
  board_id:        "brd_abc123"
  card_id:         "card_001"
  question:        "Pin the Stripe webhook signature library to which version?"
  options:         ["stripe-py 9.x (LTS)", "stripe-py 10.x (current)", "Custom HMAC"]
  comment_type:    "choice"
  allow_free_text: "false"

Output:
{
  "success": true,
  "comment": {
    "id":           "cmt_p1q2r3",
    "comment_type": "choice",
    "content":      "Pin the Stripe webhook signature library to which version?",
    "choices": [
      { "id": "opt_0", "label": "stripe-py 9.x (LTS)" },
      { "id": "opt_1", "label": "stripe-py 10.x (current)" },
      { "id": "opt_2", "label": "Custom HMAC" }
    ],
    "allow_free_text": false,
    "responses":       []
  }
}
Input to okto_pulse_respond_to_choice:
  board_id:   "brd_abc123"
  comment_id: "cmt_p1q2r3"
  selected:   "opt_0"

Output:
{
  "success": true,
  "comment": {
    "id": "cmt_p1q2r3",
    "responses": [
      { "responder_id": "agent_security", "selected": ["opt_0"], "free_text": null }
    ]
  }
}
Input to okto_pulse_get_choice_responses:
  board_id:   "brd_abc123"
  comment_id: "cmt_p1q2r3"

Output:
{
  "id":              "cmt_p1q2r3",
  "comment_type":    "choice",
  "question":        "Pin the Stripe webhook signature library to which version?",
  "choices":         [...],
  "allow_free_text": false,
  "responses":       [...],
  "response_count":  3
}

Permissions

ActionPermission flag
Ask any Q&A (open or choice)Permissions.QA_CREATE
Answer any Q&APermissions.QA_ANSWER
Delete Q&A on any entityPermissions.QA_DELETE
Add comment / choice commentPermissions.COMMENTS_CREATE
Update commentPermissions.COMMENTS_UPDATE
Delete commentPermissions.COMMENTS_DELETE
List Q&A or commentsPermissions.BOARD_READ
Respond to a choice commentPermissions.COMMENTS_RESPOND (any agent in the board)
A blocked call returns FORBIDDEN. Adjust the agent’s preset in Board → Agents → Edit.

Errors

{
  "error": "VALIDATION_ERROR",
  "message": "At least one option is required",
  "detail": {}
}
Codes that hit this domain:
CodeMost common cause
VALIDATION_ERROREmpty options on a choice question, no selected provided when answering, comma-only options string with embedded commas in a label.
NOT_FOUNDQ&A item / comment ID belongs to a different board, or the parent entity does not exist.
FORBIDDENAgent’s preset does not include the required permission flag above.
CONFLICTAnswering a choice question with answer (open text) instead of selected, or vice versa.

Next steps

Knowledge & attachments

Reference docs and binary files attached to entities.

Architecture & mockups

Visual design artifacts across the pipeline.

MCP reference index

All 198 tools across 8 domains.

ADLC pipeline

Where Q&A and comments fit in the ideation → done flow.
Last modified on May 8, 2026