create_study
ChatGPTStart a new guided user-interview study with the platform's creation agent. The agent walks the user through a multi-stage onboarding (study_goals -> recruitment_type -> recruitment_target -> interview_mode -> study_guide). This first call seeds the study and starts the conversation. Subsequent turns MUST use edit_study with the returned studyId AND the chatId from this call's response, supplying either prompt (free-form answers or refinements) or buttonClick (one of the structured events returned in nextActions). Returns the new studyId, the server-minted chatId, summary, current onboardingStatus, optional agentQuestion, suggestions, a nextActions array describing the structured events the user can send next, and the full study state (including state.studyGuide). ALWAYS print the whole study guide. After this call returns, render the entire state.studyGuide to the user verbatim: list every block in order with its title, and under each block every question and statement in order, including the full question text and all answer options. Never summarize, truncate, or omit questions. Do this on every create_study call, even when onboarding is still in progress and the guide is partial or empty (in that case say the guide has no questions yet). Organization: REQUIRED when the user belongs to more than one organization. Call list_creatable_orgs first if the user did not name a workspace, ask which org to use, then pass orgName (or orgId) on create_study. Never call create_study without orgName/orgId when multiple orgs exist. chatId: omit this argument. The server mints a fresh chatId and returns it. Persist that chatId locally so you can pass it back into edit_study for follow-up turns in the same conversation.
edit_study
ChatGPTSend a natural-language edit instruction for a study to the platform's creation agent. See the server-level instructions for the full capability boundary (what edit_study can and cannot do). Two modes, picked automatically by the server from the chatId's prior turns: 1. Fresh chatId on an existing study: direct-edit mode. Send a plain prompt ('remove Q3', 'switch panel to professionals and bump to 200 people'). No buttonClick. 2. chatId carried over from a create_study call this session: the agent walks onboarding stages. Use buttonClick values returned in the previous turn's nextActions; use prompt to answer the agent's question or refine. Each call must supply EITHER prompt OR buttonClick. Call get_study_state first if you don't already have a recent snapshot. chatId: omit on the first turn of a brand-new edit session. To continue an in-progress conversation (either a create_study walkthrough or a prior edit_study turn), pass the chatId returned in the previous turn's response. The response always echoes the chatId actually used; persist that value for follow-up turns.
get_response
ChatGPTDeep-dive into a single respondent's interview. Returns a structured transcript with question tracking, input types, and multiple choice data. Paginated for large interviews. Each transcript item carries a source_url deep-link to that exact message in the respondent's transcript (e.g. https://listenlabs.ai/response/<id>?message=<n>); it is null only for items with no respondent answer. When the respondent arrived via a recruitment link with custom URL parameters, those key/value pairs are returned in url_params (omitted when none were captured). Grounding requirement: whenever you quote a respondent, surface the quote verbatim and immediately follow it with a [Source] markdown link built from that item's source_url. Never present a quote without its source link, never reuse one item's link for another, and never state a finding, number, or sentiment that is not present in the returned transcript.
get_study_analysis
ChatGPTGet the AI-generated analysis report for a study, rendered as markdown. Use list_studies first to find studies with has_analysis=true. The returned markdown is sourced. Each respondent quote is shown verbatim followed by a [Source] link to that respondent's transcript at the cited message (e.g. https://listenlabs.ai/response/<id>?message=<n>). Named metric, chart, table, and reel references appear by name, with their real values listed in the sections appended below the report body. Grounding requirement: when you summarize or draw any conclusion from this report, support every claim or opinion with a source from this output: quote the respondent verbatim and keep its [Source] link. STRICT, NON-NEGOTIABLE REQUIREMENT: every quote you surface MUST be immediately followed by its exact [Source] link, copied verbatim from the report. Never present a quote without its [Source] link, never move, merge, reorder, paraphrase, or fabricate a link, and never reuse one quote's link for another. If a quote has no [Source] link in the returned content, do not use that quote at all. Never state a finding, number, or sentiment that is not present in the returned content, and never invent or paraphrase a quote, attribution, number, or link.
get_study_responses
ChatGPTGet response transcripts for a study. Returns formatted interview transcripts with pagination to stay within token limits. Each respondent answer is followed by a [Source] markdown link to that exact message in the respondent's transcript (e.g. https://listenlabs.ai/response/<id>?message=<n>). Grounding requirement: whenever you quote a respondent, surface the quote verbatim and immediately follow it with its exact [Source] link, copied verbatim from this output. Never present a quote without its [Source] link, never move, merge, reorder, or fabricate a link, and never reuse one quote's link for another. Never state a finding, number, or sentiment that is not present in the returned transcripts.
get_study_state
ChatGPTReturn the current state of a study (title, audience, study guide outline, questions, screener, recruitment) in a slim, LLM-friendly shape. Use this before edit_study to see what the study currently contains. Also returns a launch block: whether the study is published, the organization's credit balance, per-recruitment cost and eligibility (alreadyLaunched, eligibleAlone), the total cost to launch every unlaunched recruitment, and any blockers (e.g. no_recruitments, study_busy). Call this before launch_study to preview which recruitments will be launched and which will be skipped for insufficient credits.
launch_study
ChatGPTPublish the study's dev revision (if needed) and start every unlaunched recruitment that fits the organization's credit balance. Recruitments are launched greedily in dashboard order: each one whose cost fits the running balance is launched and its cost deducted; any that no longer fit are reported as skippedInsufficientCredits so you can tell the user exactly which ones could not run. Self-recruit links bill per response and are always launched if unlaunched. Panel recruitments have an upfront cost that must fit the balance. Custom-link recruitments (driven by external-panel dashboards) are not launched here. If the user picked "I'll bring my own participants" in onboarding but never created a recruitment link, this tool will create one automatically and activate it so the study can launch in a single step. Returns: published (whether a dev revision was promoted to prod), launched (recruitments that started successfully), skippedInsufficientCredits, skippedAlreadyLaunched, balanceBefore, balanceAfter, totalCostLaunched, and any failures. Call get_study_state before this tool to preview which recruitments will launch and which will be skipped for credits. The user must add credits in the Listen Labs dashboard if balance is too low. Safe to re-call: already-launched recruitments are skipped, not relaunched.
list_creatable_orgs
ChatGPTList organizations the user belongs to where they can create studies. Supports pagination and case-insensitive substring search on org name. Returns JSON: { "orgs": [{ "id", "name", "role" }], "total": number, "hasMore": boolean, "nextCursor"?: string, "textHint"?: string }. total is the count of all orgs matching the textHint (or all orgs the user is in, if no textHint). Inputs: textHint (optional substring to filter org names by, case-insensitive), cursor (opaque value from a previous response's nextCursor), limit (defaults to 10, max 25). Call when the user asks to list their orgs/workspaces, when they ask 'how many orgs am I in', or before create_study when they have not named which organization to use. Pagination: when hasMore is true, pass the returned nextCursor on the next call to fetch the following page. Keep textHint identical across pages of the same search. Search: when the user names a workspace, prefer passing textHint over enumerating. If textHint returns 0 orgs, ask the user for a different name; do not retry with no textHint and dump every org. If multiple orgs are returned, ask the user to choose one and pass orgName (or orgId) on create_study.
list_studies
ChatGPTList studies accessible to the authenticated user. Returns study ID, name, status, creation date, response count, and whether analysis is available. Paginated (50 per page). Response: { studies, total_count, next_cursor, text_hint? }. total_count reflects the filter (textHint + status); use it to answer 'how many studies do I have?'. Pagination: when next_cursor is non-null, pass it as cursor on the next call to fetch the following page. Keep textHint and status identical across pages of the same search. Search: when the user names a study (or part of a study title), pass it as textHint to filter case-insensitively on the study title (matches either the published or draft title). If textHint returns 0 studies, ask the user for a different name; do not retry with no textHint and dump every study.
publish_study
ChatGPTPublish the study's current dev revision to prod so respondents see the latest version. Use this after edit_study on an already-launched study, otherwise respondents keep seeing the old published guide. No-op when the dev revision is identical to prod; the response will report published=false with a note. Does not start any recruitments. Use launch_study if you also want to begin sourcing respondents; launch_study auto-publishes before launching. Returns: published (boolean), prodRevisionId on success, or a note when there were no changes.
search_across_studies
ChatGPTSearch over stud and response metadata (name, goal, and classification/theme labels)
get_response
Claudeget_study_analysis
Claudeget_study_responses
Claudelist_studies
Claudesearch_across_studies
Claude
