Knowledge > Products > Chatbot > Tools

Chatbot Tools

The chatbot has 39 tools organized across 10 categories and 3 plan tiers. Tool schemas are defined in chatbot-tools.ts as OpenAI function-calling definitions. Tool metadata (tier, category, defaults) lives in tool-config.ts. Churches toggle tools on/off via the admin Settings tab; the effective tool set is the intersection of church-enabled tools AND agent-allowed tools (see Tool Filtering below).

All 39 tools are chatbot-capable. A subset (marked below) also works on the voice channel. Tools marked "chatbot only" are disabled for voice because phone calls cannot display links, forms, or long text.

Tier 1 -- Starter (12 tools, always available)

These tools are included on all plans, including Starter. They cover the core church receptionist use case: answering questions, capturing contacts, and taking prayer requests.

Visitor Care

#	Tool	Parameters	What It Does	DB Table	Personas
1	`get_first_visit_info`	visitor_type? (individual, family, elderly, accessibility)	Returns personalized first-visit guidance: dress code, parking, children's check-in, what to expect during service. Tailored by visitor type.	--	welcome, new_member
2	`get_church_directions`	(none)	Returns the church address and a Google Maps directions link. Includes parking instructions and accessible entrances from the church's config.	--	welcome
3	`send_connection_card_link`	(none)	Shares the church's digital connection card URL. Chatbot only -- voice cannot display links inline.	--	welcome, new_member
4	`capture_visitor_contact`	name?, email?, phone?, reason (required)	Saves visitor contact information when voluntarily provided. Requires at least one of email or phone. Fires an admin notification.	`voice_visitor_contacts`	welcome, new_member, pastoral_care, prayer, giving, volunteer

Pastoral Care

#	Tool	Parameters	What It Does	DB Table	Personas
5	`submit_prayer_request`	prayer_text (required), name?, is_confidential?	Records a prayer request. Confidential requests are visible only to pastoral staff. Fires admin notification.	`voice_prayer_requests`	pastoral_care, prayer
6	`request_callback`	contact (required), reason (required), name?, urgency? (normal/urgent)	Creates a callback request so a pastor or staff member can follow up. Urgent flag triggers priority notification.	`voice_callback_requests`	pastoral_care, prayer

Church Information

#	Tool	Parameters	What It Does	DB Table	Personas
7	`get_sermon_info`	(none)	Returns the current sermon topic, series name, and theme verse from the church's voice agent config or organization settings.	--	welcome
8	`get_announcements`	(none)	Returns the church's current weekly announcements and upcoming events.	--	welcome, youth, volunteer

Communication

#	Tool	Parameters	What It Does	DB Table	Personas
9	`lookup_bible_verse`	reference (required), translation? (web/kjv/bbe/oeb-us)	Fetches a Bible verse or passage via public Bible API. Defaults to World English Bible (public domain). Chatbot only.	--	prayer, bible_study, sermon_prep, giving

Giving & Events

#	Tool	Parameters	What It Does	DB Table	Personas
10	`send_giving_link`	context (required), campaign?	Shares giving/donation information: online giving URL, e-Transfer email, or campaign details. Safety rules: never during crisis/prayer, never guilt-trip, max one mention per conversation.	--	welcome, new_member, volunteer, giving
11	`register_for_event`	event_name (required), name (required), email?, phone?, party_size?, notes?	Registers a visitor for a church event. Captures party size and special needs.	`voice_visitor_contacts`	welcome, new_member, youth, volunteer

Safety

#	Tool	Parameters	What It Does	DB Table	Personas
12	`flag_safety_concern`	level (required: warning/urgent/critical), category (required: threat_of_violence/self_harm/predatory_behavior/persistent_abuse/other), description (required), visitor_name?, visitor_contact?	Flags safety concerns to the church admin immediately. Logs a moderation violation and triggers auto-escalation for critical/urgent levels. Available to ALL personas.	`moderation_violations`	ALL

Tier 2 -- Pro (23 additional tools)

Pro adds deeper pastoral care, engagement tracking, discipleship content generation, and community resource tools. Most Pro tools are chatbot-only because they produce long-form content or require form-like input.

