Create a new UX research study using AI-powered generation.

⏱️ IMPORTANT: This takes 30-90 seconds. Tell the user it will take about a minute and ask them to wait while the AI generates the study.

This is the PRIMARY way to create studies. The AI will automatically:

1. Generate a study name from the description

2. Define research objectives

3. Identify the target user persona

4. Create appropriate sections (voice interview, prototype testing, etc.)

5. Generate interview guides for each section

After creation, ALWAYS present the study summary to the user showing what was generated (name, objectives, persona, sections).

For best results, the description should include:

• The product or feature being tested

• The target user persona (e.g., "B2B SaaS power users", "first-time mobile shoppers")

• The research goals (usability, satisfaction, discovery, etc.)

• Any specific tasks or flows to test

• Prototype or Figma URLs if testing a design

Args: description: Natural language description of the research study to create. Include details about what you want to research, the product, target users, and any specific methodologies needed.

Fetch the full configuration of a study including all sections, status, objectives, persona, product overview, and metadata.

Use this when you need raw study data for programmatic processing or to check specific field values.

For a human-readable overview to present to the user, prefer get_study_summary.

Returns: Full study object with fields: id, name, status, objective, user_details, product_overview, sections (list of section objects).

Args: study_id: The unique identifier of the study.

Get a formatted, human-readable summary of a study.

Use this to present study details to the user after creation or modification. Do NOT use this for programmatic field access — use get_study instead.

Returns: Formatted text showing study name, status, objectives, target persona, and a list of all sections with their types and names.

Args: study_id: The unique identifier of the study.

List all studies for the current tenant/organization.

Start here when no study_id is provided. Returns IDs, names, and statuses for all studies. After listing, ask the user which study they'd like to work with, then call get_study_summary for a human-readable overview or get_study for the full raw config.

Rename a study.

Args: study_id: The unique identifier of the study. name: The new name for the study.

Update study details such as objective, user details, and product overview.

Args: study_id: The unique identifier of the study. objective: The research objective or goal. user_details: Description of the target user/persona. product_overview: Overview of the product being researched.

Change the status of a study.

Args: study_id: The unique identifier of the study. status: New status — one of 'Draft', 'Active', 'Paused', 'Completed'.

Duplicate an existing study and all its sections.

Creates a new study with the same objectives, persona, sections, and interview guides. The copy starts in Draft status with no participant sessions. Useful for iterating on a study template without modifying the original.

Args: study_id: The unique identifier of the study to copy.

DESTRUCTIVE: Permanently delete a study and ALL its associated data.

This cannot be undone. It deletes all participant sessions, recordings, transcripts, analytics, and interview guides for this study.

Do NOT call this tool in the same turn as the deletion request. First respond with: "Are you sure you want to permanently delete '[study name]' and all its data? This cannot be undone." Only call this tool after the user confirms in a follow-up message.

Args: study_id: The unique identifier of the study to delete.

Check what analytics have been generated for a study.

Returns the status of each analytics component (qual, quant, QnA, summary, insights, report). Use the result to decide next steps:

• If all needed components are present: call the read tools directly.

• If analytics are missing or stale: call generate_analytics first (takes 2-5 min), then call the read tools once generation is complete.

Always call this before generate_analytics to avoid re-generating unnecessarily.

Args: study_id: The unique identifier of the study.

Trigger AI-powered analytics generation for a study.

⚠️ PREREQUISITE: The study must have at least one completed participant session. Call get_participants first — if no sessions are completed, analytics cannot be generated. Also call get_analytics_status first to avoid redundant generation.

⏱️ This takes 2-5 minutes depending on the number of sessions. Inform the user this will take several minutes.

This generates all analytics components: qualitative insights, quantitative data, Q&A analysis, summary, and overall insights.

This call returns immediately — generation runs in the background. After calling this, poll get_analytics_status to monitor progress:

• Call get_analytics_status up to 10 times to check for completion.

