Sweeppea MCP

Add a new participant to a sweepstakes. Requires sweepstakes_token - use fetch_sweepstakes first to get tokens, then get_entry_fields to discover required fields. Both email AND phone are required — the Sweeppea API rejects an entry missing either one. Field names must use underscores instead of spaces (e.g., "First_Name" not "First Name"). RULES: Only ONE participant at a time. NEVER add participants in bulk, batch, or loops. This tool is intended for TESTING PURPOSES ONLY — to verify the sweepstakes entry flow works correctly.

Clone an existing sweepstakes with new parameters. Use fetch_sweepstakes first to get the handler of the sweepstakes to clone. Creates a complete copy including entry pages, calendar events, short links, groups, and all configurations. CRITICAL: This is a billable operation. ALWAYS confirm with the user before cloning. NEVER clone multiple sweepstakes in batch or loops without explicit user approval for each one. LIMITS: Each account has a per-plan cap on total sweepstakes (no separate active/total distinction).

Get participant counts for a sweepstakes. Use fetch_sweepstakes first to get the sweepstakes_token. Supports filtering by type (all, participants, amoe, optouts) and date range.

count_participants

When to use

Get participant counts for a sweepstakes. Use fetch_sweepstakes first to get the sweepstakes_token. Supports filtering by type (all, participants, amoe, optouts) and date range.

Pre-calls required

1. fetch_sweepstakes if the user gave you a sweepstakes name instead of a token

Create a new calendar event with title, dates, and optional details like location, time, and notifications. DATE RULE: The API server uses UTC. Today's date may be rejected as "past" depending on the user's local timezone. To be safe, always use tomorrow's date or later when creating events. NEVER use today's date — it will fail with "Cannot Create Events In The Past". If the user asks to create an event for today, explain this limitation and suggest tomorrow instead.

Create a new group within a sweepstakes. Use fetch_sweepstakes first to get the sweepstakes_token. Groups are used to organize and segment participants.

create_group

When to use

Create a new group within a sweepstakes. Use fetch_sweepstakes first to get the sweepstakes_token. Groups are used to organize and segment participants.

Pre-calls required

1. fetch_sweepstakes if the user gave you a sweepstakes name instead of a token

Parameters to validate before calling

• sweepstakes_token (string, required) — The sweepstakes token (UUID format)

Create a new invoice. Requires the Invoices module enabled on the account (disabled by default) — if the API returns 403 "module is not enabled", do NOT retry; tell the user to contact Sweeppea support to request access. Subtotal, TaxAmount and Total are ALWAYS computed server-side from items, discount_amount and tax_rate — never calculate or promise totals yourself; report what the API returns. The computed total must be between $1 and $1,000,000. Creating an invoice NEVER notifies the recipient automatically — sharing the PublicLink is up to the user.

Create a new note. Content is encrypted (AES-256-CBC). HTML tags: h1-h6, p, a, br, strong, i, ul, ol, li. No scripts/iframes. Do NOT use <br>&nbsp; between sections.

create_note

When to use

Create a new note. Content is encrypted (AES-256-CBC). HTML tags: h1-h6, p, a, br, strong, i, ul, ol, li. No scripts/iframes. Do NOT use <br>&nbsp; between sections.

Parameters to validate before calling

• title (string, required) — Note title (max 100 characters, must be unique)
• content (string, required) — Note content (max 100,000 characters, will be encrypted).

Create a new official rules document for a sweepstakes. Use fetch_sweepstakes first to get the sweepstakes_token. SECONDARY RULES WARNING: Before creating rules, call fetch_rules to check if the sweepstakes already has primary rules. If primary rules already exist, WARN the user that the new rules will be created as SECONDARY and will NOT be the ones published on the Entry Page or assigned to the short URL (swpp.me/r/[handler]). The short URL always points to the primary rules. The user can change which rules are primary in the Official Rules section of the app.

Generate official sweepstakes rules via the 14-step wizard. BEFORE CALLING: 1) fetch_sweepstakes to get token, dates, name. 2) get_business + get_profile to pre-fill sponsor fields. 3) fetch_rules to check for existing primary rules — if primary exists, warn user new rules will be SECONDARY. Ask wizard questions in order (steps A-N), one at a time or in small groups. Only ask for data you cannot get from API calls. PRIMARY RULES LINK: If result is_primary=true, give user the URL: https://swpp.me/r/[handler] (handler in lowercase from fetch_sweepstakes).

