add_question
ChatGPTAppend an item to the end of a form. type is a question type, Breaker (page break — only formId + type are needed, other fields are ignored) or a display block (Statement / Swiper). Question types: SingleCheck / MultiCheck / TrueFalse; FillBlank (free text — scored in quiz via correctAnswer, an unscored data-collection field in scored_quiz); DropDown (single or multiple via multiple — prefer it over SingleCheck/MultiCheck past 20 choices); Cascade (hierarchical via choices[i].children, scored_quiz only); Ordering (quiz only, order-sensitive grading); DateField / TimeField (unscored data-collection fields, scored_quiz only, no correctAnswer/score); NumberField (quiz: optional numeric correctAnswer + score; scored_quiz: the submitted number feeds report formulas); Rate (scored_quiz only, the submitted 1..steps rating is the question score unless per-star scores are set in the web app). Display blocks carry no answer: { type: "Statement", content } renders a rich-text passage (intro, section lead-in, disclaimer) and { type: "Swiper", items } an image carousel; both work in every scene. Configure random_knowledge_quiz question banks in the web app. 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.
assign_leads
ChatGPTAssign one or more leads of the current team to a member, or clear the assignee. Pass every lead id in a single call (up to 50) — do not loop one call per lead. The assignee must be an active non-viewer member (see list_lead_settings.assignableMembers); pass "me" for yourself, or omit / null to unassign. Each actual change is recorded on the lead's timeline. When assigning, the assignee gets one aggregated in-app notification and, if enabled in their notification preferences, one email for the whole batch; assigning the same owner again does not notify them again.
create_form
ChatGPTCreate a form in the team this token is bound to. Pass the questions array and report configuration in one call instead of following up with per-question calls. In the outcome_quiz scene report.outcomes is REQUIRED at create time (TrueFalse votes via trueOutcomes/falseOutcomes). For a scored_quiz with dimensions, define report.dimensionAnalysis.dimensions with codes and formulas over question codes in this same call; a question may override its score for one dimension via choices[i].dimensionScores (TrueFalse: trueDimensionScores/falseDimensionScores). The returned structuredContent.fields carries each question code — read those first, then fill in a scored_quiz report.formula (e.g. q_a + q_b) or a report.dimensionAnalysis via update_form / set_dimension_analysis. Creates the primary language only; add other languages with create_form_translation. 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.
create_form_from_template
ChatGPTCreate a new form in the current team from a public template (find template ids with list_templates). Clones the template structure, scoring/report configuration, visual settings, and all language versions in one call; pass title to override the template title. After creation you can adjust it with update_form / update_question etc. This is the fastest way to build a quiz when a suitable template exists — prefer it over building from scratch with create_form. 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.
create_form_translation
ChatGPTAdd a language version (translation) to a form. Clones the source text as the initial draft and returns it so you can translate right away: edit the human-readable text in place, keep every code identical to the source, then save with update_form_translation. The language must differ from the form's primary language, and there is at most one translation per language (see list_form_translations).
delete_form
ChatGPTMove a form into the trash (soft delete) in the current team. The form is hidden from list_forms but kept recoverable for 5 days (then auto-purged); use restore_form to bring it back. Only the form owner or the team owner / admin can delete. Submission records are kept until permanent purge.
delete_form_translation
ChatGPTDelete one language version (translation) of a form. Submission records are anchored to the source form and are NOT deleted; reports for historical records in this language fall back to the source text. The primary language cannot be deleted this way (it lives on the form itself).
delete_question
ChatGPTDelete a single item from a form by code — a question, a page break (Breaker) or a display block (Statement / Swiper). Deleting the last one is allowed (a form can be an empty shell).
duplicate_form
ChatGPTDuplicate a form in the current team: clones its structure, scoring, report, visual settings and all language translations into a brand-new form owned by you (with fresh share links). Does NOT copy submission records, sharing, integrations, or ban state. Useful for cloning a proven quiz and tweaking it. 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.
finalize_image_upload
ChatGPTStep 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.
get_active_tenant
ChatGPTReturn 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_booking_availability
ChatGPTRead 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_examinee
ChatGPTView 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_form
ChatGPTView 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_funnel
ChatGPTRead 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_share_info
ChatGPTEverything 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_stats
ChatGPTRead 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_translation
ChatGPTRead 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_lead
ChatGPTView 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_record
ChatGPTView 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.
insert_question
ChatGPTInsert 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.
invite_member
ChatGPTInvite 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.
list_bookings
ChatGPTList 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_examinees
ChatGPTList 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_form_translations
ChatGPTList 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_forms
ChatGPTList the forms of the current team. Returned in reverse chronological order of creation, without question content (use get_form for details).
list_lead_settings
ChatGPTRead 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_leads
ChatGPTList 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_my_tenants
ChatGPTList all teams (tenants) the current user belongs to. isActive marks the team this token currently operates against.
list_records
ChatGPTList 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_templates
ChatGPTList 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.
move_question
ChatGPTMove 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.
prepare_image_upload
ChatGPTStep 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.
reschedule_booking
ChatGPTMove 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.
restore_form
ChatGPTRestore 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.
review_booking
ChatGPTApprove 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.
set_dimension_analysis
ChatGPTSet 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_lead_tags
ChatGPTSet 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.
switch_active_tenant
ChatGPTSwitch the active team (tenant) for this token. The change persists across sessions until switched again. Caller must be a member of the target team.
update_booking_status
ChatGPTClose 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_examinee
ChatGPTUpdate 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_form
ChatGPTUpdate 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_settings
ChatGPTChange 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, 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_translation
ChatGPTSave 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_lead
ChatGPTMove 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_question
ChatGPTUpdate 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_tenant_slug
ChatGPTChange 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.