• If still not complete after 10 checks, tell the user: "Analytics generation is still in progress. Please ask me to check again in a few minutes."

• Once complete, call the appropriate read tools for what the user needs.

Args: study_id: The unique identifier of the study.

Get qualitative analysis for a study — themes, patterns, and insights.

Use this when the user wants to understand the "why" behind participant behavior: recurring themes, usability friction points, and positive findings across sessions.

⚠️ PREREQUISITE: Analytics must be generated first. Call get_analytics_status — if components are missing, call generate_analytics and wait for completion.

Includes overview, positive findings, and challenges discovered across participant sessions.

Args: study_id: The unique identifier of the study.

Get quantitative metrics for a study — task completion rates, times, misclicks, and other measurable data.

Use this when the user wants numbers: "how many people completed the task", "what was the average time", or "where did people click most". Most relevant for prototype and conceptTesting sections that capture interaction data.

⚠️ PREREQUISITE: Analytics must be generated first. Call get_analytics_status — if components are missing, call generate_analytics and wait for completion.

Args: study_id: The unique identifier of the study.

Get per-participant Q&A analysis — each participant's responses organized by subtopic across all study sections.

Use this when the user wants to compare how different participants answered the same questions, or to see individual-level responses side by side.

⚠️ PREREQUISITE: Analytics must be generated first. Call get_analytics_status — if components are missing, call generate_analytics and wait for completion.

Args: study_id: The unique identifier of the study.

Get a short, concise AI-generated text summary of the study's overall findings.

Use this first when a user asks for a quick overview of study results. If they want to go deeper, follow up with the appropriate tool:

• get_qualitative_insights: themes and patterns (the "why")

• get_quantitative_data: metrics and completion rates (the "how many")

• get_qna_analysis: per-participant Q&A breakdown (individual responses)

• get_study_insights: actionable recommendations (what to fix)

⚠️ PREREQUISITE: Analytics must be generated first. Call get_analytics_status — if components are missing, call generate_analytics and wait for completion.

Returns: Short summary text (typically 200–400 words) of key findings.

Args: study_id: The unique identifier of the study.

Get overall and per-section insights for a study, including key findings and actionable recommendations.

Use this when the user asks "what should we fix", "what are the main issues", or wants prioritized action items broken down by study section.

For a shorter executive summary, use get_analytics_summary instead. For the full combined report, call generate_study_report then get_study_report.

⚠️ PREREQUISITE: Analytics must be generated first. Call get_analytics_status — if components are missing, call generate_analytics and wait for completion.

Args: study_id: The unique identifier of the study.

Retrieve the full comprehensive study report combining all analytics.

This report must be generated first using generate_study_report. Call get_analytics_status to verify the report component exists before fetching.

If this returns empty or a "not found" response, the report has not been generated yet. Recovery path:

1. Call get_analytics_status — if analytics components are missing, call generate_analytics first and wait for completion.

2. Then call generate_study_report (takes 3-5 min), polling get_analytics_status until the report component shows complete.

3. Then call this tool again to retrieve the result.

Returns: Complete report document in markdown/structured format covering qualitative insights, quantitative data, Q&A analysis, and recommendations.

Args: study_id: The unique identifier of the study.

Trigger generation of the comprehensive study report.

⚠️ PREREQUISITE: Analytics must be generated first. Call get_analytics_status — if analytics are missing, call generate_analytics and wait for completion before calling this.

⏱️ This takes 3-5 minutes. Inform the user this will take several minutes.

This call returns immediately — report generation runs in the background. After calling this, poll get_analytics_status to check the report component:

• Call get_analytics_status up to 10 times to check for completion.

• If still not complete after 10 checks, tell the user: "Report generation is still in progress. Please ask me to check again in a few minutes."

• Once the report component shows as complete, call get_study_report.

Args: study_id: The unique identifier of the study.

Get the AI analysis report for a single participant's session.

Use this when investigating one specific participant's performance, responses, or behavior in detail.