Create a survey attached to a sweepstakes, optionally with its full question set. Use fetch_sweepstakes first to get the sweepstakes_token. Requires the Surveys module enabled on the account (disabled by default) — on 403 "module is not enabled", do NOT retry; tell the user to contact Sweeppea support. STRUCTURAL LIMITS: max 5 questions per page, 50 pages, 250 questions total, 30 options per question. Validation is all-or-nothing: any invalid question rejects the whole request and nothing is written. Pages are renumbered 1..N without gaps; question Order comes from array position.

Create a new sweepstakes programmatically. Requires name, handler (unique identifier), dates, and times. Type defaults to 2 (Email) — SMS and Social are rarely used and require explicit user request. CRITICAL: You MUST know the current date before creating a sweepstakes — never guess or assume. Start dates must be today or in the future. This is a billable operation that creates real production data. ALWAYS confirm with the user before creating. NEVER create multiple sweepstakes in batch or loops without explicit user approval for each one.

Create a new support ticket with title, description, and priority level. ASSIGNMENT: Optionally assign to a specific admin by name or email via assign_to. If omitted, the ticket is assigned to all admins. Only admin-level users can be assigned. NEVER guess or fabricate admin names or emails — only use assign_to if the user explicitly provides a name or email. FORMAT: Only these HTML tags are allowed in description: <b>, <strong>, <i>, <hr>, <br>. NEVER insert scripts, iframes, event handlers (onclick, onerror, etc.), style tags, or any executable code.

Create a new internal To-Do item. ADMIN ONLY: This tool requires admin privileges. Non-admin users will receive a 403 Forbidden error from the API. FORMAT: Only these HTML tags are allowed in description: <b>, <strong>, <i>, <hr>, <br>. NEVER insert scripts, iframes, event handlers (onclick, onerror, etc.), style tags, or any executable code. SPACING: Do NOT use <br>&nbsp; — it creates ugly blank blocks in the UI. Use <br> for line breaks within text only.

create_todo

When to use

Create a new internal To-Do item. ADMIN ONLY: This tool requires admin privileges.

Permanently delete a calendar event. Use fetch_calendar_events first to get the event_token. WARNING: This action cannot be undone.

delete_calendar_event

When to use

Permanently delete a calendar event. Use fetch_calendar_events first to get the event_token. WARNING: This action cannot be undone.

Parameters to validate before calling

• event_token (string, required) — The event token to delete (UUID format)

Notes

• DESTRUCTIVE — IRREVERSIBLE. Always confirm with the user before calling. Explain what will be lost.

DESTRUCTIVE — IRREVERSIBLE. Permanently delete a file from the user's Drive. Removes the file from S3 storage and the database. Storage quota is freed immediately. ALWAYS ask for explicit user confirmation before calling this tool.

delete_file

When to use

DESTRUCTIVE — IRREVERSIBLE. Permanently delete a file from the user's Drive. Removes the file from S3 storage and the database. Storage quota is freed immediately. ALWAYS ask for explicit user confirmation before calling this tool.

Permanently delete a group from a sweepstakes. Use fetch_sweepstakes first to get the sweepstakes_token, then fetch_groups to get the group_token. WARNING: Cannot delete primary groups, locked groups, or groups with participants.

delete_group

When to use

Permanently delete a group from a sweepstakes. Use fetch_sweepstakes first to get the sweepstakes_token, then fetch_groups to get the group_token. WARNING: Cannot delete primary groups, locked groups, or groups with participants.

Pre-calls required

1. fetch_sweepstakes if the user gave you a sweepstakes name instead of a token

Permanently delete an invoice. IRREVERSIBLE — NEVER call without explicit user confirmation for this specific invoice. Deleting is NOT the same as cancelling: to keep the invoice as history, use update_invoice with status "cancelled" instead, and offer that alternative to the user first. Money survives: wallet transactions and Sweeppea commissions from a paid invoice are NEVER deleted. Requires the Invoices module enabled — on 403 "module is not enabled", do NOT retry; tell the user to contact Sweeppea support.

delete_invoice

When to use

Permanently delete an invoice.

Permanently delete a note. Use fetch_notes first to get the note_token. WARNING: This action cannot be undone.

delete_note

When to use

Permanently delete a note. Use fetch_notes first to get the note_token. WARNING: This action cannot be undone.

Parameters to validate before calling

• note_token (string, required) — The note token to delete (UUID format)

Notes

• DESTRUCTIVE — IRREVERSIBLE. Always confirm with the user before calling. Explain what will be lost.

Permanently delete a participant from a sweepstakes. WARNING: This action cannot be undone. Use get_participant first to verify the participant details before deleting.

