Gusto

SIGNUP/ONBOARDING PHASE tool. Requires an existing company — if the account does not have one yet, this reports company_exists false and next_step create_company; call create_company, then retry. Returns the onboarding status for a company's current experience. The current experience includes its questions — each with a key, a description, whether it has been answered, whether it is required, and a value_schema describing the fields its answer expects (field name, type, and allowed enum values). Use the value_schema to construct the value for save_company_onboarding_answer without guessing field names. Some answers are resolved with a helper tool rather than the value_schema alone: for `industry_selection` call search_business_info (type "industry"), present its candidates and let the user pick one rather than choosing for them — unless they name a code themselves, which already is their pick — and never guess NAICS/SIC codes. Separately, some large, well-known fields are free-text coded — their value_schema shows a string array with no enum list (e.g. states_employees_work_in, international_employees_countries). For these, collect the user's answer in natural language and map it to canonical codes yourself: US states as 2-letter uppercase codes including DC and PR (other US territories are not accepted), and countries as ISO 3166-1 alpha-2 (e.g. GB, IN, MX) — don't present the full list as options. A save with an invalid code returns the allowed values so you can correct it. Also returns total_questions and answered_questions counts (over every question listed here, required or not; questions withheld from this list are not counted). DRIVING ONBOARDING — work through the questions with the user and save each answer with save_company_onboarding_answer. Each question's required flag indicates whether it must be answered for onboarding to proceed. Required questions (required is true) are mandatory — collect an answer for every one, and do NOT offer the user the option to skip them. Only optional questions (required is false) may be skipped — surface them and offer to capture an answer, but make clear the user is free to skip them. Setup is complete once all required questions are answered — optional questions may stay unanswered, so do NOT treat answered_questions == total_questions as the bar. Bank details are withheld from this list entirely and are collected by connect_bank_via_plaid, so every listed question can be answered while the bank account is still outstanding — the counts cannot tell you that, and next_step is what surfaces it: detail connect_bank where the Plaid tool is available, otherwise a hand-off to Gusto to add the account there. Always follow next_step rather than inferring from this list that setup is done. When summarising what is left for the user, say the bank account still needs connecting unless next_step shows it is done — otherwise the summary omits a required step and the user has no way to know it is coming. IMPORTANT - the question list is dynamic; saved answers can re-route the flow (e.g. a solo owner gets different questions than an employer), so this list is stale after any save_company_onboarding_answer call. Re-plan from that call's returned onboarding_status, or re-call this tool. QUESTION ORDER — next_step.next_question_group is the set of question keys to ASK the user RIGHT NOW. They are all safe to ask this turn and independent of each other, so the order among them does not matter — ask them in whatever order and grouping reads most naturally. Use judgment on how to ask: rather than dumping all of them in one message — or asking strictly one at a time — ask them in a few logically-related, digestible chunks (a couple to a handful at a time, grouping related topics, e.g. the workforce questions — headcount and the states employees work in — together). Often it is just one key. This governs the ASK, not the save: save_company_onboarding_answer takes ONE question_key per call and there is no multi-answer save, so after the user replies, make a SEPARATE save_company_onboarding_answer call for each key using the answers you just collected. Each save returns refreshed status that STILL lists the keys you have not saved yet (next_question_group shrinks as you save) — do NOT ask those again, you already have their answers; just keep saving them, one call per key. Do NOT ask a key that is not in next_question_group, or pull later keys in from remaining_question_keys, because a saved answer can re-route the flow and change what comes next. Once you have saved every answer you collected, re-read the refreshed status and ask the new next_question_group; repeat until none remain. next_question_group and remaining_question_keys can be identical (when every remaining question is safe to ask together); remaining_question_keys is the full ordered outstanding list for context and counts — drive from next_question_group. What comes after the required questions depends on the company's current experience, so follow the next_step cue rather than assuming a plan step always follows: answer_questions (answer the questions in next_question_group); continue_in_mcp with detail select_plan (the profile experience — call get_company_onboarding_package to present Gusto's recommended plan, then save tier_selection); continue_in_mcp with detail scorp_recommendation (a Solo owner may benefit from electing S-Corp tax status — call calculate_scorp_tax_savings to walk them through a personalized estimate, then acknowledge_scorp_recommendation once they have seen it, then re-call this tool); continue_in_mcp with detail ein_registration (the company needs a federal EIN before continuing — run the EIN filing tools: file_ein then pay_ein_filing then check_ein_status, then re-call this tool); continue_in_mcp with detail scorp_election (a Solo LLC wants S-corp tax treatment and has not filed Form 2553 yet — gather the election details and call file_scorp_election, then re-call this tool; never ask for SSNs); continue_in_mcp with detail reasonable_salary_calculator (a Solo S-corp owner can set their reasonable W-2 salary now — run the Reasonable Salary Calculator tools: calculate_reasonable_salary then accept_reasonable_salary, then re-call this tool); continue_in_mcp with detail connect_bank (the company's bank account is not connected — call connect_bank_via_plaid and relay its url; bank account and routing numbers cannot be collected here, so never ask for them instead); continue_in_mcp with detail set_password (this account cannot sign in yet, so no url is returned — follow the step's own message and never give out or invent a gusto.com link); continue_in_gusto (nothing left to drive here — relay the returned url; if it is absent, treat the step as set_password); or complete (onboarding is fully finished). A next_step of complete is authoritative: tell the user they're all set and do NOT present any questions — the questions list is empty and the counts are zero regardless of any past unanswered questions. It covers the company's setup, not website access: if the account signed up in chat, check manage_account get_status and mention any unset password alongside the good news. If you drove the onboarding with the user during this conversation, first present a concise recap of the onboarding answers gathered during this conversation (each question covered and its answer) so the user can confirm what was submitted, then tell them they're all set; build that recap from what you gathered in this conversation, not from this payload (which carries no answers), and do not restate sensitive values in full (e.g. SSN, full bank account numbers). If you did not drive onboarding here (e.g. the user just asked whether they are onboarded), simply confirm they're all set without inventing a recap. VOICE: helpful, not technical. Don't show the user this tool's internal names — question keys, field names, tool names, status values — describe what they mean instead, and don't volunteer counts unless asked. Where a value has a proper name, use it: "the Plus plan", not "plus". Codes the user picks from a list, like NAICS or workers' comp class codes, are content: show those verbatim.

get_company_onboarding_status

Retrieves full details for a single pay rate record by UUID, including rate amount, payment frequency, FLSA status, and effective date. Use list_job_compensations first to find the compensation UUID. Call this for specific details about one pay rate entry. To change a pay rate, use update_compensation.

get_compensation

Returns batched contractor payment runs for the company. A payment group represents multiple contractor payments processed together on the same date. Omit contractor_payment_group_uuid to list groups with their UUIDs, check dates, and processing status, optionally within a start_date to end_date range. Pass contractor_payment_group_uuid to fetch a single group with each contractor's payment amount and details from that batch. Payments identify contractors by contractor_uuid only, so call get_contractors once without contractor_uuid to get their names.

get_contractor_payment_groups

Returns payments made to independent contractors. To list payments, pass start_date and end_date, which shows payment amounts, check dates, and contractor info for that range. Use this read-only tool to see contractor payment history, audit 1099 payments, or find how much was paid. Pass contractor_payment_uuid instead to fetch one existing payment in full, including amount, payment method, bonus breakdown, and reimbursements. Use pay_contractors to create a new domestic contractor payment. Note - only includes payments to domestic (US) contractors. International contractor payments are not included.

get_contractor_payments

Returns the company's independent contractors (1099 workers). Unlike employees (W-2), contractors are paid separately and file their own taxes. Omit contractor_uuid to list contractors with pagination and search, returning UUIDs, names, and basic info. Use this read-only tool to find contractor UUIDs or get a roster of non-employee workers; use pay_contractors to create a new domestic contractor payment. To look up several contractors at once, such as everyone in a payment group, list them in one call without contractor_uuid and match on UUID rather than fetching each one. The list includes inactive contractors, so check the is_active field for current status. Pass contractor_uuid to fetch one contractor's full profile, including name, email, business name (if applicable), payment method, and engagement dates. Note - this only includes domestic (US-based) contractors. International contractors are not included in results. If the company has international contractors, mention that totals reflect domestic contractors only.

get_contractors

Returns the company's departments with their UUIDs, titles, and the UUIDs of the employees and contractors assigned to each. Omit department_uuid to list every department, which is enough to see the org breakdown or department headcounts. Pass department_uuid to fetch a single department. Members are returned as UUIDs only, so use list_employees to resolve names. Note - department employee lists and headcounts only include domestic (US) employees. International employees are not reflected in these counts.

get_departments

Retrieves full profile for a single domestic (US-based) employee by UUID, including name, email, hire date, department, manager, job title, work location, current pay rate, time-off policy assignments, and time-off balances. Use list_employees first to find the employee UUID. Call this when you need detailed info about one specific person. International employee data is not available through this endpoint.

get_employee

Returns per-employee earning breakdowns (commissions, bonuses, tips, etc.) aggregated across all processed payrolls in a date range. Use this when the user asks about specific earning types attributed to individual employees, such as "How much has each employee been paid in commissions this year?" or "Who received bonuses last quarter?" Default date range is year-to-date. This tool provides per-employee attribution that list_payrolls cannot - list_payrolls only has payroll-wide totals. IMPORTANT - Never guess which employees received specific earning types from aggregate totals. Always use this tool for per-employee earning attribution. Note - only includes earnings for domestic (US) employees. International employee earnings are not included. For national small-business pay benchmarks rather than this company's own earnings, use get_smb_pay_metrics.

get_employee_earnings_summary

Returns an employee's residential addresses, which are used for tax withholding calculations and mailing. Pass employee_uuid to list every home address on file for that employee, including current and historical addresses with street, city, state, ZIP code, and effective dates. Pass home_address_uuid instead to fetch a single address record.

get_employee_home_addresses

Retrieves information about an employee being brought back to the company after a previous departure. Includes the new start date and any updated employment terms. Use this to check if someone is a returning worker and when they rejoined.

get_employee_rehire

Returns the work locations assigned to an employee. Work addresses determine work-state tax jurisdiction. Pass employee_uuid to list every work location assignment for that employee, including current and historical assignments with the location address and effective dates. Use this to see where someone works or has worked, especially for remote or multi-location workers. Pass work_address_uuid instead to fetch a single assignment.

get_employee_work_addresses

Retrieves full details for a single job position by UUID, including title, department, location, FLSA classification, and current pay rate. Use list_employee_jobs first to find the job UUID. Call this for detailed info about a specific role assignment.

get_job

Returns the physical office or work locations registered for the company. Locations are used for tax filing, work address assignments, and compliance. Omit location_uuid to list every location with its address, UUID, and whether it is active. Pass location_uuid to fetch one location in full, including phone number and filing addresses for tax purposes.

get_locations

Requires an existing company — if the account does not have one yet, call create_company first, otherwise this fails. Returns the current answer for a single onboarding question, identified by its question_key. Every one of the question's fields is returned — a null field value means that field has not been set. Use this to read the current state of a specific question before deciding whether to update it, or to verify a previous save took effect. WHEN TO USE: When you need the current value of one specific onboarding question. WHEN NOT TO USE: To discover available question_keys or check overall onboarding progress — use get_company_onboarding_status instead. DATA RETURNED: An answer hash containing every one of the question's fields; a null field value means that field has not been answered yet. An unknown question_key returns an error rather than an empty answer. PREREQUISITES: Call get_company_onboarding_status first to discover valid question_keys before calling this tool. VOICE: helpful, not technical. Don't show the user this tool's internal names — question keys, field names, tool names, status values — describe what they mean instead, and don't volunteer counts unless asked. Where a value has a proper name, use it: "the Plus plan", not "plus". Codes the user picks from a list, like NAICS or workers' comp class codes, are content: show those verbatim.

get_onboarding_answer

Returns the company's configured pay schedules. Omit pay_schedule_uuid to list every schedule with its frequency (weekly, biweekly, monthly, etc.), name, and UUID. Pass pay_schedule_uuid to fetch one schedule in full, including anchor dates and next scheduled pay dates, which answers when the next payday is. Does not show which workers are on each schedule; use list_pay_schedule_assignments for that.

get_pay_schedules

Retrieves complete details for a single payroll by UUID, including worker earnings, taxes, deductions, and net pay. This tool is read-only; use update_payroll to modify payroll inputs (hours, memos, bonuses, PTO) or run_payroll to calculate and submit the payroll. Entries in employee_compensations may carry a benefits breakdown, with company contribution and employee deduction as separate amounts. Benefits require the employee_benefits:read permission and are not returned for every caller, so treat their absence as a permission or configuration difference rather than as the employee having no benefits. Payroll-wide benefit totals in totals are always returned. Benefit lines cover only the employees on the requested page, so they sum to totals only when the payroll fits on one page.

get_payroll

Checks the status of one or more previously triggered reports. On success, returns the CSV content inline (as csv_content, truncated with csv_truncated: true beyond 500 KB -- when truncated, do not compute totals or other aggregates from csv_content, since rows past the cut are missing). Call this after create_reports to check progress -- check at most 5 times, a few seconds apart, then tell the user the report is still generating rather than looping indefinitely; a date-range report can take up to an hour for a large company, so a handful of quick checks won't always be enough. csv_content is per-employee wage and tax data. Summarize or answer from it rather than pasting the raw CSV into the conversation. A report_request_uuid is only readable by the same token that created it -- a different admin's token, or the same admin's token used later without that context, gets a failed status with an error_reason saying so. Do not retry; the report exists, but that token cannot read it. A connection restricted from sensitive data can only read contractor payments summaries, custom reports whose columns pass the restriction check, and (for no-PII connections) cash requirements. Any other report fails with a restricted error. Do not retry. Pass report_request_uuids (from create_reports output) as a flat list -- each report's company is looked up automatically, so no company info is needed here. Returns {results: [...]}, one entry per report_request_uuid, in the same order. One report failing does not abort the others.

get_reports

Retrieves detailed time entries for a single timesheet by UUID, including daily hours worked, overtime, breaks, and notes. Third-party time tracking only - there is no native equivalent, and passing a native shift id fails with a transport-level "resource not found" whose text talks about credentials and configuration rather than the real cause. Check that list_time_records reported a third_party source first, and take the timesheet's top-level id from there. For native companies list_time_records already returns per-shift detail, so no follow-up call is needed. Call this for a line-item breakdown of someone's hours for a specific pay period.

get_time_sheet

Returns employees' current time-off balances - available (balance), accrued, used, and pending hours per policy - with each balance attributed to the worker (name) and policy uuid. Policy name and type are included only when the token also holds the time_off_policies:read scope; without it, policy labels come back blank (the policy uuid is still returned). Use this when an admin asks about PTO, sick, or vacation balances (e.g. "how much vacation does each employee have left?"). Optionally scope with employee_uuids or policy_uuids (comma-separated). Note - covers domestic (US) employees; balances reflect the company's configured time-off policies.

get_time_off_balances

Returns a company's time-off requests (PTO, sick, vacation, etc.). Omit time_off_request_uuid to list requests. With no filters that returns all of them. Filter by status (comma-separated - pending, approved, declined, consumed), start_date/end_date (YYYY-MM-DD, matched against the request's dates), and employee_uuids (comma-separated) to scope to specific workers. Pass time_off_request_uuid to fetch a single request. Each request includes the worker (name + uuid), status, policy (type + uuid), the per-day hours requested, and the initiator/approver. Employee and employer notes are omitted, since they are free text that may contain health information. Time off may be managed natively in Gusto or by a third-party integration; this returns the company's requests either way. Note - covers domestic (US) workers.

