Gusto

Marks the Solo S-corp owner's in-progress reasonable-salary estimate as accepted, recording the chosen W-2 salary for IRS-defensibility purposes. Call this LAST in the Reasonable Salary Calculator flow. Before calling, confirm the user has reviewed the calculated estimate and explicitly wants to accept that number; do not call `accept_reasonable_salary` automatically just because a `calculate_reasonable_salary` call succeeded. IMPORTANT - any later change to the estimate's inputs silently clears the acceptance, so accept must be the final step. Takes no arguments; the company and owner come from the token context, never the caller, so it requires an existing company — if the account does not have one yet, call create_company first, otherwise this fails. It accepts the single most recently calculated in-progress estimate for that owner; if several `calculate_reasonable_salary` calls were made, only the latest can be accepted (each overwrote the previous). On success, returns the accepted estimate (id, result as an integer USD amount, range, acceptedAt). On failure, the response `errors` list names a structured kind - "no_in_progress_estimate" (calculate a reasonable salary estimate first), "company_not_eligible" (company is not taxed as an S-corp), or "no_draft_team_member" (owner profile not ready yet, usually a brief race after signup; retry shortly). Does NOT set the owner's actual pay rate, file any tax form, or finalize the estimate to an employee job. ONBOARDING HANDOFF — RSC is reached two ways, and acceptance means different things in each. (1) Standalone: the owner came directly to figure out their salary; after a successful accept, confirm the saved number and you're done. (2) As an onboarding step: an earlier `get_company_onboarding_status` `next_step` routed you here (its `detail` was `reasonable_salary_calculator`). In that case acceptance is NOT the end of onboarding — after a successful accept, call `get_company_onboarding_status` again. Acceptance advances the flow, so the refreshed `next_step` points to the real next step (typically `continue_in_gusto` with the URL to send the owner to). Never invent or hardcode that destination URL yourself; always take it from the refreshed onboarding status — and if it comes back as `set_password` instead, there is no URL to relay: follow that step's own message.

accept_reasonable_salary

Internal tool for payroll calculation. Use run_payroll instead.

calculate_payroll