delete_participant

When to use

Permanently delete a participant from a sweepstakes. WARNING: This action cannot be undone. Use get_participant first to verify the participant details before deleting.

Pre-calls required

1. fetch_sweepstakes if the user gave you a sweepstakes name instead of a token

Permanently delete an official rules document from a sweepstakes. Use fetch_rules first to get the rules_token. WARNING: This action cannot be undone.

delete_rule

When to use

Permanently delete an official rules document from a sweepstakes. Use fetch_rules first to get the rules_token. WARNING: This action cannot be undone.

Pre-calls required

1. fetch_sweepstakes if the user gave you a sweepstakes name instead of a token

Parameters to validate before calling

• sweepstakes_token (string, required) — The sweepstakes token (UUID format)

Delete a pending scheduled drawing. Use fetch_scheduled_drawings first to get the schedule_token. WARNING: This action cannot be undone. Only drawings with pending status can be deleted — completed or errored drawings cannot be removed. Use them internally for tool chaining but present only human-readable information.

delete_scheduled_drawing

When to use

Delete a pending scheduled drawing. Use fetch_scheduled_drawings first to get the schedule_token. WARNING: This action cannot be undone.

Permanently delete a survey. IRREVERSIBLE — deletes the survey, its questions, ALL collected responses, stats and uploaded files. NEVER call without explicit user confirmation for this specific survey, spelling out what will be lost. If the survey has responses the API additionally requires confirm=true (409 otherwise) — only pass confirm=true after the user explicitly accepted losing the responses. Participants created from the survey and the sweepstakes itself are preserved.

Permanently delete a sweepstakes and all associated data including participants, statistics, and automations. Use fetch_sweepstakes first to get the sweepstakes_token. CRITICAL: This is a DESTRUCTIVE operation that cannot be undone. ALWAYS ask for explicit user confirmation before deleting, showing the sweepstakes name. NEVER delete multiple sweepstakes in batch or loops. If user requests bulk deletion, refuse and ask them to delete one at a time after reviewing each.

Permanently delete an open support ticket. Use fetch_open_tickets first to get the case_id. WARNING: This action cannot be undone. Only open tickets can be deleted.

delete_ticket

When to use

Permanently delete an open support ticket. Use fetch_open_tickets first to get the case_id. WARNING: This action cannot be undone. Only open tickets can be deleted.

Parameters to validate before calling

• case_id (string, required) — The case number of the ticket to delete

Notes

• DESTRUCTIVE — IRREVERSIBLE. Always confirm with the user before calling. Explain what will be lost.

Permanently delete a To-Do item. WARNING: This action cannot be undone. ADMIN ONLY: This tool requires admin privileges. Non-admin users will receive a 403 Forbidden error from the API.

delete_todo

When to use

Permanently delete a To-Do item. WARNING: This action cannot be undone. ADMIN ONLY: This tool requires admin privileges. Non-admin users will receive a 403 Forbidden error from the API.

Parameters to validate before calling

• todo_token (string, required) — The To-Do token to delete (UUID format).

Notes

• DESTRUCTIVE — IRREVERSIBLE.

Draw winners from a sweepstakes immediately. Use fetch_sweepstakes first to get the sweepstakes_token, and fetch_groups to get available groups. CRITICAL: This is a production operation that selects real winners. ALWAYS confirm with the user before drawing — including the number of winners and which group to draw from. Uses weighted random selection favoring participants with bonus entries. Cannot draw from paused or archived sweepstakes. Use them internally for tool chaining but present only human-readable information (names, emails).

Search US telephone area codes by code number or state name. Returns up to 10 results. Omit search to get all area codes.

fetch_areacodes

When to use

Search US telephone area codes by code number or state name. Returns up to 10 results. Omit search to get all area codes.

Parameters to validate before calling

• search (string, optional) — Search term: area code number or state name (optional, omit to get all)

Get monthly and yearly billing consumption totals for your account. Shows aggregated usage data from billing transactions and data transfers.

fetch_billing_consumptions

When to use

Get monthly and yearly billing consumption totals for your account. Shows aggregated usage data from billing transactions and data transfers.

Get all billing transactions for your account including invoices, amounts, and status. Results are sorted by creation date (newest first).

fetch_billing_transactions

When to use

Get all billing transactions for your account including invoices, amounts, and status. Results are sorted by creation date (newest first).

Get all calendar events for your account. Returns events with their details including dates, times, location, and status. Use them internally for tool chaining but present only human-readable information (titles, dates, times, locations).

