Ballpark

Answers a question about a live study by reading its current contents (questions, intro/outro, settings, logic). Read-only — never changes the study. Pass the `studyUuid` (from createStudy/editStudy) and the user's `question`. Returns synchronously with the answer, so use it whenever you need to inspect or summarise a study before acting (no waitFor needed).

queryStudy

Creates a Ballpark study from the user's request. Authentication required. Returns immediately with a `url` — the live builder where the study is assembled, which the user can watch in real time and edit alongside (plus `studyUuid` and `jobId`). Reply to the user with that `url` FIRST so they can see and work with the full study, and tell them you'll wait for it to finish. The builder is real-time multiplayer, so they can edit alongside live — that does NOT interrupt the job (it can't be stopped once started). THEN call `waitFor({ jobIds: [jobId] })` to follow the job to completion and share the summary it returns. To make several variants, call createStudy for each and pass all the jobIds to one waitFor. Pass the user's request through as `researchGoal` unless they've told you to shape it.

createStudy

Applies a change to a study. Returns immediately with a `url` — the live builder where the change is applied, which the user can watch in real time and edit alongside (plus a `jobId`). Reply to the user with that `url` FIRST, and tell them you'll wait for it to finish. The builder is real-time multiplayer, so they can edit alongside the change live — that does NOT interrupt it (a job can't be stopped once started). THEN call waitFor({ jobIds: [jobId] }) to follow it to completion and share the summary it returns. Pass the user's change through as `editInstruction` unless they've told you to shape it.

editStudy

Takes a free-text recruitment brief (optionally stating how many participants to recruit), decomposes it into filter concepts, searches the Ballpark recruitment filter catalog, and returns up to 3 candidate audiences — most specific first — each with a live combined eligibility count against the target. STOP once these options come back: present all of them to the user, with their counts and what each one trades away, and wait for the user to say which they want. Do NOT call selectAudience in the same turn — the options exist so the USER can choose between them, and picking on their behalf throws that choice away.

findAudiences

Confirms which of findAudiences' candidate audiences the user chose, and re-checks its live eligibility count. Call this ONLY after the user has named the option they want — never to ratify a choice you made for them, and never in the same turn findAudiences returned. If the user has not chosen yet, ask them instead of calling this. Pass the chosen option's `optionId`, `label`, `filters` and `ageRange` exactly as findAudiences returned them — this server keeps no memory of the previous call, so the audience must be passed back in full. Read-only: it does not attach the audience to a study or place a recruitment order.

selectAudience

Blocks until the background job(s) started by `createStudy` or `editStudy` have finished applying. Pass the `jobId`(s) returned by those tools — one, or several to wait for multiple jobs at once (e.g. study variants). Call this before reading a finished study or chaining a dependent editStudy. Returns once every requested job is done or has errored.

waitFor