get_time_off_requests

Returns information about the current API access token including which permissions (scopes) are granted and which company resources can be accessed. Use this to check what data operations are available or troubleshoot access issues before attempting other API calls.

get_token_info

Retrieves the definitions of all custom fields configured for the company, including field names, data types, and selection options. Custom fields let companies track additional worker attributes beyond standard HR data. Use this to understand what custom data is available before querying individual worker field values.

list_custom_fields_schema

Lists all earning type categories configured for the company, such as regular pay, overtime, bonuses, commissions, tips, and custom earning types. Shows type name, category, and whether it's taxable. Use this to understand available pay types for payroll input.

list_earning_types

Retrieves all custom field values set for a specific employee. Custom fields are company-defined attributes like T-shirt size, emergency contact, certifications, or any other custom data. Use list_custom_fields_schema first to see available field definitions.

list_employee_custom_fields

Retrieves the complete work history timeline for an employee, including all positions held, role changes, and status transitions. Use this to answer questions about someone's tenure, past roles, or employment dates within the organization.

list_employee_employment_history

Lists all job positions held by an employee, including current and past roles. Each job record contains title, location, hire date, and rate information. Use this to see someone's role history or find job UUIDs needed for compensation lookups.

list_employee_jobs

Retrieves offboarding and separation records for an employee, including departure dates, reasons for leaving, and final pay information. Use this to find when someone left the company, their exit date, or details about their offboarding process. For national small-business hiring and separation trends rather than this company's own departures, use get_smb_jobs_report.

