create_study
Create user interview studies to gather research insights, generate shareable interview links, and optionally include visual stimuli like images or Figma prototypes for participants.
Instructions
Creates a user interview study and returns an interview_link to share with participants. Starts with 1 interview slot. Optionally include study_media to show an image or Figma prototype during the interview.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| key_research_goal | Yes | ||
| business_context | Yes | ||
| additional_context_prompt | No | ||
| language | No | ||
| duration_minutes | No | ||
| metadata | No | ||
| study_media | No | Visual stimulus shown during all interview questions (web participants only) |
Implementation Reference
- src/index.ts:72-116 (handler)The `create_study` tool is registered using `server.tool` and includes both the schema definition and the async handler function that calls the Usercall API.
server.tool( "create_study", "Creates a user interview study and returns an interview_link to share with participants. Starts with 1 interview slot. Optionally include study_media to show an image or Figma prototype during the interview.", { key_research_goal: z.string(), business_context: z.string(), additional_context_prompt: z.string().optional(), language: z.enum(["auto", "en"]).optional(), duration_minutes: z.number().int().positive().optional(), metadata: z.record(z.string(), z.unknown()).optional(), study_media: z .object({ type: z .enum(["image", "prototype"]) .describe( "Media type: 'image' for direct image URLs (.png, .jpg, .gif, .webp) or 'prototype' for Figma prototype URLs", ), url: z .string() .url() .describe("Public URL to the image or Figma prototype"), description: z .string() .max(500) .optional() .describe("Alt text / context shown to participants"), }) .optional() .describe( "Visual stimulus shown during all interview questions (web participants only)", ), }, async (input) => { const payload = await callUsercallApi("/api/v1/agent/studies", { method: "POST", body: JSON.stringify({ ...input, target_interviews: 1 }), }); const note = input.study_media ? "Study created with 1 interview slot and media attachment. Share the interview_link with 1 participant (media visible on web only). Use update_study to add more slots." : "Study created with 1 interview slot. Share the interview_link with 1 participant. Use update_study to add more slots."; return result(appendNote(payload, note)); }, );