ReminderIt

ReminderIt immediately places a consent verification call to the number; reminders
are only delivered after that person accepts. Only add someone the user genuinely
has permission to call, and confirm the number digit by digit before submitting —
a typo calls a stranger.

Args:
    name: The person's name, used in the call greeting.
    phone: Their number in full E.164 format, e.g. "+447700900123".
    relationship: Optional label for the user's own reference, e.g. "Mother".

Args:
    reminder_id: Reminder whose voice override should be cleared.

This places REAL calls, so get the schedule right the first time: resolve the
timezone via whoami, and read the result back to the user afterwards.

Provide exactly one schedule: run_at (one-off), cron_expr, or interval_days.
Leave the voice arguments empty to use the account's default voice.

Args:
    title: Short label shown in the app, e.g. "Morning pills" (max 120 chars).
    message_text: Exactly what the voice says on the call, written as speech —
        "Time to take your blood pressure tablet." (max 600 chars). Avoid
        abbreviations and symbols that sound wrong when read aloud.
    type: "once" for a single call, "recurring" for a repeating schedule.
    timezone: IANA timezone the schedule is anchored to, e.g. "America/New_York".
    run_at: ISO 8601 local datetime for a one-off call. Required when type="once".
    cron_expr: Cron schedule for recurring calls, e.g. "0 8 * * 1-5" = weekdays 8am.
    interval_days: Repeat every N days (1-365). Simpler alternative to cron_expr.
    start_date: ISO date; the recurring series does not fire before this.
    end_date: ISO date; the series stops after this (e.g. end of a medication course).
    skip_dates: Local dates to skip, ["2026-08-12"] format — holidays, travel.
    recipient_id: Call a care-recipient (from list_recipients) instead of the
        account owner. The recipient must have consented.
    voice_id: Override the account voice for this reminder only (see list_voices).
    personality: Speaking style — "gentle", "cheerful", "professional", "energetic".
    language: BCP-47 language tag for the spoken message, e.g. "en-GB", "hi-IN".
    speaking_rate: Speech speed, 0.8 (slower) to 1.2 (faster). 1.0 is normal.
    whatsapp_fallback: Send the reminder on WhatsApp if the call isn't answered.
    email_fallback: Also email the reminder if the call isn't answered.

Confirm with the user first, quoting the reminder's title and schedule. If they may
want it later, use pause_reminder instead.

Args:
    reminder_id: Reminder to delete (from list_reminders).