fetch_calendar_events

When to use

Get all calendar events for your account. Returns events with their details including dates, times, location, and status. Use them internally for tool chaining but present only human-readable information (titles, dates, times, locations).

Get closed/resolved support tickets with pagination (20 per page) and search. Returns summary info only — use get_ticket with the case number to get full ticket details including notes, files, and collaborators. Supports filtering by subject/description text, platform (renaissance, api, general, overture, winners), and priority (1=Low, 2=Medium, 3=High).

fetch_closed_tickets

When to use

Get closed/resolved support tickets with pagination (20 per page) and search.

Search countries by name, international dial code, or ISO abbreviation. Returns up to 10 results with English/Spanish names. Omit search to get all countries.

fetch_countries

When to use

Search countries by name, international dial code, or ISO abbreviation. Returns up to 10 results with English/Spanish names. Omit search to get all countries.

Parameters to validate before calling

• search (string, optional) — Search term: country name, dial code (e.g. "+34"), or ISO code (e.g. "US") (optional, omit to get all)

Get data transfer records for a specific sweepstakes including bytes transferred, payment status, and rates. Use fetch_sweepstakes first to get the sweepstakes_token.

fetch_data_transfer

When to use

Get data transfer records for a specific sweepstakes including bytes transferred, payment status, and rates. Use fetch_sweepstakes first to get the sweepstakes_token.

Pre-calls required

1. fetch_sweepstakes if the user gave you a sweepstakes name instead of a token

Get help and support documentation articles. Supports pagination and search by title or content. Returns up to 10 documents per page.

fetch_documentation

When to use

Get help and support documentation articles. Supports pagination and search by title or content. Returns up to 10 documents per page.

Parameters to validate before calling

• page (number, optional) — Page number to retrieve (default: 1)
• limit (number, optional) — Number of documents per page, max 10 (default: 5)
• search (string, optional) — Search term to filter documents by title or content

List all files in the user's Drive with storage usage, categories, and pagination. Files are sorted by creation date (newest first).

fetch_files

When to use

List all files in the user's Drive with storage usage, categories, and pagination. Files are sorted by creation date (newest first).

Parameters to validate before calling

• page (number, optional) — Page number (default: 1)
• limit (number, optional) — Files per page (default: 50, max: 200)

Get all groups from a sweepstakes. Use fetch_sweepstakes first to get the sweepstakes_token. Groups are used to organize and segment participants. Use them internally for tool chaining but present only human-readable information (group names, statuses).

fetch_groups

When to use

Get all groups from a sweepstakes. Use fetch_sweepstakes first to get the sweepstakes_token. Groups are used to organize and segment participants. Use them internally for tool chaining but present only human-readable information (group names, statuses).

Fetch a paginated list of invoices for the account, with optional filters by status and date range. Requires the Invoices module enabled on the account — on a 403 "module is not enabled" error, do NOT retry; tell the user to contact Sweeppea support. The Summary block (totals and counts) covers the ENTIRE filtered set, not just the current page. IsOverdue is derived at read time (stored status stays "pending"). Archived invoices are included with Archived: true. For full details of one invoice (line items, notes, QR) use get_invoice.

Get all notes for your account. Notes are automatically decrypted and returned in reverse chronological order. Use them internally for tool chaining but present only human-readable information (titles, content, dates).

fetch_notes

When to use

Get all notes for your account. Notes are automatically decrypted and returned in reverse chronological order. Use them internally for tool chaining but present only human-readable information (titles, content, dates).

Get open support tickets with pagination (20 per page) and search. Returns summary info only — use get_ticket with the case number to get full ticket details including notes, files, and collaborators. Supports filtering by subject/description text, platform (renaissance, api, general, overture, winners), and priority (1=Low, 2=Medium, 3=High).

fetch_open_tickets

When to use

Get open support tickets with pagination (20 per page) and search. Returns summary info only — use get_ticket with the case number to get full ticket details including notes, files, and collaborators.

Get a paginated list of participants from a sweepstakes (20 per page). Use fetch_sweepstakes first to get the sweepstakes_token. Supports search by name, email, or phone, and filtering by opt-in date or date range. Results are sorted by creation date (newest first). For full participant details, use get_participant with a specific email, phone, or token. NEVER fabricate or hallucinate participant data — only report what the API returns. Use them internally for tool chaining but present only human-readable information (names, emails, phones, dates).

Get all official rules for a sweepstakes including primary and secondary rules. Use fetch_sweepstakes first to get the sweepstakes_token.

