RooQuiz

Step 2 of 2 for adding an image: call this AFTER you have PUT the file to the uploadUrl returned by prepare_image_upload. It verifies the uploaded object in storage, records it in the team media library and returns a media id + public URL. To use the image as a quiz cover or a landing-page cover, call update_form with flagImg or landingImage set to the returned media id.

finalize_image_upload

Return the team (tenant) this token is currently operating against. All write tools default to this team. Also reports examineeSignupDisabled: when true this team has switched respondent self-signup off, so only respondents already on its roster can sign in — every quiz that asks for a login (submissionAccess examinee_only, or login_to_view_report at the report gate) turns away anyone new. Check it before blaming a quiz for "nobody can submit".

get_active_tenant

Read the current team's bookable time slots in a date range, computed from the team's weekly booking rules minus what is already taken. Returns enabled:false when the team has booking switched off or the plan does not include it. Pass bookingId to get the slots for rescheduling that booking (its own slot is not counted as taken) — always call this before reschedule_booking, since a start time outside the available slots is rejected. The range is clamped server-side if you ask for too many days.

get_booking_availability

View one form of the current team in full, including the questions list fields[] and the report configuration. For outcome forms, the outcome codes that question votes reference live in report.outcomeAnalysis.outcomes. `language` is the primary language; existing non-primary language versions are listed in `translationLanguages`.

get_form

Read the conversion funnel for a form in the current team over the last N days, from the form_sessions telemetry: overall stages (viewed → started → submitted → leadCaptured → reportViewed → ctaClicked → shared; leadCaptured is counted from submissions bound to a respondent account, not from telemetry), per-channel funnel (by utm_source, with embedded flag), UTM combos, and drop-off points (which question unsubmitted sessions stalled on). Use this to find where respondents drop and improve conversion.

get_form_funnel

Everything needed to put a form of the current team in front of an audience: the public answer link (also per language version), the team's custom domain and whether it is actually serving, ready-to-paste embed snippets in three modes (inline / popup / iframe), and the current delivery settings so you can tell whether the form will even accept responses. Pass utmSource to get every link and snippet tagged for one channel. Use this to answer "give me the link / the embed code" and to sanity-check a launch; change the switches with update_form_settings.

get_form_share_info

Read submission statistics for a form in the current team over the last N days: KPI overview (total / today / last 7 / last 30, unique examinees, anonymous, report status counts, average score, latest submission), daily submission trend, channels (by utm_source), UTM combos, login types (anonymous vs registered), device breakdown, and per-question answer distributions. Use this to gauge how a quiz is performing and to suggest improvements.

get_form_stats

Read the full content of one language version (translation) of a form, including the mirrored fields[] and report. Use this to fetch the current draft before translating: edit the human-readable text in place, keep every code identical to the source form, then save with update_form_translation. Returns an error if that language version does not exist yet (create it first with create_form_translation).

get_form_translation

View one lead of the current team by leadId: follow-up status, assignee, colour tags, the respondent block, and the next upcoming booking. Optionally include the respondent's submission history (which quizzes they took, with score / level), the team's internal follow-up comments, and the change timeline (status / assignee / tag changes plus submissions). Reference a lead by its leadId and a respondent by examineeId, never by a masked email.

get_lead

View the full detail of one submission record (lead) in the current team by its record id (the `id` field returned by list_records), including the examinee, the submitted answers, UTM metadata and the complete frozen report result (overall / dimensions / outcome / AI evaluation). Answers are returned as the respondent wrote them, except that any email address or phone number inside them comes back masked.

get_record

View the full detail of one examinee (a.k.a. respondent) in the current team by its examineeId (the business ID shown in list_examinees, e.g. AB1234567890), including customData. Sensitive auth fields are never returned.

get_examinee