Calculates an IRS-defensible reasonable salary for an S-corp owner from Bureau of Labor Statistics (BLS) wage data, given the company's ZIP code and one or more occupations. Returns the recommended annual salary, a defensible range, and the BLS wage area. Look up each occupation `code` with `search_business_info` (type `occupation`) first. GATHERING INPUTS — collect what this tool needs conversationally, one step at a time; don't ask for everything in one message and don't assume values. Follow this order: 1. Location first. Ask for the company's 5-digit ZIP code — it sets the BLS wage area. If the user offers only a city or state, ask them for the ZIP rather than guessing one yourself; a guessed ZIP can land on the wrong wage area. 2. Roles, one at a time. Ask what the owner does, then call `search_business_info` (type `occupation`) for that role, present the candidates, and let the user pick the `code` before asking about anything else — never guess BLS codes. Most owners have a single role; only gather more if the user says they wear more than one hat, resolving each role fully before starting the next. 3. Per-role details. For each chosen occupation confirm `experience_level`, plus — for a multi-role owner — the `time_percentage` split and which role is `primary`. Offer a sensible default and let the user adjust; don't apply these silently. 4. Optional refinements. Only if relevant, ask about a part-time `work_schedule` or an `annual_net_revenue` cap; otherwise leave them out. Confirm every input before calling. A failure returns a `kind` and a `message`; branch on `kind`, not on the message text. RECOVERABLE — fix the inputs per the `message` and re-call: `no_occupations` (the `occupations` array was empty — gather at least one role, per step 2), `time_percentages_not_100`, `duplicate_occupation_code`, `multiple_primary_occupations`, `part_time_hours_required`, `incomplete_occupation` (a role is missing an experience level or time percentage), `invalid_occupation_code` (re-run `search_business_info`), `missing_area` and `zip_lookup_failed` (re-confirm the business's 5-digit ZIP), and `salary_data_unavailable` (BLS publishes no wages for that role, even nationally — ask for a different role). Several of these are about one role rather than the whole request. For `duplicate_occupation_code` and `incomplete_occupation` the `message` names the role — fix only that one, and do not re-gather the others. For `invalid_occupation_code` and `salary_data_unavailable` the message does NOT say which role it was, so with more than one role you cannot tell from the response alone: re-check the codes you sent with `search_business_info` rather than guessing, and ask the user before dropping a role. TERMINAL — do NOT re-call with the same company; say what happened and stop: `company_not_eligible` (reasonable salary applies only to companies taxed as an S-corp, which no input change fixes) and `no_draft_team_member` (the owner's profile is not ready yet — tell the user to try again later rather than retrying in this conversation). Treat an unfamiliar `kind` as recoverable by reading its `message`, rather than failing the conversation. Make ONE call once the inputs are confirmed. When the owner fills more than one role (e.g. a founder who both writes software and runs the business as CEO), list every role in the `occupations` array with `time_percentage` values summing to 1.0 in that single call — do not fire separate `calculate_reasonable_salary` calls per role. The tool blends them into one composite salary; separate calls would each overwrite the last. This tool keeps ONE in-progress estimate per company/owner: every successful call overwrites that single estimate and there is no history, so do not issue parallel or speculative calls — to compare scenarios, run them one at a time and show each result before recalculating. The estimate is referenced implicitly by the authenticated company/owner, so this call intentionally returns no `id`; `accept_reasonable_salary` returns the persisted estimate's `id`. After a successful calculation, present the recommended salary and range and ask whether the owner wants to accept it as their W-2 salary; if they confirm, call `accept_reasonable_salary`. Do not call `accept_reasonable_salary` without explicit user confirmation (see that tool's description).

calculate_reasonable_salary

Reports where the company's Plaid bank connection stands. Use this to confirm the outcome of a connect_bank_via_plaid link, since that flow finishes in an external browser window and reports back to Gusto out of band — nothing in this conversation observes it directly. WHEN TO USE: After the user says they have finished (or abandoned) a Plaid link, to find out what actually landed before telling them anything. Also safe to use to check whether a company already has a bank connection before offering the Plaid flow at all. WHEN NOT TO USE: Do not poll this repeatedly in a loop while waiting — the connection only appears once Plaid reports the finished session, so call it when the user says they are done. Do not use it to ask the user for bank account or routing numbers; it only reads existing state. RETURNS: This reports the company's most recent live bank connection, not a roll-up of every bank account it has — a company can hold an already-verified account while a newly connected one is still verifying, and this reports the new one. Always branch on `status`, not on `success` alone — `success: true` only means the check ran. `connected: true` with `status: "connected"` means the bank is verified and onboarding can move on. `status: "pending_micro_deposits"` means the bank is connected but verifying over 1-2 business days; nothing further is needed from the user, so do not re-offer the link. `status: "not_connected"` means nothing landed, so the user likely did not finish. `status: "connection_unusable"` means the latest attempt failed and needs a fresh link. When present, `account_last_digits` is the last few digits of the connected account, safe to read back to the user for confirmation. On error, `{ success: false, error_type, message }`. PREREQUISITES: A valid access token whose company the acting user is a member of. 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.

check_plaid_connection_status

Opens a Plaid-hosted flow where the user connects their company bank account, verifying instantly in most cases. This is the ONLY way to add a bank account during onboarding: the bank questions cannot be answered in chat, and save_company_onboarding_answer rejects them. Whatever the user enters in the Plaid flow goes straight to Plaid and Gusto — this tool does NOT collect bank account numbers, routing numbers, or banking credentials through the conversation, and you never see what was entered. WHEN TO USE: Whenever next_step returns detail `connect_bank`, or the user asks to add or change the company's bank account. There is no manual alternative to offer alongside it. WHEN NOT TO USE: Never ask the user to type a bank login, routing number, or account number into chat, and never offer to enter those on their behalf — not as an alternative to this tool, not if the user asks to, and not if they volunteer the numbers unprompted. Those are entered only in the Plaid flow. If the user will not use Plaid, send them to Gusto to add the account there. Do not call this again for the same company while a link from earlier in this conversation is still pending — wait for the user to say they've finished, then confirm with check_plaid_connection_status before offering it again. RETURNS: Branch on `success`. On success, `{ success: true, status: "plaid_connection_pending", url, message }` — tell the user to open the link, connect their bank, and come back; do not ask them to report back what they saw or any account details. On error, `{ success: false, error_type, message }`. PREREQUISITES: A valid access token whose company the acting user is a member of. 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.

connect_bank_via_plaid

SIGNUP/ONBOARDING PHASE tool, and the first step — the other onboarding tools are company-scoped and fail until this has created a company. Create the user's Gusto company and payroll-admin account once the user has confirmed the details they want to sign up with. Use this tool for account creation; do not call a separate lead tool first (the lead is created server-side). The account email is already established — it is the address the user verified when they signed in. Do not ask the user for an email. Call create_company with the confirmed flag set to false first; the response returns `account_email`. Confirm that address and the company details with the user, then call again with the confirmed flag set to true. Company creation is not the final account step for chat signups. After onboarding setup is complete, Gusto sends a password setup email, and the user must open that email to finish securing the account and sign in to Gusto directly. Required fields, company_name, first_name, last_name, confirmed. Optional enrichment fields, number_employees, phone, states.

create_company

Retrieves comprehensive business profile information including legal name, business entity type (LLC, Corporation, etc.), EIN, primary contact details, and configured locations. Use this to answer questions about company setup, business structure, or basic organizational info. 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

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 company's available plans, add-ons, and benefits during onboarding, plus Gusto's recommended package and the company's current selection. Use this to present the options and the recommendation, compare tiers, or answer pricing questions — all from the returned payload. ONCE THE PROFILE IS READY FOR A RECOMMENDATION: when the only required question left in get_company_onboarding_status is the plan choice (tier_selection) — i.e. every other required question is answered — call this tool to present Gusto's recommendation: explain what's included and why it fits their profile, then ask whether they'd like to proceed with the recommended plan or explore other options before you save their tier_selection (via save_company_onboarding_answer). Do NOT wait for tier_selection itself to be answered before presenting the recommendation — the recommendation is what informs that choice. WHEN TO USE: When the user is choosing or asking about a Gusto plan during onboarding — to present available plans/add-ons, show the recommendation and why, compare tiers, or answer "how much does X cost". WHEN NOT TO USE: To read a single onboarding question — use get_onboarding_answer. DATA RETURNED (keys are camelCase): `plans` and `addOns`, each with `key` (the value to save as `plan`/`add_ons`; `stableId` is also present but may be null, so use `key`), `name`, `description`, and a `pricing` object (`baseFee`, `perEmployeeFee`, `currency`; a fee is null when not charged); `benefits` with `key`, `name`, and `pricingNote` (quoted with partner carriers at setup, not on the Gusto invoice); the `recommended` package (`plan`, `addOns`, `benefits`, and a `rationale`) and the company's current `selected` package; readyForPackageRecommendation (whether every required profile question EXCEPT the plan choice is answered — i.e. the recommendation is ready to present); and profileComplete (whether ALL required questions, including the plan choice, are answered). The recommended block is null until readyForPackageRecommendation is true and a recommendation has been computed. The recommendation is computed once and reflects the profile answers at that time; it is not recomputed here if answers change afterward. SIDE EFFECT: not a pure read — the first call made once the profile is ready computes and stores Gusto's recommendation (a one-time computation; later calls do not recompute it). Calling it before the profile is ready is a safe no-op for the recommendation (the recommended block stays null). PREREQUISITES: The recommendation populates once the company's required profile questions EXCEPT the plan choice are answered (see get_company_onboarding_status). 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_package

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 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 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.

get_compensation