list_employee_terminations

Lists all employees for the company with pagination and filtering options. Returns basic profile data for each person. Filter by onboarding status, active/inactive status, or search by name. Use this to find employee UUIDs, get headcount, or answer questions about the workforce roster. Without filters, returns all employees including terminated; use terminated=false for active employees only. Note - this only includes domestic (US-based) employees. International employees are not included in results or headcount. If the company has international employees, mention that totals reflect domestic employees only.

list_employees

Lists the pay rate history for a job position, showing all salary or hourly rate changes over time. Each entry includes effective date, rate amount, and payment unit (hourly/salary). Use this to see pay history or track when raises were given. By default only the current compensation is returned. Set include to all_compensations to retrieve the full history. To change a pay rate, use update_compensation. For how this company's pay compares with US small businesses nationally, use get_smb_pay_metrics alongside this tool.

list_job_compensations

Lists all pay periods (date ranges when work is performed) for the company, with links to associated payroll runs. Shows start date, end date, check date, and payroll status. Use this to see upcoming pay periods or find which payroll covers a specific date range.

list_pay_periods

Shows which employees are assigned to which pay schedules. Returns mappings between worker UUIDs and schedule UUIDs. Assignment rules vary by company setup - some assign by department, others individually. Use this to find out when a specific person gets paid or which schedule they follow.

