Gusto

Retrieves full details for a single home address record by UUID, including street, city, state, ZIP code, and effective dates. Use list_employee_home_addresses first to find the address UUID. Call this for complete address details for one specific record.

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.

Retrieves full details for a single work location assignment by UUID, including the location address and effective dates. Use list_employee_work_addresses first to find the work address UUID. Call this for complete details about a specific work location assignment.

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.

Retrieves full details for a single company location by UUID, including complete address, phone number, and filing addresses for tax purposes. Use list_locations first to find the location UUID. Call this for complete information about a specific office or work site.

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.

Retrieves full details for a single pay schedule by UUID, including frequency, anchor dates, and next scheduled pay dates. Use list_pay_schedules first to find the schedule UUID. Call this to see when the next payday is or understand schedule configuration.

Retrieves complete details for a single payroll run by UUID, including individual worker earnings, taxes withheld, deductions, and net pay amounts. Also fetches employee data for the payroll. Use list_payrolls first to find the payroll UUID. Call this to see line-item breakdowns or specific payment details for one payroll.

Retrieves detailed time entries for a single timesheet by UUID, including daily hours worked, overtime, breaks, and notes. Use list_time_records first (third_party source) to find the timesheet UUID. Call this for line-item breakdown of someone's hours for a specific pay period.

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.

Lists batched contractor payment runs for the company. A payment group represents multiple contractor payments processed together on the same date. Shows group UUID, check date, and processing status. Use this to see batched payment history or find payment group UUIDs.

Lists all payments made to independent contractors within a date range. Shows payment amounts, check dates, and contractor info. Requires start_date and end_date parameters. Use this to see contractor payment history, audit 1099 payments, or find how much was paid to contractors. Note - only includes payments to domestic (US) contractors. International contractor payments are not included.

Lists all independent contractors (1099 workers) for the company with pagination and search. Returns contractor UUIDs, names, and basic info. Unlike employees (W-2), contractors are paid separately and file their own taxes. Use this to find contractor UUIDs or get a roster of non-employee workers. Returns all contractors including inactive; check the is_active field for current status. 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.

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.

Lists all departments in the company org structure, including department names, UUIDs, and which employees are assigned to each. Use this to see the organizational breakdown, find department headcounts, or understand how workers are grouped. Note - department employee lists and headcounts only include domestic (US) employees. International employees are not reflected in these counts.

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.

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.

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.

Lists all residential addresses on file for an employee, including current and historical addresses with effective dates. Home addresses are used for tax withholding calculations and mailing.

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.

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.

Lists all work locations assigned to an employee, including current and historical assignments with effective dates. Work addresses determine work-state tax jurisdiction. Use this to see where someone works or has worked, especially for remote or multi-location workers.

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.

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.

Lists all physical office or work locations registered for the company, including addresses and whether each is active. Locations are used for tax filing, work address assignments, and compliance. Use this to see all company offices or find location UUIDs.

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.

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.

Lists all configured pay schedules for the company, showing frequency (weekly, biweekly, monthly, etc.), name, and schedule UUID. Does not show which workers are on each schedule. Use this to understand pay frequency options or find schedule UUIDs for assignment lookups.

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.

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.

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`, the employees who track time, for companies on Gusto's native time tracking. `workers` lists an employee 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. Contractors appear in neither array. - `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.

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. 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 `stableId`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. Never guess NAICS/SIC codes; only save a code returned by that tool. 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. The response also includes `next_step`, a structured cue for what to do next — follow it: `answer_questions` means ask the questions in `remaining_question_keys` in the given order — ask the first key, do not skip ahead or reorder; `continue_in_mcp` with detail `select_plan` means call get_company_onboarding_package and then save the `tier_selection` answer; `continue_in_gusto` means direct the user to the returned `url`; `complete` means onboarding is fully finished — tell the user they're all set and do NOT prompt for more answers (onboarding_status carries no questions). You may still offer any remaining non-required questions before a `continue_in_*` step, but they don't block progressing.

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"), present the returned options, and save the chosen candidate's naics_code with save_company_onboarding_answer. 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.

Submits user feedback to Gusto. The message is sent to the Gusto team; this does not change any account data. WHEN TO USE: When the user vents, suggests an improvement, reports a bug, or praises something while working in chat. Offer it after a notable action (e.g. running payroll) when the user reacts. WHEN NOT TO USE: For support that needs a synchronous answer, or account/auth problems - this is one-way product feedback, not a support ticket. RETURNS: Branch on `success`. On success, `{ success: true, status: "received", feedback_id: "<uuid>" }` - `received` means the feedback was accepted and queued for the Gusto team (delivery is asynchronous, so this confirms acceptance, not that the team has seen it yet); surface the feedback_id so the user can reference it. On invalid input, `{ success: false, error_type: "validation_error", message: "<reason>" }`. If the feedback can't be queued, `{ success: false, error_type: "delivery_error", message: "<reason>", feedback_id: "<uuid>" }` - the submission was not accepted; ask the user to retry. PREREQUISITES: A valid access token. No company context required. GOTCHAS: One-way product feedback, not a support ticket - there's no in-channel reply. `message` is capped at 5000 characters.