⚠️ PREREQUISITE: Analytics must be generated first (use generate_analytics + poll get_analytics_status until complete). Call get_participants first to get the correct participant_id and session_id.

Returns: Session report with transcript highlights, task performance, key quotes, and AI-generated observations for this participant.

Args: study_id: The unique identifier of the study. participant_id: The unique identifier of the participant. session_id: The unique identifier of the session.

Get UI annotation data (heatmaps, click data) for a study.

Most relevant for studies with prototype or conceptTesting sections — these capture click interactions that appear as heatmaps and misclick data. For voice interview sections, this data may be sparse or empty.

⚠️ PREREQUISITE: Analytics must be generated first. Call get_analytics_status — if components are missing, call generate_analytics and wait for completion.

Args: study_id: The unique identifier of the study.

List all participants in a study, including their session status and metadata.

Call this first whenever you need participant_id or session_id values. These IDs are required by get_session, get_session_report, get_session_recordings, and get_participant_sessions_report.

Returns each participant's ID, name (if available), session IDs, and completion status (e.g., completed, in-progress, invited).

Args: study_id: The unique identifier of the study.

Get raw transcript and interaction events for a single participant session.

Use this when the user wants to read what a participant actually said verbatim, or review the full unprocessed interaction log.

For an AI-analyzed summary with themes, key quotes, and task performance assessment, use get_session_report instead.

Call get_participants first to find the correct participant_id and session_id.

Args: study_id: The unique identifier of the study. participant_id: The unique identifier of the participant. session_id: The unique identifier of the session.

Get recording URLs (video/audio) for a specific session.

Returns video and/or audio stream/download links for the session recording. Call get_participants first to find the correct participant_id and session_id.

Args: study_id: The unique identifier of the study. participant_id: The unique identifier of the participant. session_id: The unique identifier of the session.

Get an aggregated analysis report across ALL sessions in a study.

Use this for study-level synthesis: overall patterns, common findings, aggregate completion rates.

For a single participant's session, use get_session_report(study_id, participant_id, session_id). For all sessions by one participant, use get_participant_sessions_report(study_id, participant_id).

Returns: Aggregated report object with overall findings, patterns, and per-section summaries across all participants.

Args: study_id: The unique identifier of the study.

Add a new section to a study.

REQUIRED NEXT STEPS after calling this — do not skip:

1. Call update_section to set the section's name and description.

2. Call generate_guide to create the AI interview guide.

3. Present the generated guide to the user for review.

SECTION TYPES:

• "prototype": Testing interactive Figma prototypes

• "conceptTesting": Feedback on mockups or early-stage concepts

• "voiceInterview": Open-ended discussion, no visual stimulus

• "liveProductResearch": Testing against a live product URL

Returns: New section object with id, type, and index.

Args: study_id: The unique identifier of the study. section_type: One of 'prototype', 'conceptTesting', 'voiceInterview', 'liveProductResearch'. index: Zero-based position for the new section (default: 0).

List all sections (tasks) in a study with their types, names, and IDs.

Use this to find section_id values needed for get_section, update_section, delete_section, generate_guide, and update_interview_guide.

Args: study_id: The unique identifier of the study.

Get full details of a specific section including its configuration and settings.

Call get_sections first if you need to find the section_id.

Args: study_id: The unique identifier of the study. section_id: The unique identifier of the section/task.

Update a section's name, description, prototype link, or Figma link.

Args: study_id: The unique identifier of the study. section_id: The unique identifier of the section/task. name: New name for the section. description: New description for the section. prototype_link: URL of the prototype associated with this section. figma_link: Figma file URL for the section.

DESTRUCTIVE: Permanently remove a section from a study.

This deletes the section, its interview guide, and all associated configuration. This cannot be undone.

Do NOT call this tool in the same turn as the deletion request. First respond with: "Are you sure you want to delete section '[name]'? This cannot be undone." Only call this tool after the user confirms in a follow-up message.

Args: study_id: The unique identifier of the study. section_id: The unique identifier of the section/task to delete.