list_pay_schedule_assignments

Identifies issues preventing a specific payroll from being processed, such as missing bank accounts, incomplete tax setup, or unsigned documents. Each blocker includes a description and resolution steps. Use this to diagnose why payroll cannot run or to check readiness before processing.

list_payroll_blockers

Lists all payroll runs for the company with filtering options. When called with no arguments, returns all payrolls (processed and unprocessed, regular, off_cycle, and external) from the past 6 months (start_date defaults to 6 months ago, end_date defaults to today). You can filter results by providing processing_statuses, payroll_types, start_date, end_date, or include parameters. Date filters apply to pay period (work dates), not payment dates. Date range constraints are that the range cannot exceed 1 year, and end_date cannot be more than 3 months in the future. Returns payroll UUIDs, check dates, processing status (processed,unprocessed), and type (regular,off_cycle,external). Use include=totals to get payroll-wide aggregate amounts (gross pay, taxes, net pay, total commissions, total bonuses). These totals are NOT broken down per employee. For per-employee earning breakdowns (who received which commissions, bonuses, etc.), use get_employee_earnings_summary instead. IMPORTANT - Never guess or infer which employees received specific earning types from aggregate totals alone. Common use case is to find the next payroll to process by filtering for processing_statuses=unprocessed and selecting the payroll with check_date closest to today's date. Note - payroll data only covers domestic (US) employees. International employee payroll is managed separately and not included here. Payroll sub-state within `unprocessed`: each list item carries `processed` (boolean) and `calculated_at` (nullable timestamp), but the roster (`employee_compensations`) is NOT included in list responses. From this list alone, use `calculated_at` to distinguish sub-states within `processing_statuses=unprocessed`: - pre-prepare candidate: `calculated_at: null`. - calculated: `calculated_at` is a timestamp. When the user asks for "unprepared", "draft", or "not-yet-prepared" payrolls, filter by `processing_statuses=unprocessed` and pick items with `calculated_at: null`. Then call `get_payroll` on the chosen item to confirm the roster is unmaterialized (`employees: []`, `employee_compensations` empty or absent) before invoking `update_payroll` — that combined signal is what makes the pre-prepare materialize path safe.