Updates an existing UNPROCESSED payroll with new hours, earnings, PTO, memos, payment methods, or off-cycle settings. Use this to correct or finalize payroll inputs before running the payroll. REQUIRED WORKFLOW: Call get_payroll FIRST for any payroll you intend to update. If get_payroll returns a populated employee_compensations array, show the user the current values, get approval for the exact proposed change, then invoke this tool with the touched employees and deltas. If get_payroll returns no materialized roster (`employee_compensations` is empty or absent, `employees` is `[]`, and `calculated_at` is null), the payroll is in a pre-prepare state (its roster has not been materialized yet). In that case, invoke this tool with an empty employee_compensations array. The tool will materialize the roster and return it; you can then read the populated employee_uuids from the response and invoke this tool again with your specific deltas. CANNOT create new or off-cycle payrolls. CANNOT run or submit payroll (use run_payroll). CANNOT edit processed or submitted payrolls — this tool returns a recoverable error and no change is made. CANNOT restructure the payroll (only values of existing fields). VALUE SEMANTICS: values REPLACE existing values, they do NOT add. Sending hours: "5" sets total hours to 5, not +5. Omitted employees, compensations, and PTO entries are LEFT UNTOUCHED — this is a partial update, not a full replace. If the user's intent is additive or subtractive ("add 5 hours", "give her 2 more hours of PTO", "cut his overtime in half"), compute the new total yourself using the current value from get_payroll's response, then send the computed total — never send the delta. Example: user says "add 5 hours to Bob" and Bob's current Regular Hours from get_payroll is 40; send `hours: "45"`, not `hours: "5"`. Show the user "40 → 45" before invoking the tool. KEYING (how a submitted entry matches an existing one): - fixed_compensations and hourly_compensations: keyed by `name` (immutable identifier — must match an existing entry from get_payroll's response; do not invent names). - paid_time_off: keyed by `name` OR `policy_uuid` (supply exactly one, not both). Per-employee updatable fields: excluded (skip employee for this payroll), payment_method ("Direct Deposit" or "Check"), memo (paystub note), fixed_compensations, hourly_compensations, paid_time_off. Deductions and reimbursements cannot be edited here. Removing an employee from a payroll: set `excluded: true` on their entry. The employee stays on the roster but is not paid on this run. Send `excluded: false` to re-include. Use this whenever the user asks to "remove", "skip", "drop", or "take off" an employee for a specific payroll run. Off-cycle-only top-level fields: withholding_pay_period, skip_regular_deductions, fixed_withholding_rate. These apply to GENERAL off-cycle payrolls only (Correction, Bonus, Adhoc). Termination and transition off-cycles reject them. Use get_payroll first to check the payroll's off_cycle_reason before sending these fields. Constraints and edge cases: - Setting payment_method to "Direct Deposit" is rejected if the employee has no bank account on file. - Response currency fields (amount, hours) are returned as strings. Do not do arithmetic on them without parsing. - Follow the input_schema types for each field: amount/hours fields are strings. - Blockers: the response may include a `blockers` array when the caller has `payrolls:run` scope. Do NOT preemptively surface these to the user during the update turn. Complete the requested update and describe what changed. Blockers will surface naturally when the user attempts to run the payroll (`run_payroll`); that is the correct moment to discuss them. - Hourly editability by FLSA status: `hourly_compensations` are editable only for employees whose `flsa_status` is Nonexempt, Salaried Nonexempt, or Commission Only Nonexempt. Attempts to edit hours on any other status (Exempt, Commission Only Exempt, Owner, Unknown) are rejected with a validation_error, since hour edits on those statuses corrupt the paystub without changing pay. To adjust pay for a non-hourly employee, use `fixed_compensations` (Bonus, Correction Payment, etc.) instead. The response returns an empty `hourly_compensations` array for non-editable employees so there is no ambiguity about what is editable. Max 100 employees per call. For payrolls with more than 100 employees, invoke this tool multiple times; each call is cumulative on the roster (omitted employees are untouched, and prepare refreshes only the specified subset of the existing roster). Use `list_employees` to discover the UUIDs of employees not returned in the first materialize response.