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 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; when a promotion applies, also `discountedPricing` with the promotional fee amounts, `discounts` with what each one `appliesTo` and a `description`, and `promotionTerms`); `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); and `bundles`, separately priced product bundles the company qualifies for (e.g. business formation), each with `key`, `name`, `price`, `description`, `includes`, and `availableAddOns`, to present with its price beside the recommended plan, not as part of the plan. A bundle's `price` is null when it can't be quoted; then say the full amount is shown before they pay. 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. PROMOTIONS: when a plan's pricing includes `discounts`, tell the user about the promotion when you present that plan. State the regular fees first, then introduce the discount explicitly as a promotion (e.g. "There's also a promotion available: ...") with the `discountedPricing`, the discount `description`, and every `promotionTerms` entry exactly as written (do not paraphrase, shorten, or add conditions); if `promotionTerms` is empty, do not state or guess any conditions. Gusto's full promotional terms are at https://gusto.com/legal/terms/promotional-terms — share that link when the user asks for the full terms. Fees without a discount still apply. Never mention or promise a promotion for a plan whose pricing has no `discounts`. PER-PERSON FEE: `perEmployeeFee` is the monthly fee per person paid. When the company only pays contractors, call it a per-person (or per-contractor) fee, not a per-employee fee. Promotions can change as profile answers change, so call this tool again before quoting a price rather than reusing an earlier response. 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; where a field also lists enum_options, show the user each option's label, with its description where it has one, and save its value). 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. Resolving the NAICS classification does not finish industry_selection on its own: you must also ask the user, as a standalone yes/no question, whether the business is in the cannabis industry and set is_crb in the saved answer. Prefer asking it up front, before you gather the industry description — once the user has described an obviously non-cannabis business (e.g. a daycare), circling back to ask reads oddly. Always ask it plainly on its own, never folded into the industry-description question, and never infer is_crb from the industry, NAICS code, or business name (save_company_onboarding_answer carries the exact wording to use). For `business_formation_details` on an LLC, check the name with check_business_name_availability before saving it. A question that carries `answer_with` is answered from that helper tool: call it as its guidance says before asking, and never guess values it supplies. 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. Some steps never appear in this list, so every listed question can be answered while one is still outstanding — the counts cannot tell you that, and only next_step surfaces it. Always follow next_step rather than inferring from this list that setup is done. A present next_step ALWAYS means its step is NOT finished: never tell the user that step is complete — and never accept the user's own claim that it is done — while next_step still targets it (e.g. detail create_signatory means no signatory has been created yet, no matter what the user says). Treat a user saying they have finished a step as a prompt to re-call this tool and confirm next_step has moved on, not as proof it has. When telling the user what is left, describe only the questions in next_question_group and the step next_step targets. Do not mention or guess at anything beyond them — what follows depends on answers not yet given, so a guess is often wrong. 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 personal identifiers in chat); 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 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_mcp with detail create_signatory (the company needs a signatory before its forms can be signed — call open_secure_session with purpose signatory_creation and relay the secure panel it opens; the admin completes the signatory details in that panel; never collect them in chat); continue_in_mcp with detail sign_company_forms (the company has forms awaiting signature — call open_secure_session with purpose form_signing and relay the secure panel it opens; never collect a signature or personal details in chat); continue_in_mcp with detail collect_owner_ssn (the Solo owner's own tax identifier is outstanding on their profile — call open_secure_session with purpose ssn_collection and relay the secure panel it opens; the owner enters it in the panel, never in chat); 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 such as identifiers or account numbers in full. 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 preview or revise a domestic contractor payment draft; the human must review and submit in the secure panel or on gusto.com. Note - only includes payments to domestic (US) contractors. International contractor payments are not included. For status questions, human reports and silent widget hints are unverified, including execution_in_progress and execution_outcome_unknown. Establish status only from matching authoritative read-only records for the relevant contractor, amount, and payment date. Use contractor_payment_uuid for an individual payment, never a draft pay_group_id. Use get_contractor_payment_groups to find a submitted group when appropriate. An empty or missing read does not establish processing, success, failure, or non-submission; if reads do not establish status, say the actual payment status is unconfirmed. Never prepare, revise, open a review, or retry a payment to resolve a status question. Do not describe unverified processing as normal or expected. Say "unconfirmed outcome" instead of a raw status, even when the human supplied the code. Share the returned Gusto link and, when present, the support_reference value with a natural support-reference label. Do not display other opaque identifiers or construct a payment link. A human approval click alone does not establish that processing began or that submission reached Gusto. Do not infer that the payment went through the proper submission channel. Include the exact returned Gusto link in the final answer even when no tools are needed or records are empty.

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 preview or revise a domestic contractor payment draft; the human must review and submit in the secure panel or on gusto.com. 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. For a 401(k)-only account this returns retirement_only true and a message instead of onboarding data; relay that message. 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

Requires a company in context. Lists the authenticated user's outstanding tasks (to-dos) across Gusto - payroll blockers, time-off requests, compliance items, document signatures, and more, in one flat list. Each task includes a title, message, category, optional due date, and an optional deep link (a ready-to-use absolute URL) for tasks with no matching tool. Priority is one of "high", "medium", or "low"; "high" tasks are payroll blockers. Returns an empty list when there are no outstanding tasks, rather than an error. Returns at most 100 tasks; if more exist, the response includes truncated: true. Use this to answer "what needs my attention in Gusto?" Attempt to resolve each task with a tool you already have; when none applies, hand the task off to the caller via its deep link instead of claiming it was resolved.

get_tasks

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. An end_date more than 90 days ahead is moved back to 90 days; the result is then an object with the list under `pay_periods` and a `notes` array saying so. A window that starts more than 90 days ahead is sent as-is (with no end_date, that returns an empty list). Listing creates an unprocessed payroll record for any due regular pay period that doesn't have one yet.

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 regular, off_cycle, and external payrolls: processed payrolls and unprocessed off_cycle/external payrolls from the past 6 months, and unprocessed regular payrolls from the past 3 months (start_date defaults to 6 months before today, or before end_date if that's earlier; 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. The range can be at most 1 year and end_date at most 90 days ahead; dates outside that are moved inside it, but a window that starts more than 90 days ahead is sent as-is (with no end_date, that returns an empty list). When dates move or the unprocessed range is narrowed, the result is an object with the list under `payrolls` and a `notes` array saying what changed; otherwise it's the plain list. A call with no arguments always narrows the unprocessed range, so it returns the object form. Unprocessed regular payrolls are listed only from 3 months ago onward; everything else covers the full range. A paginated call (page or per) stays one request: with both statuses it returns the requested range unchanged, and with processing_statuses=unprocessed it starts every payroll type at 3 months ago. Listing creates an unprocessed payroll record for any due regular pay period that doesn't have one yet. 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. A payroll's pay_period may include pay_schedule_custom_name, the name of its pay schedule. It is omitted when the payroll has no pay schedule, when the schedule has no custom name, or when the caller lacks the pay_schedules:read permission, so its absence says nothing about the payroll. 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

Starts or updates a business insurance application, which could be to submit a lead, get a quote, or bind a policy, with Gusto Insurance Agency, a licensed insurance agency. Today this sends the request to a licensed agent who follows up; it does not return quotes or bind policies. Returns the application's `id` and `status`, plus `needs`, `next_steps`, `disclosure` and `guidance`. Works for businesses that don't use Gusto. Call it only after the user asks for coverage or asks to be contacted about it. Pass only what the user has told you; never guess or invent a value. If you already have every detail, pass them all in the first call. Never infer `business.state` from a city name alone: a city can be in more than one state. If the user gives only a city or region, leave `state` out of the call and ask which state before sending it. Send the state when the user names or confirms it, or when it follows from a ZIP code in the business's own address. A contact's phone number says nothing about where the business operates, so never use an area code to fill in the state. When `needs` is non-empty, ask the user for everything it names in one message, then call again with the same `application_id`. Don't present the application as submitted until `status` says so. If the response includes `suggested_contact_email`, that is the email on file for the user's Gusto account. Propose it as the contact email and ask the user to confirm it or give another. Never use it without their confirmation. ALWAYS FOLLOW `guidance`: it says what happens next for this application and how to present it. ALWAYS show `disclosure` verbatim. NEVER state or estimate prices, name carriers, or recommend coverage unless this tool returns them. Not for policies the user already has, claims, certificates of insurance, or general questions about what coverage a business needs. For WA or WY workers' comp class code lookups, use `search_workers_comp_class`.

manage_business_insurance_application

Adds or changes ONE company member (employee or contractor) per call — the name is plural for the resource, not for batching. A single call can do the whole job: create the member, set whichever of their basics, compensation, employment and work-address you pass fields for, and with submit: true finalize them into a real team member. Two ways to call it: - New worker: omit draft_company_member_id and set worker_type. Pass everything you already know, including submit: true when you have their legal name, and this one call finishes the job. - Existing draft: pass the draft_company_member_id this tool returned plus the fields to change. Use this to fix anything that came back wrong, and to finalize later with submit: true. Finalizing: pass submit: true only once you have the worker's LEGAL name from the user. If you have just a display or preferred name, leave submit off, confirm the legal name, then call again with the returned draft_company_member_id and submit: true. Never guess a legal name. For a business contractor set person_type BUSINESS before finalizing. Finalizing is one-way on this connection: once a team member is finalized, no tool here can change them — corrections are made in Gusto. So do not offer to fix a finalized team member; tell the user what to change in Gusto instead. Fields by section — only the sections you pass fields for are touched: - basics: legal_first_name + legal_last_name (provide together), legal_middle_name, email, preferred_first_name, business_name, worker_type, person_type, works_from_home. - compensation: compensation_type, amount (+ optional currency_code, defaults USD), payment_unit, receives_commission_payments, add_to_time_tracking, state_managed_wc_covered + state_managed_wc_state (+ optional state_managed_wc_class_code). - employment: start_date, work_state, country_code, flsa_status, employment_status, two_percent_shareholder. - work_address: work_address_id (the id of an existing company location from get_locations — this does not create one). To add a location, answer company_work_address with save_company_onboarding_answer, then re-read get_locations for the new id. The new address becomes a work location either way; physical_business_address is a separate, single designation, so pass it false unless the user wants this address to become the company's physical business address — passing true moves that designation off whichever address holds it now. PO boxes are rejected for either flag. Use works_from_home only for genuinely remote workers, never in place of a location not yet added: it records no address until the worker finishes self-onboarding (their home address then becomes their work address), so state tax setup stays locked until then, and telling the user it is covered is wrong. Required before a worker can be finalized — a submit fails until each of these is set: - Everyone: worker_type, legal_first_name + legal_last_name, country_code, start_date, and — unless no invite is being sent (send_invite false, or an omitted flag on a draft-id finalize) — email, since the self-onboarding invite is sent there. - Employees: flsa_status, employment_status, payment_unit, amount, and a work location: ask the user for the address where they work — not their home address — and pass its work_address_id, since that work address is what unlocks state tax setup. works_from_home plus work_state is only for an employee the user says is remote. - Employees working in WA or WY: also state_managed_wc_covered + state_managed_wc_state, because those states run their own workers' comp fund, plus state_managed_wc_class_code when covered (the user may have it; otherwise look it up with search_workers_comp_class). - Contractors: person_type, compensation_type, amount, and business_name for a BUSINESS contractor. - Unpaid members: nothing beyond the shared fields — they have no compensation. Per-member: no bulk. For several workers, call this once per worker. Before finalizing a worker, tell the user what the invite does and let them choose: the worker gets an email with a secure link and enters their own personal, tax, and payment details — the fastest, most private route, and the only one that finishes onboarding through this tool. Declining (send_invite: false) means the admin completes those details in the Gusto web app; no tool here can, so the worker stays onboarding-incomplete and unpayable until then. The choice cannot be changed from here — a finalized worker can only be invited in Gusto. Exception — the worker is the user themselves: when the person you are talking to is the worker being set up (they are putting themselves on payroll, e.g. an owner paying only themselves), there is no invite to offer and no choice to present. If they already accepted a reasonable salary, set their compensation from it — see `amount`. Do not mention self-onboarding, an email, or a secure link: an invite would point them at a flow Gusto routes an owner out of, so it cannot help them. Pass send_invite: false and tell them their own SSN and payment details are entered in Gusto, not here. NEVER ask for or accept SSN, bank, or routing numbers — on either path, and not even if the user offers them unprompted. They are entered by the worker through the emailed self-onboarding link, or by the admin in Gusto; never in this conversation. Pass send_invite: false only if the user explicitly wants to enter everything on the worker's behalf, and tell them Gusto is where those details go. Such a worker cannot be paid until the admin completes them there. send_invite is read from the call that finalizes and is not remembered from earlier calls: an omitted flag on a draft-id finalize is treated as no invite, so pass send_invite: true on that call if the worker should be emailed. Onboarding: whenever you finalize a team member while onboarding is in progress, ALWAYS re-call get_company_onboarding_status right after and continue from its next_step — finalizing a worker can unlock later steps (e.g. state tax setup, which needs an employee's work address). Do this even after a single worker; do not end your turn at the add or send the user to Gusto without first checking what onboarding needs next. Results: every error names the input field to fix in its argument, and nothing is finalized unless each part came back clean — so submitted is true only when the worker is really final, and invited is true when their self-onboarding invite has gone out or had already been sent. This call is NOT idempotent when it creates: if it returns a draft_company_member_id alongside errors, fix the flagged fields and call again WITH that id — calling again without it adds a second team member. 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.

manage_company_members

Opens a secure Gusto panel on screen where the user completes a sensitive action themselves. Supported purposes: signing a company form (e.g. a tax authorization), setting the acting admin up as the company signatory (which requires their SSN), and collecting a Social Security number or ITIN — either the Solo owner's, for their own onboarding profile, or the IRS Form SS-4 responsible party's, for the company's EIN request. Whatever the user enters in the panel is submitted straight to Gusto — this tool does NOT collect or accept a signature, legal name, SSN, bank details, or any other personal detail through the conversation, and you never see what was entered. WHEN TO USE: During onboarding when the company has a sensitive action to complete — a form awaiting signature, the admin needing to become the company signatory, the Solo owner's Social Security number still outstanding on their profile, or the EIN request missing the responsible party's personal tax ID — and the user wants to do it. Call this tool once with the matching purpose, and for ssn_collection the matching subject; the panel then handles the rest, including showing the user which items are outstanding and confirming each one. WHEN NOT TO USE: Do not ask the user to type their signature, legal name, SSN, or bank details into chat — those are entered only in the panel. RETURNS: Branch on `success`. On success, `{ success: true, status: "secure_session_ready", message }` — confirm to the user that the panel is open and invite them to complete it there. On error, `{ success: false, error_type, message }`. The panel resolves what is outstanding when it loads, and tells the user directly when there is nothing left to do. AFTER THE PANEL OPENS: Opening the panel does not complete the action, and neither does the user saying they are done — only their actually completing it does. Never tell the user the action is complete on the strength of their word alone. When they say they have finished, confirm it actually completed if you have a way to check before you tell them it is done; if it is still pending, say so plainly and offer to reopen the panel. PREREQUISITES: A valid access token whose company the acting user is a member of. GOTCHAS: The panel's session expires after a short while. If the user says it expired, call this tool again to open a fresh one. 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.

open_secure_session