list_payrolls

Requires an existing company — if the account does not have one yet, call create_company first, otherwise this fails. Lists time records for the company over a pay period. The response is discriminated by `source`: - `source: 'native'` returns `shifts` (clock-in/out events, breaks, durations) plus `workers`, everyone who tracks time at the company, for companies on Gusto's native time tracking. `workers` covers employees and contractors alike, and lists a worker even when they have no shifts in the requested period, so use it to find the `companyMemberUuid` for someone you want to record a first shift for. - `source: 'third_party'` returns `timesheets` for companies with an active third-party time tracking integration, each carrying `shiftStartedAt`, `shiftEndedAt` and `timezone` so you can tell which day it covers. The tool eagerly paginates the third-party feed internally, so callers receive every timesheet in one response. - `source: 'none'` returns neither array; the company has not completed native onboarding and has no active third-party integration. For companies that have both native onboarding and third-party time tracking active, only the third-party data is returned, mirroring what those customers see in product. Always check `source` before reading shape-specific fields. Every shift and timesheet also carries the worker's identity: `firstName`, `lastName`, `preferredName`, `workerType` (`employee`, `contractor`, or `international_contractor`), and the worker's public id - `employeeUuid` for employees or `contractorUuid` for contractors (the other is null). Use these to label records and to join back to employee/contractor tools. Identity fields are null when a member can't be resolved. On native time tracking, a contractor's `clockInTimestamp` and `clockOutTimestamp` are only readable when the time was entered or edited by an admin; for time the contractor clocked themselves both come back null, because Gusto withholds a contractor's raw clock times from everyone but the contractor. `date` and `durationInMinutes` are always populated, so report contractor hours from those rather than treating a null timestamp as a missing shift. Employee timestamps are unaffected.

