Lyssna

Create a draft Lyssna usability test from a spec: test details, welcome and thank you screens, an optional screener, and sections in order. Supports information sections, questions sections with any question type, preference tests, first click tests, five second tests, design surveys, card sorts, tree tests and live website tests. Preference, first click, five second and design survey sections are created without their images: tell the user to upload them in the builder. Give questions and screener questions a key so later sections and questions can show or hide based on their answers. Everything is created in one go, or nothing is. Returns links to the builder and a preview, and whether the draft is ready to recruit. The draft is never launched; the user reviews and launches it in Lyssna.

create_study

Describes the Lyssna Data API. With no arguments, the result is the complete supported-operation catalog for the currently loaded API document. With a path copied from that catalog, the result is a self-contained guide with the applicable tool and exact MCP argument placement: pathParams, selectors for get_data, and filter, sort, cursor, and page_size for search_data. A method is required only when the selected path offers multiple methods. Identical requests against an unchanged API document return the same information. Catalog hints cover simple calls; operation guides include nested filters, selector semantics, result shape, and an example. The catalog and guides are compiled from the exact loaded OpenAPI document generation; Rails remains the final validation, authorization, masking, tenant, and record-access boundary. Unknown paths or methods fail permanently with offered choices.

describe_data

Edit a draft Lyssna usability test with a list of operations: change details and screens, add, update, move or remove sections, questions and screener questions, change the screener, and add, update or remove tasks. Call get_study first for the ids and version. Operations apply in order, and either all apply or none do. Give added sections, questions and screener questions a key to refer to them in later operations. Use dry_run to check an edit without saving it. Saved edits are rate limited to a burst of 5, then 10 a minute, and dry runs to a burst of 10, then 20 a minute. A test that's recruiting can't be edited, and nothing is ever launched; the user reviews and launches it in Lyssna.

update_study

Fetch Data API data with a GET request. Source path and pathParams exactly from describe_data: template segments (e.g. {test_unique_id}) go in pathParams; all filters go in selectors, never as top-level arguments. Returns one of: a list result { rows, meta, guidance } for paginated (list) operations, or a detail result { data } for single-resource operations. For lists, follow meta.next_cursor by passing it as cursor on the next call; the guidance field states whether another page exists. page_size defaults to 50, max 100, and applies to list operations only. Non-ok statuses: invalid_request (fix path/selectors/pagination), not_available (resource missing or unauthorized), unavailable_retryable (retry later), and too_large (narrow selectors or reduce page_size, then retry).

get_data

Read a Lyssna usability test as an editable draft: its details, welcome and thank you screens, screener, and sections with their tasks and questions, shaped like a create_study spec but with the ids and version update_study needs. It isn't a create_study spec: to copy a draft, write a new spec against create_study's input schema, giving questions keys and pointing logic at those keys. Also returns its project and space, links to the builder and a preview, whether the draft is ready to recruit, and whether it's recruiting now, which blocks update_study.

get_study

Search Data API list data with a POST search request. Source path and pathParams exactly from describe_data: template segments (e.g. {test_unique_id}) go in pathParams; structured predicates go in filter, never as top-level arguments, flat selectors, raw body, or raw page objects. Returns a list result only: { rows, meta, guidance }. Follow meta.next_cursor by passing it as cursor on the next call; omit cursor for the first page. page_size defaults to 50, max 100; requests above the max are rejected by the tool contract. Use sort only when describe_data documents a supported search sort; the Data API validates sort values and filter shape. Non-ok statuses: invalid_request (fix path/filter/sort/pagination), not_available (resource missing or unauthorized), unavailable_retryable (retry later), and too_large (narrow filter or reduce page_size, then retry).

search_data

Search the account's research content by meaning and return either the passages that answer a question or the studies that are about it, with the citations needed to attribute them. Interview transcripts are searchable today; other content becomes searchable as it is indexed. Use this when the evidence could be anywhere; use describe_data and get_data when you already know the study and want its full records. queries is an array on purpose. Send 3-5 phrasings of the same question — the user's wording, a paraphrase, and the words a participant would actually have said — and they are fused into one ranking. A single phrasing finds noticeably less. Ask unrelated questions in separate calls. granularity decides what is ranked. Leave it at passage to build an answer out of evidence. Set it to study for a question about studies rather than about findings — "which of my studies are about the new checkout flow", "have we researched this before" — which also reaches studies that are still being set up or have no responses yet, and which a passage search cannot see at all. At passage granularity results come back in two arrays, never as whole documents. fragments are verbatim spans of what was said in a session, each carrying its own score, the study and session it came from, and time offsets when it has them; quote these as they are and attribute every claim to the fragment that supports it. A transcript passage usually carries the interviewer's turns as well as the participant's, so before presenting a quote as a finding, match the label prefixing its turn against the fragment's speakers to check the role: only participant is the researched voice, interviewer turns are the questions asked, and unknown means we could not tell and you should not guess. summaries are model-written descriptions of whole interviews — generated text, not testimony — so use them to decide which interviews to read and never quote or attribute anything from one. Scores rank matches within one response and carry no meaning across responses, so never treat one as a confidence threshold. To read what surrounds a hit, take its study and session ids to the study-specific paths through get_data. At study granularity the studies array carries the ranked studies instead, each with its name, its handle, and up to three of the fragments that justify it, and the other two arrays are empty. A study with no fragments matched on what it set out to ask, so say that it exists and what it covers — never that it found anything. Optionally scope the search with project_ids or space_ids UUID arrays, reusable typed study handles returned by study citations, and date. Values within each selector are ORed; populated selector dimensions and every date comparator are ANDed. studies accepts { kind: "interview", id: UUID } and { kind: "usability_test", id: unique_id }; it does not select sessions, responses, recordings, questions, or answers. date is Study.created_at at study granularity and the evidence occurrence time at passage granularity; it also does not select evidence-level records. Omit every scope to search the whole account. limit defaults to 20 and cannot exceed 50, counting fragments and summaries together or studies at study granularity; there is no pagination. Only indexed content is searched, so no result means no indexed evidence was found, not that the research never happened. Non-ok statuses: invalid_request (fix queries, granularity, project_ids, space_ids, studies, date, or limit), not_available (nothing searchable for this token), access_denied (the workspace's plan or admin settings block all MCP access — relay the guidance to the user, do not retry or try other paths), unavailable_retryable (retry later), and too_large (lower limit, then retry).

semantic_search