Listen Labs

Start 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. Folder: pass folderName only when the user says where the study should live, and only a folder that already exists. An unknown name is rejected, listing the available folders: retry with one of those, or create the folder with manage_folder first if the user wants a new one. When several folders share a name, pass the full path or the folderId from the error. Omit both and the study lands on the main dashboard; use move_study to file it later.

create_study

Send 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.

edit_study

Deep-dive into a single respondent's interview. Returns a structured transcript with question tracking, input types, and multiple choice data. Paginated for large interviews. Works for incomplete interviews too (the respondent dropped off, or is still being interviewed). Check `is_complete` before describing the interview, and never present a partial transcript as a finished one. `quality_category`: platform rating (Excellent, Good, Average, Low, To Review = maybe dishonest or AI; null = not rated). `incentive_status`: payment state (e.g. payment_sent); only on studies that pay a reward. A high rating does not mean paid. 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). Panel or other linked respondent attributes (e.g. Age, Country) are returned as ordered key/value pairs in `linked_data` (omitted when none exist). 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_response

Get 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_analysis

Get response transcripts for a study. Returns formatted interview transcripts with pagination to stay within token limits. Both completed and incomplete interviews are returned (incomplete = the respondent dropped off, or is still being interviewed), so `total_responses` covers both. Each response carries `is_complete`: check it before describing an interview, never present a partial transcript as a finished one, and when a count matters say how many of each you are reporting on. `quality_category`: platform rating (Excellent, Good, Average, Low, To Review = maybe dishonest or AI; null = not rated). `incentive_status`: payment state (e.g. payment_sent); only on studies that pay a reward. A high rating does not mean paid. 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_responses

Return 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.

get_study_state

Publish 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.

launch_study

List 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_creatable_orgs

List studies accessible to the authenticated user, plus the folders they are organized into. Each study returns ID, name, status, creation date, response count, whether analysis is available, and `folder` (the folder it sits in, or null for the dashboard root). When multiple organizations are included, each study also returns `organization`. Paginated (50 per page). Response: { studies, folders, unfiled_study_count, total_count, next_cursor, text_hint?, folder_filter? }. `total_count` reflects the filter (textHint + status + folder or folderId + organization); use it to answer 'how many studies do I have?'. Folders: `folders` lists every folder in scope as { id, path, study_count, organization? }, where `path` is the full nesting chain (e.g. "Research / Q3 2026"), `study_count` is how many studies it holds, and `organization` is included when multiple organizations are in scope. `unfiled_study_count` is how many sit on the dashboard root. This is the answer to 'what folders do I have', 'how is my work organized', or 'what is in folder X'. Folders with study_count 0 are listed too, so an empty folder is still visible. Important: `folders` and their study_count are a stable directory view of the selected organization scope. They deliberately IGNORE textHint and status, so a folder's study_count will not match a filtered `studies` array. Only `total_count` and `studies` follow the filters. Pagination: when next_cursor is non-null, pass it as cursor on the next call to fetch the following page. Keep textHint, status, folder, folderId, orgName, and orgId identical across pages of the same search. `folders` repeats unchanged on every page, so read it once. 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. Scoping: pass orgName or orgId when the user names an organization. Pass folder to list only the studies inside it. Folder names are resolved within the selected organization; without organization scoping, use folderId when the same path exists in multiple organizations. Folder filtering is exact, not recursive: studies in a subfolder are NOT included, so query the subfolder by its own path to see them.

list_studies

Create, rename, re-nest, or delete a dashboard folder. Folders only: it never creates, moves, or deletes a study. Use move_study to file a study in a folder. Rename, move, and delete need an existing folder, matched case-insensitively at any depth; pass a "/"-separated path (e.g. "Research / Q3 2026") to choose between duplicate names. When a name is unknown or ambiguous the error lists the folders with their full paths: retry with one of those exactly. action="create": makes the folder, plus any missing parents along the path. The path is resolved from the dashboard root, so "Q3" is a root-level folder even when a nested "Research / Q3" exists. A folder already at exactly that path is returned unchanged with didCreate=false. action="rename": renames the folder, keeping its position and contents. Requires newName. action="move": re-nests the folder under parentFolderName (or parentFolderId), or to the dashboard root when both are omitted. Works on a folder holding studies or subfolders too: the contents travel with it. A folder cannot move into itself or its own descendants. action="delete": permanently removes an EMPTY folder, and only when the user explicitly asked to delete it. Folders holding studies or subfolders are refused; empty them with move_study first rather than assuming the contents are unwanted. Never delete to "tidy up" on your own initiative. create_study and move_study only accept a folder that already exists, so this is also how you make room for them when the user names a folder they do not have yet. Organization: REQUIRED when the user belongs to more than one organization, same as create_study. Call list_creatable_orgs first if they did not name a workspace.

manage_folder