list_time_records

Performs account-level actions on the signed-in Gusto account. Set `action` to choose what to do; only the actions listed below are supported, so do not invent others. action "get_status" — reports whether this account has set a Gusto password and can sign in on the website. Onboarding tools already withhold their gusto.com `url` until a password is set, so you need this only when the user says they set one, asks why they cannot sign in, or when a chat-signup account reaches next_step `complete` — that covers the company's setup, not website access, so mention any unset password alongside the good news. action "resend_password_setup_email" — re-sends the email that lets the user set a Gusto password and finish converting their signup into a full account. Use this only when the user says they did not get that email, deleted it, or the link expired. The email is sent automatically when signup setup completes, so there is no need to call this as a normal step. Sending is rate limited, so a repeat call inside a few minutes reports that the most recent email is still valid rather than sending another — relay that to the user instead of retrying. A successful response means the email was sent, NOT that the account is already upgraded: the user still has to open it and choose a password.

manage_account

Records admin-entered time for a worker over a pay period. Routes automatically to the company's native time tracking or their connected external time-tracking partner - the caller never chooses the destination. Always preview existing hours with list_time_records and get explicit admin approval before calling this tool. On success the response carries `status`, `source`, `id`, and `resulting_hours`, and sometimes `warning`. `resulting_hours` is only populated for third-party writes; it is always null on the native path, so confirm native hours by re-reading with list_time_records rather than from the write response. `id` is the value to pass back as `shift_id` when updating the same record, but it is null whenever Gusto can't tell which shift it just wrote. That covers a native contractor, whose clock times are withheld, on any day that ends up holding more than one of their shifts, and any worker whose recorded clock-in doesn't match the one Gusto echoes back. The write still succeeded; get the shift's id from list_time_records before updating it. A `warning` means the write landed but something the caller asked for did not - relay it to the admin instead of reporting a clean success. One case where re-reading is not proof: a contractor who has no Gusto account of their own comes back from list_time_records with null start and end times even though the hours recorded, because Gusto withholds a contractor's clock times from admins unless it can confirm who last edited them. Do not re-record hours that came back successful, and do not tell the admin the write failed - a second write books the hours twice.

record_time

Calculates and submits an existing unprocessed payroll for W-2 employees. Use pay_contractors for domestic contractor payments. CANNOT create new payrolls or off-cycle payrolls. To modify payroll inputs (hours, amounts, earnings, memos, PTO) before running, use update_payroll. If the user needs an off-cycle payroll (bonus, correction, termination), they must first create it in Gusto, then return here to run it. When multiple unprocessed payrolls exist, prefer the one with a check date closest to today.

run_payroll

