The Gusto MCP connector routes your AI agent's tool calls to Gusto's own MCP server through Scalekit. Each user signs in to Gusto once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 71 tools.
- Tools
- 71
- What they doRead · write · destructive
- 53 · 17 · 153 read17 write1 destructive
- Users sign in with
- OAuth
- OAuth app
- Scalekit's or your own
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. Find values in app.scalekit.com > Developers > API Credentials..env SCALEKIT_ENVIRONMENT_URL=<your-environment-url>SCALEKIT_CLIENT_ID=<your-client-id>SCALEKIT_CLIENT_SECRET=<your-client-secret>Create the Gusto MCP connection
In AgentKit > Connections, create a Gusto MCP connection. The name you give it is the
connection_nameyour code passes. See Configure connections.Scalekit credentials are available for Gusto MCP server, so you don't need to register an OAuth app.
Authorize a user and make your first call
quickstart.mts import { ScalekitClient } from '@scalekit-sdk/node'import 'dotenv/config'import { createInterface } from 'node:readline/promises'const scalekit = new ScalekitClient(process.env.SCALEKIT_ENVIRONMENT_URL,process.env.SCALEKIT_CLIENT_ID,process.env.SCALEKIT_CLIENT_SECRET,)const actions = scalekit.actionsconst connector = 'gustomcp'const identifier = 'user_123'// Generate an authorization link for the userconst { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })console.log('Authorize Gusto MCP:', link)const rl = createInterface({ input: process.stdin, output: process.stdout })await rl.question('Press Enter after authorizing...')rl.close()// Make your first callconst result = await actions.executeTool({connector,identifier,toolName: 'gustomcp_get_company',toolInput: {},})console.log(result)Terminal window npx tsx quickstart.mtsquickstart.py import osfrom scalekit import ScalekitClientfrom dotenv import load_dotenvload_dotenv()scalekit_client = ScalekitClient(env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),client_id=os.getenv("SCALEKIT_CLIENT_ID"),client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),)actions = scalekit_client.actionsconnection_name = "gustomcp"identifier = "user_123"# Generate an authorization link for the userlink_response = actions.get_authorization_link(connection_name=connection_name,identifier=identifier,)print("Authorize Gusto MCP:", link_response.link)input("Press Enter after authorizing...")# Make your first callresult = actions.execute_tool(tool_input={},tool_name="gustomcp_get_company",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach user signs in once. See Authorize a user for the full flow and statuses.
Tools
Pass the exact name toexecute_toolgustomcp_get_companyRetrieve the company profile including legal name, entity type, EIN, and status.Read-onlyGet Company
Retrieve the company profile including legal name, entity type, EIN, and status.
Inputs
company_uuidstring- The UUID of the company to act on. Call get_token_info to list available company UUIDs.
gustomcp_get_company_onboarding_statusGet the company's onboarding status for its current experience, including outstanding questions, whether each is required, and their answer schemas.Read-onlyGet Company Onboarding Status
Get the company's onboarding status for its current experience, including outstanding questions, whether each is required, and their answer schemas. Drives step-by-step onboarding: save answers with save_company_onboarding_answer and re-check status after each save since a save can reroute the remaining questions.
Inputs
company_uuidstring- The UUID of the company to act on. Call get_token_info to list available company UUIDs.
gustomcp_get_compensationRetrieve a single pay rate record by UUID, including rate, frequency, and FLSA status.Read-onlyGet Compensation
Retrieve a single pay rate record by UUID, including rate, frequency, and FLSA status.
Inputs
compensation_uuidstringrequired- The unique identifier (UUID) for the record
gustomcp_get_contractorRetrieve full profile for a contractor by UUID, including name, email, and payment method.Read-onlyGet Contractor
Retrieve full profile for a contractor by UUID, including name, email, and payment method.
Inputs
contractor_uuidstringrequired- The unique identifier (UUID) for the contractor
_contextstring- The original user question or request that prompted this tool call
gustomcp_get_contractor_paymentRetrieve details for a single contractor payment by UUID, including amount and payment method.Read-onlyGet Contractor Payment
Retrieve details for a single contractor payment by UUID, including amount and payment method.
Inputs
contractor_payment_uuidstringrequired- The unique identifier (UUID) for the contractor payment
_contextstring- The original user question or request that prompted this tool call
gustomcp_get_contractor_payment_groupRetrieve all individual contractor payments within a batched payment group by UUID.Read-onlyGet Contractor Payment Group
Retrieve all individual contractor payments within a batched payment group by UUID.
Inputs
contractor_payment_group_uuidstringrequired- The unique identifier (UUID) for the contractor payment group
_contextstring- The original user question or request that prompted this tool call
gustomcp_get_contractor_payment_groupsReturns batched contractor payment runs for the company.Read-onlyGet Contractor Payment Groups
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.
Inputs
company_uuidstring- The UUID of the company to act on. Call get_token_info to list available company UUIDs.
contractor_payment_group_uuidstring- Optional. The UUID of one contractor payment group to fetch. Omit to list groups.
end_datestring- Optional end of date range (YYYY-MM-DD) when listing. Must be within 1 year of start_date.
pageinteger- Page number for pagination
perinteger- Number of items per page
start_datestring- Optional start of date range (YYYY-MM-DD) when listing. The range from start_date to end_date must be 1 year or less.
gustomcp_get_contractor_paymentsReturns payments made to independent contractors.Read-onlyGet Contractor Payments
Returns payments made to independent contractors. To list payments, pass start_date and end_date, which shows payment amounts, check dates, and contractor info for that range. Use this read-only tool to see contractor payment history, audit 1099 payments, or find how much was paid. Pass contractor_payment_uuid instead to fetch one existing payment in full, including amount, payment method, bonus breakdown, and reimbursements. Use pay_contractors to create a new domestic contractor payment. Note - only includes payments to domestic (US) contractors. International contractor payments are not included.
Inputs
company_uuidstring- The UUID of the company to act on. Call get_token_info to list available company UUIDs.
contractor_payment_uuidstring- Optional. The UUID of one contractor payment to fetch. Omit to list payments, which then requires start_date and end_date.
contractor_uuidstring- Filter payments by contractor UUID
end_datestring- End of date range (YYYY-MM-DD) for contractor payments. Required when listing.
group_by_dateboolean- When true, groups results by check date
pageinteger- Page number for pagination
perinteger- Number of items per page
start_datestring- Start of date range (YYYY-MM-DD) for contractor payments. Required when listing.
gustomcp_get_contractorsReturns the company's independent contractors (1099 workers).Read-onlyGet Contractors
Returns the company's independent contractors (1099 workers). Unlike employees (W-2), contractors are paid separately and file their own taxes. Omit contractor_uuid to list contractors with pagination and search, returning UUIDs, names, and basic info. Use this read-only tool to find contractor UUIDs or get a roster of non-employee workers; use pay_contractors to create a new domestic contractor payment. To look up several contractors at once, such as everyone in a payment group, list them in one call without contractor_uuid and match on UUID rather than fetching each one. The list includes inactive contractors, so check the is_active field for current status. Pass contractor_uuid to fetch one contractor's full profile, including name, email, business name (if applicable), payment method, and engagement dates. Note - this only includes domestic (US-based) contractors. International contractors are not included in results. If the company has international contractors, mention that totals reflect domestic contractors only.
Inputs
company_uuidstring- The UUID of the company to act on. Call get_token_info to list available company UUIDs.
contractor_uuidstring- Optional. The UUID of one contractor to fetch. Omit to list contractors.
includestring- Comma-separated fields to include: company_name, portal_invitations
onboardedboolean- Filter by contractors who have completed onboarding
onboarded_activeboolean- Filter by contractors who are onboarded and currently active
pageinteger- Page number for pagination
perinteger- Number of items per page
search_termstring- A string to search for in names
sort_bystring- Sort field and optional direction, e.g. name:asc. Supported fields: created_at, name, onboarding_status, type
terminatedboolean- Filter by contractors who are no longer active
terminated_todayboolean- Filter by contractors whose last day was today
gustomcp_get_departmentRetrieve details for a single department by UUID, including name and assigned employees.Read-onlyGet Department
Retrieve details for a single department by UUID, including name and assigned employees.
Inputs
department_uuidstringrequired- The unique identifier (UUID) for the department
_contextstring- The original user question or request that prompted this tool call
gustomcp_get_departmentsReturns the company's departments with their UUIDs, titles, and the UUIDs of the employees and contractors assigned to each.Read-onlyGet Departments
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.
Inputs
company_uuidstring- The UUID of the company to act on. Call get_token_info to list available company UUIDs.
department_uuidstring- Optional. The UUID of one department to fetch. Omit to list all departments.
gustomcp_get_employeeRetrieve full profile for an employee by UUID, including name, hire date, job, and location.Read-onlyGet Employee
Retrieve full profile for an employee by UUID, including name, hire date, job, and location.
Inputs
employee_uuidstringrequired- The unique identifier (UUID) for the employee to retrieve
includestring- Comma-separated fields to include: all_compensations, all_home_addresses, company_name, current_home_address, custom_fields, portal_invitations
gustomcp_get_employee_earnings_summaryReturn per-employee earning breakdowns aggregated across all payrolls in a date range.Read-onlyGet Employee Earnings Summary
Return per-employee earning breakdowns aggregated across all payrolls in a date range.
Inputs
company_uuidstring- The UUID of the company to act on. Call get_token_info to list available company UUIDs.
end_datestring- End of date range (YYYY-MM-DD). Defaults to today.
start_datestring- Start of date range (YYYY-MM-DD). Defaults to Jan 1 of current year.
gustomcp_get_employee_home_addressRetrieve a single home address record by UUID, including street, city, state, and ZIP.Read-onlyGet Employee Home Address
Retrieve a single home address record by UUID, including street, city, state, and ZIP.
Inputs
home_address_uuidstringrequired- The unique identifier (UUID) for the address
_contextstring- The original user question or request that prompted this tool call
gustomcp_get_employee_home_addressesReturns an employee's residential addresses, which are used for tax withholding calculations and mailing.Read-onlyGet Employee Home Addresses
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.
Inputs
employee_uuidstring- The UUID of the employee whose home addresses to list. Required unless home_address_uuid is given.
home_address_uuidstring- Optional. The UUID of one home address record to fetch.
gustomcp_get_employee_rehireRetrieve rehire details for an employee, including new start date and updated employment terms.Read-onlyGet Employee Rehire
Retrieve rehire details for an employee, including new start date and updated employment terms.
Inputs
employee_uuidstringrequired- The unique identifier (UUID) for the employee
gustomcp_get_employee_work_addressRetrieve a single work location assignment by UUID, including address and effective dates.Read-onlyGet Employee Work Address
Retrieve a single work location assignment by UUID, including address and effective dates.
Inputs
work_address_uuidstringrequired- The unique identifier (UUID) for the work location
_contextstring- The original user question or request that prompted this tool call
gustomcp_get_employee_work_addressesReturns the work locations assigned to an employee.Read-onlyGet Employee Work Addresses
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.
Inputs
employee_uuidstring- The UUID of the employee whose work addresses to list. Required unless work_address_uuid is given.
work_address_uuidstring- Optional. The UUID of one work address assignment to fetch.
gustomcp_get_jobRetrieve details for a job position by UUID, including title, department, and current pay rate.Read-onlyGet Job
Retrieve details for a job position by UUID, including title, department, and current pay rate.
Inputs
job_uuidstringrequired- The unique identifier (UUID) for the job
includestring- Use all_compensations to include all effective dated compensations instead of only the current compensation
gustomcp_get_locationRetrieve details for a company location by UUID, including address and filing information.Read-onlyGet Location
Retrieve details for a company location by UUID, including address and filing information.
Inputs
location_uuidstringrequired- The unique identifier (UUID) for the location
_contextstring- The original user question or request that prompted this tool call
gustomcp_get_locationsReturns the physical office or work locations registered for the company.Read-onlyGet Locations
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.
Inputs
company_uuidstring- The UUID of the company to act on. Call get_token_info to list available company UUIDs.
location_uuidstring- Optional. The UUID of one location to fetch. Omit to list all locations.
pageinteger- Page number for pagination
perinteger- Number of items per page
gustomcp_get_onboarding_answerGet the current answer for a single onboarding question by question_key (as surfaced by get_company_onboarding_status), including any unset fields as null.Read-onlyGet Onboarding Answer
Get the current answer for a single onboarding question by question_key (as surfaced by get_company_onboarding_status), including any unset fields as null.
Inputs
question_keystringrequired- The onboarding question to read (e.g. "ein", "who_to_pay"), as surfaced by get_company_onboarding_status.
company_uuidstring- The UUID of the company to act on. Call get_token_info to list available company UUIDs.
gustomcp_get_pay_scheduleRetrieve a pay schedule by UUID, including frequency and next scheduled pay dates.Read-onlyGet Pay Schedule
Retrieve a pay schedule by UUID, including frequency and next scheduled pay dates.
Inputs
pay_schedule_uuidstringrequired- The unique identifier (UUID) for the pay schedule
_contextstring- The original user question or request that prompted this tool call
gustomcp_get_pay_schedulesReturns the company's configured pay schedules.Read-onlyGet Pay Schedules
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.
Inputs
company_uuidstring- The UUID of the company to act on. Call get_token_info to list available company UUIDs.
pageinteger- Page number for pagination
pay_schedule_uuidstring- Optional. The UUID of one pay schedule to fetch. Omit to list all pay schedules.
perinteger- Number of items per page
gustomcp_get_payrollRetrieve complete details for a payroll run by UUID, including earnings, taxes, and net pay.Read-onlyGet Payroll
Retrieve complete details for a payroll run by UUID, including earnings, taxes, and net pay.
Inputs
payroll_uuidstringrequired- The unique identifier (UUID) for the payroll
company_uuidstring- The UUID of the company to act on. Call get_token_info to list available company UUIDs.
employee_compensations_pageinteger- Page number for paginating employee compensations within the payroll. Defaults to 1.
employee_compensations_perinteger- Number of employee compensations per page. Defaults to 100 (max).
gustomcp_get_reportsChecks the status of one or more previously triggered reports.Read-onlyGet Reports
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.
Inputs
report_request_uuidsarrayrequired- IDs (UUIDs) returned by create_reports.
gustomcp_get_time_off_balancesReturns 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.Read-onlyGet Time Off Balances
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.
Inputs
company_uuidstring- The UUID of the company to act on. Call get_token_info to list available company UUIDs.
employee_uuidsstring- Comma-separated employee UUIDs to scope results to specific workers.
policy_uuidsstring- Comma-separated time-off policy UUIDs to scope results to specific policies.
gustomcp_get_time_off_requestsReturns a company's time-off requests (PTO, sick, vacation, etc.).Read-onlyGet Time Off Requests
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.
Inputs
company_uuidstring- The UUID of the company to act on. Call get_token_info to list available company UUIDs.
employee_uuidsstring- Comma-separated employee UUIDs to scope results to specific workers.
end_datestring- Only return requests on or before this date (YYYY-MM-DD).
pageinteger- The page requested. When unspecified, returns all requests unless the endpoint forces pagination.
perinteger- Number of objects per page.
sort_orderstring- Sort by date ascending (asc) or descending (desc). Defaults to asc.
start_datestring- Only return requests on or after this date (YYYY-MM-DD).
statusstring- Comma-separated statuses to filter by: pending, approved, declined, consumed.
time_off_request_uuidstring- Optional. The UUID of one time-off request to fetch. Omit to list requests.
gustomcp_get_time_sheetRetrieve time entries for a timesheet by UUID, including daily hours, overtime, and notes.Read-onlyGet Time Sheet
Retrieve time entries for a timesheet by UUID, including daily hours, overtime, and notes.
Inputs
time_sheet_uuidstringrequired- The unique identifier (UUID) for the timesheet
gustomcp_get_token_infoReturn information about the current API token, including granted scopes and accessible resources.Read-onlyGet Token Info
Return information about the current API token, including granted scopes and accessible resources.
Inputs
This tool takes no inputs.
gustomcp_list_contractor_payment_groupsList batched contractor payment runs, showing payment group UUIDs and check dates.Read-onlyList Contractor Payment Groups
List batched contractor payment runs, showing payment group UUIDs and check dates.
Inputs
_contextstring- The original user question or request that prompted this tool call
end_datestring- Optional end of date range (YYYY-MM-DD)
pageinteger- Page number for pagination
perinteger- Number of items per page
start_datestring- Optional start of date range (YYYY-MM-DD)
gustomcp_list_contractor_paymentsList payments made to contractors within a date range.Read-onlyList Contractor Payments
List payments made to contractors within a date range. Requires start_date and end_date.
Inputs
end_datestringrequired- End of date range (YYYY-MM-DD) for contractor payments
start_datestringrequired- Start of date range (YYYY-MM-DD) for contractor payments
_contextstring- The original user question or request that prompted this tool call
contractor_uuidstring- Filter payments by contractor UUID
group_by_dateboolean- When true, groups results by check date
pageinteger- Page number for pagination
perinteger- Number of items per page
gustomcp_list_contractorsList all independent contractors for the company with pagination and search support.Read-onlyList Contractors
List all independent contractors for the company with pagination and search support.
Inputs
_contextstring- The original user question or request that prompted this tool call
includestring- Comma-separated fields to include: company_name, portal_invitations
onboardedboolean- Filter by contractors who have completed onboarding
onboarded_activeboolean- Filter by contractors who are onboarded and currently active
pageinteger- Page number for pagination
perinteger- Number of items per page
search_termstring- A string to search for in names
sort_bystring- Sort field and optional direction, e.g. name:asc. Supported fields: created_at, name, onboarding_status, type
terminatedboolean- Filter by contractors who are no longer active
terminated_todayboolean- Filter by contractors whose last day was today
gustomcp_list_custom_fields_schemaRetrieve definitions of all custom fields configured for the company, including types and options.Read-onlyList Custom Fields Schema
Retrieve definitions of all custom fields configured for the company, including types and options.
Inputs
company_uuidstring- The UUID of the company to act on. Call get_token_info to list available company UUIDs.
pageinteger- Page number for pagination (default 1)
perinteger- Number of items per page (default 25, max 500)
gustomcp_list_departmentsList all departments in the company, including names, UUIDs, and assigned employees.Read-onlyList Departments
List all departments in the company, including names, UUIDs, and assigned employees.
Inputs
_contextstring- The original user question or request that prompted this tool call
gustomcp_list_earning_typesList all earning type categories for the company, such as regular pay, overtime, and bonuses.Read-onlyList Earning Types
List all earning type categories for the company, such as regular pay, overtime, and bonuses.
Inputs
company_uuidstring- The UUID of the company to act on. Call get_token_info to list available company UUIDs.
gustomcp_list_employee_custom_fieldsRetrieve all custom field values set for a specific employee.Read-onlyList Employee Custom Fields
Retrieve all custom field values set for a specific employee.
Inputs
employee_uuidstringrequired- The unique identifier (UUID) for the employee
pageinteger- Page number for pagination
perinteger- Number of items per page
gustomcp_list_employee_employment_historyRetrieve the work history timeline for an employee, including all roles and status changes.Read-onlyList Employee Employment History
Retrieve the work history timeline for an employee, including all roles and status changes.
Inputs
employee_uuidstringrequired- The unique identifier (UUID) for the employee
gustomcp_list_employee_home_addressesList all home addresses on file for an employee, including current and historical entries.Read-onlyList Employee Home Addresses
List all home addresses on file for an employee, including current and historical entries.
Inputs
employee_uuidstringrequired- The unique identifier (UUID) for the employee
_contextstring- The original user question or request that prompted this tool call
gustomcp_list_employee_jobsList all job positions held by an employee, including title, location, and rate information.Read-onlyList Employee Jobs
List all job positions held by an employee, including title, location, and rate information.
Inputs
employee_uuidstringrequired- The unique identifier (UUID) for the employee
includestring- Use all_compensations to include all effective dated compensations for each job
pageinteger- Page number for pagination
perinteger- Number of items per page
gustomcp_list_employee_terminationsRetrieve separation records for an employee, including departure dates and final pay details.Read-onlyList Employee Terminations
Retrieve separation records for an employee, including departure dates and final pay details.
Inputs
employee_uuidstringrequired- The unique identifier (UUID) for the employee
gustomcp_list_employee_work_addressesList all work locations assigned to an employee, with effective dates.Read-onlyList Employee Work Addresses
List all work locations assigned to an employee, with effective dates.
Inputs
employee_uuidstringrequired- The unique identifier (UUID) for the employee
_contextstring- The original user question or request that prompted this tool call
gustomcp_list_employeesList all employees for the company with pagination and filtering by status, onboarding, or name.Read-onlyList Employees
List all employees for the company with pagination and filtering by status, onboarding, or name.
Inputs
company_uuidstring- The UUID of the company to act on. Call get_token_info to list available company UUIDs.
includestring- Comma-separated fields to include: all_compensations, all_home_addresses, company_name, current_home_address, custom_fields, portal_invitations
location_uuidstring- Filter by employees assigned to a specific location UUID
onboardedboolean- Filter by employees who have completed onboarding
onboarded_activeboolean- Filter by employees who are onboarded and currently active
pageinteger- Page number for pagination
payroll_uuidstring- Filter by employees included in a specific payroll UUID
perinteger- Number of items per page
search_termstring- A string to search for in names
sort_bystring- Sort field and optional direction, e.g. name:asc. Supported fields: created_at, name, onboarding_status
terminatedboolean- Filter by employees who are no longer active with the company
terminated_todayboolean- Filter by employees whose last day was today
uuidsarray- Subset of employee UUIDs to fetch. Maximum 100 UUIDs.
gustomcp_list_job_compensationsList the pay rate history for a job position, showing all rate changes over time.Read-onlyList Job Compensations
List the pay rate history for a job position, showing all rate changes over time.
Inputs
job_uuidstringrequired- The unique identifier (UUID) for the job
includestring- Use all_compensations to include all effective dated compensations instead of only the current compensation
pageinteger- Page number for pagination
perinteger- Number of items per page
gustomcp_list_locationsList all physical office and work locations registered for the company.Read-onlyList Locations
List all physical office and work locations registered for the company.
Inputs
_contextstring- The original user question or request that prompted this tool call
pageinteger- Page number for pagination
perinteger- Number of items per page
gustomcp_list_pay_periodsList all pay periods for the company, showing start and end dates and linked payroll runs.Read-onlyList Pay Periods
List all pay periods for the company, showing start and end dates and linked payroll runs.
Inputs
company_uuidstring- The UUID of the company to act on. Call get_token_info to list available company UUIDs.
end_datestring- Filter pay periods ending on or before this date (YYYY-MM-DD). Defaults to today. More than 90 days ahead is moved back to 90 days, with a note.
payroll_typesstring- Comma-separated payroll types to include: regular, transition
start_datestring- Filter pay periods starting on or after this date (YYYY-MM-DD). Defaults to 3 months before today, or before end_date if that's earlier.
gustomcp_list_pay_schedule_assignmentsShow which employees are assigned to which pay schedules.Read-onlyList Pay Schedule Assignments
Show which employees are assigned to which pay schedules.
Inputs
company_uuidstring- The UUID of the company to act on. Call get_token_info to list available company UUIDs.
gustomcp_list_pay_schedulesList all pay schedules for the company, showing frequency and schedule UUID.Read-onlyList Pay Schedules
List all pay schedules for the company, showing frequency and schedule UUID.
Inputs
_contextstring- The original user question or request that prompted this tool call
pageinteger- Page number for pagination
perinteger- Number of items per page
gustomcp_list_payroll_blockersIdentify issues preventing a payroll from being processed, such as missing setup or documents.Read-onlyList Payroll Blockers
Identify issues preventing a payroll from being processed, such as missing setup or documents.
Inputs
payroll_uuidstringrequired- The unique identifier (UUID) for the payroll to check blockers for
company_uuidstring- The UUID of the company to act on. Call get_token_info to list available company UUIDs.
gustomcp_list_payrollsList all payroll runs for the company with optional filtering by type, date, and status.Read-onlyList Payrolls
List all payroll runs for the company with optional filtering by type, date, and status.
Inputs
company_uuidstring- The UUID of the company to act on. Call get_token_info to list available company UUIDs.
date_filter_bystring- Switch start_date/end_date filtering from pay-period to check-date. Requires processing_statuses=processed. Only valid value is "check_date". Defaults to pay-period if not provided.
end_datestring- Filters where the pay period ends on or before this date (YYYY-MM-DD). Defaults to today. More than 90 days ahead is moved back to 90 days, with a note.
includestring- Comma-separated: taxes, totals, payroll_status_meta, risk_blockers, reversals
pageinteger- The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.
payroll_typesstring- Comma-separated: regular,off_cycle,external
perinteger- Number of objects per page. For majority of endpoints will default to 25.
processing_statusesstring- Comma-separated: processed,unprocessed
sort_bystring- Sort field: pay_period or check_date
sort_orderstring- Sort payrolls in ascending (asc) or descending (desc) chronological order. Defaults to asc.
start_datestring- Filters where the pay period starts on or after this date (YYYY-MM-DD). Defaults to 6 months before today, or before end_date if that's earlier. A range over 1 year is shortened from the start, with a note.
gustomcp_list_time_recordsList time records for the company over a date range.Read-onlyList Time Records
List time records for the company over a date range. Requires start_date and end_date.
Inputs
end_datestringrequired- End date of the pay period (YYYY-MM-DD). Filters both native shifts and third-party timesheets.
start_datestringrequired- Start date of the pay period (YYYY-MM-DD). Filters both native shifts and third-party timesheets.
company_uuidstring- The company's UUID.
gustomcp_search_business_infoResolve free-text business info to canonical codes: type industry returns NAICS industry classifications, type occupation returns BLS occupation codes, matched against the user's query.Read-onlySearch Business Info
Resolve free-text business info to canonical codes: type industry returns NAICS industry classifications, type occupation returns BLS occupation codes, matched against the user's query.
Inputs
querystringrequired- The user's free-text description of what to resolve, in their own words (e.g. "we run an apple orchard" for industry, or "software developer" for occupation).
typestringrequired- What kind of business information to resolve. "industry" returns NAICS industry classifications; "occupation" returns BLS occupation codes.one of
industryoccupation company_uuidstring- The UUID of the company to act on. Call get_token_info to list available company UUIDs.
gustomcp_search_workers_comp_classResolves a description of the work someone does into that state's workers' comp risk-class candidates, each with a verified code and description.Read-onlySearch Workers Comp Class
Resolves a description of the work someone does into that state's workers' comp risk-class candidates, each with a verified code and description. Requires `state` (WA or WY — only those two run their own state fund, so only they use class codes). Use this to get the state_managed_wc_class_code that manage_company_members needs to finalize a covered employee there: search the work the employee does (e.g. "roofing", "office administration"), present the candidates, and pass the code the user picks. Never guess a class code — it is validated against the state's list and a wrong one is rejected. Query with the WORK AS A NOUN, never a job title and never what the person does. These lists name trades, so "software" works where "work with computers" and "write code" do not, "plumbing" where "plumber" and "fixing pipes" may not, and "barber shop" where "hair stylist" does not. Verb and activity phrasing is the most common reason this search comes back wrong, because words like "work" appear in dozens of unrelated trades. If the user describes an activity, name the industry it belongs to and search that. If nothing comes back, rephrase in the state's industry terms and search again; two or three attempts is reasonable. If the user gives you a code themselves, that is their choice — pass it straight to manage_company_members as-is and do not run it through this search to second-guess it. Use this search only to resolve a code the user does not have. If a second wording also finds nothing in WA, call again with list_categories: true instead of guessing further. That returns the headings WA files its codes under — the list may simply not use your word for the work ("hair stylist" appears nowhere; the heading is "Beauty parlors"). Pick the heading that best covers the work, search again using it as the query, and present the codes it returns. WY has no such headings, so there rely on the search and on company_industry_candidates. If you still cannot find a code, stop and say so. Do not guess one, and do not set state_managed_wc_covered to false to get past the error — that tells Gusto the employee is not covered by the state fund, which is a false compliance answer and worse than leaving the work unfinished. Leaving the worker unfinalized is the correct outcome here: say you could not identify the class code and ask the user to set it in Gusto, where the picker lists the codes their company has configured. The code describes THE WORK THIS PERSON DOES, not what the business does. Two people at the same company routinely need different codes, and picking the company's trade for someone who doesn't do it overcharges the employer. In WY, office and sales staff have their own codes regardless of the industry — 000010 Clerical Office Occupations, 000020 Outside Sales, 000030 Inside Sales, 000040 Temporary Help - Office, 000050 Temporary Help - Other — so a bookkeeper at a roofing company is 000010, not a roofing code. Search for the person's actual work first; only reach for the company's trade when they really do that trade. For WY the results may also include company_industry_candidates: the codes matching the company's own registered industry. Those are the right answer only for someone doing that trade, and there is often more than one (roofing splits into all-types, residential and nonresidential), so present them and let the user choose rather than assuming the first. If the list comes back empty, ask the user for a clearer description and search again. VOICE: helpful, not technical. Don't show the user this tool's internal names — question keys, field names, tool names, status values — describe what they mean instead, and don't volunteer counts unless asked. Where a value has a proper name, use it: "the Plus plan", not "plus". Codes the user picks from a list, like NAICS or workers' comp class codes, are content: show those verbatim.
Inputs
querystringrequired- The user's free-text description of the work the person does, in their own words (e.g. "roofing" or "office administration").
statestringrequired- Two-letter state; only WA and WY have class codes.
company_uuidstring- The UUID of the company to act on. Call get_token_info to list available company UUIDs.
list_categoriesboolean- WA only: returns the headings WA files its class codes under instead of searching. Use it after a search and one rephrase have both come back empty, then search again with the heading that best covers the work.
gustomcp_accept_reasonable_salaryAccept the most recently calculated reasonable-salary estimate (from calculate_reasonable_salary) for a Solo S-corp owner, recording it as their W-2 salary for IRS-defensibility.WriteAccept Reasonable Salary
Accept the most recently calculated reasonable-salary estimate (from calculate_reasonable_salary) for a Solo S-corp owner, recording it as their W-2 salary for IRS-defensibility. Call only after the user has reviewed and explicitly confirmed the estimate.
- Idempotent
Inputs
company_uuidstring- The UUID of the company to act on. Call get_token_info to list available company UUIDs.
salaryinteger- The salary to accept, in whole US dollars, when the user chose a specific figure from inside the estimate's `range`. Omit to accept the recommended `result`. A value outside the range is rejected.
gustomcp_calculate_rd_tax_creditEstimates the annual federal R&D tax credit (IRC §41) a business could claim, from how many US people work on building or improving its product, what they're paid on average, and what the business does.WriteCalculate Rd Tax Credit
Estimates the annual federal R&D tax credit (IRC §41) a business could claim, from how many US people work on building or improving its product, what they're paid on average, and what the business does. Returns the estimated credit, the inputs it used, and `guidance`. A ballpark for comparison, NOT tax advice, and it files nothing. CALL IT BEFORE ASKING THE USER ANYTHING. Every argument is optional, so pass whatever they have already told you and call it empty only when they have told you nothing — calling empty and then again with numbers already in hand just costs a round trip. If they are signed in to Gusto the server already knows their business and may hand back a complete estimate with no questions at all — for a company that has run payroll that is Gusto's own modelled estimate from real payroll, better than anything these three inputs can produce. The company's own figures take precedence over values you pass, so a number the user guessed cannot improve the answer and asking for it wastes their time. It also needs no company, EIN, entity or payroll history at all, so a business that isn't a Gusto customer still gets an estimate from the three inputs below. ALWAYS FOLLOW `guidance`, returned on every response. It says how to present the number, what to ask for next, and whether an industry code would change anything. It is the authority when it differs from this description; paraphrase it rather than reading it out. When `needs` is non-empty, ask for everything it names in one message and call again. Never invent a headcount, a salary or an industry code: a guessed number becomes a number the user believes. Resolve an industry code with `search_business_info` (type `industry`) from the business's own words and let the user pick, but only when `guidance` asks for one. IT DOES NOT ANSWER WHETHER THEY QUALIFY. That turns on whether the work itself looks like research, which this tool never sees. A number here is what the credit could be worth if they qualify, never confirmation that they do, AND A LOW NUMBER IS NOT EVIDENCE THEY DON'T — it reflects only headcount and pay. Send "can we claim this?" to `check_rd_credit_qualification`. NOT THE SAME AS ITS NEIGHBOURS: `calculate_scorp_tax_savings` estimates savings from electing S-corp status, and `calculate_reasonable_salary` suggests an owner's W-2 salary. Neither has anything to do with the R&D credit. `check_rd_credit_qualification` answers whether the work qualifies at all. Use this tool for "how much".
Inputs
avg_yearly_salaryinteger- Average annual pay across those people, in whole US dollars. Optional, and ignored when the signed-in company has a figure of its own.
naics_codestring- The business's NAICS industry code, from `search_business_info` (type `industry`). Optional; sharpens the estimate when no industry is already known for the business.
num_peopleinteger- Number of US employees and contractors working on building or improving the product. Optional, and ignored when the signed-in company has a figure of its own.
gustomcp_calculate_reasonable_salaryCalculate an IRS-defensible reasonable salary for an S-corp owner from BLS wage data, given the company's zip_code and one or more occupations (codes from search_business_info with type occupation).WriteCalculate Reasonable Salary
Calculate an IRS-defensible reasonable salary for an S-corp owner from BLS wage data, given the company's zip_code and one or more occupations (codes from search_business_info with type occupation). Overwrites the single in-progress estimate for the company/owner; call accept_reasonable_salary to persist it after user confirmation.
- Idempotent
Inputs
occupationsarrayrequired- The occupation(s) making up the owner's role. At least one entry is required — an empty array is rejected with kind `no_occupations`. Pass one entry for a single role; for a split role pass several, with time_percentage values summing to 1.0.
zip_codestringrequired- The company's 5-digit ZIP code, used to find the BLS wage area.
annual_net_revenueinteger- The company's annual net revenue in whole USD; when provided, caps the salary at this amount.
company_uuidstring- The UUID of the company to act on. Call get_token_info to list available company UUIDs.
work_scheduleobject- The owner's work schedule. Defaults to full-time.
gustomcp_check_plaid_connection_statusReports where the company's Plaid bank connection stands.WriteCheck Plaid Connection Status
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.
Inputs
company_uuidstring- The company's UUID. Only needed when the acting user is authorized for more than one company; omit it otherwise.
gustomcp_check_rd_credit_qualificationAssesses whether a business's work could qualify for the federal R&D tax credit (IRC §41): whether what they build looks like research, what stands in the way, and which tax year to pursue.WriteCheck Rd Credit Qualification
Assesses whether a business's work could qualify for the federal R&D tax credit (IRC §41): whether what they build looks like research, what stands in the way, and which tax year to pursue. Returns an assessment, what would sharpen it, and `guidance`. NOT tax advice, and it files nothing. NEVER TELL THE USER THEY DO NOT QUALIFY. This tool cannot return that answer and neither should you. Around half the businesses who walk away from this credit talk themselves out of it, usually because "we don't do research" — while running exactly the kind of work that counts. A weak result here means we have seen little, not that there is nothing there. That goes for every blocker too: each one carries a `remedy`, none of them is total, and none of them is a no. TIMING IS NEVER A REASON THEY CANNOT CLAIM EITHER — the year this names always has an open window, and the credit is claimable every year. CALL IT WITH NO ARGUMENTS FIRST, before asking the user anything. Every argument is optional. For a signed-in company the server often already knows the entity type, financial year end, claim year and whether they have filed, and hands back a filing window with no questions at all. ALWAYS FOLLOW `guidance`, returned on every response. It says how to present the result, which blockers to state as fact and which to raise as questions, what to ask next, and how much weight this assessment carries. It is the authority when it differs from this description; paraphrase it rather than reading it out. When `needs` is non-empty, ask for what it names — one thing at a time, in the user's own words, never as a tax question — and call again. Never guess an entity type or a tax year. NOT THE SAME AS `calculate_rd_tax_credit`, which estimates how much the credit could be worth. That one answers "how much could we get"; this one answers "can we claim it". Use both when the user wants both. `calculate_scorp_tax_savings` and `calculate_reasonable_salary` are about S-Corp election and owner pay, have nothing to do with the R&D credit, and are never a substitute for this tool.
Inputs
claim_tax_yearinteger- The tax year the business wants to claim. When the business's financial year does not end in December, pass the calendar year its fiscal year starts in, not the year it ends (a year ending September 2026 started in 2025, so pass 2025); work it out from the year end month. For a December year end both are the same year. A year whose window has closed is moved forward rather than refused.
company_namestring- The name of the business. Used to work out what the business does; not written to our tool call logs.
company_websitestring- The business's website, used for a read of its public web presence; the response says what that read found, or that it did not run. Only ask for it when `guidance` does; not written to our tool call logs.
does_client_workboolean- Whether this work is done for clients. On its own this changes nothing - it only matters alongside the next two.
entity_typestring- How the business is set up for tax. Optional, and prefilled for a signed-in company - call with no arguments first. Never guess it.one of
general_partnershippartnershiplimited_partnershipllps_corpc_corpproprietorshipassociationco_ownershipjoint_venturenon_profittrusteeship has_filed_returnboolean- Whether the return for that tax year has already been filed. Never a reason they cannot claim - it only changes which route to take.
paid_regardless_of_outcomeboolean- Whether the business is paid whether or not the work succeeds.
received_government_fundingboolean- Whether any of this work was paid for by a government grant. Only the funded portion is affected.
retains_rights_to_resultsboolean- Whether the business keeps the rights to what it builds.
tax_year_end_monthinteger- The month the business's financial year ends, 1-12. Defaults to December; only ask if they mention a non-calendar year.
work_descriptionstring- What the business builds or improves, in their own words. Ask for it plainly ("what do you make, and what have you been trying to get working?") rather than as a tax question; not written to our tool call logs.
work_performed_in_usboolean- Whether the research work is performed in the United States, including Puerto Rico and Guam. If only some of it is, answer true and say which part.
gustomcp_connect_bank_via_plaidOpens a Plaid-hosted flow where the user connects the company's payroll funding account — the account payroll and taxes are paid from — verifying instantly in most cases.WriteConnect Bank Via Plaid
Opens a Plaid-hosted flow where the user connects the company's payroll funding account — the account payroll and taxes are paid from — 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. NAMING: When you tell the user about this step, call it the company's payroll funding account. Do not shorten it to "your bank account". WHEN TO USE: Whenever next_step returns detail `connect_bank`, or the user asks to add or change the company's payroll funding 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 the company's payroll funding account, 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.
Inputs
company_uuidstring- The company's UUID. Only needed when the acting user is authorized for more than one company; omit it otherwise.
gustomcp_create_companySIGNUP/ONBOARDING PHASE tool, and the first step — the other onboarding tools are company-scoped and fail until this has created a company.WriteCreate Company
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.
Inputs
company_namestringrequired- The company's name (required).
confirmedbooleanrequired- Pass false on the first call to get back the `account_email` to confirm with the user. Set true only after the user explicitly confirms they want to create this real Gusto company now with the supplied details, including that `account_email`.
first_namestringrequired- The user's first name (required).
last_namestringrequired- The user's last name (required).
number_employeesinteger- Number of employees, including the owner.
phonestring- Contact phone number for the account.
statesarray- USPS state codes where the company operates (e.g. ["CA", "NY"]).
gustomcp_create_reportsEnqueues one or more reports.WriteCreate Reports
Enqueues one or more reports. A single-payroll entry usually finishes in 10-60 seconds. A payroll_journal date-range entry can take up to an hour for a company with over 100 active employees, since it routes to a slower queue -- other date-range report types (e.g. contractor_payments_summary) run on a faster queue and don't have that delay. After calling this tool, call get_reports to check progress. There's no wait primitive here and no clock to pace a fixed cadence against, so check at most 5 times, a few seconds apart, then tell the user the report is still generating rather than looping indefinitely -- especially for a payroll_journal date-range entry, where a handful of quick checks won't be enough; don't mistake incomplete generation for failure. Use this tool, not get_payroll, whenever the user asks for a "payroll report", "payroll summary report", "payroll journal report", "payroll journal", or a CSV/exportable payroll document -- these all describe the same report_type: payroll_journal, not distinct or ambiguous intents. get_payroll only returns raw JSON line-item details for a single payroll; it does not produce a report file. Available report types: - payroll_journal: Payroll Journal Report (CSV). Either payroll_uuid for a single payroll (its company is looked up automatically, so company_uuid is not needed), or company_uuid plus a start_date/end_date date range (dates alone can't identify a company -- if you don't already know it, call get_token_info first: use resource.uuid for a single-company token, or pick one from accessible_resources for a multi-company token). Dates filter on paycheck date (the day employees are paid), not pay period -- list_payrolls defaults to pay-period dates, so pass date_filter_by=check_date and processing_statuses=processed there to match this report's basis. The date range cannot exceed 366 days. Use list_payrolls to find a payroll_uuid if unsure. - cash_requirements: Cash Requirements Report, summarizing the cash needed to fund a single payroll. Requires payroll_uuid (its company is looked up automatically). There is no date-range variant. - contractor_payments_summary: Contractor Payments Summary Report (CSV). Requires company_uuid plus a start_date/end_date date range (dates alone can't identify a company -- if you don't already know it, call get_token_info first). Dates filter on paycheck date. The date range cannot exceed 366 days. There is no single-payroll variant. Not every report type is available on every connection. Attempt the entry either way and react to the result: if it comes back with error_type restricted_report, this connection cannot create that report type and retrying will not help, so tell the user instead. Returns {reports: [...]}, one entry per input entry, in the same order. A successful entry is {company_uuid, report_request_uuid, status: 'pending', message}; a failed one is {company_uuid, success: false, error} with no report_request_uuid -- skip entries carrying success: false rather than assuming every entry has an id to poll.
Inputs
reportsarrayrequired- One or more reports to enqueue. Each entry specifies a report_type and its params.
gustomcp_get_company_onboarding_packageGet the company's available onboarding plans, add-ons, and benefits, plus Gusto's recommended package and the company's current selection.WriteGet Company Onboarding Package
Get the company's available onboarding plans, add-ons, and benefits, plus Gusto's recommended package and the company's current selection. The first call made once the profile is ready also computes and stores the recommendation, a one-time side effect.
Inputs
company_uuidstring- The UUID of the company to act on. Call get_token_info to list available company UUIDs.
gustomcp_manage_accountGet the Gusto account's status or resend the password setup email, via the action parameter.WriteManage Account
Get the Gusto account's status or resend the password setup email, via the action parameter.
Inputs
actionstringrequired- The account action to perform.one of
get_statusresend_password_setup_email
gustomcp_manage_company_membersAdds or changes ONE company member (employee or contractor) per call — the name is plural for the resource, not for batching.WriteManage Company Members
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.
Inputs
add_to_time_trackingboolean- Contractors — add to time tracking.
amountstring- Pay amount, e.g. "120000.00". When the worker is a Solo S-corp owner and get_company_onboarding_status reports owner_profile.accepted_reasonable_salary, pass that figure here with payment_unit YEAR rather than asking what they should pay themselves — it is the salary they already accepted from the Reasonable Salary Calculator, and leaving it out puts them on payroll at no salary.
business_namestring- Legal business name, for BUSINESS contractors.
company_uuidstring- The UUID of the company to act on. Call get_token_info to list available company UUIDs.
compensation_typestring- Contractor wage type — HOURLY or FIXED. Not used for employees: an employee's salaried-vs-hourly is set by payment_unit (YEAR = salaried, HOUR = hourly).
country_codestring- Two-letter ISO COUNTRY code the worker is employed in — "US" for a US worker. Required to finalize any worker, including US ones; it is never assumed, so set it explicitly. This is the country, not the state: "CA" here means Canada. For a worker in California set country_code "US" and work_state "CA".
currency_codestring- Defaults to USD.
draft_company_member_idstring- Omit to add a new team member; pass the id this tool returned to change or finalize one already started.
emailstring- Work email; the self-onboarding invite is sent here. Required to finalize a worker you are inviting — ask the user for it. Optional when no invite is being sent, which is send_invite false, or a finalize of an existing draft that does not pass send_invite.
employment_statusstring- Employees only: FULL_TIME, PART_TIME_ELIGIBLE, PART_TIME, SEASONAL, or VARIABLE. Required to finalize a domestic employee.one of
FULL_TIMEPART_TIMEPART_TIME_ELIGIBLESEASONALVARIABLE flsa_statusstring- Employees: EXEMPT, NONEXEMPT, or NOTAPPLICABLE.one of
EXEMPTNONEXEMPTNOTAPPLICABLE legal_first_namestring- First name as it appears on the worker's government ID. Do not put a display or preferred name here — if the user simply named the worker, that is a display name, so leave this unset and ask them for the legal name. Provide together with legal_last_name.
legal_last_namestring- Last name as it appears on the worker's government ID — same rule as legal_first_name: never a display name. Provide together with legal_first_name.
legal_middle_namestring- Middle name or initial as it appears on the government ID; omit if none.
payment_unitstring- Pay unit: HOUR, WEEK, MONTH, YEAR, or PAYCHECK. For an employee this sets salaried (YEAR) vs hourly (HOUR); omit for a contractor paid a fixed amount.one of
HOURWEEKMONTHPAYCHECKYEAR person_typestring- For contractors, set this — INDIVIDUAL or BUSINESS (a contractor added without it defaults to INDIVIDUAL). Omit for employees and unpaid members.one of
INDIVIDUALBUSINESS preferred_first_namestring- Preferred first name.
receives_commission_paymentsboolean- Whether the worker receives commission payments.
send_inviteboolean- Whether the worker is emailed a secure link to enter their own personal, tax, and payment details (SSN, bank) — the fastest, most private way to finish setup, and the only way to complete a worker through this tool. Omitting it means an invite when adding a new worker, and NO invite when finalizing an existing draft, since the flag is not carried over from the call that created it: pass it explicitly on a finalize. Set false only when the admin will enter those details in the Gusto web app, or when the worker is the user themselves (nobody to invite). No tool here enters a worker's personal, tax, or payment details, so a send_invite:false worker stays onboarding-incomplete and unpayable until the admin finishes them in Gusto. Either way those details are never collected in this conversation.
start_datestring- Employment start date, YYYY-MM-DD. Required to finalize any worker.
state_managed_wc_class_codestring- Workers' comp class code. Required when state_managed_wc_covered is true; omit when it is false. If the user gives you a code, use it as-is — that is their choice, don't second-guess it with a lookup. If it is needed and neither you nor the user has it, resolve it with the search_workers_comp_class tool and present the candidates for the user to pick (never guess — a wrong code is rejected); if that tool is unavailable or finds nothing, leave the worker unfinalized and ask the user to set the code in Gusto.
state_managed_wc_coveredboolean- Employees in WA or WY: whether the state workers' comp fund covers them. Required to finalize such an employee, and must be sent together with state_managed_wc_state.
state_managed_wc_statestring- WA or WY — the state running the workers' comp fund. Send together with state_managed_wc_covered.
submitboolean- true finalizes the team member at the end of this call. Only set it once the user has given the worker's legal name — finalizing is one-way here, and afterwards changes have to be made in Gusto.
two_percent_shareholderboolean- Employees only, and only meaningful for S-corp companies: whether the employee owns more than 2% of an S-corp, which affects their benefits tax treatment. Optional — defaults to false — and you do not need to ask the user about it. Pass true only when you already know the company is an S-corp and this employee is a 2%-or-more shareholder; the system rejects true for any non-S-corp company. Otherwise omit it.
work_address_idstring- Id of an existing company work location (CompanyAddress); omit if not assigning one.
work_statestring- Two-letter US work state, e.g. "CA". Required to finalize a work-from-home employee; otherwise it comes from the assigned work location.
worker_typestring- EMPLOYEE, CONTRACTOR, or UNPAID. Required when adding a new team member.one of
EMPLOYEECONTRACTORUNPAID works_from_homeboolean- Employees — true only if the worker genuinely works from home. Do not combine with work_address_id, and never use it in place of a location that has not been added yet — add one by answering company_work_address instead: works_from_home records no address until the worker finishes self-onboarding, so state tax setup stays locked until then.
gustomcp_open_secure_sessionOpens a secure Gusto panel on screen where the user completes a sensitive action themselves.WriteOpen Secure Session
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 SSN or ITIN — 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.
Inputs
purposestringrequired- Required — the caller must choose. Which secure action to open: form_signing (sign an outstanding company form), signatory_creation (set the acting admin up as the company signatory — they enter their own SSN in the panel), or ssn_collection (someone enters a Social Security number or ITIN — see `subject`). The last two both take an SSN and are not interchangeable: choose signatory_creation only when the company still needs a signatory, and ssn_collection when a number is missing from onboarding data. Never ask for or accept the SSN in chat.one of
form_signingsignatory_creationssn_collection company_uuidstring- The UUID of the company to act on. Call get_token_info to list available company UUIDs.
subjectstring- Only for ssn_collection, and the two choices are NOT interchangeable, because they are different people's numbers and different panels. Use `self` (the default) when the Solo owner's own employee profile is missing their Social Security number — the step get_company_onboarding_status returns as detail `collect_owner_ssn`. Use `responsible_party` only when a file_ein validation has reported the IRS Form SS-4 responsible party's SSN or ITIN outstanding. Pick it from which item is actually outstanding right now, never from who happens to be talking and never by carrying over the subject from an earlier call in the same conversation: the owner's profile and the company's EIN request are separate items that can both be open, and the wrong subject writes one person's number into the other's record. Ignored for the other purposes.one of
selfresponsible_party
gustomcp_run_payrollCalculate and submit an existing unprocessed payroll by payroll_uuid.WriteRun Payroll
Calculate and submit an existing unprocessed payroll by payroll_uuid. Cannot create new or off-cycle payrolls; use update_payroll first to adjust hours, amounts, or PTO before running.
- Idempotent
Inputs
payroll_uuidstringrequired- The unique identifier (UUID) for the payroll
company_uuidstring- The UUID of the company to act on. Call get_token_info to list available company UUIDs.
gustomcp_save_company_onboarding_answerSave the answer for one onboarding question_key.WriteSave Company Onboarding Answer
Save the answer for one onboarding question_key. The value's shape depends on the question (see its value_schema from get_company_onboarding_status); a successful save returns the refreshed onboarding_status since a save can reroute the remaining questions.
- Idempotent
Inputs
question_keystringrequired- The onboarding question to answer (e.g. "who_to_pay"), as surfaced by the onboarding status read.
valueobjectrequired- The answer object for the given question_key. Most questions take a flat object whose keys are the field names from the question value_schema — e.g. { "pay_employees": true } for question_key "who_to_pay". Exception: "company_state_tax_setup" nests its state-qualified keys under a "fields" object — e.g. { "fields": { "CA.edd_account_number": "123-4567-8", "CA.ett_rate": "0.1" } }, NOT those keys at the top level. On a wrong shape, the errors list names the expected fields.
company_uuidstring- The UUID of the company to act on. Call get_token_info to list available company UUIDs.
gustomcp_submit_feedbackSubmit user feedback about the Gusto MCP experience, with an optional category and freeform context metadata (e.g.WriteSubmit User Feedback
Submit user feedback about the Gusto MCP experience, with an optional category and freeform context metadata (e.g. tool invoked, app version, OS).
Inputs
messagestringrequired- The user's feedback about the Gusto AI integration (required, max 5000 characters)
categorystring- Optional category for the feedbackone of
bugfeature_requestgeneralpraise contextobject- Optional metadata (e.g. tool invoked, app version, OS) to help the reviewer
gustomcp_update_compensationUpdates an employee's compensation - the pay rate, pay period, or FLSA status for one of their jobs.WriteUpdate Compensation
Updates an employee's compensation - the pay rate, pay period, or FLSA status for one of their jobs. Use this for a raise, a pay cut, or to correct a rate that was entered wrong. REQUIRED WORKFLOW: Call list_job_compensations (or get_compensation) FIRST for the job you intend to change. Show the user the current rate and effective date, get explicit approval for the exact proposed change, then invoke this tool with the target compensation_uuid, the version from that read, and the new values. APPEND vs OVERWRITE is decided by effective_date, compared against the CURRENT compensation's effective_date (not today), not by you: - An effective_date AFTER the current compensation's effective_date records a NEW dated compensation that takes effect on that date; current pay is unchanged until then. This is the normal path for a raise or any scheduled change. If the current compensation has minimum-wage adjustment enabled, a scheduled change is refused (it cannot carry that setting forward) - tell the user to make it in Gusto. - Omitting effective_date (or passing the current compensation's own effective_date) CORRECTS the current compensation in place, with no new dated row. Use this only to fix a rate that was entered wrong and has NOT yet been paid. If a payroll covering that period has already been calculated but not submitted, the in-place correction is refused (it would not update that draft) - schedule the change with a future effective_date, or make the correction in Gusto so the payroll picks up the new rate. - An effective_date BEFORE the current compensation's effective_date is rejected with a recoverable error: you cannot move a compensation earlier onto an already-run payroll. Use a Correction off-cycle payroll for an amount that was already paid. Correcting a compensation in place affects pay going forward and does not retroactively change an already-run payroll, which stays as it was paid. To change an amount that was already paid, run a Correction off-cycle payroll in Gusto. CANNOT create a new job or delete a compensation. To stop paying someone or remove a compensation, tell the user to do it in Gusto (for example by terminating them or ending the job); never set the rate to 0, or a near-zero amount, as a substitute: a $0 rate means pay calculated at that compensation is $0 from its effective date. CANNOT rename a job title on its own: a title change with no pay change is a job update and is out of scope, so tell the user to rename the title in Gusto. A title supplied ALONGSIDE a pay change is applied at the change's effective date. VALUE SEMANTICS: values REPLACE existing values, they do not add. rate: "85000.00" sets the rate to 85000; it is not a delta. Omitted fields are left unchanged. If the user's intent is relative ("bump her 5%"), compute the new absolute rate yourself from the current value and send that, showing the user "70000.00 -> 73500.00" before invoking the tool. Constraints and edge cases: - rate is a string; follow the input_schema types and do not do arithmetic on returned string amounts without parsing. - payment_unit is the pay basis (Hour, Week, Month, Year, Paycheck). Switching an employee between hourly and salaried has downstream effects on how they are paid; confirm the switch with the user before sending it. - effective_date is YYYY-MM-DD. - version is required: pass the version from your most recent read of this compensation (get_compensation, list_job_compensations, or a prior update_compensation response). If the compensation changed since then, the tool returns a recoverable stale-version error and writes nothing: re-read it, show the user the current values, and get their approval again before retrying. Recompute any relative change from the new values. - A successful response may include a `warnings` array describing real side effects of the change (for example: converting a worker to hourly can turn off AutoPilot for their whole pay schedule; an owner's rate is stored as a converted per-paycheck amount, so the stored number differs from what you sent). Relay every warning to the admin.
Inputs
compensation_uuidstringrequired- UUID of the current compensation to change. Get it from list_job_compensations or get_compensation.
versionstringrequired- The compensation's version from your most recent read of it (get_compensation, list_job_compensations, or a prior update_compensation response). A mismatch means it changed since you read it.
effective_datestring- YYYY-MM-DD. A date after the current compensation's effective_date appends a new dated compensation; omitting it (or passing the current date) corrects in place; a date earlier than the current effective_date is rejected.
flsa_statusstring- FLSA classification (e.g. Exempt, Nonexempt, Salaried Nonexempt, Owner). REPLACES the existing status.
payment_unitstring- Pay basis. Changing between Hour and a salaried unit (Year/Month/Week) changes how the employee is paid; confirm with the user.one of
HourWeekMonthYearPaycheck ratestring- New pay rate as a string (e.g. "85000.00" for salaried, "22.50" for hourly). REPLACES the existing rate.
titlestring- Job title, applied only alongside a pay change and at the change's effective date. A title change with NO pay change is out of scope - do not call this tool for a bare rename.
gustomcp_update_payrollUpdate inputs (hours, amounts, memos, PTO, exclusions, payment method) for employees on an unprocessed payroll before running it.WriteUpdate Payroll
Update inputs (hours, amounts, memos, PTO, exclusions, payment method) for employees on an unprocessed payroll before running it. Send an empty employee_compensations array only to materialize the roster of a pre-prepare payroll. withholding_pay_period, skip_regular_deductions, and fixed_withholding_rate apply to general off-cycle payrolls only.
Inputs
employee_compensationsarrayrequired- Array of per-employee updates. Only include employees you want to change; omitted employees are left as-is. Max 100. Send an EMPTY array to materialize the roster of a pre-prepare payroll (one where get_payroll returned no materialized roster). The tool rejects an empty array unless get_payroll shows the payroll is pre-prepare (no calculated_at and no materialized roster).
payroll_uuidstringrequired- UUID of the unprocessed payroll to update.
company_uuidstring- The UUID of the company to act on. Call get_token_info to list available company UUIDs.
fixed_withholding_rateboolean- General off-cycle only. Withholds federal at IRS supplemental rate (22%) and state at state supplemental rate.
skip_regular_deductionsboolean- General off-cycle only. Blocks regular deductions and contributions for this payroll.
withholding_pay_periodstring- General off-cycle only (Correction/Bonus/Adhoc). Not accepted by termination or transition payrolls.one of
Every weekEvery other weekTwice per monthMonthlyQuarterlySemiannuallyAnnually
gustomcp_record_timeRecord time for an employee or contractor (identified by company_member_uuid, from list_time_records), either adding a new shift or updating an existing one via on_existing.DestructiveRecord Time
Record time for an employee or contractor (identified by company_member_uuid, from list_time_records), either adding a new shift or updating an existing one via on_existing. shift_started_at, shift_ended_at, and timezone are always required, but may be sent as null on an update to leave that field unchanged; updates additionally require shift_id.
Inputs
company_member_uuidstringrequired- The company member UUID for the worker whose time is being recorded, from list_time_records's `companyMemberUuid` field. Gusto works out from it whether they're an employee or a contractor and which of their ids the write needs, so it's the only worker argument. International contractors can only be recorded for companies on Gusto's native time tracking; third-party time tracking refuses them. International employees aren't supported on either and are always refused. Both refusals happen before anything is written.
company_uuidstringrequired- The company's UUID.
shift_ended_atstringrequired- ISO8601 timestamp for the end of the shift, same format rules as shift_started_at - always include the offset. Must be later than shift_started_at, and must be in the past - neither destination accepts hours that haven't been worked yet. Null behaves the same as on shift_started_at - it leaves the stored end alone on an update, and is refused on an add.
shift_started_atstringrequired- ISO8601 timestamp for the start of the shift, including an explicit UTC offset. The offset is required and a timestamp without one is refused, because it would be read as UTC rather than in the timezone argument and could record the hours on the wrong day. Must be earlier than shift_ended_at. Null is only meaningful when on_existing is "update", where it leaves the stored start alone; on an add it is refused. On a native update you can null it to leave the start alone only if you supply shift_ended_at - Gusto locates the shift by date, so nulling both ends refuses with shift_times_required.
timezonestringrequired- IANA timezone of the worker (e.g. America/Los_Angeles). It sets the tracker's timezone when one isn't already set; it does not reinterpret the shift timestamps, so it is not a substitute for the offset on those. Null leaves the stored timezone alone on an update.
hours_workednumber- Only used for external/third-party time tracking; ignored for native. Omit it or send null and the hours are derived from the shift window, which is what you want in almost every case. Supplying it overrides that derivation rather than validating against it, so a 3-hour value inside a 09:00-17:00 window records 3 hours against that window - correct when unpaid breaks account for the gap, silently wrong otherwise. Hours exceeding the window are rejected by the partner.
job_uuidstring- The job UUID the hours belong to, from list_employee_jobs. When adding time for an employee who holds a single job you can leave it out and Gusto attributes the hours to that job; if they hold several, the call refuses with ambiguous_job naming each one so you can ask which. That automatic attribution applies to adds only - a native update always requires job_uuid and refuses with job_id_required if it's missing, so pass the job of the shift you're editing. A job the worker doesn't hold refuses with invalid_job rather than being attributed to something else. Omit it entirely for a contractor - contractors don't hold jobs, and passing one refuses with job_not_allowed_for_contractor before anything is written.
notestring- Optional note to attach to the entry. Only used for native time tracking; the external/third-party time-tracking API has no field for it, so it is dropped there and the response comes back with a warning saying so - the hours still record. Report that warning to the admin rather than treating the note as saved, because no read tool returns notes, so nothing else will contradict it.
on_existingstring- Whether to add a new entry alongside existing time, or update an existing one. Defaults to add when omitted, so leaving it out writes new hours rather than doing nothing - set it explicitly when you mean to edit. update also requires shift_id. On update you can send null for any of shift_started_at, shift_ended_at, timezone or hours_worked to leave that value as it is, and only what you supply is changed. shift_started_at, shift_ended_at and timezone stay required, so pass them as null rather than leaving them out. On native time tracking Gusto locates the shift by date, so at least one of shift_started_at or shift_ended_at must be non-null on an update - a job- or note-only change still needs shift_started_at (its current value from list_time_records leaves the start unchanged), and nulling both refuses with shift_times_required. Null leaves a value alone rather than clearing it, so there is no way to blank out a shift's end through this tool and reopen the shift. Hours stay tied to the shift window, so moving either end recomputes them against the end you left alone - pass hours_worked yourself if the new window shouldn't set them. An update that supplies nothing at all is refused rather than recorded as a change. Pay classification isn't an argument on this tool - an update keeps the entry's existing one, and an add takes it from the company's setup. Either way, if the company's time-tracking partner doesn't accept that classification the write refuses with entry_classification_conflict rather than quietly reclassifying the hours, and the message says where to go next.one of
addupdate ot_policy_approvedboolean- Only relevant for external/third-party time tracking with unclassified hours. Set it to true once the admin has explicitly approved the overtime policy suggestion that a prior refusal from this tool returned. Nothing on the Gusto side verifies that approval happened, or even that a refusal was ever issued - the flag is taken at face value, so you are asserting the admin agreed and are trusted on it. Do not set it speculatively to get past a refusal. Approving provisions the policy immediately, and it is not rolled back if the write then fails for an unrelated reason such as the partner rejecting the shift, so an employee can end up with a policy nobody asked for. A retry reuses the policy rather than provisioning a second one.
shift_idstring- Required when on_existing is "update". The simplest source is the id this tool returned when the hours were recorded, when it returned one. From list_time_records instead, it differs by destination - for native time tracking it's a shift's id under shifts; for third-party it's the timesheet's own top-level id under timesheets, not the nested entries[].id, which is not accepted and refuses with unknown_shift_id.
No tools match.