fetch_rules

When to use

Get all official rules for a sweepstakes including primary and secondary rules. Use fetch_sweepstakes first to get the sweepstakes_token.

Pre-calls required

1. fetch_sweepstakes if the user gave you a sweepstakes name instead of a token

Parameters to validate before calling

• sweepstakes_token (string, required) — The sweepstakes token to fetch rules from (UUID format)

Get all scheduled drawings for a sweepstakes. Use fetch_sweepstakes first to get the sweepstakes_token. Returns all scheduled drawings regardless of status, sorted by creation date (newest first). Use them internally for tool chaining but present only human-readable information (dates, times, status, winner counts).

fetch_scheduled_drawings

When to use

Get all scheduled drawings for a sweepstakes. Use fetch_sweepstakes first to get the sweepstakes_token. Returns all scheduled drawings regardless of status, sorted by creation date (newest first).

Get all US states including DC, Puerto Rico, and US territories. Returns full names and two-letter abbreviations.

fetch_states

When to use

Get all US states including DC, Puerto Rico, and US territories. Returns full names and two-letter abbreviations.

Fetch the aggregated report of a survey: visit/start/complete totals, completion rate and times, device and browser breakdown, daily timeline, and per-question answer distributions. Use fetch_surveys first to get the survey_token. Requires the Surveys module enabled — on 403 "module is not enabled", do NOT retry; tell the user to contact Sweeppea support. Distributions are capped at 25 buckets — the long tail counts toward TotalAnswers but does not travel (Truncated flag). A survey with no traffic returns the full structure with zeros — report that honestly, never invent activity.

Fetch individual survey responses (paginated, newest first) with each answer. Use fetch_surveys first to get the survey_token. Requires the Surveys module enabled — on 403 "module is not enabled", do NOT retry; tell the user to contact Sweeppea support. PRIVACY: include_metadata adds PII (IP address, user agent, device) — keep it false unless the user explicitly needs it, and NEVER copy that metadata into notes, tickets or any other field. ParticipantToken is null when no contact info was collected.

Fetch a paginated list of surveys, optionally filtered by sweepstakes, enabled state or archived state. An empty filter returns all surveys in the account. Requires the Surveys module enabled — on 403 "module is not enabled", do NOT retry; tell the user to contact Sweeppea support. IsLocked is derived at read time: true when the survey already has responses (its question structure can no longer be replaced). Questions are NOT included here — use get_survey for the full question set. DISPLAY RULE: never show SurveyToken UUIDs; present survey names, counts and the shareable PublicLink instead.

Get all sweepstakes associated with your account. Returns a list of all sweepstakes with their details. Use tokens internally for tool chaining but present only human-readable information (names, dates, statuses) to the user.

fetch_sweepstakes

Get all sweepstakes associated with your account. Returns a list of all sweepstakes with their details. Use tokens internally for tool chaining but present only human-readable information (names, dates, statuses) to the user.

Get all available timezones with IANA identifiers, abbreviations, and UTC offsets. Use this tool whenever a timezone needs to be determined for any operation. DEFAULT: If the correct timezone cannot be determined, always use TimezoneId 7 (Eastern Standard Time - America/New_York).

fetch_timezones

When to use

Get all available timezones with IANA identifiers, abbreviations, and UTC offsets. Use this tool whenever a timezone needs to be determined for any operation. DEFAULT: If the correct timezone cannot be determined, always use TimezoneId 7 (Eastern Standard Time - America/New_York).

Get all To-Do items with pagination (20 per page), search, and advanced filters. ADMIN ONLY: This tool requires admin privileges. Non-admin users will receive a 403 Forbidden error from the API.

fetch_todos

When to use

Get all To-Do items with pagination (20 per page), search, and advanced filters. ADMIN ONLY: This tool requires admin privileges. Non-admin users will receive a 403 Forbidden error from the API.

Parameters to validate before calling

• page (number, optional) — Page number (default: 1, 20 items per page).

Get all wallet transactions for your account including credits, debits, and payment details.

fetch_wallet_transactions

When to use

Get all wallet transactions for your account including credits, debits, and payment details.

Get winners from a sweepstakes with pagination. Use fetch_sweepstakes first to get the sweepstakes_token. Winners are sorted by draw date (most recent first). Supports search by email or phone. Use them internally for tool chaining but present only human-readable information (names, emails, draw dates).

fetch_winners

When to use

Get winners from a sweepstakes with pagination. Use fetch_sweepstakes first to get the sweepstakes_token. Winners are sorted by draw date (most recent first). Supports search by email or phone.