Insert an item at a specific position: a question, a page break (Breaker) or a display block (Statement with `content` / Swiper with `items`). Use after / before to reference an existing field code (from get_form's field.code). To insert at the very front: before references the first field's code. To insert at the end, use add_question. Plan limit: on the Free plan a quiz can hold at most 50 questions (page breaks, statements and carousels do not count; a random-question slot counts as its draw count); Pro is unlimited. Not idempotent: if the call times out it may still have succeeded, so retrying blindly can create a duplicate — check first, then retry only if it is really missing.

insert_question

Invite someone to the active team (tenant) by email. The pending membership is created immediately and an invitation email with a join link is queued for delivery; the link and its token are never returned in the tool result. Only the team owner or an admin can invite; the call is rejected for other roles. role defaults to "member" and may be "viewer" (read-only) or "admin". You cannot invite someone as the owner. Fails if the email is already a member or already has a pending invite, or if the team has hit its member limit. Operates on the team this token currently targets — use list_my_tenants / switch_active_tenant to change teams first.

invite_member

List the 1:1 bookings (discovery calls / consultations booked from a quiz report page) of the current team, earliest first. Each item carries the time range, status, meeting type, the attendee, the source quiz and submission, and the lead owner who should handle it. Filter by status / quiz / respondent / time range. Typical use: status "pending" lists the approval queue waiting on someone. Reference a booking by its bookingId; the attendee name / email come back masked.

list_bookings

List the existing language versions (translations) of a form. Returns each translation's language, isActive flag, public share link and timestamps. The primary language lives on the form itself (see get_form.language) and is not listed here.

list_form_translations

List the forms of the current team. Returned in reverse chronological order of creation, without question content (use get_form for details).

list_forms

Read the current team's lead configuration: the follow-up status codes (with label and colour, in display order), the colour tag library, and the members a lead can be assigned to. Call this before update_lead / set_lead_tags / assign_leads — status codes, tag codes and member ids are all team-specific and the write tools reject unknown values.

list_lead_settings

List the leads (CRM records) of the current team — one lead per respondent across all forms, carrying follow-up status, assignee, colour tags, submission count and the next upcoming booking. Newest activity first by default. Filter by status / assignee / tags / created-at range / keyword / whether they have an upcoming booking. Status codes and tag codes are team-defined — call list_lead_settings first to get the valid ones, never guess. Reference a lead by its leadId and a respondent by examineeId, never by a masked email.

list_leads

List all teams (tenants) the current user belongs to. isActive marks the team this token currently operates against.

list_my_tenants

List submission records (leads) of the current team, newest first. Each item includes the examinee (name / email / customData if captured), the submitted answers, UTM metadata and a compact report result (status / score / level / outcome). Optionally filter by form, report status, and submitted-at range. Reference a respondent by examineeId, never by a masked email; email addresses and phone numbers written into the answers come back masked too. Use get_record for one record's full detail.

list_records

List the examinees — also called respondents, the people who answer the quizzes — of the current team, newest first. Sensitive auth fields (password, verification code, reset token, etc.) are never returned. The examineeId business ID is returned unmasked and is what get_examinee / update_examinee take. Use get_examinee for one examinee's full detail including customData.

list_examinees

List active templates in the public template library (id, title, scene, description, category, recommended flag, usage count), most-used first. Use this to find a template, then call create_form_from_template with its id to create a form from it — the fastest way to build a quiz when a suitable template exists.

list_templates

Move an existing item (question, page break or display block) to a specific position by code. Choose either after or before, referencing another field's code. Move to the front: before references the current first field's code. Move to the end: after references the current last field's code.

move_question

Step 1 of 2 for adding an image (PNG / JPEG / GIF / WebP) to the current team media library. This tool does NOT receive image bytes — it returns a short-lived presigned URL you upload the file to directly, so even large images never pass through this conversation. Workflow: (1) save the image to a local temp file; (2) if the file is larger than 5MB, compress / downscale it to 5MB or less FIRST (e.g. `sips -Z 2048 in.png --out out.jpg` on macOS, or `magick in.png -resize "2048x2048>" -quality 82 out.webp`) — uploads over 5MB are rejected; (3) call this tool with filename, mimeType and (optionally) fileSize; (4) HTTP PUT the temp file to the returned uploadUrl with the matching Content-Type header, e.g. `curl -X PUT --upload-file <file> "<uploadUrl>" -H "Content-Type: image/png"`; (5) call finalize_image_upload with the returned key; (6) delete the temp file. Max 5MB after compression. Only image/png, image/jpeg, image/gif and image/webp are accepted.

prepare_image_upload

Move a confirmed booking of the current team to a different time, as the organiser. The new start time must be one of the available slots — call get_booking_availability with this bookingId first and pick a startAt from its slots. The attendee is emailed about the new time, the 24h reminder is re-armed, and the booking.rescheduled integration event fires. Only works on a scheduled booking; it is rejected if the slot got taken in the meantime or if that respondent already has another active booking. Not safe to retry blindly after a timeout: the first call may have succeeded, and retrying can repeat notifications or other side effects — read the current state first.

reschedule_booking

Restore a form from the trash in the current team (undo delete_form). Only the form owner or the team owner / admin can restore; errors if the form is not in the trash.

restore_form

Approve or decline a pending booking request of the current team. Approving turns it into a confirmed meeting and sends the attendee the confirmation with the meeting address; declining sends a short "not approved" note with the optional reason. Only works on a booking whose status is pending, and a request whose meeting time has already passed can only be declined. On approval you may set the meeting link / instructions for this one meeting (leave empty to fall back to the team-level settings). Only the team owner / admin or the lead owner can review.

review_booking

Set the multi-dimension analysis (form.report.dimensionAnalysis) of a form, replacing the dimension list without touching overallAnalysis (title / radar settings you omit are kept). Dimension codes are stable: pass dimensions[].code to keep or set one, or omit it and a dimension with the same name keeps its existing code. In the knowledge_quiz scene each dimension needs fieldCodes (question codes); in the scored_quiz scene a formula is optional — dimensions that questions score into via choices[i].dimensionScores sum those automatically, so only give a formula to dimensions no question scores directly. A dimension still referenced by a question's dimensionScores or by report.formula (the overall formula) cannot be removed. Pass an empty dimensions array to clear the multi-dimension analysis. Call get_form first to read the question and dimension codes. Not supported for random_knowledge_quiz forms.

set_dimension_analysis

Set the colour tags on one or more leads of the current team. Pass every lead id in a single call (up to 50) — do not loop. mode: "replace" (default, overwrite the whole tag set — for editing a single lead), "add" or "remove" (for batches, where each lead has different tags and overwriting would wipe other people's tags). Tag codes must exist in the team's tag library (see list_lead_settings.tags); "remove" also accepts stale codes. Changes are recorded on each lead's timeline.

set_lead_tags

Switch the active team (tenant) for this token. The change persists across sessions until switched again. Caller must be a member of the target team.

switch_active_tenant

Close out a confirmed booking of the current team: mark it completed, mark the attendee as a no-show, or cancel it. Only works on a booking whose status is scheduled; completed / no_show additionally require the meeting to have already started. Cancelling notifies the attendee by email and fires the booking.cancelled integration event; completed / no_show are internal bookkeeping and do not contact the attendee. To handle a pending request use review_booking instead.

update_booking_status

Update a form of the current team: title / description / isActive / flagImg / landingImage / theme / report / openGraph / language / systemText. flagImg is the quiz cover, landingImage the landing-page cover (sets the image only, does not toggle the landing page); both take a media id from finalize_image_upload, a media URL, or "" to clear. report and openGraph (the social share card on the answer link) merge by sub-key — only what you pass is replaced, "" clears an openGraph sub-key; in the outcome_quiz scene outcomes are matched by code so existing images survive, and removing an outcome still referenced by question votes is rejected. systemText is replaced wholesale ({} clears it). language is changeable only while the form has no language versions; scene never. Questions go through add_question / update_question / delete_question / move_question, dimensionAnalysis alone through set_dimension_analysis.

update_form

Change how a form of the current team is delivered, as opposed to what it says (use update_form for title / questions / report / theme). Editable: submissionAccess (who may answer and whether seeing the report needs a login — this is the lead-capture gate), reportGateRequireCode (whether that login gate collects an emailed verification code, trading completion rate against lead quality), timeLimit, sharing (the result-page share button and personalised share card, which is what drives organic spread), answerSheet, crowdCompare (show respondents what share of people picked the same option — off by default, not for knowledge quizzes), booking (the result-page booking block that feeds the 1:1 call queue), feedback (a one-question feedback block on the result page), allowPdfDownload (respondents can download their full report as a PDF — Pro), gaTrackingId, sharedWithAll (whether every team member can see this form), searchIndexable (whether search engines may list the quiz), and slug (the custom path that gives the public link a memorable, SEO-friendly address). Only the keys you pass are changed. Read the current values with get_form_share_info.

update_form_settings

Save translated copy for one language version of a form. Pass the translated title / description / fields / report / systemText / booking / feedback, mirroring the shape returned by get_form_translation; fields you omit keep their current value and partial translation is allowed. Translation fields[] must not introduce codes that do not exist on the source form. Pass isActive=false to pause just this language version, independently of the form's overall isActive.

update_form_translation

Move one lead of the current team to another follow-up status (e.g. new → contacted). The change is recorded on the lead's timeline. Status codes and tag codes are team-defined — call list_lead_settings first to get the valid ones, never guess.

update_lead

Update a single question of an existing form, located by code. Changeable: name / description / explain / required / score / correctAnswer / aiMatch (FillBlank AI grading) / precision (DateField/TimeField picker precision) / min / max / unit / decimalPlaces (NumberField) / words (Rate scale labels) / choices (replaces ALL choices of a choice-based question). NOT changeable — delete_question then add_question instead: question type, Rate steps, DropDown multiple, Ordering shuffle. DateField / TimeField / Rate reject score / correctAnswer / aiMatch (configure date/time scoring in the web app). The scored_quiz and outcome_quiz scenes reject the top-level score / correctAnswer / aiMatch as well: pass choices carrying choices[i].score or choices[i].outcomes instead (TrueFalse outcome votes still need delete + recreate). Display blocks are edited here too, with their own keys: Statement takes content, Swiper takes items (replacing all slides), and both take name / description — every question key is rejected on them.

update_question

Update an examinee (a.k.a. respondent) in the current team, located by its examineeId (the business ID from list_examinees). Editable: name / status (active|disabled) / customData (validated against the team's examinee field definitions: required / unique / type / regex). email, tenant and examineeId cannot be changed. customData REPLACES the whole object and masked values are rejected: never re-send customData you just read, or you will wipe or corrupt phone fields — only write values the user gave you.

update_examinee

Change the team address of the current team — the first path segment of every quiz link on the platform domain (quizster.app/<team-address>/<quiz-path>). Owner / admin only. Lowercase letters, digits, hyphens and underscores, 4-32 chars, must start and end with a letter or digit, unique across the whole platform, and cannot be cleared. Changing it moves EVERY public quiz link of the team at once and the old address stops resolving (cached entries may linger briefly), so treat this as a rare, deliberate rename — not routine tuning; token addresses (/a/<publicToken>) keep working. Read the current value with get_active_tenant.

update_tenant_slug