Use this to answer "did it call me?", "why didn't I get it?", or to confirm a
reminder is really firing. Statuses: completed/answered = the person picked up;
no-answer/busy = rang but nobody answered (a WhatsApp fallback usually follows);
failed = the call could not be placed; blocked = suppressed before dialling (no
credit, unsupported country, or a recipient who hasn't consented);
sent/delivered/read = a WhatsApp or email fallback.

Args:
    limit: Number of recent delivery records (1-50, default 10).

Use when you need detail that list_reminders omits — the exact spoken message,
cron expression, skip dates, channel toggles, or voice override. Also use this to
read current values before a partial update, so you don't overwrite settings.

Args:
    reminder_id: Reminder ID from list_reminders.

Needed to get the recipient_id for create_reminder. Consent status matters: only
"confirmed" recipients receive calls; "pending" means they haven't accepted the
verification call yet, so reminders to them will be blocked.

Start here for almost any request about existing reminders — it is the only way to
discover reminder IDs, which every other reminder tool needs. Paused reminders show
WHY they are paused (out_of_credit, destination_not_allowed, completed).

Answers "what's coming up?" better than list_reminders, because it expands
recurring rules into actual upcoming occurrences and merges them into one timeline.

Args:
    limit: How many upcoming occurrences to return (1-50, default 10).

Call before set_voice_settings or set_reminder_voice to get valid voice IDs —
never guess one. Voices marked premium may not be included in every plan; if the
account's plan doesn't include one, calls fall back to a standard voice.

Prefer this over delete_reminder whenever the user might want it back — it is
fully reversible with resume_reminder.

Args:
    reminder_id: Reminder to pause (from list_reminders).

Returns a URL to the generated audio. Useful when a user is deciding between
voices, or wants to check how their own reminder wording will sound.

Args:
    voice_id: Voice ID from list_voices.
    text: Words to speak in the sample. Defaults to a standard demo line; pass the
        user's actual reminder message to preview exactly what they'll hear.
    personality: "gentle", "cheerful", "professional", or "energetic".
    language: BCP-47 tag, e.g. "en-GB".
    speaking_rate: 0.8 to 1.2.

Any reminders targeting them will stop being delivered. Confirm with the user first.

Args:
    recipient_id: Recipient to remove (from list_recipients).

Use when list_recipients shows consent as pending and the person missed the first
call. Don't repeat it more than necessary — each attempt rings their phone.

Args:
    recipient_id: Recipient to re-verify (from list_recipients).

If it was paused automatically for out_of_credit and the account still has no calls
left, it will pause again at the next occurrence — check get_usage and tell the user.

Args:
    reminder_id: Reminder to resume (from list_reminders).

The phone call itself is always attempted. These toggles control the follow-ups:
WhatsApp is on by default, email is off. Note each delivered fallback also consumes
one call from the account's quota.

Args:
    reminder_id: Reminder to configure (from list_reminders).
    whatsapp_fallback: True to send a WhatsApp message when the call is missed.
    email_fallback: True to also email the reminder when the call is missed.

Use when a specific reminder should sound different — a calm, slower voice for
medication; an energetic one for a workout; a different language for a relative.
Call list_voices first to get valid voice IDs, and preview_voice if the user
wants to hear it before committing. Other reminders are unaffected.

Args:
    reminder_id: Reminder to restyle (from list_reminders).
    voice_id: Voice ID from list_voices.
    personality: "gentle", "cheerful", "professional", or "energetic".
    language: BCP-47 tag for the spoken message, e.g. "en-GB", "es-ES", "hi-IN".
    speaking_rate: 0.8 (slower, good for elderly listeners) to 1.2 (faster).

The right way to handle holidays, travel, or a pause of a few days — far better
than deleting a reminder and rebuilding it. This REPLACES the existing skip list,
so include dates the user still wants skipped (read them with get_reminder first).
Pass an empty list to clear all skips.

Args:
    reminder_id: Reminder to adjust (from list_reminders).
    skip_dates: Local dates in "YYYY-MM-DD" form, e.g. ["2026-08-12", "2026-08-13"].

For a single reminder only, use set_reminder_voice instead. Get valid IDs from
list_voices; preview_voice lets the user hear one first.

Args:
    voice_id: Voice ID from list_voices.
    personality: "gentle", "cheerful", "professional", or "energetic".
    language: BCP-47 tag, e.g. "en-US", "en-GB", "hi-IN".
    speaking_rate: 0.8 (slower — often better for elderly listeners) to 1.2 (faster).
    greet_by_name: Whether calls open by greeting the user by name.

Use for "not tomorrow, but keep it going after that". To skip particular calendar
dates instead, use set_skip_dates.

Args:
    reminder_id: Reminder whose next call should be skipped.

The phone will ring within seconds — only do this when the user has asked to test,
and never repeatedly. It consumes one call from their quota and does not change
the schedule.

Args:
    reminder_id: Reminder to test (from list_reminders).

Use for "move it to 7am", "say it differently", "stop after the 20th". To pause or
resume, use pause_reminder / resume_reminder. To change the voice, use
set_reminder_voice. To skip particular dates, use set_skip_dates.

Args:
    reminder_id: Reminder to edit (from list_reminders).
    title: New short label.
    message_text: New spoken message (written as natural speech, max 600 chars).
    cron_expr: New cron schedule, e.g. "0 7 * * *" for daily 7am.
    interval_days: New "every N days" interval (1-365).
    run_at: New ISO 8601 datetime for a one-off reminder.
    timezone: New IANA timezone. Changing this moves every future call.
    start_date: New ISO start date for a recurring series.
    end_date: New ISO end date; the series stops after it.

Two jobs. First, it is the connection check — call it when the user asks "am I
connected?", "which account is this?", or when another tool returns an auth error,
to confirm the API key is valid and see whose account it opens.

Second, call it BEFORE creating or rescheduling a reminder: it returns the user's
saved timezone, so you can schedule silently instead of asking. It also warns when
the phone is unverified or the account is opted out — in either case no reminder can
be delivered, so surface that before scheduling anything.