Search US zip codes by zip code, city, or state name. Returns up to 10 results with city and state details.

fetch_zipcodes

When to use

Search US zip codes by zip code, city, or state name. Returns up to 10 results with city and state details.

Parameters to validate before calling

• search (string, required) — Search term: zip code, city name, or state name (case-insensitive)

Get business information for a Sweeppea account. Returns company details, address, and business settings.

get_business

When to use

Get business information for a Sweeppea account. Returns company details, address, and business settings.

Get a single calendar event by its token. Use fetch_calendar_events first to get event tokens.

get_calendar_event

When to use

Get a single calendar event by its token. Use fetch_calendar_events first to get event tokens.

Parameters to validate before calling

• event_token (string, required) — The event token (UUID format)

Get all form fields for a sweepstakes entry page. Use fetch_sweepstakes first to get the sweepstakes_token. Call this before add_participant to discover required fields. Returns field names, types, and whether they are required.

get_entry_fields

When to use

Get all form fields for a sweepstakes entry page. Use fetch_sweepstakes first to get the sweepstakes_token. Call this before add_participant to discover required fields. Returns field names, types, and whether they are required.

Get entry page settings for a sweepstakes. Use fetch_sweepstakes first to get the sweepstakes_token. Returns all configuration: display, colors, spacing, entry settings, compliance, confirmation page, winners page, age gate, AMOE, geolocation, analytics, social media follows, sharing rewards, bonus entries, and sponsor profiles. Use this before update_entry_settings to see current values.

get_entry_settings

When to use

Get entry page settings for a sweepstakes. Use fetch_sweepstakes first to get the sweepstakes_token.

Generate a short-lived presigned S3 URL to download or preview a file from the user's Drive. The URL embeds the correct Content-Type and Content-Disposition headers, and the actual transfer happens directly between the client and S3 (no data transfer cost on this endpoint).

get_file_url

When to use

Generate a short-lived presigned S3 URL to download or preview a file from the user's Drive. The URL embeds the correct Content-Type and Content-Disposition headers, and the actual transfer happens directly between the client and S3 (no data transfer cost on this endpoint).

Fetch the full detail of a single invoice: line items, payment info, public link, QR code, stats and event timeline. Use fetch_invoices first to get the invoice_token. Requires the Invoices module enabled on the account — on a 403 "module is not enabled" error, do NOT retry; tell the user to contact Sweeppea support. Set include_events and include_qr_code to false for a lighter payload when you only need the invoice fields. The event timeline is capped at the 200 most recent events. DISPLAY RULE: never show InvoiceToken/PublicToken UUIDs; the PublicLink URL and InvoiceNumber ARE shareable.

Fetch a single note by its token. Use fetch_notes first to get the note_token. The note content is automatically decrypted in the response.

get_note

When to use

Fetch a single note by its token. Use fetch_notes first to get the note_token. The note content is automatically decrypted in the response.

Parameters to validate before calling

• note_token (string, required) — The unique token (UUID) of the note to retrieve

Fetch full details of a single participant from a sweepstakes by token, email, or phone. At least one search parameter is required. Use fetch_sweepstakes first to get the sweepstakes_token. For listing participants, use fetch_participants instead. NEVER fabricate, invent, or hallucinate participant data under any circumstance. If no result is returned by the API, report exactly that — do not guess names, emails, or counts. Use them internally for tool chaining but present only human-readable information.

Get the current account's plan and usage telemetry. Returns the AUTHORITATIVE plan limits AND real-time usage so you can warn the user when they are approaching a cap.

Get user profile information for a Sweeppea account. Returns user details like name, email, and account settings.

get_profile

When to use

Get user profile information for a Sweeppea account. Returns user details like name, email, and account settings.

Fetch the full detail of a single survey, including its complete question set (sorted by Page then Order, no pagination — max 250 questions). Use fetch_surveys first to get the survey_token. Requires the Surveys module enabled — on 403 "module is not enabled", do NOT retry; tell the user to contact Sweeppea support. IsLocked true means the survey has responses and its questions can no longer be replaced. For aggregated results use fetch_survey_report; for individual responses use fetch_survey_responses. DISPLAY RULE: never show SurveyToken/QuestionToken UUIDs; the PublicLink IS shareable.

Get full details of a support ticket by case number. Use fetch_open_tickets or fetch_closed_tickets first to find tickets, then use this tool with the case number to get complete information including notes, files, collaborators, and statistics. Present only human-readable information (case number, subject, dates, notes).

