Listen Labs

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. Each reel section lists the reel's ID and its Listen Labs URL (login required). To get a public link, call share_reel with that ID. For the MP4 file, call get_reel_download_url. 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

Use this before designing questions for a project: the brief says what decision the research serves and who it is for. Returns the full brief, the default panel, the reference files attached to the project, and the runs filed under it (pass a runId to summarize_run or find_quotes). These are Listen Twins projects, not Listen Labs studies or study folders. For studies and folders, use list_studies, move_study and manage_folder.

get_project

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

List the Twins organizations the user belongs to, with their role in each (user or admin). Call this first to obtain the organizationId that fetch_organization_calls takes. Returns `{organizations: [{organizationId, name, role}]}`.

list_organizations

START HERE for Twins. Call this first whenever the user asks anything about what real people think, prefer, or would pick: it shows you which Twins panels you have access to and the kinds of questions each one will answer. Every run_* tool needs a real panelName from this list, or a projectId whose project has a default panel. Each entry: panelName (pass verbatim to run_mcq / run_oe / run_ranking), panelistCount, description (who this panel represents and what topics they're good for), composition (the demographic axes its Twins are profiled on; use these to judge fit for the question), and supportedKinds (the subset of {mcq, oe, ranking} this panel can run). Every panel listed is ready to run for the kinds it lists. This listing is deliberately thin. Once you've picked a panel, `describe_panel(panelName)` is free and adds the two things you need to plan a study: the segment dimensions it can be cut by, and what its real respondents were asked. Returns `{panels: [...]}`.

list_panels

List the user's Listen Twins Projects: named research contexts, each with a brief and a default panel that every chat in the project starts from. Returns the opening of each brief; get_project has the full brief and reference files. Pass includeArchived=true to include archived projects. These are Listen Twins projects, not Listen Labs studies or study folders. For studies and folders, use list_studies, move_study and manage_folder.

list_projects

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

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.

move_study

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_study

Use this when comparing 2-16 VISUAL concepts and the user wants to know which would win in market: ad creative, product designs, packaging, landing-page variants, app screens, logo options. Returns a yes-rate per concept, ordered so the winner is obvious. Yes-rates are calibrated against real launch outcomes, so read them as the share of the population that would buy, click or engage, not as abstract scores. Pick this over run_mcq when each concept stands on its own and you want absolute approval, not a forced pick. Pick this over run_oe when you already have the concepts and want the numerical winner, not language about why. BLOCKS until the panel finishes (typically 30-90s); progress notifications stream while it works if your client supports them. Returns {runId, taskId, kind, result}. `result.rankingAggregate` carries each concept's yes-rate with `respondentCount` and `stdDev`: Listen's uncertainty for that rate in percentage points, covering systematic error as well as sampling noise. Never call it a 95% CI or a standard deviation; when the panel hides uncertainty it is absent. `result.questionClassification.confidence` (very_high/high/medium/low, with a `reason`) says how well the question fits what the panel's respondents were asked: ALWAYS check it, and caveat or rephrase when it is low. When the panel declares segments, `result.segmentBreakdown.dimensions[]` carries a `rankingAggregate` per segment value (per-cell `n`), so you can see which segments drive each concept. Per-Twin responses are left out by default; pass `verbose=true` for each Twin's yes/no per concept. Each concept needs a stable `ref` (the key it comes back under), a short `title` (scored with the image) and an optional `description` (1-2 sentences of context the panel sees, never displayed). `path` is optional: - `[image_N]`, naming an `attachments` entry: scored from image, title and description. This is the calibrated read. Send each image inline as an MCP ImageContent block plus a ref: `{ref: 'image_1', type: 'image', data: <base64>, mimeType: 'image/png'}`. All images in one call share a budget of about 3 MB, so downscale large creative first. - omitted: a text-only concept, scored from title and description. Fine for comparing rough ideas, LESS reliable than the image read for a decision. `path` takes refs only, never URLs, and a ref with no matching attachment fails the call instead of quietly scoring the concept as text. When the work belongs to a project (see `list_projects`), pass its `projectId`: the run is filed there, `get_project` lists it, and `panelName` defaults to the project's default panel. Set `includeCsv=true` to also attach the yes-rates as a downloadable CSV; the JSON result is returned either way.

run_ranking

Use this when the user wants to know HOW A POPULATION SPLITS across concrete options: A vs B preference, brand pick, feature priority, ad-creative winner, pricing tier, anything where the answers can be listed up front. Returns the share of the panel's Twins that picks each option. Reach for run_mcq over run_oe whenever you can list the options: a forced choice gives you a percentage to quote. The chain worth knowing: run_mcq to size the split, then run_oe with `screen={screenerRunId: <this runId>, keepOptions: [<option>]}` to ask WHY of only the Twins who picked it, with `{{choice}}` in the question standing in for each one's pick. Cheaper still when you only need the reasons: `find_quotes(runId, option=...)` reads them off this finished run without asking the panel again. BLOCKS until the panel finishes (typically 30-90s); progress notifications stream while it works if your client supports them. Returns {runId, taskId, kind, result}. `result.finalDistribution` carries each option's percentage with `stdDev`: Listen's uncertainty for that share in percentage points, covering systematic error as well as sampling noise. Quote splits as `47% (±2.1)` and never call it a 95% CI or a standard deviation; when the panel hides uncertainty `stdDev` is absent, so quote shares without one. `result.questionClassification.confidence` (very_high/high/medium/low, with a `reason`) says how well the question fits what the panel's respondents were asked: ALWAYS check it, and caveat or rephrase when it is low. When the panel declares segments, `result.segmentBreakdown.dimensions[]` carries the same split per segment value (with per-cell `n`), so you can quote 'Women: 72% A' directly. `result.responses` is a sample of about 5 Twins per option (uniqueId, choice, note); pass `verbose=true` for every Twin. `panelName` must come from `list_panels`. To show the panel images, send them inline in `attachments` (an MCP ImageContent block plus a ref: `{ref: 'image_1', type: 'image', data: <base64>, mimeType: 'image/png'}`) and name each as `[image_1]` in `optionConceptImagePaths` (images per option) or `conceptImagePaths` (images shown with the question). Those fields take refs only, never URLs. All images in one call share a budget of about 3 MB, so downscale large creative first. When the work belongs to a project (see `list_projects`), pass its `projectId`: the run is filed there, `get_project` lists it, and `panelName` defaults to the project's default panel. Set `includeCsv=true` to also attach the option split as a downloadable CSV; the JSON result is returned either way.

run_mcq

Use this when the user wants the WHY, the verbatims or the themes: anything where the answers can't be listed up front and the population's own words are the point. Good for reasons behind a behavior, unprompted feature requests, language for marketing copy, and objections you didn't know to ask about. Reach for run_oe over run_mcq whenever forcing a choice would throw away the interesting variance. Most useful chained onto a prior run_mcq via `screen`: with `screen={screenerRunId: <the mcq's runId>, keepOptions: ['B']}` only the Twins who picked B are asked, so the answers belong to a known group. In the question text, `{{choice}}` and `{{answer}}` become each Twin's own earlier answer: 'You picked {{choice}}. What made it land?' reads as a real follow-up. BLOCKS until the panel finishes (typically 30-90s); progress notifications stream while it works if your client supports them. Returns {runId, taskId, kind, result}. `result.themes` is the aggregate `[{name, count}]` and `result.responses` holds verbatims tagged with their themes. `result.questionClassification.confidence` (very_high/high/medium/low, with a `reason`) says how well the question fits what the panel's respondents were asked: ALWAYS check it, and caveat or rephrase when it is low. When the panel declares segments, `result.segmentBreakdown.dimensions[]` carries theme counts per segment value (`themeCounts`, with per-cell `n`). Responses are a sample of about 3 verbatims per theme; pass `verbose=true` for every Twin's answer. `respondentContext` ({uniqueId: {key: value}}) is the manual form of the same thing: it fills `{{key}}` per Twin and asks only the Twins it names. Prefer `screen`, which derives all of it from one runId. To show the panel an image, send it inline in `attachments` (an MCP ImageContent block plus a ref: `{ref: 'image_1', type: 'image', data: <base64>, mimeType: 'image/png'}`) and put `[image_1]` in `conceptImagePaths`. That field takes refs only, never URLs. All images in one call share a budget of about 3 MB, so downscale large creative first. When the work belongs to a project (see `list_projects`), pass its `projectId`: the run is filed there, `get_project` lists it, and `panelName` defaults to the project's default panel. Set `includeCsv=true` to also attach the theme counts as a downloadable CSV; the JSON result is returned either way.

run_oe

Search study metadata

search_across_studies

Use this to RECALL the aggregate results of a past Twins run without asking the panel again. Free and instant: it reads the stored results. Reach for it whenever the user references a prior run ('what did the last MCQ say?', 'compare to the Tuesday ranking'), or any time you need the headline numbers from a runId without the 30-90s of a new run. Pass the `runId` returned by run_mcq / run_oe / run_ranking, or any earlier runId of yours. Returns one entry per question in the run with a kind-specific rollup: - mcq: `distribution` of option percentages. - oe: `themes` (label + how many Twins per theme). - ranking: `aggregate` of per-concept yes-rates. Pair with `find_quotes` to pull the actual verbatim answers behind each OE theme. Set `includeCsv=true` to also attach the aggregate as a downloadable CSV (one row per option / theme / concept); the JSON result is returned either way.

summarize_run