Listen Labs

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.

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.

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

Search study metadata

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.

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.

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.

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.

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

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.

Move a study into a folder, or back out to the dashboard root. Pass folderName to move it into an existing folder. Names are matched case-insensitively at any nesting depth; when several folders share a name, pass the full path instead (e.g. "Research / Q3 2026"). Omit both folderName and folderId to move the study out of its folder and back to the dashboard root. The folder must already exist: an unknown or ambiguous name is rejected and the error lists the available folders with their full paths. Retry with one of those exactly, or create the folder with manage_folder first if the user asked for a new one. Never invent a folder name the user did not say. A study lives in exactly one folder, so this replaces its current location rather than adding to it. Same organization only: folderName and folderId are resolved against the folders of the study's own organization, so a folder from another org (even one the user can access) is not a valid destination. This tool cannot transfer a study to another organization, and nothing else can either. If that is what the user wants, say it is not possible. Returns the resolved destination: folderPath (null when the study is now on the dashboard root) and a human-readable location.