Pastoral Care

#	Tool	Parameters	What It Does	DB Table	Personas
13	`book_appointment`	name (required), email (required), reason (required)	Books an appointment via Cal.com if configured; otherwise creates a detailed callback request as fallback.	`voice_callback_requests` (fallback)	pastoral_care
14	`request_pastoral_visit`	name (required), contact (required), location (required), relationship?, urgency? (normal/urgent/emergency), reason?	Requests a hospital, home, or facility visit from pastoral staff. Emergency flag for end-of-life situations.	`voice_callback_requests`	pastoral_care, prayer
15	`report_care_need`	person_in_need (required), description (required), reporter_name?, reporter_contact?, urgency? (normal/urgent)	Reports a community care need -- meals, rides, financial help, or other support. Chatbot only.	`voice_callback_requests`	pastoral_care, youth
16	`grief_support_resources`	situation? (loss/divorce/addiction/crisis/general), specific_need?	Provides grief and crisis support resources: church programs, counseling referrals, support groups, and crisis hotline numbers.	--	pastoral_care, prayer
17	`schedule_counseling`	name (required), email (required), counseling_type? (pre_marital/marriage/grief/addiction/general), preferred_time?, intake_notes?	Schedules pastoral counseling via Cal.com if configured, otherwise creates callback request. Intake notes kept confidential. Chatbot only.	`voice_callback_requests` (fallback)	pastoral_care

Engagement & Connection

#	Tool	Parameters	What It Does	DB Table	Personas
18	`find_small_group`	interests?, life_stage? (young_adult/family/seniors/college/men/women/general), day_preference?	Matches visitors with small groups based on interests, life stage, and schedule preferences.	--	bible_study, small_group, welcome, new_member
19	`signup_for_volunteer_role`	name (required), contact (required), interests?, availability?, skills?	Captures volunteer interest with skills, availability, and ministry area preferences for gift-based placement.	`voice_visitor_contacts`	volunteer, new_member
20	`subscribe_to_updates`	email (required), name?, preferences? (array: weekly_newsletter/events/prayer_updates/youth_ministry)	Subscribes a visitor to church email communications. Chatbot only.	`voice_visitor_contacts`	new_member
21	`send_message_to_staff`	message (required), staff_name?, sender_name?, sender_contact?	Routes a message to a specific staff member by name or role. Creates a callback request with the message content.	`voice_callback_requests`	welcome, new_member
22	`start_visitor_followup`	name (required), email (required), phone?, visit_date?, interests?	Enrolls a new visitor in the follow-up communication sequence for welcome messages and church information. Chatbot only.	`voice_visitor_contacts`	welcome, new_member

Communication

#	Tool	Parameters	What It Does	DB Table	Personas
23	`conversation_summary`	summary (required), tags? (array), sentiment? (positive/neutral/concerned/distressed), follow_up_needed?	Saves a structured summary of the conversation with tags, sentiment, and follow-up flag. Called near end of meaningful conversations. Chatbot only.	`voice_visitor_contacts`	pastoral_care

Children & Family

#	Tool	Parameters	What It Does	DB Table	Personas
24	`register_child_checkin`	parent_name (required), parent_contact (required), children? (array: {name, age, allergies, special_needs}), authorized_pickup?	Pre-registers children before a first visit to reduce check-in friction. Captures allergies, special needs, and authorized pickup list. Chatbot only.	`voice_visitor_contacts`	-- (coordinator tools)
25	`get_kids_info`	child_age?, specific_question?	Returns children's and youth ministry information -- programs by age, check-in procedures, safety protocols, nursery details.	--	welcome, new_member, youth

Church Information

