Attune

Replace a guide's whole segment flow in one call. orderedSegments is the complete new list, in order: existing segments are kept or updated by id, new segments are added with a localKey (the response's minted map gives each new segment ID), and any existing segment left out is removed with its questions and sample questions. An existing segment you are not changing needs only its id; any field you omit on an existing segment keeps its saved value (a legacy next route only when type is also omitted; a multiple-choice question and choices only when both are omitted). To add, rename, reorder, or remove sections, pass sections as the complete ordered list: existing ones by id ({ id } alone keeps the name), new ones by localKey with a name, and place each new segment with sectionId or sectionLocalKey; existing segments that omit both stay in their saved section. Existing multiple-choice segments must stay in the list, by id and as multiple-choice; remove one with remove_from_guide. For each segment it sets the type, title, objective, depth, required questions, sample questions, classification or multiple-choice setup, and routing or display conditions. Set flowMode to label-conditions to qualify later segments on categories picked in earlier classification segments (requiredCategoryIds, displayConditions); omit it to keep the default routing. To show or hide a whole section, put displayConditions or choiceDisplayConditions on the section instead of on each of its segments; their sources must come before the section. A section entry that omits them keeps its saved rules, and [] clears them. The whole flow is validated before anything is saved, so an invalid flow changes nothing. On a published guide with responses, a flow that removes content may be refused; the error explains why. For a single change, use edit_segments, edit_questions, or edit_sample_questions. Response envelope: {guide, rev, ok, ...result, liveSnapshotSync?}. When liveSnapshotSync is pending, a removal has been saved but is not yet effective for future interview starts; do not report it as removed until the state is synced. Conflicts include the expected and current rev to aid retry.

apply_flow

Creates a draft interview guide from a title and a research objective, landing in the caller's default workspace. The objective becomes the guide's first segment (with null title and depth initially). Optionally sets the maximum interview length and the interviewer voice in the same call. Creating a guide costs 1 token on the free plan and is included on paid plans. Returns the created guide with {guide, rev, ok, orgContextExists}; if voice is successfully applied, the response includes voice echoing the applied interviewer display name. Available interviewer voices (by display name): "Blake" (default), "Katie", "Alan", "Mary". If the create is uncertain (e.g. a timeout), pass the same `idempotencyKey` again to safely retry — it returns the guide already created for that key instead of creating a second one. Without a key, check `list_interview_guides` for a guide with a matching title before retrying. Requires `organizationId` if the caller belongs to multiple organizations; omit it if the caller belongs to only one.

create_interview_guide

Add, update, or reorder the required questions of a structured segment, one action per call. Actions: `add` (segmentId, text, aiFollowUp, aiFollowUpInstructions, aiFollowUpMax), `update` (questionId, text, aiFollowUp, aiFollowUpInstructions, aiFollowUpMax), `reorder` (segmentId, orderedQuestionIds). To delete a question use remove_from_guide. Pass expectedRev (the rev from your last read or edit) to detect concurrent edits; a conflict error includes the current rev. Response: {guide, rev, ok, ...result, liveSnapshotSync?}. When liveSnapshotSync.state is pending, the change is saved but not yet live for new interviews; don't report a removal as done until it is synced.

edit_questions

Add, update, or reorder the sample questions that steer a conversational segment, one action per call. Actions: `add` (segmentId, text), `update` (sampleQuestionId, text), `reorder` (segmentId, orderedSampleQuestionIds). To delete a sample question use remove_from_guide. Pass expectedRev (the rev from your last read or edit) to detect concurrent edits; a conflict error includes the current rev. Response: {guide, rev, ok, ...result, liveSnapshotSync?}. When liveSnapshotSync.state is pending, the change is saved but not yet live for new interviews; don't report a removal as done until it is synced.

edit_sample_questions

Add, update, or reorder a guide's segments, one action per call. Actions: `add` (type, title, objective, depth, requiredQuestions, classification, multipleChoice, ranking, matrix, endScreen, question, selectionMode, choices), `update` (segmentId, type, title, objective, depth, classification, multipleChoice, question, selectionMode, choices, ranking, matrix, endScreen), `reorder` (orderedSegmentIds). add creates a conversational, structured, classification, multiple-choice, ranking, or matrix segment; a structured segment can include its required questions, a classification segment needs its classification setup, a multiple-choice segment needs its question and choices, a ranking segment needs its question, options, and mode, and a matrix segment needs its question, rows, and columns. update changes a segment's title, objective, depth, classification setup, multiple-choice question and choices, ranking setup, or matrix setup, and can switch a segment between conversational, structured, and classification; a multiple-choice, ranking, or matrix segment can't be converted to or from another type. update can remove content: switching to conversational deletes the segment's required questions, switching to structured deletes its sample questions, lowering depth drops sample questions past the new limit, and a replacement category or choice list drops the ones it leaves out. reorder takes every segment ID in the new order. On a published guide with responses, an update that removes content may be refused; the error explains why. To convert a classification segment to another type or rebuild the whole flow, use apply_flow; to delete a segment, use remove_from_guide. Pass expectedRev (the rev from your last read or edit) to detect concurrent edits; a conflict error includes the current rev. Response: {guide, rev, ok, ...result, liveSnapshotSync?}. When liveSnapshotSync.state is pending, the change is saved but not yet live for new interviews; don't report a removal as done until it is synced.

edit_segments

Retrieves participant answers, utterances, and email addresses across responses for one structured question (pass questionId) or one segment (pass segmentId), within the guide version that defined it. Returns one entry per participant, newest interview first. Use segmentId for conversational segments, or to read a whole structured segment at once. IDs come from get_interview_guide; archived questions and segments stay queryable by their historical IDs, and distinct versions need separate calls. Page size defaults to 20, maximum is 100.

get_answers

Retrieves the organization's stored business context — company overview, pricing, ICP, buying process, positioning, products, competitors, and more — plus its provenance (which fields are user-authored vs. AI-generated, source URLs) and generation state. Context is org-wide: it feeds every interview guide in the organization, not just one. If context has never been authored or generated, the response has `status: "not_set"` instead of empty fields. Requires `organizationId` if the caller belongs to multiple organizations; omit it if the caller belongs to only one. Organizations on the newer business context get `overview`, `vocabulary`, and `sources` (kind, title, excerpt) instead of the record fields.

get_business_context

Returns the authenticated caller identity: all memberships with their roles and email. Calls that name a guide or response resolve the org automatically; a multi-org caller passes organizationId only on calls that name neither, such as list_interview_guides or create_interview_guide.

whoami

Retrieves the full guide and revision. Classification segments include their mode, question or context source, category IDs, labels, guidance, matching policy, and fallback. Segment conditions and legacy routes are included for flow edits.

get_interview_guide

Retrieves the full response transcript, sectioned by guide segment, with metadata (including the response mode, voice or chat) and participant fields including the participant email address. Transcripts are paginated at the section level (utterances[from..to]) to handle interviews that exceed the client size budget. Provide the cursor from a prior call to resume paging; omit it to start from the beginning.

get_response