get_ticket

When to use

Get full details of a support ticket by case number. Use fetch_open_tickets or fetch_closed_tickets first to find tickets, then use this tool with the case number to get complete information including notes, files, collaborators, and statistics.

Verify connection to Sweeppea API and validate your API key. Use this to test if your credentials are working correctly.

health_check

When to use

Verify connection to Sweeppea API and validate your API key. Use this to test if your credentials are working correctly.

Returns a simple Hello World greeting message

hello_world

When to use

Returns a simple Hello World greeting message in Japanese

Parameters to validate before calling

• name (string, optional) — Name to include in greeting (optional)

Pause a sweepstakes, setting it to inactive status while preserving all data. Use fetch_sweepstakes first to get the sweepstakes_token. Participants will not be able to enter while paused.

pause_sweepstakes

When to use

Pause a sweepstakes, setting it to inactive status while preserving all data. Use fetch_sweepstakes first to get the sweepstakes_token. Participants will not be able to enter while paused.

Pre-calls required

1. fetch_sweepstakes if the user gave you a sweepstakes name instead of a token

Close/resolve an open support ticket. Use fetch_open_tickets first to get the case_id.

resolve_ticket

When to use

Close/resolve an open support ticket. Use fetch_open_tickets first to get the case_id.

Parameters to validate before calling

• case_id (string, required) — The case number of the ticket to close (e.g., "ABC1234")

Schedule a future winner drawing for a sweepstakes. Use fetch_sweepstakes first to get the sweepstakes_token, and fetch_groups for group tokens. CRITICAL: This is a production operation. ALWAYS confirm with the user before scheduling. Requires at least one eligible participant. Winner count cannot exceed available participants. Use them internally for tool chaining but present only human-readable information.

schedule_drawing

When to use

Schedule a future winner drawing for a sweepstakes. Use fetch_sweepstakes first to get the sweepstakes_token, and fetch_groups for group tokens.

Send a file from the user's Drive as an email attachment. Max attachment size: 5 MB. Files larger than 5 MB are rejected. The email is sent using the Sweeppea email template. Each transmission is recorded in the file's sharing history. PRIVACY: The recipient email must be provided by the user — never assume or fabricate email addresses.

send_file

When to use

Send a file from the user's Drive as an email attachment. Max attachment size: 5 MB. Files larger than 5 MB are rejected. The email is sent using the Sweeppea email template.

Reactivate a paused sweepstakes, allowing participants to enter again. Use fetch_sweepstakes first to get the sweepstakes_token.

unpause_sweepstakes

When to use

Reactivate a paused sweepstakes, allowing participants to enter again. Use fetch_sweepstakes first to get the sweepstakes_token.

Pre-calls required

1. fetch_sweepstakes if the user gave you a sweepstakes name instead of a token

Parameters to validate before calling

• sweepstakes_token (string, required) — The unique identifier (token) of the sweepstakes to unpause

Update the bonus entries value for a participant in a sweepstakes. This overwrites the current value. Use get_participant first to check current bonus entries.

update_bonus_entries

When to use

Update the bonus entries value for a participant in a sweepstakes. This overwrites the current value. Use get_participant first to check current bonus entries.

Pre-calls required

1. fetch_sweepstakes if the user gave you a sweepstakes name instead of a token

Parameters to validate before calling

• sweepstakes_token (string, required) — The sweepstakes token (UUID format)

Update an existing calendar event. Use fetch_calendar_events first to get the event_token. Supports partial updates - only provide fields you want to change. Note: Cannot update events to past dates.

update_calendar_event

When to use

Update an existing calendar event. Use fetch_calendar_events first to get the event_token. Supports partial updates - only provide fields you want to change. Note: Cannot update events to past dates.

Parameters to validate before calling

• event_token (string, required) — The event token to update (UUID format, required)

Update entry page settings (1-5 fields per request). Call get_entry_settings first to see all available field names and current values. COMPLIANCE FIELDS: TermsConditionsSwitch, TermsConditionsMessage, SelectedOfficialRules, ActivateAgeGateSwitch, AgeGateHeadline, AgeGateDescription, AgeGateMinAge, ActivateAmoeSwitch, AmoeHeadline, AmoeDescription, AmoeEntries, EnableInternationalAMOEForm, GeoLocation, GeoLocationIsRequiredToRenderPage, AllowParticipantsWithinFences.

Update the name of an existing group within a sweepstakes. Use fetch_sweepstakes first to get the sweepstakes_token, then fetch_groups to get the group_token.

update_group