#	Tool	Parameters	What It Does	DB Table	Personas
26	`daily_devotional`	topic?, scripture?	Shares a brief devotional thought anchored in the church's current sermon series or theme verse, tailored to the church's theological tradition. Chatbot only.	--	bible_study, sermon_prep
27	`facility_booking`	name (required), contact (required), facility_type?, date?, time?, purpose?, estimated_attendance?	Submits a request to book a church room or facility (fellowship hall, classroom, sanctuary). Chatbot only.	`voice_callback_requests`	-- (coordinator tools)
28	`find_past_sermon`	topic?, speaker?, scripture?, date_range?	Searches for past sermons by topic, speaker, or scripture reference. Shares current series info and directs to church media archives. Chatbot only.	--	bible_study, sermon_prep
29	`get_worship_playlist`	service_date?	Returns this week's planned worship songs and music style information. Chatbot only.	--	-- (coordinator tools)

Giving & Financial

#	Tool	Parameters	What It Does	DB Table	Personas
30	`submit_benevolence_request`	name (required), contact (required), description (required), household_size?, urgency? (normal/urgent)	Submits a confidential request for financial assistance from the church benevolence fund. Treated with same sensitivity as confidential prayer requests. Chatbot only.	`voice_callback_requests`	giving

Community Resources

#	Tool	Parameters	What It Does	DB Table	Personas
31	`lookup_local_resources`	category? (19 categories: crisis_hotline, food_bank, shelter, counseling, etc.), need_description?	Looks up local community resources configured by the church -- food banks, shelters, counseling centers, crisis numbers, medical clinics, legal aid, utility assistance.	--	pastoral_care, prayer, welcome, giving

Discipleship Content Generation

#	Tool	Parameters	What It Does	DB Table	Personas
32	`search_illustrations`	query (required), scripture_ref?, content_types? (array), limit? (1-10, default 5)	Searches the curated library of 30,000+ sermon illustrations, analogies, poetry, and theological content. Results filtered by the church's theological tradition via RAG embeddings. Chatbot only.	--	bible_study, sermon_prep
33	`generate_devotional`	theme (required), scripture_reference?, audience?, tone? (warm/reflective/encouraging/challenging/contemplative)	Generates a complete devotional: title, scripture, content (300-400 words), reflection questions, prayer, and action step. Uses the church's theological lens. Chatbot only.	--	bible_study, sermon_prep
34	`theological_deep_dive`	scripture_reference (required), compare_traditions?	Provides in-depth theological analysis of a scripture passage within the church's tradition. Includes doctrinal connections, preaching angles, and key commentators. Optional cross-tradition comparison. Chatbot only.	--	bible_study, sermon_prep, small_group
35	`generate_lesson_plan`	topic (required), age_group (required: preschool/elementary/middle_school/high_school/young_adult/adult), duration?, scripture_reference?, learning_goals?	Creates a complete, age-appropriate, timed lesson plan with activities, materials list, and adaptations. Chatbot only.	--	bible_study, sermon_prep, small_group

Tier 3 -- Suite (4 additional tools)

Suite adds advanced admin/analytics tools and AI-drafted follow-up messages. These are operational tools for high-volume churches.

#	Tool	Parameters	What It Does	DB Table	Personas
36	`draft_follow_up_message`	visitor_name (required), conversation_context (required), message_tone? (warm/professional/casual)	AI-drafts a personalized follow-up message that a pastor or staff member can review and send. Chatbot only.	--	-- (all agents)
37	`get_giving_history`	name?, email?	Helps a member access their giving history or tax receipt. Directs them to the church giving platform (no direct ChMS integration yet). Chatbot only.	--	giving
38	`detect_engagement_drop`	member_name?, member_email?	Internal/admin tool -- checks recent interaction history for a specific member. Returns activity summary for the last 90 days. Chatbot only.	--	pastoral_care
39	`generate_weekly_report`	period? (this_week/last_week/last_30_days)	Internal/admin tool -- generates a summary of chatbot activity: visitor contacts, prayer requests, callback requests, and sentiment trends. Chatbot only.	--	pastoral_care

Tool Categories

Tools are organized into 10 categories for the admin UI (tool toggle checkboxes in Settings):

Category	Label	Tool Count
`visitor_care`	Visitor Care	5
`pastoral_care`	Pastoral Care	8
`church_info`	Church Information	8
`communication`	Communication	3
`engagement`	Engagement & Connection	5
`giving_financial`	Giving & Financial	3
`children_family`	Children & Family	2
`admin_background`	Admin Tools	2
`community_resources`	Community Resources	1
`safety`	Safety & Moderation	1

