List the clinic's doctors with their specialty and usual weekly hours.

Use this first when the caller does not name a doctor, or asks who they can see for a particular problem. The returned doctor_id is what check_availability and book_appointment expect.

The availability_summary is the regular weekly pattern, not live openings — call check_availability for actual free slots.

Example: list_doctors()

Find open appointment slots for a doctor, in clinic-local time.

Always call this before book_appointment so you offer times that are genuinely free. Slots already in the past are excluded automatically.

If the requested date has nothing open, next_available holds the next three openings after it, so you can offer an alternative instead of a dead end.

Args: doctor_id: From list_doctors. date: Clinic-local 'YYYY-MM-DD'. Defaults to today. days_ahead: How many days to scan, starting at date. Use 7 for "sometime next week".

Example: check_availability(doctor_id=1, date="2027-01-25", days_ahead=3)

Search patients by partial name or phone number.

Use this before booking for someone who says they have been here before.

When count is greater than 1, ask the caller which record is theirs — do not guess. Two people share a surname far more often than you would like, and booking the wrong record is worse than asking one extra question. A count of 0 means they are new: use register_patient.

Example: find_patient(query="Shah") or find_patient(query="9876543210")

List appointments, filtered by any combination of patient, doctor, date and status.

Use this to answer "when is my appointment?", to find the appointment_id needed by reschedule_appointment or cancel_appointment, or to review a doctor's day.

With no filters it returns everything, so pass at least one for a busy clinic.

Args: patient_id: From find_patient. doctor_id: From list_doctors. date: Clinic-local 'YYYY-MM-DD'. status: One of booked, rescheduled, cancelled, completed, no_show.

Example: get_appointments(patient_id=1, status="booked")

Retrieve the intake form for an appointment, plus a ready-to-read doctor brief.

doctor_brief is a single paragraph written to be absorbed in about ten seconds — read that to the doctor rather than reciting every field.

Returns submitted: false when no intake has been taken yet, which is your cue to collect one with submit_intake.

Example: get_intake(appointment_id=12)

Answer a question about the clinic: timings, fees, location, payment, insurance.

Use this for anything informational rather than transactional.

Read the result carefully before replying:

• match: "high" — read the answer back as-is.

• match: "medium" — offer it, but check you understood ("did you mean...?").

• match: "none" — say you will check with the front desk. Do NOT improvise an answer about fees, insurance or policy; a confident wrong answer about money is worse than a short delay.

Medical questions return the clinic's standard redirect to the doctor. Read it as written and offer to book an appointment — never supplement it with clinical information of your own.

Example: answer_faq(question="what are your timings on saturday?")

Give a doctor-by-doctor overview of one day: appointments, free time, and gaps.

Use this for "what does today look like?" or when staff want to know where attention is needed. pending_intakes and unsent_reminders are the actionable parts — they are the work the front desk still has to do.

Args: date: Clinic-local 'YYYY-MM-DD'. Defaults to today.

Example: daily_summary(date="2027-01-25")

Register a new patient, or return the existing record for that phone number.

Call find_patient first. If the phone number is already on file this returns that patient with created: false instead of creating a duplicate — so a repeat caller keeps one history rather than several.

Confirm the spelling of the name and the phone number with the caller before calling this.

Args: name: Full name as the patient gives it. phone: Any common format; '+91 98765-43210' and '+919876543210' are treated as the same number. dob: 'YYYY-MM-DD', optional but useful for distinguishing same-name patients. notes: Anything the front desk should remember. Not clinical notes.

Example: register_patient(name="Rajesh Shah", phone="+919876543210", dob="1968-04-12")

Book an appointment and queue a reminder for 24 hours beforehand.

Call check_availability first and offer the caller a real opening. Read the returned confirmation back to them.

The slot must be free, inside the doctor's working hours, and aligned to their appointment grid. If it is taken, the error names the nearest alternatives — offer those rather than repeating the request.

Args: patient_id: From find_patient or register_patient. doctor_id: From list_doctors. starts_at: Clinic-local ISO 8601, e.g. '2027-01-25T18:00'. Not UTC. reason: Why they are coming, in the caller's own words.

Example: book_appointment(patient_id=1, doctor_id=1, starts_at="2027-01-25T18:00", reason="diabetes follow-up")

Move an existing appointment to a new time and update its reminder.

Use check_availability first to confirm the new time is free. The old slot is released and the 24-hour reminder is re-queued for the new time.

Cancelled appointments cannot be rescheduled — book a new one instead.

Args: appointment_id: From get_appointments. new_starts_at: Clinic-local ISO 8601, e.g. '2027-01-27T09:30'.

Example: reschedule_appointment(appointment_id=12, new_starts_at="2027-01-27T09:30")

Cancel an appointment. Requires explicit confirmation.

Call it first WITHOUT confirm to get a preview of exactly what would be cancelled. Read that back to the caller, and only call again with confirm=True once they have said yes.

This two-step gate exists because cancelling is not reversible from here — a mistakenly cancelled slot may be taken by someone else within minutes.

Confirming releases the slot and cancels the pending reminder.

Args: appointment_id: From get_appointments. confirm: Must be True to actually cancel.

Example: cancel_appointment(appointment_id=12) # preview cancel_appointment(appointment_id=12, confirm=True) # actually cancel

Record pre-visit intake for an appointment and regenerate the doctor brief.

Collect this after booking. Ask about medications and allergies explicitly — both change what the doctor can safely prescribe, and "no answer" is not the same as "none".

Record what the patient says in their own words. Do not interpret symptoms, suggest what they might indicate, or add clinical terminology of your own.

Re-submitting replaces the previous intake, so it is safe to call again if the caller corrects themselves.

Args: appointment_id: From get_appointments or book_appointment. chief_complaint: The main reason for the visit, in one line. symptoms: What they are experiencing, as described. duration: How long it has been going on, e.g. "about 3 weeks". current_medications: What they take now, including dosage if offered. allergies: Known allergies, or "none reported" if they say none. notes: Anything else logistically relevant.

Example: submit_intake(appointment_id=12, chief_complaint="blood sugar review", symptoms="tired in the afternoons", duration="2 months", current_medications="metformin 500mg twice daily", allergies="penicillin")

Send this appointment's reminder now, ahead of its scheduled time.

Use when a caller asks to be reminded again, or to confirm details in writing. Normal reminders go out on their own via process_due_reminders — you do not need this for routine bookings.

Delivery goes through the configured channel: printed to the server log by default, or SMS when Twilio is configured.

Example: send_reminder(appointment_id=12)

Send every reminder that has come due. Run this periodically.

Picks up all pending reminders whose send time has passed and whose appointment is still active. Reminders for cancelled appointments are dropped rather than sent. A failed delivery stays pending for the next run.

Args: limit: Maximum to process in one pass.

Example: process_due_reminders()

Add an entry to the clinic FAQ so future callers get a consistent answer.

Use this when staff tell you something the FAQ does not cover yet, or after answer_faq returns match: "none" and a human supplies the answer.

Only for clinic logistics — timings, fees, policies, facilities. Never add medical guidance; clinical questions must keep routing to the doctor.

Args: question: The question as a caller would ask it. answer: The exact wording to read back. Write it as speech, not a document. keywords: Comma-separated search terms, including likely synonyms and misspellings, e.g. "parking,park,vehicle,two wheeler,car".

Example: add_faq(question="Do you have parking?", answer="Yes, free two-wheeler parking is available at the rear.", keywords="parking,park,vehicle,two wheeler,bike,car")