Get all interview guides for every section in a study.

Returns the full guide content (markdown) for each section that has one. Use this after study creation to see the AI-generated interview guides.

Args: study_id: The unique identifier of the study.

Replace the interview guide content for a specific section.

Users should FIRST generate a guide using generate_guide, then edit it using this tool if changes are needed. Do NOT write guides from scratch.

Args: study_id: The unique identifier of the study. section_id: The unique identifier of the section/task. guide_content: The full guide content in markdown format.

Generate an AI-powered interview guide for a section using the study's objectives, target persona, and section configuration.

⚠️ PREREQUISITES: The study must have objectives and persona set, and the section must have a name and description. Call update_study_details and update_section first if these are not yet configured.

⏱️ This takes 30–90 seconds. Warn the user before calling.

After generation, present the guide to the user for review. If they request changes, use update_interview_guide — do NOT regenerate from scratch.

Returns: The full guide content in markdown format.

Args: study_id: The unique identifier of the study. section_id: The unique identifier of the section.

Start a new Synthesis Studio AI analysis chat for a study.

Synthesis Studio lets you have an AI-powered conversation to explore research findings, ask follow-up questions, and generate new insights.

Best used after the study has collected participant sessions — the AI analyzes the actual session data to answer questions. Analytics do not need to be pre-generated; Synthesis Studio works directly from session data.

After creating, use send_synthesis_message to ask questions.

Args: study_id: The unique identifier of the study to analyze. title: Optional title for the chat session.

List all Synthesis Studio AI chats across all studies.

Returns chat IDs, titles, and associated study IDs. Use this to find existing chats to resume with get_synthesis_chat, or to show the user their analysis history before creating a new one.

Get a specific Synthesis Studio chat with its full message history.

Use this to review a previous conversation, show the user what questions have already been asked, or pick up where an analysis session left off.

Args: chat_id: The unique identifier of the chat.

Send a message to a Synthesis Studio AI chat and receive an analysis response.

Use this to ask questions about research data, explore themes, request comparisons across participants, or generate new insights from the data.

⏱️ Responses take 30–90 seconds depending on query complexity. Warn the user.

Returns: AI analyst's response text with findings, patterns, or answers based on the study's session data.

Args: chat_id: The unique identifier of the chat (from create_synthesis_chat). message: The question or request to send to the AI analyst.

DESTRUCTIVE: Delete a Synthesis Studio chat and its entire message history.

Do NOT call this tool in the same turn as the deletion request. First respond with: "Are you sure you want to delete this analysis chat? The full conversation history will be permanently lost." Only call this tool after the user confirms in a follow-up message.

Args: chat_id: The unique identifier of the chat to delete.

Enable public sharing for a Synthesis Studio chat.

Returns a shareable link that anyone can access without authentication.

Args: chat_id: The unique identifier of the chat to share.

Get an aggregated report for all sessions completed by a specific participant.

Use when the user wants to understand one person's overall experience or performance across multiple sessions in the same study.

For reports across ALL participants, use get_sessions_report. For a single specific session, use get_session_report.

⚠️ PREREQUISITE: Analytics should be generated first for best results (use generate_analytics + poll get_analytics_status until complete). Call get_participants first to find the correct participant_id.

Args: study_id: The unique identifier of the study. participant_id: The unique identifier of the participant.

Get all tags assigned to a study, useful for organizing and filtering studies.

Args: study_id: The unique identifier of the study.

Update the tags for a study. Provide tags as a comma-separated string.

Args: study_id: The unique identifier of the study. tags: Comma-separated list of tags (e.g., "usability,checkout,mobile").

Analyze a Figma prototype and extract screen context for UX research.

This fetches the Figma file, extracts screen information, and returns structured data about the prototype's pages and frames.

Args: user_id: The Userology user ID of the person requesting Figma access. This is the account owner's UID — if unknown, ask the user to provide it or check their Userology profile settings. Note: this is NOT the study_id. figma_link: The Figma file URL to analyze.