Source: CATEGORY_LABELS in tool-config.ts.

Tool Execution Flow

executeTool(toolName, args, context)
  |
  try:
    _executeToolInner(toolName, args, context)
      |
      switch (toolName):
        case 'submit_prayer_request' -> submitPrayerRequest(args, ctx)
        case 'capture_visitor_contact' -> captureVisitorContact(args, ctx)
        ... (39 cases)
        default -> "Unknown tool" error string
      |
      Each implementation:
        1. Extract and validate args (type coercion, required field checks)
        2. Execute action (Supabase insert, Bible API call, LLM generation, etc.)
        3. Fire admin notification if applicable (fire-and-forget)
        4. Return string result (success message with instructions for the LLM)
  |
  catch:
    Return generic error string (never throws)

The ToolContext passed to every tool:

type ToolContext = {
  churchId: string;          // UUID of the church
  churchName: string;        // Display name
  churchData: Record;        // Full church record (address, phone, website, etc.)
  premiumData: Record;       // premium_churches row (tier, plan, config)
  voiceAgentData: Record;    // church_voice_agents row (if exists)
  sessionId: string;         // Unique chat session ID
  lensId?: number;           // Theological lens ID (from sai_theological_lenses)
  lensName?: string;         // Theological lens name (e.g. "Reformed", "Catholic")
};

Tool Filtering

Tool availability is determined by the intersection of two filters:

1. Church-Enabled Tools (`organization_settings.agent_tool_config`)

Each church has a JSONB column storing which tools they have toggled on:

{
  "chatbot_tools": ["submit_prayer_request", "capture_visitor_contact", ...],
  "voice_tools": ["submit_prayer_request", "request_callback", ...]
}

When no per-church config exists, DEFAULT_TOOL_CONFIG is used -- all tools with chatbotDefault: true in TOOL_CATALOG are enabled (32 of 39 tools). The 7 tools not enabled by default are: book_appointment, draft_follow_up_message, get_giving_history, detect_engagement_drop, generate_weekly_report (all require explicit opt-in or Suite tier).

2. Agent-Allowed Tools (`AGENT_TOOL_MAP` in `agent-prompts.ts`)

Each agent persona has a whitelist of tools it is permitted to use:

pastoral_care: [submit_prayer_request, capture_visitor_contact, request_callback,
                book_appointment, request_pastoral_visit, grief_support_resources,
                report_care_need, schedule_counseling, flag_safety_concern,
                conversation_summary, lookup_local_resources]

welcome:       [capture_visitor_contact, get_church_directions, get_first_visit_info,
                get_sermon_info, get_announcements, send_connection_card_link,
                start_visitor_followup, get_kids_info, find_small_group,
                send_giving_link, register_for_event, flag_safety_concern,
                lookup_local_resources]

prayer:        [submit_prayer_request, capture_visitor_contact, request_callback,
                request_pastoral_visit, lookup_bible_verse, grief_support_resources,
                flag_safety_concern, lookup_local_resources]

youth:         [get_announcements, find_small_group, lookup_bible_verse,
                flag_safety_concern, report_care_need, get_kids_info,
                register_for_event]

bible_study:   [lookup_bible_verse, find_small_group, find_past_sermon,
                daily_devotional, flag_safety_concern, search_illustrations,
                generate_devotional, theological_deep_dive, generate_lesson_plan]

sermon_prep:   [lookup_bible_verse, find_past_sermon, daily_devotional,
                flag_safety_concern, search_illustrations,
                generate_devotional, theological_deep_dive, generate_lesson_plan]

small_group:   [find_small_group, lookup_bible_verse, get_announcements,
                register_for_event, flag_safety_concern,
                generate_lesson_plan, theological_deep_dive]

new_member:    [capture_visitor_contact, get_church_directions, get_first_visit_info,
                send_connection_card_link, start_visitor_followup, find_small_group,
                signup_for_volunteer_role, subscribe_to_updates, get_kids_info,
                send_giving_link, register_for_event, flag_safety_concern]

