Ballpark

Answers a question about a live study by reading its current contents (questions, intro/outro, settings, logic). Read-only — never changes the study. This is study structure during creation/edit, not participant results and not who created or owns the study — those go to exploreData. Pass the study's identifier — its `studyUuid`, the numeric id from its /project/<id> URL, or a pasted study URL as-is — 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

MUST be called for any question about participant responses, views, opinions, demographics, segments, counts, percentages, ratings, comparisons, quotes, study catalog filters/sorts, who created or owns a study, or other study results. Call this directly even when you do not know which study contains the answer and even when no studyUuid is available; this tool can discover the relevant study itself. Do NOT call searchStudies first unless the user explicitly asked to search/find/list/choose studies by topic or name. Do NOT call queryStudy for ownership, creator, or participant-result questions. Pass the user’s complete request through as `question` unchanged by default. Do not rewrite, summarise, split it into separate questions, or paraphrase an analysis request into "find/search/list studies". Tool arguments are not a place to reinterpret the goal. Answers a natural-language question about the workspace's study data — counts, breakdowns, comparisons, trends across studies, catalog lists, and study owner identity from the graph. Runs a server-side analysis agent that queries the response graph. Use this when the user wants the actual numbers/answer, not just a list of studies. Only pass a studyUuid when you actually hold a study uuid (it looks like "ut_" followed by a UUID) — one the user pasted, or one a previous tool result returned. Otherwise pass studyUuid as null. A study NAME is not a studyUuid: when the user refers to a study in words, pass null and name the study in the question instead. Returns immediately with a `jobId`. Call `waitFor({ jobIds: [jobId] })`, then use the completed entry in `structuredContent.jobs`: present its `summary` verbatim — do NOT re-summarise, re-interpret, or drop figures; the analysis was already done with full schema context, so re-summarising only loses detail (e.g. dropping rating buckets or rows). Use its `result.data` only for follow-up computation, never to rewrite the summary. (This is the opposite of searchStudies, which returns raw candidates for you to synthesise.)

exploreData

Places a previewed recruitment order. THIS SPENDS REAL CREDITS AND RECRUITS REAL PARTICIPANTS — it must only ever be called after the user has seen the previewOrder summary (participants, credits) and explicitly said to place THAT order, in their own words, in this conversation. A ready preview, an agreed audience, or a chosen count is NOT that agreement. Takes only the previewId previewOrder issued: everything about the order is read from the stored quote, and the order placed is exactly the one previewed. If the quote has expired (they last an hour) or the price has moved, nothing is charged and the result says to preview again. Never call it to see what would happen, and never retry a failure without the user asking.

placeOrder

Costs a recruitment order for a chosen audience against a study and returns a summary to show the user before anything is placed: participant count, estimated duration, credits required, and the balance left afterwards. Takes the audienceId exactly as suggestAudiences issued it — never invent one. Omit studyUuid to reuse the study supplied when suggesting the audience, or supply the study the user chose or created later. After study creation finishes, continue here with the audience the user already selected and their previously supplied participant count; creating a study does not require suggesting or choosing audiences again. A study is needed before pricing. The audienceId is required: find it in the conversation, however far back the choice was made. If you genuinely do not have one, call suggestAudiences instead so the user can pick — never ask them to repeat an id, and never guess at which audience they meant. Omit `participants` unless the user has actually said a number: the tool comes back asking for one rather than guessing, and choosing on their behalf spends their credits. Nothing is charged here. On success it returns a previewId — the only thing placeOrder takes, since the order placed is read from the stored quote. An order that cannot be paid for, or that asks for more participants than match the audience, returns no previewId at all — follow the instructions in the result rather than retrying with a count you chose. Present the summary, then put placing it to the user as a choice they select from — using whatever multiple-choice affordance you have, falling back to a numbered list only if you have none — and follow the `presentation` instruction in the result. A ready preview is not agreement to spend.

previewOrder

ONLY use this for explicit semantic discovery by topic or name, such as "find studies about onboarding". Do NOT use it for catalog lists, filters, or sorts (recent, launched, by type, N+ responses), who created or owns a study, or questions about participant responses, views, opinions, demographics, segments, counts, percentages, ratings, comparisons, quotes, or other study results — call exploreData directly for those, with studyUuid null if you do not already hold a ut_ id. Semantically searches the workspace's studies by topic — matches on each study's title, research goal and question wording, not just exact keywords. Before calling, verify that the user’s own words explicitly request study discovery by topic or name; search/find/list words that you introduce while paraphrasing do not count. Only then compose the query. Prefer a descriptive query over a bare word: when the user is terse (e.g. "politics"), expand it into a fuller query that captures their intent and related terms (e.g. "political opinion, elections, voting, government") — matching is much sharper on a rich query — but never change their meaning or turn a results question into a study search. Returns ranked candidate studies (title, link, relevance score, and which field matched); these are retrieval candidates, not a finished answer. Judge relevance, drop weak or off-topic hits, and synthesise a concise summary for the user instead of dumping the raw list.

searchStudies

Find new candidate audiences when the user first describes whom to recruit, or requests a change to audience targeting. A reply selecting a previously returned option completes audience selection: retain its audienceId and continue toward previewOrder, asking which study to use if unknown. Do not submit a selection or your own description of an option as a new brief. A study is optional here: copy the user's recruitment request into brief and omit studyUuid or set it to null when unknown. Never invent a study reference; copy one supplied by the user or returned by a tool. Returns audienceIds and eligibility counts, not prices or orders. Follow the result's presentation instructions. Keep the selected audienceId and participant count while finding, creating or editing a study. A research topic or question about participants does not by itself impose a new eligibility requirement. If study creation or editing is running, call waitFor with its jobId and wait for successful completion before previewing or reconsidering targeting. If the finished study suggests a targeting change, explain which requirement differs from the selected audience and why, then ask for agreement before calling suggestAudiences. Otherwise continue with previewOrder with the same audienceId and the resolved study. A new search is appropriate when the user explicitly changes audience requirements or agrees to your proposed change; if a tool reports the selected audience is unavailable, explain that before searching again. Finding a study or changing participant count alone does not require a new audience search.

suggestAudiences

Re-prices an existing preview with a new participant count and returns a fresh previewId. The widget must display the returned quote and use its id when placing. Earlier ids keep their original quotes.

updatePreview

Blocks until background job(s) started by `createStudy`, `editStudy`, or `exploreData` have finished. Pass the returned `jobId`(s) — one, or several to wait for multiple jobs at once. For exploreData, relay the finished summary verbatim. Call this before reading a finished study, chaining a dependent editStudy, or answering an exploreData question. Returns once every requested job is done or has errored.

waitFor