Tool Catalog

Every tool MIA can call. There are 60 tool files under functions/pivotAiAgent/tools/, organized into 16 category folders. The main chat pipeline registers 51 of them; the onboarding / MIA Tips pipeline registers a 20-tool subset including 8 onboarding-only tools.

Each tool is a module that exports a definition (Anthropic tool schema with name, description, input_schema) and an execute(companyId, input, token, _reqId?, userId?, personaName?) function. The dispatcher is executeTool() in functions/pivotAiAgent/tools/index.ts:192. See Agent SDK for the architecture.

Tool-set membership

• Main chat (51 tools): registered in TOOL_CATALOG at tools/index.ts:96. Sent to Sonnet on every /api/chat data-path request via buildToolSet() — Sonnet picks what it needs.
• Onboarding / MIA Tips (20 tools): imported individually in functions/pivotAiAgent/onboarding-pipeline.ts via its own ONBOARDING_TOOL_MAP. Used by both the new-owner onboarding flow and the MIA Tips configuration UI (differentiated by a flow parameter).
• Always loaded for main chat (CORE_TOOL_DEFINITIONS, tools/index.ts:163): find_employee, get_current_user, set_user_rule, update_company_memory. These are mentioned explicitly so they're not dependent on category-based filtering.

A comment at the top of tools/index.ts mentions a search_tools meta-tool for on-demand discovery. This is aspirational — there is no search_tools in the registered set today; all tools are loaded up front.

Employees (11)

Tool	File	Description	Key inputs	Mutates?
get_employees	employees/getEmployees.ts	List employees with optional filters (role, name search, archived). Optional fields array to slim payload.	role?, search?, archived?, fields?[]	No
find_employee	employees/findEmployee.ts	Resolve employee by name to canonical ID. Call before any tool that needs an employee ID.	name	No
get_employee_rates	employees/getEmployeeRates.ts	Hourly rates per employee per position.	(none)	No
get_current_user	employees/getCurrentUser.ts	Info on the calling manager (name, email, role, ID).	(none)	No
get_employee_availability	employees/getEmployeeAvailability.ts	Weekly availability windows, max days/hours, preferences.	employeeId?	No
get_employee_days_off	employees/getEmployeeDaysOff.ts	Approved days off in a date range.	startDate, endDate, employeeId?	No
create_employee	employees/createEmployee.ts	Create one employee; optionally send invitation email.	name, surname, positions, email?, phone?, ...	Yes
batch_create_employees	employees/batchCreateEmployees.ts	Bulk create from raw CSV.	csvText	Yes
update_employee	employees/updateEmployee.ts	Patch employee profile fields (allow-listed).	employeeId, field overrides	Yes
archive_employee	employees/archiveEmployee.ts	Soft-delete an AI-created employee (must have createdByPivotAiAgent flag).	employeeId	Yes
update_employee_positions	employees/updateEmployeePositions.ts	Update assigned positions/roles with priority + history.	employeeId, positions[]	Yes

Schedule (6)

Tool	File	Description	Key inputs	Mutates?
get_schedule	schedule/getSchedule.ts	Shifts in a date range; filter by employee/position; toggle draft/manual.	startDate, endDate, employeeId?, positionId?, includeManual?, includeDraft?	No
create_shift	schedule/createShift.ts	Create a shift. Tech debt: writes WeeklySchedule/{cid}/{date} directly via Firebase REST because the schedule module has no "create published shift" endpoint yet. File has TODO(refacto-endpoint).	date, employeeId, startTime, endTime	Yes
update_shift	schedule/updateShift.ts	Update an existing shift (pass locator fields from get_schedule).	shiftId, date, employeeId, ...	Yes
delete_shift	schedule/deleteShift.ts	Remove a shift.	shiftId, date, employeeId, positionId, subRoleId, mode	Yes
update_schedule_template	schedule/updateScheduleTemplate.ts	Update the weekly template for a specific role (or copy across roles).	roleId, template	Yes
set_schedule_template (onboarding-only)	schedule/setScheduleTemplate.ts	Write the full weekly daysStructure. Used when the user uploads a picture of an existing schedule.	daysStructure	Yes

Attendance (6)