volunteer:     [signup_for_volunteer_role, capture_visitor_contact, get_announcements,
                send_connection_card_link, send_giving_link, register_for_event,
                flag_safety_concern]

giving:        [get_giving_history, submit_benevolence_request, capture_visitor_contact,
                lookup_bible_verse, send_giving_link, flag_safety_concern,
                lookup_local_resources]

Effective Tool Set

effectiveTools = churchEnabledTools.filter(t => agentAllowedTools.includes(t))

For super-agents (combined specialists like care_support, visitor_guide, ministry_hub, teaching), the agent-allowed set is the union of all constituent persona tool lists.

DB Tables Written To

All tools that persist data write to tables with the voice_ prefix. This is a legacy naming convention from the voice agent -- the tables serve both chatbot and voice channels.

Table	Tools That Write	What Gets Stored
`voice_prayer_requests`	submit_prayer_request	Prayer text, name, confidentiality flag, status
`voice_visitor_contacts`	capture_visitor_contact, signup_for_volunteer_role, register_for_event, start_visitor_followup, subscribe_to_updates, conversation_summary, register_child_checkin	Name, email, phone, reason/interests, status
`voice_callback_requests`	request_callback, request_pastoral_visit, report_care_need, send_message_to_staff, book_appointment (fallback), schedule_counseling (fallback), facility_booking, submit_benevolence_request	Contact, reason, urgency, status
`moderation_violations`	flag_safety_concern (via `logViolation`)	Level, category, description, session info

Tools that read from external APIs or generate content on-the-fly (lookup_bible_verse, daily_devotional, generate_devotional, theological_deep_dive, generate_lesson_plan, search_illustrations) do not write to any table. They return content directly to the LLM for inclusion in the response.

Code References

Tool schemas (OpenAI function definitions): churchwiseai-web/src/lib/chatbot-tools.ts -- TOOL_SCHEMAS object
Tool implementations: churchwiseai-web/src/lib/chatbot-tools.ts -- individual async functions + _executeToolInner switch
Tool metadata and tier assignment: churchwiseai-web/src/lib/tool-config.ts -- TOOL_CATALOG array
Agent-to-tool mapping: churchwiseai-web/src/lib/agent-prompts.ts -- AGENT_TOOL_MAP
Tool-to-agent mapping: churchwiseai-web/src/lib/tool-config.ts -- TOOL_AGENT_MAP
Chat route wiring: churchwiseai-web/src/app/api/chatbot/stream/route.ts -- loads agent_tool_config from organization_settings

Tier 1 -- Starter (12 tools, always available)​

Visitor Care​

Pastoral Care​

Church Information​

Communication​

Giving & Events​

Safety​

Tier 2 -- Pro (23 additional tools)​

Pastoral Care​

Engagement & Connection​

Communication​

Children & Family​

Church Information​

Giving & Financial​

Community Resources​

Discipleship Content Generation​

Tier 3 -- Suite (4 additional tools)​

Tool Categories​

Tool Execution Flow​

Tool Filtering​

1. Church-Enabled Tools (organization_settings.agent_tool_config)​

2. Agent-Allowed Tools (AGENT_TOOL_MAP in agent-prompts.ts)​

Effective Tool Set​

DB Tables Written To​

Code References​

Tier 1 -- Starter (12 tools, always available)

Visitor Care

Pastoral Care

Church Information

Communication

Giving & Events

Safety

Tier 2 -- Pro (23 additional tools)

Pastoral Care

Engagement & Connection

Communication

Children & Family

Church Information

Giving & Financial

Community Resources

Discipleship Content Generation

Tier 3 -- Suite (4 additional tools)

Tool Categories

Tool Execution Flow

Tool Filtering

1. Church-Enabled Tools (`organization_settings.agent_tool_config`)

2. Agent-Allowed Tools (`AGENT_TOOL_MAP` in `agent-prompts.ts`)

Effective Tool Set

DB Tables Written To

Code References