Tools

MCP tools for creating studies, querying results, and recruiting.

Authenticated clients see a live study-builder flow. Research Coach and recruitment tools are listed only when those features are enabled for the workspace. Clients that support MCP Apps also get an interactive preview widget for drafts and audience picking.

Create and edit studies

These are the default tools for a signed-in workspace.

Tool	Description	Input	Output
`createStudy`	Creates a live study in Ballpark from a research brief. Returns immediately while the builder fills in.	`researchGoal` — the user’s request, passed through as-is. Include a Figma prototype URL here if you want a prototype task.	`url` (builder) `studyUuid` `jobId` Then call `waitFor`.
`editStudy`	Applies a natural-language change to a live study.	`studyUuid` (or a `/project/<id>` URL), `editInstruction`.	Updated study draft `url` `jobId` Then call `waitFor`.
`queryStudy`	Read-only: answers a question about the study’s current structure (questions, intro, logic). Not participant results.	`studyUuid` (or project URL), `question`.	Synchronous answer. No `waitFor`.
`waitFor`	Waits until background jobs from `createStudy`, `editStudy`, or `exploreData` finish.	`jobIds` — one or more ids (max 10).	Job status plus a summary when done.

Results and discovery

Listed when Research Coach is enabled for the workspace. (currently in Beta and feature flagged, please contact us to enable on your workspace)

Tool	Description	Input	Output
`searchStudies`	Semantic search across the workspace by topic or name. Use only when the user asked to find studies.	`query`, optional `limit` (max 50).	Ranked studies with title, link, and match field.
`exploreData`	Answers questions about participant responses, demographics, quotes, and catalog filters.	`question`, `studyUuid` (`ut_…` or `null`).	`jobId`. Then call `waitFor` and relay the summary verbatim.

Recruitment

Listed when recruitment MCP is enabled and the user is an Owner, Admin, or Editor. (currently in Beta and feature flagged, please contact us to enable on your workspace)

Tool	Description	Input	Output
`suggestAudiences`	Suggests up to three audiences with live eligibility counts.	`brief` and/or `studyUuid`.	Candidate audiences, each with an `audienceId`. Interactive picker in supported clients.
`previewOrder`	Costs an order for a chosen audience. Does not charge credits.	`audienceId` from `suggestAudiences`, `studyUuid`, optional `participants`.	Quote (count, duration, credits, remaining balance) and an `orderId`. Interactive preview in supported clients.