Tool	File	Description	Key inputs	Mutates?
get_attendance	attendance/getAttendance.ts	Clock punches in a date range.	startDate, endDate, employeeId?	No
get_payroll_issues	attendance/getPayrollIssues.ts	Anomaly detector: ghost punches, overtime, short shifts, labor variance.	startDate, endDate, employeeId?	No
get_payroll_settings	attendance/getPayrollSettings.ts	Effective payroll config (global + latest-period merge).	(none)	No
update_payroll_settings	attendance/updatePayrollSettings.ts	Update payroll settings (frequency, rounding, overtime, tipping, ...).	various optional fields	Yes
get_tips_data	attendance/getTipsData.ts	Tip-out distribution entries (how tips split per shift) — not gross tips earned.	startDate, endDate, employeeId?	No
add_manual_punch	attendance/addManualPunch.ts	Insert manual clock-in/out entries (batch).	entries[]	Yes

Requests (3)

Tool	File	Description	Key inputs	Mutates?
get_requests	requests/getRequests.ts	Employee requests (time-off, swap, replace, availability, emergency). Latest 50.	type, status?	No
approve_request	requests/approveRequest.ts	Approve a request.	requestId/notificationId, type	Yes
decline_request	requests/declineRequest.ts	Decline a request, optional reason.	requestId/notificationId, type, reason?	Yes

AI Memory (5)

Tool	File	Description	Key inputs	Mutates?
set_user_rule	ai-memory/setUserRule.ts	Save a persistent manager rule ("always do X", "never show Y").	rule	Yes
list_user_rules	ai-memory/listUserRules.ts	List all saved rules.	(none)	No
delete_user_rule	ai-memory/deleteUserRule.ts	Delete a rule by ID.	ruleId	Yes
update_company_memory	ai-memory/updateCompanyMemory.ts	Update learned company facts (revenue, labor budget, peak days, ...).	updates (object)	Yes
set_cron_task	ai-memory/setCronTask.ts	Schedule a recurring AI report.	taskName, schedule, description, recipient?	Yes

Tips Rules (4)

Tool	File	Description	Key inputs	Mutates?
save_ai_tips_rule	tips-rules/saveAiTipsRule.ts	Create a tip-distribution rule (strict 30+ field canonical schema).	variableName, variableLabelFr, variableLabelEn, kind, sourceRoleIds?, ...	Yes
update_ai_tips_rule	tips-rules/updateAiTipsRule.ts	Patch an existing rule.	ruleId, partial fields	Yes
delete_ai_tips_rule	tips-rules/deleteAiTipsRule.ts	Remove a rule.	ruleId	Yes
list_ai_tips_rules	tips-rules/listAiTipsRules.ts	List active rules sorted by priority.	(none)	No

Company (4)

Tool	File	Description	Key inputs	Mutates?
get_company_info	company/getCompanyInfo.ts	Company name, jobs/positions, timezone, settings. fields to slim payload.	fields?[]	No
get_company_settings	company/getCompanySettings.ts	Detailed config: schedule rules, attendance flags, feature toggles.	(none)	No
update_company_settings	company/updateCompanySettings.ts	Update schedule rules, feature toggles, company info, visibility policies.	partial fields	Yes
get_integration_status	company/getIntegrationStatus.ts	Active POS / payroll / reservation integrations grouped by category.	(none)	No

Posts (2)

Tool	File	Description	Key inputs	Mutates?
get_posts	posts/getPosts.ts	Recent group-feed posts with comment + reaction counts.	(none)	No
create_post	posts/createPost.ts	Text-only announcement to the group feed.	text	Yes

Chat (3)

The employee-to-employee chat module, not the AI chat.

Tool	File	Description	Key inputs	Mutates?
get_chats	chat/getChats.ts	List the manager's chat conversations.	(none)	No
get_chat_messages	chat/getChatMessages.ts	Recent messages in one chat (call get_chats first for the ID).	chatId	No
send_chat_message	chat/sendChatMessage.ts	Send a text message on behalf of the manager.	chatId, message	Yes

Applicants (2)

Tool	File	Description	Key inputs	Mutates?
get_applicants	applicants/getApplicants.ts	All applicants with status, contact, positions, availability.	status?	No
update_applicant_status	applicants/updateApplicantStatus.ts	Move applicant through pipeline (does not hire — UI required).	applicantId, status	Yes

Sales (1)

