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.
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&A | Comments |
|---|
| Lives on | entity.qa_items (JSONB on parent) | Dedicated comments table linked by card_id |
| Attached to | Ideation, refinement, spec, card, sprint | Card only |
| Question types | Open (free-text answer) and choice (single- or multi-select, optional free-text) | Text comments and choice “polls” (single/multi-select) |
| Lifecycle | ask → answer → optional delete | add → optional update / respond → delete |
| Permissions | Permissions.QA_CREATE, _ANSWER, _DELETE | Permissions.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.
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)
| Tool | Line | Purpose |
|---|
okto_pulse_ask_ideation_question | 4282 | Ask an open-ended question. |
okto_pulse_ask_ideation_choice_question | 4331 | Ask a structured question with options (the ambiguity-killer entry point). |
okto_pulse_answer_ideation_question | 4418 | Answer a Q&A item — pass answer for open, selected for choice. |
okto_pulse_list_ideation_qa | 4485 | List Q&A items on an ideation. |
okto_pulse_delete_ideation_question | 12011 | Delete a Q&A item. |
Refinement (server.py:5204–5460)
| Tool | Line | Purpose |
|---|
okto_pulse_ask_refinement_question | 5204 | Ask an open question. |
okto_pulse_ask_refinement_choice_question | 5253 | Ask a structured choice question. |
okto_pulse_answer_refinement_question | 5340 | Answer. |
okto_pulse_list_refinement_qa | 5407 | List Q&A. |
okto_pulse_delete_refinement_question | 12050 | Delete. |
Spec (server.py:10413–10974)
| Tool | Line | Purpose |
|---|
okto_pulse_ask_spec_question | 10413 | Ask an open question. |
okto_pulse_ask_spec_choice_question | 10464 | Ask a structured choice question. |
okto_pulse_answer_spec_question | 10552 | Answer. |
okto_pulse_list_spec_qa | 10619 | List Q&A. |
okto_pulse_delete_spec_question | 11973 | Delete. |
Card (server.py:2638–2777)
| Tool | Line | Purpose |
|---|
okto_pulse_ask_question | 2639 | Ask an open question on a card. |
okto_pulse_answer_question | 2689 | Answer a card Q&A. |
okto_pulse_delete_question | 2742 | Delete 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)
| Tool | Line | Purpose |
|---|
okto_pulse_ask_sprint_question | 11903 | Ask an open question on a sprint. |
okto_pulse_answer_sprint_question | 11937 | Answer a sprint Q&A. |
okto_pulse_delete_sprint_question | 12089 | Delete a sprint Q&A. |
Cross-stage carry-over
| Tool | Line | Purpose |
|---|
okto_pulse_copy_qa_to_card | 7838 | Copy 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.
| Format | Example | When |
|---|
| 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.
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 | Line | Purpose |
|---|
okto_pulse_add_comment | 2778 | Add a text comment to a card. |
okto_pulse_add_choice_comment | 2829 | Add a choice “poll” — comment_type ∈ choice / multi_choice, optional allow_free_text. |
okto_pulse_respond_to_choice | 2914 | Respond to a poll. selected accepts the same multi-value formats as options. |
okto_pulse_get_choice_responses | 2975 | Get all responses (per-responder, with optional free-text). |
okto_pulse_list_comments | 3013 | List all comments on a card (text + choice, in order). |
okto_pulse_update_comment | 3059 | Edit an existing comment’s body. |
okto_pulse_delete_comment | 3119 | Delete a comment. |
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
| Action | Permission flag |
|---|
| Ask any Q&A (open or choice) | Permissions.QA_CREATE |
| Answer any Q&A | Permissions.QA_ANSWER |
| Delete Q&A on any entity | Permissions.QA_DELETE |
| Add comment / choice comment | Permissions.COMMENTS_CREATE |
| Update comment | Permissions.COMMENTS_UPDATE |
| Delete comment | Permissions.COMMENTS_DELETE |
| List Q&A or comments | Permissions.BOARD_READ |
| Respond to a choice comment | Permissions.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:
| Code | Most common cause |
|---|
VALIDATION_ERROR | Empty options on a choice question, no selected provided when answering, comma-only options string with embedded commas in a label. |
NOT_FOUND | Q&A item / comment ID belongs to a different board, or the parent entity does not exist. |
FORBIDDEN | Agent’s preset does not include the required permission flag above. |
CONFLICT | Answering 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.