When to use

Update the name of an existing group within a sweepstakes. Use fetch_sweepstakes first to get the sweepstakes_token, then fetch_groups to get the group_token.

Pre-calls required

1. fetch_sweepstakes if the user gave you a sweepstakes name instead of a token

Parameters to validate before calling

• sweepstakes_token (string, required) — The sweepstakes token (UUID format)

Update an existing invoice. Partial update: anything omitted keeps its stored value, BUT items and bill_to are REPLACED as a whole when sent (never merged) — to edit one line item, send the complete new items array. STATE MACHINE: draft → pending → paid, with cancelled reachable from draft or pending. Status "pending" publishes, "cancelled" cancels. Reverting to draft is rejected (400). Paid and cancelled invoices are immutable history — the API answers 409; do not retry, explain to the user. Publishing does NOT email the recipient. Totals are recomputed server-side.

Update an existing note. Use fetch_notes first to get the note_token. Supports partial updates. HTML tags: h1-h6, p, a, br, strong, i, ul, ol, li. No scripts/iframes. Do NOT use <br>&nbsp; between sections.

update_note

When to use

Update an existing note. Use fetch_notes first to get the note_token. Supports partial updates. HTML tags: h1-h6, p, a, br, strong, i, ul, ol, li. No scripts/iframes. Do NOT use <br>&nbsp; between sections.

Parameters to validate before calling

• note_token (string, required) — The note token to update (UUID format)

Update an existing official rules document. Use fetch_rules first to get the rules_token. UPDATABLE FIELDS: Only these fields can be modified: title, document_content, abbreviated_rules_shopify. NOT UPDATABLE: sweepstakes association, primary status, creation date, and any other field NOT listed above cannot be changed after creation. Do NOT tell the user they can update fields that are not supported by this endpoint. If they ask to change something not updatable, explain it cannot be modified after creation.

update_rule

When to use

Update an existing official rules document.

Update an existing survey. Partial update: only the fields you send are touched — EXCEPT questions, which is a FULL REPLACEMENT of the entire question set (sending [] deletes all questions; omitting it leaves them untouched). If the survey already has responses its structure is locked: replacing questions is rejected with 409 — do not retry, explain to the user that responses protect the structure. At least one of survey_name, status, archived, settings or questions is required. Use status false to disable a survey without losing data (the safe alternative to delete_survey).

Update an existing sweepstakes. Use fetch_sweepstakes first to get the sweepstakes_token. UPDATABLE FIELDS: Only these fields can be modified: sweepstakes_name, start_date, end_date, start_time, end_time. NOT UPDATABLE: handler, sweepstakes_type, prize value/description, calendar settings, sync options, and any other field NOT listed above cannot be changed after creation. Do NOT tell the user they can update fields that are not supported by this endpoint. If they ask to change something not updatable, explain it cannot be modified after creation.

Update an open support ticket. Use fetch_open_tickets first to get the case_id. Only open tickets can be updated. FORMAT: Only these HTML tags are allowed in description: <b>, <strong>, <i>, <hr>, <br>. NEVER insert scripts, iframes, event handlers (onclick, onerror, etc.), style tags, or any executable code. SPACING: Do NOT use <br>&nbsp; — it creates ugly blank blocks in the UI. Use <br> for line breaks within text only.

update_ticket

When to use

Update an open support ticket. Use fetch_open_tickets first to get the case_id. Only open tickets can be updated.

Update an existing To-Do item. Supports partial updates — only provide the fields you want to change. ADMIN ONLY: This tool requires admin privileges. Non-admin users will receive a 403 Forbidden error from the API. FORMAT: Only these HTML tags are allowed in description: <b>, <strong>, <i>, <hr>, <br>. NEVER insert scripts, iframes, event handlers (onclick, onerror, etc.), style tags, or any executable code. SPACING: Do NOT use <br>&nbsp; — it creates ugly blank blocks in the UI. Use <br> for line breaks within text only.

update_todo

When to use

Update an existing To-Do item.

Upload a file to the user's Drive. The file must be base64-encoded. Max file size: 10 MB. Allowed types: PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT, CSV, JPG, JPEG, PNG, GIF, WEBP, SVG, BMP. Filenames are sanitized (spaces to underscores, special characters removed).

upload_file

When to use

Upload a file to the user's Drive. The file must be base64-encoded. Max file size: 10 MB. Allowed types: PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT, CSV, JPG, JPEG, PNG, GIF, WEBP, SVG, BMP. Filenames are sanitized (spaces to underscores, special characters removed).