Tool	File	Description	Key inputs	Mutates?
get_sales	sales/getSales.ts	POS sales: totals, tips, transactions, per-hour, ratios. Multiple grouping options.	startDate, endDate, groupBy?, period?, hours?, source?, employeeId?, ...	No

Documents (1)

Tool	File	Description	Key inputs	Mutates?
upload_employee_document	documents/uploadEmployeeDocument.ts	Generate styled PDF and upload to employee's profile (warning, write-up, compliance, etc.). Honors locale from find_employee.	employeeId, title, content, documentType?	Yes

Research (2)

Tool	File	Description	Key inputs	Mutates?
web_search	research/webSearch.ts	Brave Search (DuckDuckGo fallback) for current events, labor laws, weather alerts, etc. External API.	query, count?	No
lookup_pivot_help	research/pivotKnowledgeBase.ts	Pivot app knowledge base — how-to guides, feature docs, troubleshooting.	query	No

Weather (1)

Tool	File	Description	Key inputs	Mutates?
get_weather	weather/getWeather.ts	Open-Meteo geocoding + archive/forecast. Public API, no auth.	location, startDate, endDate, includeHistorical?	No

Calculator (1)

Tool	File	Description	Key inputs	Mutates?
calculate	calculator/calculate.ts	Deterministic arithmetic — Mia must never do math in her head. Many ops: add, sub, mul, div, percent_of, cap_max, floor_min, round, divide_equally, sum, avg, min, max, abs, neg.	op, then op-specific fields	No

Onboarding (8) — onboarding/MIA Tips pipeline only

Tool	File	Description	Key inputs	Mutates?
research_business	onboarding/researchBusiness.ts	Look up business by name (Brave Search) for address, industry, size.	businessName, location?	No
create_company	onboarding/createCompany.ts	Create the Pivot company. Uses POST /companiesApi/companies + several PATCH /companies/{id} calls with Mia's privileged token. Falls back to Admin SDK for paths without an endpoint: AIOnboardingSessions/, Companies/{cid}/businessProfile, Users/{uid}/signupPhase.	name, address, ...	Yes
create_positions	onboarding/createPositions.ts	Create the company's job categories and subcategories.	positions[]	Yes
get_onboarding_status	onboarding/getOnboardingStatus.ts	Resume an onboarding session — return checklist and next step.	(none)	No
complete_onboarding	onboarding/completeOnboarding.ts	Mark onboarding complete; flips onboardingCompleted: true.	companyId?	Yes
import_competitor_csv	onboarding/importCompetitorCsv.ts	Parse Agendrix / 7shifts CSV export, stage into ImportStagingArea/, then import.	csvText, format, timezone?	Yes
scrape_agendrix	onboarding/scrapeAgendrix.ts	Log into Agendrix on the user's behalf, scrape roster, import.	email, password, businessName	Yes
scrape_7shifts	onboarding/scrape7shifts.ts	Same as scrape_agendrix but for 7shifts.	email, password, businessName	Yes

Onboarding-pipeline tool set (20)

The onboarding pipeline does not load the full main-chat catalog. Its 20-tool set is the 8 onboarding tools above, plus a curated subset:

• find_employee, get_employees, create_employee, batch_create_employees, update_employee
• get_company_info
• set_schedule_template
• save_ai_tips_rule, update_ai_tips_rule, delete_ai_tips_rule, list_ai_tips_rules
• calculate

The MIA Tips frontend (src/routes/MiaTips/) uses the same backend pipeline with a flow parameter; that's why the tips rule tools live in the onboarding set rather than the main set.

What the "Mutates?" column means

Yes = the tool writes server-side state when it runs (new RTDB rows, status updates, files in Storage, emails sent, Temporal schedules created, etc.). No = the tool is a pure read or an external lookup that leaves the Pivot side unchanged.

The architectural call path is the same either way (executeTool → globalThis.fetch → internal endpoint with the user's Bearer token). The difference is just what the endpoint on the other side does. Because the user's token is forwarded, a mutating tool can only mutate things the calling user has permission to mutate — the AI inherits the user's auth scope. See Security Model: tools inherit user permissions.

Mutation summary

26 tools mutate state (~43%). 34 are read-only or external (~57%). Two tools (create_shift and the onboarding tools) currently bypass the standard HTTP path for some writes — that's tech debt for RTDB paths that don't have an endpoint yet, not an architectural exception. See Agent SDK: exceptions.