SIGNUP/ONBOARDING PHASE tool. Requires an existing company — if the account does not have one yet, call create_company first, otherwise this fails. Saves a single onboarding answer for the company. A saved answer can RE-ROUTE the onboarding flow — e.g. answering who_to_pay as a solo owner changes which questions remain — so any previously fetched question list is stale after a save. A successful response includes `onboarding_status`: the refreshed post-save status in the same shape as get_company_onboarding_status. Always re-derive the remaining questions from it (or re-call get_company_onboarding_status) instead of continuing through an earlier list. The re-routing is yours to handle, not the user's to hear about: do not tell them the question set or its count changed, and just ask the next question. Report a count only if they ask for one. If the answer is invalid, the response `errors` list names the expected fields and allowed values — retry with corrections. Don't invent question_keys; use the get_company_onboarding_status tool to discover valid keys and which remain unanswered. For question_key `tier_selection` (plan selection), first call get_company_onboarding_package — its plans/addOns `key`s are the valid `plan` and `add_ons` values, and it includes Gusto's recommendation to present to the user. Present that recommendation and confirm the user's choice before saving tier_selection. For question_key `industry_selection`, first call search_business_info with type "industry" and the business's own words — its results carry the verified `naics_code` to save. Present those candidates and confirm which one the user picks before saving: the pick is theirs, not yours, so do not settle on the top-ranked result yourself, and a document or profile that names the business's industry is not a pick — it describes the business, it does not choose between codes. A code or classification the user names themselves is the exception: that already IS their pick, so save it without asking them to choose again. Never guess NAICS/SIC codes; only save a code returned by that tool. The industry_selection answer also carries `is_crb`, a cannabis-related-business flag that steers package eligibility (a cannabis business cannot be offered 401(k)), so it must be set, not left blank. Ask the user a standalone yes/no question — near-verbatim: "To make sure we show you the right package options, is your business in the cannabis industry?" — and include `is_crb` (true or false) in the same industry_selection answer you save. Ask it plainly on its own; do not fold it into the industry-description question, and never set `is_crb` true without the user's explicit yes — do not infer it from the industry, NAICS code, or business name. For question_key `tax_payer_type`, only "LLC" and "C-Corporation" can elect S-corp taxation. When the user picks one of those, ask a separate follow-up — whether the business is taxed as an S corp (an elective status that passes profits through to the owner's personal return, avoiding double taxation) — and include `taxable_as_scorp` with their answer; do NOT assume false. For any other classification you don't need to ask about or send `taxable_as_scorp`; the system sets it. Bank accounts ARE connected here, with connect_bank_via_plaid: give the user the url it returns and confirm the outcome with check_plaid_connection_status rather than assuming it worked. Never tell the user the bank step has to happen in the Gusto web app while that tool is available. What cannot happen here is typing the details into chat: `company_bank_account` and `plaid_bank_account` are rejected if sent and are not listed as questions, so never ask for an account number, routing number, or bank login, and never offer to enter them on the user's behalf — even if they volunteer them or insist. Only if connect_bank_via_plaid is unavailable, send them to Gusto instead. The response also includes `next_step`, a structured cue for what to do next — follow it: `answer_questions` means the key(s) in `next_question_group` are all safe to ask this turn — ask them in a few related, digestible chunks (not all at once, not strictly one at a time), then make a SEPARATE save call per key with the answers you collected — there is no multi-answer save. The status returned by each save still lists the not-yet-saved keys, so keep saving them rather than re-asking; do not skip ahead or ask keys outside that group (`remaining_question_keys` is the full outstanding list for context; drive from `next_question_group`); `continue_in_mcp` with detail `select_plan` means call get_company_onboarding_package and then save the `tier_selection` answer; `continue_in_mcp` with detail `connect_bank` means call connect_bank_via_plaid and relay its url — do not ask for bank numbers instead; `continue_in_mcp` with detail `set_password` means the account cannot sign in yet, so no `url` is returned — follow the step's own message and never give out or invent a gusto.com link; `continue_in_gusto` means relay the returned `url` to the user — if it is absent, treat the step as `set_password`; `complete` means onboarding is fully finished — before saying anything else, present a concise recap of the onboarding answers gathered during this conversation (each question covered and its answer) so the user can confirm what was submitted, then tell them they're all set and do NOT prompt for more answers. Build the recap from what you gathered in this conversation; onboarding_status carries no questions at this point. Do not restate sensitive values in full (e.g. SSN, full bank account numbers) — refer to them without echoing the digits. You may still offer any remaining non-required questions before a `continue_in_*` step, but they don't block progressing. VOICE: helpful, not technical. Don't show the user this tool's internal names — question keys, field names, tool names, status values — describe what they mean instead, and don't volunteer counts unless asked. Where a value has a proper name, use it: "the Plus plan", not "plus". Codes the user picks from a list, like NAICS or workers' comp class codes, are content: show those verbatim.

save_company_onboarding_answer

Resolves a free-text description into verified, codified business-information candidates the user can choose from. Set `type` to pick what you're resolving; `query` is the user's free-text description in their own words. type "industry" — resolve what the business does into NAICS industry candidates, each with a verified 6-digit naics_code, name, and description. Use this whenever you need to set the industry_selection answer: pass the business's own words (e.g. "we run an apple orchard"), then save the naics_code the user picks with save_company_onboarding_answer. Candidates come back ranked by relevance, but ranking is a hint, not a decision — list them with their names and descriptions, ask which one fits, and wait for the answer before saving. Do not pick the top result on the user's behalf, and do not treat a document or profile that names the industry as the pick: near-identical candidates differ in how the business is treated downstream, so only the user can say which describes them. The exception is the user naming a code or classification themselves — that IS their pick, already made: check it appears in the results, then save it straight away rather than listing the candidates or asking them to choose again. Never guess NAICS codes; only save codes returned here. type "occupation" — resolve a job/role description into Bureau of Labor Statistics (BLS) occupation candidates, each with a code, name, and description (e.g. the code a reasonable- salary estimate needs). Pass the user's role in their words (e.g. "software developer" or "restaurant line cook"), present the options, and use the chosen candidate's code. Never guess BLS codes; only use codes returned here. For either type, if the list comes back empty, ask the user for a clearer description and search again. VOICE: helpful, not technical. Don't show the user this tool's internal names — question keys, field names, tool names, status values — describe what they mean instead, and don't volunteer counts unless asked. Where a value has a proper name, use it: "the Plus plan", not "plus". Codes the user picks from a list, like NAICS or workers' comp class codes, are content: show those verbatim.

search_business_info

Resolves a description of the work someone does into that state's workers' comp risk-class candidates, each with a verified code and description. Requires `state` (WA or WY — only those two run their own state fund, so only they use class codes). Use this to get the state_managed_wc_class_code that manage_company_members needs to finalize a covered employee there: search the work the employee does (e.g. "roofing", "office administration"), present the candidates, and pass the code the user picks. Never guess a class code — it is validated against the state's list and a wrong one is rejected. Query with the WORK AS A NOUN, never a job title and never what the person does. These lists name trades, so "software" works where "work with computers" and "write code" do not, "plumbing" where "plumber" and "fixing pipes" may not, and "barber shop" where "hair stylist" does not. Verb and activity phrasing is the most common reason this search comes back wrong, because words like "work" appear in dozens of unrelated trades. If the user describes an activity, name the industry it belongs to and search that. If nothing comes back, rephrase in the state's industry terms and search again; two or three attempts is reasonable. If the user gives you a code themselves, that is their choice — pass it straight to manage_company_members as-is and do not run it through this search to second-guess it. Use this search only to resolve a code the user does not have. If a second wording also finds nothing in WA, call again with list_categories: true instead of guessing further. That returns the headings WA files its codes under — the list may simply not use your word for the work ("hair stylist" appears nowhere; the heading is "Beauty parlors"). Pick the heading that best covers the work, search again using it as the query, and present the codes it returns. WY has no such headings, so there rely on the search and on company_industry_candidates. If you still cannot find a code, stop and say so. Do not guess one, and do not set state_managed_wc_covered to false to get past the error — that tells Gusto the employee is not covered by the state fund, which is a false compliance answer and worse than leaving the work unfinished. Leaving the worker unfinalized is the correct outcome here: say you could not identify the class code and ask the user to set it in Gusto, where the picker lists the codes their company has configured. The code describes THE WORK THIS PERSON DOES, not what the business does. Two people at the same company routinely need different codes, and picking the company's trade for someone who doesn't do it overcharges the employer. In WY, office and sales staff have their own codes regardless of the industry — 000010 Clerical Office Occupations, 000020 Outside Sales, 000030 Inside Sales, 000040 Temporary Help - Office, 000050 Temporary Help - Other — so a bookkeeper at a roofing company is 000010, not a roofing code. Search for the person's actual work first; only reach for the company's trade when they really do that trade. For WY the results may also include company_industry_candidates: the codes matching the company's own registered industry. Those are the right answer only for someone doing that trade, and there is often more than one (roofing splits into all-types, residential and nonresidential), so present them and let the user choose rather than assuming the first. If the list comes back empty, ask the user for a clearer description and search again. VOICE: helpful, not technical. Don't show the user this tool's internal names — question keys, field names, tool names, status values — describe what they mean instead, and don't volunteer counts unless asked. Where a value has a proper name, use it: "the Plus plan", not "plus". Codes the user picks from a list, like NAICS or workers' comp class codes, are content: show those verbatim.

search_workers_comp_class