Tools Reference

Complete reference for all BookYourPTO MCP tools — every tool across all 18 categories, with parameters, types, and risk level.

BookYourPTO MCP exposes 385 tools across 18 categories to every connected client. A self-hosted server running in per-user mode also registers the login tool described under Auth. Every tool is listed below with its parameters and behaviour. This page is generated from the live tool registry, so it matches what your AI client actually sees.

Authentication

Authentication is handled automatically via OAuth 2.0 with PKCE. When you first connect, your browser opens a BookYourPTO login page; after you sign in, your AI client receives a short-lived access token — no credentials are ever shared with the AI. Every tool runs with your own identity and role-based permissions.

How to read this page

Each tool shows MCP annotations and a risk level that the host uses to decide when to prompt you for confirmation:

  • Read-only — does not change any data (readOnlyHint). Safe to call freely.
  • Write — creates or updates data. The AI should confirm intent before calling.
  • Destructive — deletes data or performs an irreversible action (destructiveHint). Hosts typically require explicit confirmation.
  • Risk: medium / high — surfaced to the client; high-risk tools (offboarding, deletes, payouts, publishing) should only be called after you explicitly confirm the specific record by ID.

Tool Categories

CategoryToolsJump to
Leaves12Leaves
Time Tracking15Time Tracking
Expenses25Expenses
Users21Users
Schedules12Schedules
Projects15Projects
Organization17Organization
Reports2Reports
HR73HR
Clients5Clients
Notifications5Notifications
Calendar8Calendar
Performance37Performance
Training14Training
Benefits8Benefits
Documents21Documents
Admin94Admin
System1System
Auth1 (per-user mode only)Auth

Leaves

12 tools.

query_leaves

List one person's leave requests that start in a given year. Without a status filter only PENDING and APPROVED leaves are returned; pass a status to see REJECTED, CANCELLED or WITHDRAWN ones. Defaults to the signed-in user. Reading someone else's leave follows the organization's calendar-visibility settings (ADMINISTRATOR and EXECUTIVE may read anyone; others may be refused with 403), and private leave types are shown as "Private" to viewers who are not the owner, an administrator/executive or the owner's department head.

Read-only

ParameterTypeRequiredDescription
userIdstringNoUser ID to query (defaults to authenticated user)
yearintegerNoYear the leaves start in (defaults to the current year)
statusenum: PENDING, APPROVED, REJECTED, CANCELLED, WITHDRAWNNoOnly this status. Omit for PENDING and APPROVED together.

get_leave_balance

Get the leave balance for a user and fiscal year: the annual bucket (allowance includes carry-over), the sick bucket, a row per balance-deducting leave type, and the non-deducting leave types used this year (days taken, and the cap where the type has one). Each row carries the leaveTypeId that create_leave_request needs. Defaults to the signed-in user. Reading someone else follows the calendar-visibility settings: ADMINISTRATOR and EXECUTIVE may read anyone in the organization; others may be refused with 403.

Read-only

ParameterTypeRequiredDescription
userIdstringNoUser ID (defaults to authenticated user)
yearintegerNoFiscal year (defaults to current year)

get_pending_leave_approvals

List PENDING leave requests waiting for a decision. Available to ADMINISTRATOR, EXECUTIVE and DEPARTMENT_HEAD, and to anyone flagged as an approver; others get 403. The caller's own requests are never included (no self-approval). A department head sees only the departments they head or manage. An EMPLOYEE flagged as an approver sees only the requests on which they are the first- or second-level approver, and a private leave type shows to them as "Private" with its reason and notes hidden. For requests to cancel already-approved leave, use get_pending_leave_cancellations.

Read-only

No parameters.

create_leave_request

Submit a new leave request. Anyone may book for themselves; ADMINISTRATOR and EXECUTIVE may book for anyone in the organization; a DEPARTMENT_HEAD may book for people in the departments they head or manage. The request is APPROVED at once when the leave type needs no approval, when the person is an EXECUTIVE, or when an administrator, executive or the person's department head books it for someone else; otherwise it is PENDING. Refused when the person is deactivated or offboarded, when the dates are not YYYY-MM-DD or the end is before the start, when the type's minimum notice or maximum days per request is not met, when the range covers only non-business days or holidays, when it overlaps an existing pending or approved leave, when the dates are locked, or when the balance is insufficient. Custom start/end times are only for single-day leaves. Use get_leave_balance first to check availability.

Write · Risk: medium

ParameterTypeRequiredDescription
userIdstringYesID of the person the leave is for (pass your own user ID to book for yourself)
leaveTypeIdstringYesLeave type ID (use bypto://leave-types resource to look up)
startDatestringYesFirst day of leave (YYYY-MM-DD)
endDatestringYesLast day of leave (YYYY-MM-DD)
startHalfenum: FULL_DAY, FIRST_HALF, SECOND_HALFNoHalf-day setting: FULL_DAY, FIRST_HALF, or SECOND_HALF (default: "FULL_DAY")
endHalfenum: FULL_DAY, FIRST_HALF, SECOND_HALFNoHalf-day setting: FULL_DAY, FIRST_HALF, or SECOND_HALF (default: "FULL_DAY")
leaveStartTimestringNoStart time (HH:mm) for an hours-based single-day leave
leaveEndTimestringNoEnd time (HH:mm) for an hours-based single-day leave
reasonstringNoReason for leave
notesstringNoAdditional notes

approve_or_reject_leave

Approve or reject a PENDING leave request. Requires an active ADMINISTRATOR, EXECUTIVE or DEPARTMENT_HEAD, or someone flagged as an approver; a department head only for people in their departments, and an EMPLOYEE flagged as an approver only for requests assigned to them as first- or second-level approver (403 otherwise). Refused for your own leave and for a leave that is no longer PENDING. For a request to cancel an approved leave, use approve_or_reject_leave_cancellation.

Destructive · Risk: high

ParameterTypeRequiredDescription
leaveIdstringYesID of the leave request
actionenum: approve, rejectYesAction to take
reasonstringNoRejection reason shown to the employee

update_leave

Change a PENDING leave request (type, dates, half days, hours or reason). Only the fields you provide change; the rest are kept. Allowed for the owner, ADMINISTRATOR and EXECUTIVE, and a DEPARTMENT_HEAD for people in their departments. An APPROVED, rejected or cancelled leave cannot be edited: to change an approved leave, cancel it (delete_leave) or ask for cancellation (request_leave_cancellation) and book again. The new dates pass the same rules as a new request (notice, overlaps, locked dates, balance). Pass userId when the leave belongs to someone else.

Write · Risk: medium

ParameterTypeRequiredDescription
leaveIdstringYesResource ID
userIdstringNoOwner of the leave (defaults to the signed-in user; needed to find someone else's leave)
leaveTypeIdstringNoNew leave type ID
startDatestringNoNew first day (YYYY-MM-DD)
endDatestringNoNew last day (YYYY-MM-DD)
startHalfenum: FULL_DAY, FIRST_HALF, SECOND_HALFNo
endHalfenum: FULL_DAY, FIRST_HALF, SECOND_HALFNo
leaveStartTimestringNoStart time (HH:mm), single-day hours-based leave
leaveEndTimestringNoEnd time (HH:mm), single-day hours-based leave
reasonstringNo

delete_leave

Cancel a leave request. Nothing is deleted: the leave is marked CANCELLED, kept in history, and stops counting against the balance. ADMINISTRATOR and EXECUTIVE may cancel anyone's PENDING or APPROVED leave, even after it started; a DEPARTMENT_HEAD may do the same for people in their departments. The owner may cancel their own PENDING leave until its first day; the owner's APPROVED leave cannot be cancelled here (refused) - use request_leave_cancellation so an approver decides. Rejected, cancelled or withdrawn leave cannot be cancelled. The owner is notified when someone else cancels it.

Destructive · Risk: high

ParameterTypeRequiredDescription
leaveIdstringYesResource ID

query_leave_schedule

Who is on leave between two dates, across the team: each active person with PENDING or APPROVED leave overlapping the range, plus the public holidays in it. Useful for capacity planning and spotting staffing gaps. What the caller sees follows the organization's privacy settings: when department viewing is restricted, non-admins see only their own department (department heads, the departments they head or manage). Private leave types show as "Private" to viewers who may not see them.

Read-only

ParameterTypeRequiredDescription
startDatestringYesStart date (YYYY-MM-DD)
endDatestringYesEnd date (YYYY-MM-DD)
departmentIdsstringNoOnly people in these departments

group_book_leaves

Book the same leave for every active person in one department (e.g. a shutdown or offsite). ADMINISTRATOR or EXECUTIVE only. Each person gets their own leave record, approved at once. People with an overlapping leave, or without enough balance, are skipped and listed; the result reports how many were created, skipped and failed. Refused when the department is unknown or inactive, has no active people, or the range covers only weekends and public holidays.

Write · Risk: medium

ParameterTypeRequiredDescription
departmentIdstringYesDepartment whose active members are booked
leaveTypeIdstringYesLeave type ID
startDatestringYesFirst day (YYYY-MM-DD)
endDatestringYesLast day (YYYY-MM-DD)
startHalfenum: FULL_DAY, FIRST_HALF, SECOND_HALFNoHalf-day setting: FULL_DAY, FIRST_HALF, or SECOND_HALF (default: "FULL_DAY")
endHalfenum: FULL_DAY, FIRST_HALF, SECOND_HALFNoHalf-day setting: FULL_DAY, FIRST_HALF, or SECOND_HALF (default: "FULL_DAY")
reasonstringNo
notesstringNo

request_leave_cancellation

Ask for one of your own APPROVED leaves to be cancelled. The leave stays APPROVED (and keeps its days reserved) until an approver accepts or declines the request; approvers are notified. Only the owner may ask. Refused when the leave is not APPROVED, when a cancellation request is already pending for it, or when the leave has already ended (judged on the owner's calendar day). A PENDING leave does not need this: cancel it directly with delete_leave.

Write · Risk: medium

ParameterTypeRequiredDescription
leaveIdstringYesResource ID
reasonstringNoWhy the leave should be cancelled

get_pending_leave_cancellations

List APPROVED leaves whose owner has asked for them to be cancelled and that are waiting for a decision, oldest request first. Available to ADMINISTRATOR, EXECUTIVE and DEPARTMENT_HEAD, and to anyone flagged as an approver; others get 403. The caller's own requests are never included; a department head sees only the departments they head or manage. An EMPLOYEE flagged as an approver sees only requests on which they are the first- or second-level approver, and a private leave type shows to them as "Private" with its reason and notes hidden. Decide each with approve_or_reject_leave_cancellation.

Read-only

No parameters.

approve_or_reject_leave_cancellation

Decide a pending request to cancel an APPROVED leave. Approving cancels the leave (status CANCELLED, days returned to the balance); rejecting clears the request and the leave stays APPROVED. The owner is notified either way. Requires an active ADMINISTRATOR, EXECUTIVE or DEPARTMENT_HEAD, or someone flagged as an approver; a department head only for people in their departments, and an EMPLOYEE flagged as an approver only for requests assigned to them as first- or second-level approver (403 otherwise). Refused for your own leave, when there is no pending cancellation request, or when the leave is no longer APPROVED.

Destructive · Risk: high

ParameterTypeRequiredDescription
leaveIdstringYesResource ID
actionenum: approve, rejectYesapprove = cancel the leave; reject = keep it approved
reasonstringNoReason given to the owner when rejecting

Time Tracking

15 tools.

get_time_tracking_status

Get current clock status (clocked in / out / on break) and today's summary for a user.

Read-only

ParameterTypeRequiredDescription
userIdstringNoUser ID (defaults to authenticated user)

clock_action

Clock the caller in or out, or start/end a break, at the current time. The organization may require a project, task or description on clock_in (PROJECT_REQUIRED, TASK_REQUIRED, DESCRIPTION_REQUIRED). This tool cannot send a GPS position, so in an organization that requires location, or enforces geofencing in REQUIRED mode, clock_in and clock_out are refused with LOCATION_REQUIRED: the person must clock from the mobile app or browser instead, or ask an administrator to add a manual entry. Also refused when time tracking is switched off (TIME_TRACKING_DISABLED) or the state does not allow the action (ALREADY_CLOCKED_IN, NOT_CLOCKED_IN, ALREADY_ON_BREAK, NOT_ON_BREAK).

Write · Risk: medium

ParameterTypeRequiredDescription
actionenum: clock_in, clock_out, start_break, end_breakYesThe clock action to perform
projectIdstringNoProject ID (for clock_in, if required by org settings)
taskIdstringNoTask ID (for clock_in)
descriptionstringNoWork description (for clock_in, max 500 characters)

query_time_entries

List time entries, newest clock-in first, with the total approved / pending / rejected minutes for the whole filtered set (not just this page). Without userId an EMPLOYEE sees their own entries, a DEPARTMENT_HEAD their departments and ADMINISTRATOR/EXECUTIVE the organization; asking for someone outside that scope is refused (403). A date range may span at most 120 days: for a longer period (for example "hours this year") call this once per window of up to 120 days and add the totals. durationMinutes is already net of breaks.

Read-only

ParameterTypeRequiredDescription
userIdstringNoOnly this person's entries
departmentIdstringNoOnly this department (ADMINISTRATOR/EXECUTIVE only; ignored for other roles)
startDatestringNoClock-in on or after (YYYY-MM-DD)
endDatestringNoClock-in on or before (YYYY-MM-DD). At most 120 days after startDate.
projectIdstringNoFilter by project ID
approvalStatusenum: PENDING, APPROVED, REJECTEDNo
billablebooleanNoOnly billable (true) or non-billable (false) entries
tagstringNoOnly entries carrying this tag
pageintegerNoPage number (default: 1)
limitintegerNoResults per page (max 50) (default: 20)

create_time_entry

Create a manual time entry (for example a forgotten clock-in). Refused (403) when the organization turned manual entry off, unless the caller is an ADMINISTRATOR/EXECUTIVE. Only an ADMINISTRATOR/EXECUTIVE may pass another person's userId; for a deactivated person only time up to their last day is accepted. Entries by administrators/executives are approved at once; others are PENDING when the organization requires approval. A taskId must belong to the projectId given (otherwise 400). Refused (403) for an entry in a locked pay period, unless the caller is an ADMINISTRATOR/EXECUTIVE, and refused for everyone when the entry falls in a FINALIZED or SIGNED timesheet period.

Write · Risk: medium

ParameterTypeRequiredDescription
userIdstringNoWhose time this is (ADMINISTRATOR/EXECUTIVE only); defaults to the caller
clockInstringYesClock-in date and time (ISO 8601 with offset, e.g. 2026-05-24T09:00:00-04:00)
clockOutstringNoClock-out date and time (ISO 8601 with offset)
projectIdstringNo
taskIdstringNo
descriptionstringNoWhat was worked on (max 500 characters)
notesstringNo
isBillablebooleanNo
tagsstringNoFree-form labels
breakDurationintegerNoUnpaid break in minutes, subtracted from the duration

update_time_entry

Update a time entry. Only the fields passed are changed. The owner or an ADMINISTRATOR/EXECUTIVE may edit; changing clock-in/out times is refused when the organization turned clock editing off (administrators exempt). Editing an APPROVED entry in an organization that requires approval sends it back to PENDING. A taskId must belong to the project the entry has after the edit (otherwise 400); changing projectId without a taskId clears the old task. Refused (403) for an entry in a locked pay period, unless the caller is an ADMINISTRATOR/EXECUTIVE, and refused for everyone when the entry falls in a FINALIZED or SIGNED timesheet period.

Write · Risk: medium

ParameterTypeRequiredDescription
entryIdstringYesResource ID
clockInstringNoISO 8601 with offset
clockOutstringNoISO 8601 with offset
projectIdstringNo
taskIdstringNo
descriptionstringNoWhat was worked on (max 500 characters)
notesstringNo
isBillablebooleanNo
tagsstringNoFree-form labels
breakDurationintegerNoUnpaid break in minutes, subtracted from the duration

delete_time_entry

Delete a time entry (it is marked DELETED and drops out of lists and totals). The owner or an ADMINISTRATOR/EXECUTIVE may delete. Refused (403) for an entry in a locked pay period, unless the caller is an ADMINISTRATOR/EXECUTIVE, and refused for everyone when the entry falls in a FINALIZED or SIGNED timesheet period.

Destructive · Risk: medium

ParameterTypeRequiredDescription
entryIdstringYesResource ID

query_time_approvals

List completed time entries by approval status (default PENDING), excluding the caller's own, with each entry's rate and cost and the count per status. DEPARTMENT_HEAD (their departments), ADMINISTRATOR and EXECUTIVE only; employees are refused (403).

Read-only

ParameterTypeRequiredDescription
statusenum: PENDING, APPROVED, REJECTEDNoDefault PENDING
limitintegerNoMaximum entries to return (max 500)

approve_time_entry

Approve or reject one PENDING time entry. DEPARTMENT_HEAD (entries from their departments), ADMINISTRATOR and EXECUTIVE only; nobody may decide their own entries. An entry already decided is refused (409).

Write

ParameterTypeRequiredDescription
entryIdstringYesResource ID
actionenum: approve, rejectYes
reasonstringNoReason, shown to the employee (max 1000 characters)

bulk_approve_time

Approve or reject many time entries at once. Same rules as approve_time_entry: only PENDING entries are changed, never the caller's own, and a DEPARTMENT_HEAD only inside their departments. The returned count is how many were actually changed.

Write · Risk: medium

ParameterTypeRequiredDescription
idsstringYesTime entry IDs
actionenum: approve, rejectYes
reasonstringNo

get_billing_report

Billing report for APPROVED, completed time entries between two dates: totals (hours, billable hours, billable amount) and breakdowns by project, employee, day and task. ADMINISTRATOR/EXECUTIVE only. Optionally limited to one project. Pass includeEntries to also get every entry (can be large).

Read-only

ParameterTypeRequiredDescription
startDatestringYesFirst day (YYYY-MM-DD)
endDatestringYesLast day (YYYY-MM-DD)
projectIdstringNo
includeEntriesbooleanNo(default: false)

query_timesheet_periods

List the organization's pay periods (weekly, biweekly, semi-monthly or monthly, as configured): the current period plus the previous five, newest first, each with periodStart and periodEnd. Pass from and to (YYYY-MM-DD) for the periods in a range instead. Use the dates with query_timesheets. Any role may call it.

Read-only

ParameterTypeRequiredDescription
fromstringNoRange start (YYYY-MM-DD); pass with to
tostringNoRange end (YYYY-MM-DD); pass with from

query_timesheets

List the timesheets for one pay period, with hours (regular, overtime, break, paid leave, holiday), pay when rates are set, and status. An EMPLOYEE sees only their own; a DEPARTMENT_HEAD their departments' active people; ADMINISTRATOR/EXECUTIVE the organization. OPEN timesheets are recomputed live from time entries; people with no time in the period are left out (except the caller). periodStart and periodEnd should be a period from query_timesheet_periods. Timesheet status flow: OPEN -> SUBMITTED -> APPROVED -> FINALIZED -> SIGNED; a rejection returns it to OPEN.

Read-only

ParameterTypeRequiredDescription
periodStartstringYesFirst day of the pay period (YYYY-MM-DD)
periodEndstringYesLast day of the pay period (YYYY-MM-DD)

submit_timesheet

Submit an OPEN timesheet for approval, which freezes its totals. The owner may submit their own; a DEPARTMENT_HEAD (their departments), ADMINISTRATOR or EXECUTIVE may submit on someone's behalf. Any other status is refused (409). Get the id from query_timesheets.

Write · Risk: medium

ParameterTypeRequiredDescription
timesheetIdstringYesTimesheet ID

approve_or_reject_timesheet

Approve a SUBMITTED timesheet, or reject a SUBMITTED or APPROVED one back to OPEN for correction with an optional note to the employee. DEPARTMENT_HEAD (their departments), ADMINISTRATOR and EXECUTIVE only; nobody may approve or reject their own timesheet. A timesheet in another status is refused (409).

Write · Risk: medium

ParameterTypeRequiredDescription
timesheetIdstringYesTimesheet ID
actionenum: approve, rejectYes
notesstringNoFor reject: what needs correcting (max 1000 characters)

finalize_timesheet

Finalize an APPROVED timesheet for payroll. This locks it: no one, administrators included, can then add, edit or delete time entries in that period for that person, and it cannot be reopened from here. When sign is true, or sign is omitted and the organization auto-sends timesheets for signature, a PDF is generated and sent to the employee in Documents for e-signature. DEPARTMENT_HEAD (their departments), ADMINISTRATOR and EXECUTIVE only; any status other than APPROVED is refused (409).

Destructive · Risk: high

ParameterTypeRequiredDescription
timesheetIdstringYesTimesheet ID
signbooleanNotrue sends it for e-signature, false does not; omit to follow the organization setting

Expenses

25 tools.

Every expense tool that takes a report id also accepts the report number instead (for example EXP-2026-0001), so "approve EXP-2026-0042" works without looking the id up first. The number is resolved through the same list you could open yourself, so it only ever finds a report you can already see.

query_expenses

List expense reports, newest first by default. An EMPLOYEE sees their own; a DEPARTMENT_HEAD sees their departments; ADMINISTRATOR/EXECUTIVE see the organization. Passing another person's userId is refused (403) for an employee, and for a department head outside their departments. Date filters match reports whose departure is on/after startDate and whose return is on/before endDate.

Read-only

ParameterTypeRequiredDescription
userIdstringNoOnly reports submitted by this user
statusenum: DRAFT, SUBMITTED, PENDING_APPROVAL, APPROVED, REJECTED, PAID, CANCELLED, pending, activeNoA status, or "pending" (SUBMITTED + PENDING_APPROVAL) or "active" (everything except PAID)
reportTypeenum: REIMBURSEMENT, COMPANY_CARDNoFilter by report type
searchstringNoMatches title, report number, trip purpose or description
sortenum: newest, oldest, amount-high, amount-low, title-az, title-za, departureDateNoSort order (default newest)
startDatestringNoDeparture on or after (YYYY-MM-DD)
endDatestringNoReturn on or before (YYYY-MM-DD)
pageintegerNo(default: 1)
limitintegerNoPage size (max 50) (default: 20)

get_expense_details

Get full details of one expense report: totals, line items (purchases), per diems, mileage entries, receipts, approval and rejection details, and payment. The submitter, their manager, the assigned approver, a DEPARTMENT_HEAD for their departments and ADMINISTRATOR/EXECUTIVE may read it; others get 403.

Read-only

ParameterTypeRequiredDescription
expenseIdstringYesExpense report id (the id from query_expenses), or its report number such as EXP-2026-0001.

get_expense_approvals

List expense reports waiting for approval (SUBMITTED or PENDING_APPROVAL), oldest submission first. ADMINISTRATOR/EXECUTIVE see the whole organization, a DEPARTMENT_HEAD sees their departments, and an employee with direct reports sees those reports; anyone else is refused (403). Returns pendingCount and pendingTotal.

Read-only

ParameterTypeRequiredDescription
pageintegerNo(default: 1)
limitintegerNoPage size (max 200) (default: 20)

approve_or_reject_expense

Approve or reject an expense report that is SUBMITTED or PENDING_APPROVAL. Allowed for the assigned approver, the submitter's manager, a DEPARTMENT_HEAD for reports in their departments, and ADMINISTRATOR/EXECUTIVE. Nobody may approve or reject their own report. A rejection requires a reason, which is sent to the submitter; an approval takes optional notes.

Destructive · Risk: high

ParameterTypeRequiredDescription
expenseIdstringYesExpense report id (the id from query_expenses), or its report number such as EXP-2026-0001.
actionenum: approve, rejectYesAction to take
notesstringNoFor approve: optional approver notes. For reject: the rejection reason (required).

create_expense

Create a new DRAFT expense report for the caller. Supports REIMBURSEMENT (default) and COMPANY_CARD. COMPANY_CARD is refused (403) unless the organization enabled company cards and the caller is an administrator/executive, every role is allowed, or the caller was named as a card holder. Also refused when the plan's expense-claim limit is reached. payableToId must be an active person in the organization. Add items afterwards with add_expense_line_item, add_per_diem and add_mileage, then submit_expense.

Write · Risk: medium

ParameterTypeRequiredDescription
titlestringYesReport title
departureDatestringYesStart/departure date (YYYY-MM-DD)
returnDatestringYesEnd/return date (YYYY-MM-DD)
reportTypeenum: REIMBURSEMENT, COMPANY_CARDNoReport type (default: "REIMBURSEMENT")
descriptionstringNoReport description
tripPurposestringNoTrip purpose
currencystringNoCurrency code (e.g. CAD, USD). Defaults to the organization currency.
departmentIdstringNoDepartment ID
projectIdstringNoProject ID
payableToIdstringNoUser ID to pay (for reimbursements to another user)

submit_expense

Submit a DRAFT expense report for approval (the submitter or an ADMINISTRATOR/EXECUTIVE). Refused when the report has no items, when an item above the receipt threshold has no receipt, when the total exceeds the organization maximum, or for a company card report when the organization does not require approval for them. Reports below the auto-approve amount are approved immediately (autoApproved: true).

Write · Risk: medium

ParameterTypeRequiredDescription
expenseIdstringYesExpense report id (the id from query_expenses), or its report number such as EXP-2026-0001.

mark_expense_paid

Mark an approved expense report as paid. Requires ADMINISTRATOR or EXECUTIVE role. Optionally records payment reference and method. Triggers QuickBooks sync if configured.

Destructive · Risk: high

ParameterTypeRequiredDescription
expenseIdstringYesExpense report id (the id from query_expenses), or its report number such as EXP-2026-0001.
paymentReferencestringNoPayment reference (e.g. cheque number, transfer ID)
paymentMethodstringNoPayment method: DIRECT_DEPOSIT, CHEQUE, WIRE_TRANSFER, CASH, CREDIT_CARD, OTHER

get_expense_settings

Get the organization expense settings: which sections are enabled (purchases, per diems, travel/mileage, receipt scanning), approval rules, receipt requirements, the maximum report amount, company card configuration (and whether the caller may create company card claims), per-diem rates per meal type, mileage rates per km and per mile, tax rates and the default currency. Readable by every role.

Read-only

No parameters.

analyze_receipt

Scan a receipt (or a bank statement) with AI and return the extracted vendor, date, amounts, taxes (a separately printed liquor, city or tourism tax comes back as otherTax with its otherTaxLabel), currency and a category suggestion, plus the scan confidence and the monthly scan usage. Each scan counts against the plan's monthly receipt limit and is refused (403) once it is reached, or when receipt scanning is switched off for the organization. Pass expenseId to also attach the file to that report (the submitter, or an ADMINISTRATOR/EXECUTIVE). The extracted values are suggestions: create the line item with add_expense_line_item afterwards.

Write

ParameterTypeRequiredDescription
imageBase64stringYesThe file as base64 (a data: URL is accepted). JPEG, PNG, GIF, WebP or PDF, at most 10MB.
mimeTypeenum: image/jpeg, image/png, image/gif, image/webp, application/pdfNoFile type, only needed when it cannot be detected from the file itself
fileNamestringNoFile name to record (default receipt.<ext>)
typeenum: receipt, bank_statementNoWhat the file is (default: "receipt")
expenseIdstringNoExpense report to attach the scanned file to. Expense report id (the id from query_expenses), or its report number such as EXP-2026-0001.

upload_expense_receipt

Attach a receipt file (JPEG, PNG, GIF, WebP or PDF, at most 10MB) to an expense report without scanning it. The submitter may upload only to a DRAFT report; an ADMINISTRATOR/EXECUTIVE may also upload to SUBMITTED and PENDING_APPROVAL reports. Refused (403) once the plan's monthly receipt limit is reached. Link the returned receipt id to a purchase with update_line_item (receiptId).

Write

ParameterTypeRequiredDescription
reportIdstringYesExpense report id (the id from query_expenses), or its report number such as EXP-2026-0001.
imageBase64stringYesThe file as base64 (a data: URL is accepted). JPEG, PNG, GIF, WebP or PDF, at most 10MB.
mimeTypeenum: image/jpeg, image/png, image/gif, image/webp, application/pdfNoFile type, only needed when it cannot be detected from the file itself
fileNamestringNoFile name to record (default receipt.<ext>)

get_receipt_quota

Get this month's receipt usage for the organization's plan: how many receipts were used, the limit and how many remain (remaining is null on an unlimited plan).

Read-only

No parameters.

delete_receipt

Delete a receipt from an expense report. The submitter may delete only from a DRAFT report; an ADMINISTRATOR/EXECUTIVE may also delete from SUBMITTED and PENDING_APPROVAL reports.

Destructive · Risk: medium

ParameterTypeRequiredDescription
reportIdstringYesExpense report id (the id from query_expenses), or its report number such as EXP-2026-0001.
receiptIdstringYesResource ID

add_expense_line_item

Add a purchase (line item) to an expense report. date, description, expenseType and amountBeforeTax are required; taxes (gst, pst, hst, qst, plus one named otherTax such as a liquor tax) and gratuity are separate amounts added on top. Refused when the organization switched the purchases section off. The submitter may change items only while the report is DRAFT; an ADMINISTRATOR/EXECUTIVE may also change SUBMITTED and PENDING_APPROVAL reports. Report totals are recalculated by the server.

Write

ParameterTypeRequiredDescription
reportIdstringYesExpense report id (the id from query_expenses), or its report number such as EXP-2026-0001.
datestringYesDate of the purchase (YYYY-MM-DD)
descriptionstringYesWhat was bought
expenseTypeenum: MEALS_ENTERTAINMENT, TRANSPORTATION, ACCOMMODATION, COMMUNICATION, SUPPLIES, PARKING, TOLLS, FLIGHTS, CAR_RENTAL, TAXI_RIDESHARE, PUBLIC_TRANSIT, CONFERENCE_FEES, CLIENT_GIFTS, FUEL, AIRFARE, OFFICE_SUPPLIES, EQUIPMENT, SOFTWARE, PHONE_INTERNET, PROFESSIONAL_SERVICES, TRAINING, MEMBERSHIP, OTHERYesExpense category
amountBeforeTaxnumberYesAmount before taxes (including otherTax) and gratuity
vendorstringNoMerchant / vendor name
expenseClassstringNoAccounting class, from the organization expenseClasses list
currencystringNoCurrency code. Defaults to the report currency.
exchangeRatenumberNoRate to the organization currency (default 1)
gstnumberNoGST amount
pstnumberNoPST amount
hstnumberNoHST amount
qstnumberNoQST amount
gratuitynumberNoTip amount
otherTaxnumberNoOne extra tax printed on its own line that is not GST/PST/HST/QST or sales tax, e.g. a liquor tax, city tax or tourism levy. Never also count it in pst. 0 removes it.
otherTaxLabelstringNoName of otherTax as printed, at most 40 characters: usually "Liquor tax", "City tax" or "Tourism levy". Defaults to "Other tax" when otherTax is above 0.
notesstringNo
receiptIdstringNoA receipt already uploaded to this report

update_line_item

Update a purchase on an expense report. Only the fields passed are changed. The submitter may change items only while the report is DRAFT; an ADMINISTRATOR/EXECUTIVE may also change SUBMITTED and PENDING_APPROVAL reports. Report totals are recalculated by the server.

Write

ParameterTypeRequiredDescription
reportIdstringYesExpense report id (the id from query_expenses), or its report number such as EXP-2026-0001.
itemIdstringYesResource ID
datestringNoDate in YYYY-MM-DD format
descriptionstringNo
expenseTypeenum: MEALS_ENTERTAINMENT, TRANSPORTATION, ACCOMMODATION, COMMUNICATION, SUPPLIES, PARKING, TOLLS, FLIGHTS, CAR_RENTAL, TAXI_RIDESHARE, PUBLIC_TRANSIT, CONFERENCE_FEES, CLIENT_GIFTS, FUEL, AIRFARE, OFFICE_SUPPLIES, EQUIPMENT, SOFTWARE, PHONE_INTERNET, PROFESSIONAL_SERVICES, TRAINING, MEMBERSHIP, OTHERNo
amountBeforeTaxnumberNo
vendorstringNoMerchant / vendor name
expenseClassstringNoAccounting class, from the organization expenseClasses list
currencystringNoCurrency code. Defaults to the report currency.
exchangeRatenumberNoRate to the organization currency (default 1)
gstnumberNoGST amount
pstnumberNoPST amount
hstnumberNoHST amount
qstnumberNoQST amount
gratuitynumberNoTip amount
otherTaxnumberNoOne extra tax printed on its own line that is not GST/PST/HST/QST or sales tax, e.g. a liquor tax, city tax or tourism levy. Never also count it in pst. 0 removes it.
otherTaxLabelstringNoName of otherTax as printed, at most 40 characters: usually "Liquor tax", "City tax" or "Tourism levy". Defaults to "Other tax" when otherTax is above 0.
notesstringNo
receiptIdstringNoA receipt already uploaded to this report

delete_line_item

Delete a purchase from an expense report. The submitter may change items only while the report is DRAFT; an ADMINISTRATOR/EXECUTIVE may also change SUBMITTED and PENDING_APPROVAL reports. Report totals are recalculated by the server.

Destructive

ParameterTypeRequiredDescription
reportIdstringYesExpense report id (the id from query_expenses), or its report number such as EXP-2026-0001.
itemIdstringYesResource ID

add_per_diem

Add a per-diem (meal allowance) to an expense report. The amount is computed by the server from the organization rate for perDiemType (see get_expense_settings perDiemRates) times quantity, unless rateApplied is passed. Refused when the organization switched the per-diem section off. The submitter may change items only while the report is DRAFT; an ADMINISTRATOR/EXECUTIVE may also change SUBMITTED and PENDING_APPROVAL reports. Report totals are recalculated by the server.

Write

ParameterTypeRequiredDescription
reportIdstringYesExpense report id (the id from query_expenses), or its report number such as EXP-2026-0001.
datestringYesDay the allowance applies to (YYYY-MM-DD)
perDiemTypeenum: BREAKFAST, LUNCH, DINNER, BREAKFAST_LUNCH, LUNCH_DINNER, BREAKFAST_DINNER, FULL_DAY, INCIDENTALSYesWhich meals the allowance covers
quantityintegerNoNumber of units claimed (default 1)
rateAppliednumberNoOverride the rate. Defaults to the organization rate for the per-diem type.
currencystringNoCurrency code. Defaults to the report currency.
exchangeRatenumberNo
gstnumberNo
pstnumberNo
mealProvidedbooleanNoThe meal was provided by someone else: recorded, but pays 0
notesstringNo

update_per_diem

Update a per-diem on an expense report. Only the fields passed are changed; changing perDiemType without rateApplied re-applies the organization rate for the new type. The submitter may change items only while the report is DRAFT; an ADMINISTRATOR/EXECUTIVE may also change SUBMITTED and PENDING_APPROVAL reports. Report totals are recalculated by the server.

Write

ParameterTypeRequiredDescription
reportIdstringYesExpense report id (the id from query_expenses), or its report number such as EXP-2026-0001.
itemIdstringYesResource ID
datestringNoDate in YYYY-MM-DD format
perDiemTypeenum: BREAKFAST, LUNCH, DINNER, BREAKFAST_LUNCH, LUNCH_DINNER, BREAKFAST_DINNER, FULL_DAY, INCIDENTALSNo
quantityintegerNoNumber of units claimed (default 1)
rateAppliednumberNoOverride the rate. Defaults to the organization rate for the per-diem type.
currencystringNoCurrency code. Defaults to the report currency.
exchangeRatenumberNo
gstnumberNo
pstnumberNo
mealProvidedbooleanNoThe meal was provided by someone else: recorded, but pays 0
notesstringNo

delete_per_diem

Delete a per-diem from an expense report. The submitter may change items only while the report is DRAFT; an ADMINISTRATOR/EXECUTIVE may also change SUBMITTED and PENDING_APPROVAL reports. Report totals are recalculated by the server.

Destructive

ParameterTypeRequiredDescription
reportIdstringYesExpense report id (the id from query_expenses), or its report number such as EXP-2026-0001.
itemIdstringYesResource ID

add_mileage

Add a mileage (travel) entry to an expense report. date, description and distance are required; the amount is distance times the organization rate for the unit unless ratePerUnit is passed. Refused when the organization switched the travel section off. The submitter may change items only while the report is DRAFT; an ADMINISTRATOR/EXECUTIVE may also change SUBMITTED and PENDING_APPROVAL reports. Report totals are recalculated by the server.

Write

ParameterTypeRequiredDescription
reportIdstringYesExpense report id (the id from query_expenses), or its report number such as EXP-2026-0001.
datestringYesDate of the trip (YYYY-MM-DD)
descriptionstringYesPurpose of the trip
distancenumberYesTotal distance driven, in the unit
startLocationstringNoWhere the trip started
endLocationstringNoWhere the trip ended
roundTripbooleanNoMarks the trip as a round trip. It does not double the distance: pass the full distance.
unitenum: KILOMETERS, MILESNoKILOMETERS or MILES. Defaults to the organization unit.
ratePerUnitnumberNoOverride the rate. Defaults to the organization rate per km or per mile.
currencystringNoCurrency code. Defaults to the report currency.
exchangeRatenumberNo
gstnumberNo
notesstringNo

update_mileage

Update a mileage entry on an expense report. Only the fields passed are changed; changing unit without ratePerUnit re-applies the organization rate for the new unit. The submitter may change items only while the report is DRAFT; an ADMINISTRATOR/EXECUTIVE may also change SUBMITTED and PENDING_APPROVAL reports. Report totals are recalculated by the server.

Write

ParameterTypeRequiredDescription
reportIdstringYesExpense report id (the id from query_expenses), or its report number such as EXP-2026-0001.
itemIdstringYesResource ID
datestringNoDate in YYYY-MM-DD format
descriptionstringNo
distancenumberNo
startLocationstringNoWhere the trip started
endLocationstringNoWhere the trip ended
roundTripbooleanNoMarks the trip as a round trip. It does not double the distance: pass the full distance.
unitenum: KILOMETERS, MILESNoKILOMETERS or MILES. Defaults to the organization unit.
ratePerUnitnumberNoOverride the rate. Defaults to the organization rate per km or per mile.
currencystringNoCurrency code. Defaults to the report currency.
exchangeRatenumberNo
gstnumberNo
notesstringNo

delete_mileage

Delete a mileage entry from an expense report. The submitter may change items only while the report is DRAFT; an ADMINISTRATOR/EXECUTIVE may also change SUBMITTED and PENDING_APPROVAL reports. Report totals are recalculated by the server.

Destructive

ParameterTypeRequiredDescription
reportIdstringYesExpense report id (the id from query_expenses), or its report number such as EXP-2026-0001.
itemIdstringYesResource ID

cancel_expense

Cancel an expense report that is SUBMITTED, PENDING_APPROVAL or APPROVED (not yet paid); its status becomes CANCELLED and the record is kept. The submitter or an ADMINISTRATOR/EXECUTIVE may cancel. A DRAFT is removed with delete_expense instead.

Write · Risk: medium

ParameterTypeRequiredDescription
reportIdstringYesExpense report id (the id from query_expenses), or its report number such as EXP-2026-0001.

delete_expense

Permanently delete an expense report and its items. Only two cases are allowed: a DRAFT (by the submitter or an ADMINISTRATOR/EXECUTIVE) or a PAID report (EXECUTIVE only). Any other status is refused; use cancel_expense for submitted or approved reports.

Destructive · Risk: high

ParameterTypeRequiredDescription
reportIdstringYesExpense report id (the id from query_expenses), or its report number such as EXP-2026-0001.

bulk_mark_expenses_paid

Mark up to 50 APPROVED expense reports as paid in one call (for example after a payroll run). ADMINISTRATOR/EXECUTIVE only. All-or-nothing: if any id is not APPROVED, not found, or in another organization, nothing is marked. The payment date is recorded as now.

Destructive · Risk: high

ParameterTypeRequiredDescription
expenseIdsstringYesExpense report ids (the id from query_expenses) or report numbers such as EXP-2026-0001, at most 50
paymentReferencestringNoCheque number, transfer ID, payroll run, ...
paymentMethodstringNoPayment method, e.g. DIRECT_DEPOSIT, CHEQUE, WIRE_TRANSFER, CASH, CREDIT_CARD, OTHER

update_expense_settings

Update organization-wide expense settings. ADMINISTRATOR/EXECUTIVE only. Only the fields passed are changed. A rate change is recorded in the rate history (with rateChangeReason) and applies to new items only.

Write · Risk: medium

ParameterTypeRequiredDescription
enabledbooleanNoTurn the expenses module on or off
enablePurchasesbooleanNo
enablePerDiemsbooleanNo
enableTravelbooleanNo
enableReceiptScanningbooleanNo
defaultCurrencystringNo
mileageUnitenum: KILOMETERS, MILESNo
mileageRatePerKmnumberNo
mileageRatePerMilenumberNo
breakfastRatenumberNo
lunchRatenumberNo
dinnerRatenumberNo
breakfastLunchRatenumberNo
lunchDinnerRatenumberNo
breakfastDinnerRatenumberNo
fullDayRatenumberNo
incidentalsRatenumberNo
gstRatenumberNoPercent
pstRatenumberNoPercent
hstRatenumberNoPercent
qstRatenumberNoPercent
rateChangeReasonstringNoRecorded with any rate change
requireReceiptsbooleanNo
receiptThresholdnumberNoReceipts are required above this amount
autoApproveBelownumber or nullNoAuto-approve reports below this total; null turns it off
maxReportAmountnumber or nullNoLargest report total allowed; null removes the cap
maxDaysToSubmitintegerNo
requireApprovalbooleanNo
requireSecondApprovalbooleanNo
secondApprovalThresholdnumber or nullNo
enableCompanyCardbooleanNo
companyCardAllRolesbooleanNo
companyCardRequiresApprovalbooleanNo

Users

21 tools.

get_team_members

List the people in the organization the caller may see, with role, department, manager and (for administrators, executives and department heads) employment start date. By default only active people are returned; set activeOnly=false to include deactivated and offboarded people as well. Department heads only see their own department scope. Use this to "list active users"; use search_directory to find someone by name.

Read-only

ParameterTypeRequiredDescription
activeOnlybooleanNoOnly active people (default true). false also returns deactivated / offboarded people. (default: true)

get_user_profile

Get detailed profile for a specific user by ID.

Read-only

ParameterTypeRequiredDescription
userIdstringYesUser ID

get_departments

List the departments in the organization with code, color, head and member count. Inactive departments are hidden unless includeInactive is true.

Read-only

ParameterTypeRequiredDescription
includeInactivebooleanNoAlso list inactive departments (default: false)

search_directory

Search the people directory by first name, last name or email (job title and employee number are not searched). Returns a page of matching people with department and role, plus total/page/pageSize. Uses the directory view, so a department head or employee sees as much of the organization as the directory access settings allow.

Read-only

ParameterTypeRequiredDescription
querystringYesSearch text — matches first name, last name or email (case-insensitive)
departmentIdstringNoFilter to a specific department
includeInactivebooleanNoInclude deactivated / offboarded people (default: false)
pageintegerNoPage number (1-indexed) (default: 1)
pageSizeintegerNoPage size (max 200) (default: 50)

get_org_chart

Get the organization reporting hierarchy as a tree of active people. Each node lists a person, their job title, department and direct reports. Uses the directory view, so how much of the organization a department head or employee sees follows the organization's directory access settings. Use this for "who reports to whom?" questions.

Read-only

ParameterTypeRequiredDescription
rootUserIdstringNoUser ID to root the tree at — defaults to every top-level person
includeInactivebooleanNoInclude deactivated / offboarded people in the tree (default: false)

update_user_profile

Update an employee profile: basic info, contact details, address, social links, employment and emergency contact. Only the fields you provide are changed. Anyone may edit their own personal and contact fields; employment fields (jobTitle, employeeId, departmentId, reportsToId, employmentType, employmentStartDate, probationPeriodMonths, payrollId) need ADMINISTRATOR or EXECUTIVE; a DEPARTMENT_HEAD may edit people in their own department scope. Role changes go through change_role, deactivation through offboard_user. Refusals: 403 for insufficient role, 400 MANAGER_NOT_FOUND when reportsToId is not an active person in the organization, 400 DEPARTMENT_NOT_FOUND.

Write · Risk: medium

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
firstNamestringNoFirst name
lastNamestringNoLast name
middleNamestringNoMiddle name
preferredNamestringNoPreferred / display name
jobTitlestringNoJob title (admin/exec only)
employeeIdstringNoEmployee number (admin/exec only)
phoneMobilestringNoMobile phone
phoneLandlinestringNoWork / landline phone
phoneHomestringNoHome phone
phoneExtensionstringNoPhone extension
homeEmailstringNoPersonal/home email
addressLine1stringNo
addressLine2stringNo
citystringNo
statestringNoState / province
postalCodestringNo
countrystringNo
timezonestringNoPersonal IANA timezone override (e.g. America/Toronto); empty string inherits the organization timezone
dateOfBirthstringNoDate of birth (YYYY-MM-DD)
genderenum: MALE, FEMALE, OTHER, PREFER_NOT_TO_SAYNo
maritalStatusenum: SINGLE, MARRIED, DIVORCED, WIDOWED, DOMESTIC_PARTNERSHIP, PREFER_NOT_TO_SAYNo
nationalitystringNo
shirtSizeenum: XS, S, M, L, XL, XXL, XXXLNo
linkedinUrlstringNoLinkedIn profile URL
githubUrlstringNoGitHub profile URL
twitterUsernamestringNoX / Twitter handle or URL
facebookUrlstringNoFacebook profile URL
employmentStartDatestringNoEmployment start / hire date (YYYY-MM-DD)
reportsToIdstring or nullNoManager's user ID (must be an active person); null removes the manager
departmentIdstringNoDepartment ID
divisionstringNoDivision name (free text)
workLocationstringNo
employmentTypeenum: FULLTIME, PARTTIME, CONTRACT, INTERN, TEMPORARY, SEASONALNoEmployment status
probationPeriodMonthsenum: 3, 6 or nullNoProbation length in months (3 or 6), null for none
payrollIdstringNo
emergencyContactNamestringNo
emergencyContactRelationshipstringNo
emergencyContactPhonestringNoPrimary phone
emergencyContactPhoneSecondarystringNoSecondary phone
emergencyContactEmailstringNo

create_user

Create a new employee account. ADMINISTRATOR or EXECUTIVE only; only an EXECUTIVE may create an executive. A welcome email with an account-setup link is always sent. No onboarding is started automatically — that is a separate step. Manager, employee number and other profile fields are set afterwards with update_user_profile. Refusals: 400 EMAIL_TAKEN (email already used anywhere), 400 DEPARTMENT_NOT_FOUND, 403 SEAT_LIMIT when the plan has no free seat.

Write · Risk: medium

ParameterTypeRequiredDescription
firstNamestringYesFirst name
lastNamestringYesLast name
emailstringYesWork email — used for login
roleenum: EMPLOYEE, DEPARTMENT_HEAD, ADMINISTRATOR, EXECUTIVENoRole (default EMPLOYEE)
jobTitlestringNoJob title
departmentIdstringNoDepartment ID
employmentStartDatestringNoEmployment start / hire date (YYYY-MM-DD)
probationPeriodMonthsenum: 3, 6NoProbation length in months (3 or 6); omit for none

offboard_preview

Preview what will happen if a user is offboarded. Returns counts of leaves, time entries, expenses, document assignments, direct reports, department head assignments, 1:1 series, onboarding instances, projects, tasks, benefit enrollments, and future shifts that will be cleaned up. It also lists the departments the person heads and candidate replacement heads. ADMINISTRATOR or EXECUTIVE only. Always run this before offboard_user so you can show the operator a 'what will happen' summary.

Read-only

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID

offboard_user

Offboard (deactivate) an employee with structured cleanup: cancels future leaves and shifts, reassigns department head duties, archives 1:1 series, closes onboarding and so on. ADMINISTRATOR or EXECUTIVE only; only an EXECUTIVE may offboard an executive, you cannot offboard yourself or the last active executive, and an already inactive person is refused. Run offboard_preview FIRST and confirm with the operator. If the person heads any departments, replacementHeads must have exactly one entry per department they head (replacementHeadId null leaves it vacant). Writes an OFFBOARD audit log entry.

Destructive · Risk: high

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
employmentEndDatestringYesLast day of employment (YYYY-MM-DD)
terminationCodeenum: VOLUNTARY_RESIGNATION, INVOLUNTARY, LAYOFF, RETIREMENT, END_OF_CONTRACT, MUTUAL_AGREEMENT, OTHERYesReason the employment ended
terminationNoticeDatestringNoDate notice was given (YYYY-MM-DD)
roeCompletedDatestringNoDate the ROE / separation paperwork was completed (YYYY-MM-DD)
notesstringNoInternal notes about the offboarding
replacementHeadsobjectNoOne entry per department the person heads (see offboard_preview)
replacementHeads[].departmentIdstringYesA department this person heads
replacementHeads[].replacementHeadIdstring or nullYesActive person who takes over as head, or null to leave it vacant

reactivate_user

Restore login access for a previously offboarded user. ADMINISTRATOR or EXECUTIVE only (an executive account needs an EXECUTIVE). Refused when the person is already active or the plan has no free seat. Does NOT undo the offboarding cleanup (cancelled leaves, archived 1:1s, etc).

Write · Risk: medium

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID

change_user_role

Change a user role to EMPLOYEE, DEPARTMENT_HEAD, ADMINISTRATOR, or EXECUTIVE. ADMINISTRATOR or EXECUTIVE only; only an EXECUTIVE may grant EXECUTIVE or edit an executive account, and nobody can change their own role. Writes an audit log entry with the previous and new role.

Write · Risk: high

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
roleenum: EMPLOYEE, DEPARTMENT_HEAD, ADMINISTRATOR, EXECUTIVEYesUser role

create_department

Create a new department. ADMINISTRATOR or EXECUTIVE only. A code is generated from the name when omitted (and made unique). The head must be an active ADMINISTRATOR, EXECUTIVE or DEPARTMENT_HEAD in the organization (400 otherwise); one person may head several departments and keeps their own department.

Write · Risk: medium

ParameterTypeRequiredDescription
namestringYesDepartment name
codestringNoShort code (upper-cased; generated when omitted)
descriptionstringNoDescription
colorstringNoHex color (#RRGGBB), default #3b82f6
headOfDepartmentIdstringNoUser ID of the department head

update_department

Update a department. Only the fields you provide are changed. ADMINISTRATOR or EXECUTIVE may change anything; the DEPARTMENT_HEAD who leads it may change only name, description and color. headOfDepartmentId null removes the head. The head must be an active ADMINISTRATOR, EXECUTIVE or DEPARTMENT_HEAD in the organization (400 otherwise); one person may head several departments and keeps their own department. A duplicate code is refused with 400.

Write · Risk: medium

ParameterTypeRequiredDescription
departmentIdstringYesResource ID
namestringNo
codestringNo
descriptionstringNo
colorstringNo
isActivebooleanNofalse hides the department from lists
headOfDepartmentIdstring or nullNoUser ID of the new department head, or null to clear it

delete_department

Permanently delete a department. ADMINISTRATOR or EXECUTIVE only. Refused with 400 while any person is still assigned to it — reassign them first.

Destructive · Risk: high

ParameterTypeRequiredDescription
departmentIdstringYesResource ID

query_teams

List every team in the organization (sorted by name) with its department and member count. Any signed-in person may call it.

Read-only

No parameters.

create_team

Create a new team. ADMINISTRATOR or EXECUTIVE only. The name must be unique in the organization (409 NAME_TAKEN); a departmentId must belong to the organization (400 DEPARTMENT_NOT_FOUND).

Write · Risk: medium

ParameterTypeRequiredDescription
namestringYesTeam name
descriptionstringNo
departmentIdstringNoDepartment the team belongs to

update_team

Update a team. ADMINISTRATOR or EXECUTIVE only. Only the fields you provide are changed; departmentId null detaches it from its department. A duplicate name is refused with 409.

Write · Risk: medium

ParameterTypeRequiredDescription
teamIdstringYesResource ID
namestringNo
descriptionstring or nullNoNew description, or null to clear it
departmentIdstring or nullNoDepartment ID, or null to clear it

delete_team

Permanently delete a team and its memberships. ADMINISTRATOR or EXECUTIVE only.

Destructive · Risk: high

ParameterTypeRequiredDescription
teamIdstringYesResource ID

query_team_members

List the members of a team with their team role and join date. Any signed-in person may call it.

Read-only

ParameterTypeRequiredDescription
teamIdstringYesResource ID

add_team_member

Add an active person to a team. ADMINISTRATOR or EXECUTIVE only. A deactivated person or one outside the organization is refused (404); an existing member is refused with 409.

Write · Risk: medium

ParameterTypeRequiredDescription
teamIdstringYesResource ID
userIdstringYesUser ID to add
rolestringNoRole within the team (default MEMBER)

remove_team_member

Remove a person from a team. ADMINISTRATOR or EXECUTIVE only. Looks up the membership by user ID, then deletes it.

Destructive · Risk: medium

ParameterTypeRequiredDescription
teamIdstringYesResource ID
userIdstringYesUser ID to remove

Schedules

11 tools.

query_schedules

List scheduled shifts for a date range (dates and times in the organization's timezone), with the number of leave-days and the public holidays in the range and which weeks are published. ADMINISTRATOR and EXECUTIVE see everyone; a DEPARTMENT_HEAD sees the departments they head or manage; employees see their own shifts plus whatever the organization's schedule-visibility settings allow, and only published weeks unless default schedules are auto-generated. Naming a userId outside your view is refused with 403. The date shown for each shift is what update_shift expects as shiftDate.

Read-only

ParameterTypeRequiredDescription
startDatestringNoStart date (YYYY-MM-DD, defaults to today)
endDatestringNoEnd date (YYYY-MM-DD, defaults to +7 days)
userIdstringNoFilter by user ID
departmentIdstringNoFilter by department ID

create_shift

Create a scheduled shift on one day, with times in the organization's timezone. Requires ADMINISTRATOR, EXECUTIVE or DEPARTMENT_HEAD. Omit userId to create an open shift anyone eligible can claim. The assigned person must be an active member of the organization (a deactivated or unknown person is refused with "Invalid user"). A department head may only assign people in, or file open shifts to, the departments they head or manage.

Write · Risk: medium

ParameterTypeRequiredDescription
datestringYesShift date (YYYY-MM-DD)
startTimestringYesStart time (HH:MM, e.g. "09:00")
endTimestringYesEnd time (HH:MM, e.g. "17:00")
userIdstringNoUser ID (omit for open shift)
departmentIdstringNoDepartment the shift belongs to (useful for open shifts)
shiftTypestringNoShift type: REGULAR, MORNING, AFTERNOON, NIGHT, CUSTOM (default: "REGULAR")
breakDurationnumberNoBreak duration in minutes (default: 30)
notesstringNoNotes
confirmPublishedbooleanNoSet to true only after the user confirmed changing a published week. Without it, a shift in a published week is refused

The week is checked first: a shift in a week that is already published (visible to employees) is refused until the user confirms.

create_shifts

Create many scheduled shifts in ONE call: the same times for each listed person on each listed day (e.g. a whole team, Monday to Friday). Use this instead of repeated create_shift calls whenever more than a few shifts are needed. Requires ADMINISTRATOR, EXECUTIVE or DEPARTMENT_HEAD; a department head may only schedule people in the departments they head or manage. Every person must be an active member of the organization. Times are in the organization's timezone. A person who already has a shift on a day is skipped for that day. At most 500 shifts per call. It checks each week first and returns its status (Draft or Published) and how many shifts were already there; a PUBLISHED week is refused unless confirmPublished is true, which you set only after the user agreed.

It looks at each week first and returns its status (Draft or Published) and how many shifts were already there. A person who already has a shift on a day is left as they are unless existing is "update", which changes that shift to the new times. A published week is refused unless confirmPublished is true.

Write · Risk: medium

ParameterTypeRequiredDescription
userIdsstringYesPeople to schedule (1–500)
datesstringYesDays to schedule (YYYY-MM-DD, 1–31)
startTimestringYesStart time, HH:MM 24-hour (e.g. "08:30")
endTimestringYesEnd time, HH:MM 24-hour (e.g. "16:30"); must be after the start
breakDurationintegerNoUnpaid break in minutes (default: 30)
shiftTypestringNoREGULAR, MORNING, AFTERNOON, NIGHT, CUSTOM (default: "REGULAR")
notesstringNoNotes added to every shift
existingstringNo"skip" (default) leaves existing shifts as they are; "update" changes them to these times. Use "update" only after the user agreed
confirmPublishedbooleanNoSet to true only after the user confirmed changing a published week

Returns how many shifts were created, updated, left as they were and skipped, plus each week's status.

publish_schedule

Publish one or more consecutive weeks for the whole organization (publication is org-wide, not per department), making their shifts visible to employees. ADMINISTRATOR or EXECUTIVE only. Optionally emails each scheduled employee; the result says how many were notified.

Destructive · Risk: high

ParameterTypeRequiredDescription
weekStartstringYesFirst day of the first week to publish (YYYY-MM-DD)
numberOfWeeksintegerNoNumber of weeks to publish (1-4) (default: 1)
sendNotificationbooleanNoSend email notification to employees (default: true)

update_shift

Change an existing shift. Only the fields you provide change; the rest are kept. Times are in the organization's timezone. Requires ADMINISTRATOR, EXECUTIVE or DEPARTMENT_HEAD; a department head only for shifts of people (or open shifts) in the departments they head or manage. Pass userId to reassign the shift (it must be an active person; a department head may only assign within their departments) or null to turn it into an open shift. shiftDate is the date the shift is on now, as query_schedules shows it; it is used to look the shift up.

Write · Risk: medium

ParameterTypeRequiredDescription
shiftIdstringYesResource ID
shiftDatestringYesThe date the shift is currently on (YYYY-MM-DD)
datestringNoMove the shift to this date (YYYY-MM-DD)
startTimestringNoNew start time (HH:mm)
endTimestringNoNew end time (HH:mm)
shiftTypestringNoREGULAR, MORNING, AFTERNOON, NIGHT or CUSTOM
breakDurationintegerNoBreak in minutes
notesstringNo
userIdstring or nullNoReassign to this person, or null to make it an open shift

delete_shift

Permanently delete one shift. Requires ADMINISTRATOR, EXECUTIVE or DEPARTMENT_HEAD; a department head only for shifts in the departments they head or manage.

Destructive · Risk: medium

ParameterTypeRequiredDescription
shiftIdstringYesResource ID

claim_shift

Claim an open (unassigned) shift for yourself. Any role may claim. Refused with 409 when someone already has it, once the shift has started, or when its week has not been published yet (an unpublished week is still a draft), and with 403 when the shift is restricted to a department you are not in.

Write · Risk: medium

ParameterTypeRequiredDescription
shiftIdstringYesResource ID

copy_week

Copy one week's assigned shifts onto the following week(s), matched by weekday, on business days only. Requires ADMINISTRATOR, EXECUTIVE or DEPARTMENT_HEAD (a department head copies only the departments they head or manage). Open shifts and shifts of people who are no longer active are not copied. By default a person who already has a shift on a target day is skipped. Pass employeeIds to copy only those people (a department head only people in their departments, otherwise 403); an empty employeeIds list copies nothing. With sendNotification, only the people who actually got new shifts are emailed. Returns how many shifts were created and skipped.

Write · Risk: medium

ParameterTypeRequiredDescription
sourceWeekStartstringYesFirst day of the week to copy (YYYY-MM-DD)
targetWeekStartstringYesFirst day of the first destination week (YYYY-MM-DD)
numberOfWeeksintegerNoHow many consecutive weeks to fill (1-4) (default: 1)
departmentIdstringNoOnly copy shifts of people in this department
employeeIdsarray of stringNoOnly copy shifts of these people (user ids, up to 500). Takes precedence over departmentId. An empty list copies nothing.
skipConflictsbooleanNoSkip a person/day that already has a shift (default: true)
sendNotificationbooleanNoEmail the affected employees their new schedule (default: false)

clear_week

Permanently delete every shift in the organization for one week (weekStart and the six days after it), across all departments. Cannot be undone. ADMINISTRATOR or EXECUTIVE only. Refused when the week is published; unpublish it first.

Destructive · Risk: high

ParameterTypeRequiredDescription
weekStartstringYesFirst day of the week (YYYY-MM-DD), as shown in the schedule

unpublish_schedule

Move a published week back to draft for the whole organization (publication is org-wide, not per department), hiding it from employees again. ADMINISTRATOR or EXECUTIVE only.

Write · Risk: medium

ParameterTypeRequiredDescription
weekStartstringYesFirst day of the week (YYYY-MM-DD), as shown in the schedule

submit_schedule_for_review

Send a draft week to the organization's administrators and executives for review before they publish it. DEPARTMENT_HEAD only (others get 403); departmentId, when given, must be one the head heads or manages.

Write

ParameterTypeRequiredDescription
weekStartstringYesFirst day of the week (YYYY-MM-DD), as shown in the schedule
departmentIdstringNoDepartment whose schedule is submitted (defaults to your own)

email_schedule

Email each scheduled employee their shifts for a date range (by default one week from weekStart). Requires ADMINISTRATOR, EXECUTIVE or DEPARTMENT_HEAD. Pass departmentId to email only that department's active members.

Write

ParameterTypeRequiredDescription
weekStartstringYesFirst day of the week (YYYY-MM-DD), as shown in the schedule
endDatestringNoLast day to include (YYYY-MM-DD, defaults to weekStart + 6 days)
departmentIdstringNoOnly email people in this department

Projects

15 tools.

list_projects

List projects, newest first. ADMINISTRATOR/EXECUTIVE see every project (and may filter by department); a DEPARTMENT_HEAD sees their departments' projects plus organization-wide ones; an EMPLOYEE sees their department's projects plus organization-wide ones. Hourly rate and budget amount are returned only to DEPARTMENT_HEAD, ADMINISTRATOR and EXECUTIVE. includeStats adds tracked hours and budget used.

Read-only

ParameterTypeRequiredDescription
statusenum: ACTIVE, ON_HOLD, COMPLETED, CANCELLED, ARCHIVEDNoFilter by status
departmentIdstringNoOnly this department's projects (ADMINISTRATOR/EXECUTIVE only; ignored otherwise)
includeStatsbooleanNoInclude tracked hours and budget used (default: false)

get_project

Get one project with its client, every task and issue (status, type, priority, due date, assignee), and time stats. Visible to anyone who can see the project in list_projects; hourly rate, budget amount and billed amount are returned only to DEPARTMENT_HEAD, ADMINISTRATOR and EXECUTIVE.

Read-only

ParameterTypeRequiredDescription
projectIdstringYesProject ID

create_task

Create a billable work item (task) in a project that people can track time against; it starts ACTIVE. Pass parentTaskId to make it a subtask. An EMPLOYEE may only add tasks to their department's projects or organization-wide ones. For a tracked issue with type, priority, due date and assignee use create_issue.

Write

ParameterTypeRequiredDescription
projectIdstringYesProject ID
namestringYesTask name
descriptionstringNoTask description
budgetHoursnumberNoBudget hours for this task
isBillablebooleanNoWhether the task is billable (default: true)
parentTaskIdstringNoMake this a subtask of another task in the same project

query_project_tasks

List a project's top-level tasks with their subtasks and the time tracked against each (hours, entry count; cost only for DEPARTMENT_HEAD, ADMINISTRATOR and EXECUTIVE). This list has no filters; to filter by status, type, priority, assignee or text use query_project_issues.

Read-only

ParameterTypeRequiredDescription
projectIdstringYesResource ID

update_task

Update a project task or issue: change its status (for example mark it DONE), reassign it, set the due date or priority, rename it. Only the fields passed are changed. Anyone who can see the project may change only the status; any other change needs a DEPARTMENT_HEAD, ADMINISTRATOR or EXECUTIVE, or the item's assignee or reporter. A new assignee must be an active person in the organization (400 Invalid assignee otherwise).

Write

ParameterTypeRequiredDescription
projectIdstringYesResource ID
taskIdstringYesResource ID
namestringNoTitle
descriptionstringNo
statusenum: TODO, IN_PROGRESS, IN_REVIEW, DONE, ACTIVE, COMPLETED, CANCELLEDNoBoard columns are TODO, IN_PROGRESS, IN_REVIEW, DONE
typeenum: TASK, BUG, FEATURE, STORY, EPICNo
priorityenum: LOW, MEDIUM, HIGH, URGENT, CRITICALNo
labelsstringNoReplaces the whole label list
dueDatestring or nullNoDue date (YYYY-MM-DD); null clears it
estimatedHoursnumber or nullNo
budgetHoursnumber or nullNo
isBillablebooleanNo
assigneeIdstring or nullNoActive person to assign; null unassigns
parentTaskIdstring or nullNoParent task in the same project; null detaches

delete_task

Permanently delete a project task. DEPARTMENT_HEAD, ADMINISTRATOR or EXECUTIVE only.

Destructive · Risk: medium

ParameterTypeRequiredDescription
projectIdstringYesResource ID
taskIdstringYesResource ID

get_project_board

Get the Kanban board of a project: items grouped into the TODO, IN_PROGRESS, IN_REVIEW and DONE columns. Items in other statuses (ACTIVE, COMPLETED, CANCELLED) are not on the board.

Read-only

ParameterTypeRequiredDescription
projectIdstringYesResource ID

add_project_comment

Post a comment on a task or issue in a project (comments belong to a task, not to the project itself).

Write

ParameterTypeRequiredDescription
projectIdstringYesResource ID
taskIdstringYesThe task or issue to comment on
contentstringYesComment text

query_project_comments

List the comments on one task or issue in a project, oldest first.

Read-only

ParameterTypeRequiredDescription
projectIdstringYesResource ID
taskIdstringYesThe task or issue whose comments to list

query_project_issues

List a project's tasks and issues (including subtasks) in board order, filtered by status, type, priority, assignee or a name search.

Read-only

ParameterTypeRequiredDescription
projectIdstringYesResource ID
statusenum: TODO, IN_PROGRESS, IN_REVIEW, DONE, ACTIVE, COMPLETED, CANCELLEDNo
typeenum: TASK, BUG, FEATURE, STORY, EPICNo
priorityenum: LOW, MEDIUM, HIGH, URGENT, CRITICALNo
assigneeIdstringNo
searchstringNoMatches the name

create_issue

Create a tracked issue in a project (task, bug, feature, story or epic) with priority, due date, labels and an optional assignee; it starts in TODO and the caller is the reporter. An EMPLOYEE may only add issues to their department's projects or organization-wide ones. The assignee must be an active person.

Write

ParameterTypeRequiredDescription
projectIdstringYesResource ID
namestringYesTitle
descriptionstringNo
typeenum: TASK, BUG, FEATURE, STORY, EPICNoDefault TASK
priorityenum: LOW, MEDIUM, HIGH, URGENT, CRITICALNoDefault MEDIUM
statusenum: TODO, IN_PROGRESS, IN_REVIEW, DONE, ACTIVE, COMPLETED, CANCELLEDNoDefault TODO
labelsstringNo
dueDatestringNoDue date (YYYY-MM-DD)
estimatedHoursnumberNo
assigneeIdstringNo
parentTaskIdstringNoParent task in the same project

update_issue

Update a project issue. Only the fields passed are changed. Anyone who can see the project may change only the status; any other change needs a DEPARTMENT_HEAD, ADMINISTRATOR or EXECUTIVE, or the item's assignee or reporter. A new assignee must be an active person in the organization (400 Invalid assignee otherwise).

Write

ParameterTypeRequiredDescription
projectIdstringYesResource ID
issueIdstringYesResource ID
namestringNoTitle
descriptionstringNo
statusenum: TODO, IN_PROGRESS, IN_REVIEW, DONE, ACTIVE, COMPLETED, CANCELLEDNoBoard columns are TODO, IN_PROGRESS, IN_REVIEW, DONE
typeenum: TASK, BUG, FEATURE, STORY, EPICNo
priorityenum: LOW, MEDIUM, HIGH, URGENT, CRITICALNo
labelsstringNoReplaces the whole label list
dueDatestring or nullNoDue date (YYYY-MM-DD); null clears it
estimatedHoursnumber or nullNo
budgetHoursnumber or nullNo
isBillablebooleanNo
assigneeIdstring or nullNoActive person to assign; null unassigns
parentTaskIdstring or nullNoParent task in the same project; null detaches

delete_issue

Permanently delete a project issue. DEPARTMENT_HEAD, ADMINISTRATOR or EXECUTIVE only.

Destructive · Risk: medium

ParameterTypeRequiredDescription
projectIdstringYesResource ID
issueIdstringYesResource ID

update_project

Update a project. Only the fields passed are changed. ADMINISTRATOR/EXECUTIVE may edit any project; a DEPARTMENT_HEAD only projects in their departments (not organization-wide ones). Only ADMINISTRATOR/EXECUTIVE can move a project to another department. The code must be unique in the organization; the manager must be an active person.

Write · Risk: medium

ParameterTypeRequiredDescription
projectIdstringYesResource ID
namestringNo
codestringNo
descriptionstring or nullNo
statusenum: ACTIVE, ON_HOLD, COMPLETED, CANCELLED, ARCHIVEDNo
priorityenum: LOW, MEDIUM, HIGH, URGENTNo
colorstringNo
isBillablebooleanNo
hourlyRatenumber or nullNo
budgetHoursnumber or nullNo
budgetAmountnumber or nullNo
managerIdstring or nullNoProject manager; null clears
clientIdstring or nullNoA client from query_clients; null clears
departmentIdstring or nullNoADMINISTRATOR/EXECUTIVE only; null makes it organization-wide
startDatestring or nullNoDate in YYYY-MM-DD format
endDatestring or nullNoDate in YYYY-MM-DD format

delete_project

Permanently delete a project with all its tasks, issues, comments and members. Time entries, shifts and expense reports that referenced it are kept but lose the link. ADMINISTRATOR/EXECUTIVE only. Cannot be undone.

Destructive · Risk: high

ParameterTypeRequiredDescription
projectIdstringYesResource ID

Organization

17 tools.

get_org_info

Get organization settings: name, timezone, currency, leave allowances, fiscal year, etc.

Read-only

No parameters.

get_public_holidays

List public holidays for a year (default: the caller's current year). Without userId, returns the organization's holidays. With userId, returns the holidays that apply to that person — their personal holiday country and their add/exclude overrides — when the caller may see them (the person, administrators/executives, or their department head); otherwise the organization's holidays are returned.

Read-only

ParameterTypeRequiredDescription
yearintegerNoCalendar year
userIdstringNoResolve the holidays that apply to this person

get_dashboard_stats

Get organization-level stats: total users, departments, leave types, leaves. Requires EXECUTIVE role.

Read-only

No parameters.

get_notifications

Get the authenticated user's notifications. Supports filtering by read status.

Read-only

ParameterTypeRequiredDescription
filterenum: all, unread, readNoFilter: all, unread, or read (default: "all")
pageintegerNo(default: 1)
limitintegerNoPage size (max 100) (default: 20)

get_directory_settings

Get the organization's people directory and org chart settings: whether each is enabled, who may view and export them (orgChartAccess, orgChartExportAccess, directoryAccess), and which profile fields the directory shows. Explains why search_directory or get_org_chart return less of the organization for some roles. Any signed-in person may read it.

Read-only

No parameters.

add_public_holiday

Add a holiday LOCATION to the organization: imports every public holiday for a country (optionally one state/province) for the given year from the public holiday calendar. It does not create a single custom holiday — for a one-off day for one person use add_user_holiday_override. ADMINISTRATOR or EXECUTIVE only. Refused with 400 when that country/subdivision is already added, 404 when no holidays are found for it. Use query_holiday_countries / query_holiday_subdivisions for valid codes.

Write · Risk: medium

ParameterTypeRequiredDescription
countrystringYesISO 3166-1 alpha-2 country code (e.g. "CA")
subdivisionstringNoISO 3166-2 subdivision code as listed by query_holiday_subdivisions (e.g. "CA-ON")
yearintegerYesYear to import (2020-2050)

delete_public_holiday

Remove a holiday LOCATION: deletes EVERY public holiday the organization has for the same country as the given holiday (all years and all subdivisions of that country), not just the one day. Cannot be undone. ADMINISTRATOR or EXECUTIVE only.

Destructive · Risk: high

ParameterTypeRequiredDescription
holidayIdstringYesID of any holiday belonging to the country to remove

query_holiday_countries

List the countries available for importing public holidays (code and name).

Read-only

No parameters.

query_holiday_subdivisions

List the subdivisions (states/provinces) that have their own public holidays in a country.

Read-only

ParameterTypeRequiredDescription
countryCodestringYesISO country code (e.g. "CA", "US")

query_user_holiday_overrides

List one person's holiday overrides: EXCLUDE (an organization holiday they do not observe) and ADD (an extra personal holiday). Readable by the person, administrators/executives, and their department head; anyone else is refused with 403.

Read-only

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID

add_user_holiday_override

Add a holiday override for one person. type EXCLUDE removes an organization holiday for them (publicHolidayId required, from get_public_holidays); type ADD gives them an extra personal holiday (name and date required). ADMINISTRATOR or EXECUTIVE only.

Write · Risk: medium

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
typeenum: EXCLUDE, ADDYes
publicHolidayIdstringNoOrganization holiday to exclude (EXCLUDE only)
namestringNoHoliday name (ADD only)
datestringNoHoliday date YYYY-MM-DD (ADD only)
isRecurringbooleanNoRepeats every year (default true) (default: true)
isHalfDaybooleanNo(default: false)

query_asset_categories

List the active asset categories defined for the organization (Laptop, Phone, Badge, etc.) with how many assets use each. Used by add_asset and update_asset.

Read-only

No parameters.

create_asset_category

Create a new asset category. ADMINISTRATOR or EXECUTIVE only.

Write

ParameterTypeRequiredDescription
namestringYesCategory name (e.g. "Laptop")
descriptionstringNo

delete_asset_category

Deactivate an asset category so it is no longer offered; existing assets keep it. ADMINISTRATOR or EXECUTIVE only.

Destructive · Risk: medium

ParameterTypeRequiredDescription
categoryIdstringYesResource ID

query_certification_types

List the active certification types defined for the organization (AWS Solutions Architect, PMP, etc.) with how many certifications use each. Used by add_certification.

Read-only

No parameters.

create_certification_type

Create a new certification type. ADMINISTRATOR or EXECUTIVE only.

Write

ParameterTypeRequiredDescription
namestringYesCertification name (e.g. "AWS Solutions Architect Associate")
descriptionstringNoDescription (e.g. issuing body, validity)

delete_certification_type

Deactivate a certification type so it is no longer offered; existing certifications keep it. ADMINISTRATOR or EXECUTIVE only.

Destructive · Risk: medium

ParameterTypeRequiredDescription
typeIdstringYesResource ID

Reports

2 tools.

generate_leave_report

Leave report: leave requests whose start date falls in a range, newest first, with counts by status (approved, pending, rejected) and total days across every matching request. Paged (up to 500 per page). ADMINISTRATOR and EXECUTIVE see the whole organization; a DEPARTMENT_HEAD sees only the departments they head or manage (a departmentId outside that is refused with 403). Employees get 403.

Read-only

ParameterTypeRequiredDescription
startDatestringNoEarliest start date (YYYY-MM-DD)
endDatestringNoLatest start date (YYYY-MM-DD)
departmentIdstringNoFilter by department
userIdstringNoFilter by person
leaveTypeIdstringNoFilter by leave type
statusenum: PENDING, APPROVED, REJECTED, CANCELLED, WITHDRAWNNoFilter by status (all statuses when omitted)
pageintegerNoPage number (1-indexed) (default: 1)
limitintegerNoRows per page (max 500) (default: 50)

generate_timesheet_report

Time-tracking report over clocked time entries. reportType: summary (totals, billable share, overtime, per-weekday hours), by_employee, by_project, by_department, overtime or attendance. Durations are in MINUTES (the summary fields named totalHours, billableHours, overtimeHours and avgHoursPerDay hold minutes). Give startDate and endDate for a custom range; otherwise range picks a preset (default: this week). ADMINISTRATOR and EXECUTIVE see the whole organization and cost figures; a DEPARTMENT_HEAD sees only the departments they head or manage and no costs (a departmentId outside that is refused with 403). Employees get 403. Refused when time tracking is switched off for the organization.

Read-only

ParameterTypeRequiredDescription
reportTypeenum: summary, by_employee, by_project, by_department, overtime, attendanceNoWhich report to build (default: "summary")
startDatestringNoReport start date (YYYY-MM-DD); needs endDate too
endDatestringNoReport end date (YYYY-MM-DD); needs startDate too
rangeenum: today, week, month, quarter, yearNoPreset range, used when startDate/endDate are not both given (default week)
userIdstringNoFilter by person
departmentIdstringNoFilter by department

HR

73 tools.

query_employee_notes

List notes attached to an employee that the caller may read. Each note carries visibleToRoles, the roles allowed to read it (EMPLOYEE there means the employee the note is about). ADMINISTRATOR, EXECUTIVE, a DEPARTMENT_HEAD for their departments, and the employee themselves see the notes shared with their role; anyone else gets an empty list.

Read-only

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID

add_employee_note

Add a note to an employee profile. An EMPLOYEE may only add notes to their own profile, and their notes are always visible to every role. ADMINISTRATOR and EXECUTIVE may add notes to anyone; a DEPARTMENT_HEAD only to people in their departments, and must include ADMINISTRATOR in visibleToRoles. Everyone other than an EMPLOYEE must pass visibleToRoles; include EMPLOYEE only if the employee should read it. The employee and admins may be notified.

Write · Risk: medium

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
contentstringYesThe note text (max 5000 characters)
visibleToRolesarray of enum: EMPLOYEE, DEPARTMENT_HEAD, ADMINISTRATOR, EXECUTIVENoRoles that may read the note. EMPLOYEE means the employee the note is about. A DEPARTMENT_HEAD must include ADMINISTRATOR.

delete_employee_note

Permanently delete a note. Only its author, an ADMINISTRATOR or an EXECUTIVE may. Cannot be undone.

Destructive · Risk: high

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
noteIdstringYesResource ID

query_education

List education records (institution, degree, major, GPA, dates) for one person. An HR record: readable by the person themselves, ADMINISTRATOR and EXECUTIVE for anyone in the organization, and a DEPARTMENT_HEAD for people in the departments they head; anyone else is refused with 403 (Access denied).

Read-only

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID

add_education_entry

Add an education record for a user. institution is required. The employee themselves, ADMINISTRATOR or EXECUTIVE only.

Write · Risk: medium

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
institutionstringYesSchool name
degreeenum: HIGH_SCHOOL, ASSOCIATE, BACHELOR, MASTER, DOCTORATE, DIPLOMA, CERTIFICATE, GDIP, OTHERNoDegree type
majorstringNo
gpastringNoGPA as text, e.g. "3.8" or "3.8/4.0"
startDatestringNoDate in YYYY-MM-DD format
endDatestringNoDate in YYYY-MM-DD format

update_education_entry

Correct an education record. Only the fields you pass change. The employee themselves, ADMINISTRATOR or EXECUTIVE only.

Write

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
educationIdstringYesResource ID
institutionstringNo
degreeenum: HIGH_SCHOOL, ASSOCIATE, BACHELOR, MASTER, DOCTORATE, DIPLOMA, CERTIFICATE, GDIP, OTHERNoDegree type
majorstringNo
gpastringNo
startDatestringNoDate in YYYY-MM-DD format
endDatestringNoDate in YYYY-MM-DD format

delete_education_entry

Permanently delete an education record. The employee themselves, ADMINISTRATOR or EXECUTIVE only.

Destructive · Risk: medium

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
educationIdstringYesResource ID

query_languages

List language proficiencies for one person, with separate reading/writing and speaking levels. An HR record: readable by the person themselves, ADMINISTRATOR and EXECUTIVE for anyone in the organization, and a DEPARTMENT_HEAD for people in the departments they head; anyone else is refused with 403 (Access denied).

Read-only

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID

add_language

Add a language proficiency record for a user. language is required. The employee themselves, ADMINISTRATOR or EXECUTIVE only.

Write

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
languagestringYesLanguage name (e.g. "Spanish", "Mandarin")
readingWritingProficiencyenum: ELEMENTARY, LIMITED_WORKING, PROFESSIONAL, FULL_PROFESSIONAL, NATIVENoReading and writing proficiency
speakingProficiencyenum: ELEMENTARY, LIMITED_WORKING, PROFESSIONAL, FULL_PROFESSIONAL, NATIVENoSpeaking proficiency

update_language

Update a language proficiency record. Only the fields you pass change. The employee themselves, ADMINISTRATOR or EXECUTIVE only.

Write

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
languageIdstringYesResource ID
languagestringNo
readingWritingProficiencyenum: ELEMENTARY, LIMITED_WORKING, PROFESSIONAL, FULL_PROFESSIONAL, NATIVENo
speakingProficiencyenum: ELEMENTARY, LIMITED_WORKING, PROFESSIONAL, FULL_PROFESSIONAL, NATIVENo

delete_language

Permanently delete a language record. The employee themselves, ADMINISTRATOR or EXECUTIVE only.

Destructive

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
languageIdstringYesResource ID

query_certifications

List certifications for a user (name, type, issuing body, credential ID, issued and expiry dates). Past-expiry certifications are marked EXPIRED. Visible to the employee themselves, ADMINISTRATOR, EXECUTIVE, and a DEPARTMENT_HEAD for their departments.

Read-only

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID

add_certification

Add a certification for a user. name is required. The employee themselves, ADMINISTRATOR or EXECUTIVE only. Adding one for someone else returns 404 when that person is deactivated or not in your organization, or when certificationTypeId is not one of your organization's types.

Write · Risk: medium

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
namestringYesCertification name
certificationTypeIdstringNoID of one of the organization's certification types
issuingBodystringNoOrganization that issued the certification
credentialIdstringNoCredential / licence number
issuedDatestringNoDate in YYYY-MM-DD format
expiryDatestringNoDate in YYYY-MM-DD format

update_certification

Update a certification. Only the fields you pass change; changing expiryDate recomputes ACTIVE/EXPIRED. The employee themselves, ADMINISTRATOR or EXECUTIVE only.

Write

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
certIdstringYesResource ID
namestringNo
certificationTypeIdstringNo
issuingBodystringNo
credentialIdstringNo
issuedDatestringNoDate in YYYY-MM-DD format
expiryDatestringNoDate in YYYY-MM-DD format

delete_certification

Permanently delete a certification record. The employee themselves, ADMINISTRATOR or EXECUTIVE only.

Destructive · Risk: medium

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
certIdstringYesResource ID

query_visa

List visa / work authorization records for a user (type, issuing country, status, dates, note). Past-expiry visas are marked EXPIRED. Visible to the employee themselves, ADMINISTRATOR, EXECUTIVE, and a DEPARTMENT_HEAD for their departments.

Read-only

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID

add_visa_entry

Add a visa / work authorization record for a user. visaType is required. A past expiryDate is stored as EXPIRED. The employee themselves, ADMINISTRATOR or EXECUTIVE only.

Write · Risk: medium

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
visaTypestringYesVisa type (e.g. "H-1B", "TN", "Permanent Resident")
issuingCountrystringNoIssuing country
statusstringNoStatus, defaults to ACTIVE (e.g. ACTIVE, PENDING)
issuedDatestringNoDate in YYYY-MM-DD format
expiryDatestringNoDate in YYYY-MM-DD format
notestringNo

delete_visa_entry

Permanently delete a visa record. The employee themselves, ADMINISTRATOR or EXECUTIVE only.

Destructive · Risk: medium

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
visaIdstringYesResource ID

query_assets

List company equipment held by a user (description, category, serial number, status, assigned and returned dates). Visible to the employee themselves, ADMINISTRATOR, EXECUTIVE, and the DEPARTMENT_HEAD of their department.

Read-only

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID

assign_asset

Issue a piece of company equipment to a user (status ASSIGNED). description is required. Pass categoryId, or categoryName to use (or create) a category by name. ADMINISTRATOR, EXECUTIVE, or the DEPARTMENT_HEAD of the holder's department. Refused for a deactivated person (INACTIVE_PERSON).

Write · Risk: medium

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
descriptionstringYesWhat the asset is (e.g. "MacBook Pro 14 2024")
categoryIdstringNoAsset category ID
categoryNamestringNoCategory name; an existing category with this name is used, otherwise one is created
serialNumberstringNo
dateAssignedstringNoDate issued (YYYY-MM-DD)

update_asset

Update an equipment record held by a user. Only the fields you pass change. ADMINISTRATOR, EXECUTIVE, or the DEPARTMENT_HEAD of the holder's department.

Write

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
assetIdstringYesResource ID
descriptionstringNo
serialNumberstringNo
categoryIdstringNo
categoryNamestringNo
dateAssignedstringNoDate in YYYY-MM-DD format
dateReturnedstringNoDate in YYYY-MM-DD format
statusenum: AVAILABLE, ASSIGNED, RETIRED, LOSTNoAsset status

return_asset

Mark an asset as returned: sets its status to AVAILABLE and, when dateReturned is given, records that date. Pass dateReturned (YYYY-MM-DD) to record when it came back; without it the return date is left as it was. ADMINISTRATOR, EXECUTIVE, or the DEPARTMENT_HEAD of the holder's department.

Write

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
assetIdstringYesResource ID
dateReturnedstringNoDate the asset was returned (YYYY-MM-DD)

delete_asset

Permanently delete an asset record (use return_asset to mark it returned without losing history). ADMINISTRATOR, EXECUTIVE, or the DEPARTMENT_HEAD of the holder's department.

Destructive · Risk: high

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
assetIdstringYesResource ID

query_custom_field_values

Read a user's values for the organization's custom profile fields (each with its field id, name, fieldType and options). Only fields that have a value are returned, and values on custom tabs hidden from the caller's role are left out. The employee themselves, ADMINISTRATOR or EXECUTIVE only.

Read-only

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
tabIdstringNoOnly values for fields on this custom tab

set_custom_field_values

Set a user's values for one or more custom profile fields (creates or replaces each value). Every value is a string: numbers as text, CHECKBOX as "true"/"false", DATE as YYYY-MM-DD, LIST_SINGLE as one of the field's options, LIST_MULTI as a JSON array string of options. A required field cannot be set empty. Fields come from query_custom_field_values (customField.id). The employee themselves, ADMINISTRATOR or EXECUTIVE only; a field on a tab hidden from the caller's role returns 404. Values are applied in order and stop at the first invalid one.

Write · Risk: medium

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
valuesobjectYes
values[].customFieldIdstringYes
values[].valuestringYes

query_compensation_history

List compensation history (pay rate changes over time) for a user, newest first. ADMINISTRATOR or EXECUTIVE only; everyone else, including the employee themselves, is refused.

Read-only

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID

add_compensation_entry

Add a compensation change record (a raise, a new pay rate, or a move between salaried and hourly). ADMINISTRATOR or EXECUTIVE only. effectiveDate, payType and a positive payRate are required.

Write · Risk: medium

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
effectiveDatestringYesDate this rate took effect (YYYY-MM-DD)
payTypestringYesPay type. The app offers SALARY or HOURLY.
payRatenumberYesPay rate: the annual amount for SALARY, the hourly rate for HOURLY
currencystringNoISO currency code, defaults to USD on the server
paySchedulestringNoPay schedule. The app offers WEEKLY, BIWEEKLY, SEMIMONTHLY or MONTHLY.
overtimeStatusstringNoOvertime status. The app offers EXEMPT or NON_EXEMPT.
changeReasonstringNoWhy the pay changed (e.g. Promotion, Annual review)
commentstringNo

update_compensation_entry

Correct an existing compensation history entry. Only the fields you pass change. ADMINISTRATOR or EXECUTIVE only.

Write · Risk: medium

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
compIdstringYesResource ID
effectiveDatestringNoDate in YYYY-MM-DD format
payTypestringNoPay type. The app offers SALARY or HOURLY.
payRatenumberNo
currencystringNo
paySchedulestringNoPay schedule. The app offers WEEKLY, BIWEEKLY, SEMIMONTHLY or MONTHLY.
overtimeStatusstringNoOvertime status. The app offers EXEMPT or NON_EXEMPT.
changeReasonstringNo
commentstringNo

delete_compensation_entry

Permanently delete a compensation history entry. ADMINISTRATOR or EXECUTIVE only.

Destructive · Risk: high

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
compIdstringYesResource ID

query_bonuses

List one-off bonus records for a user, newest first. ADMINISTRATOR or EXECUTIVE only.

Read-only

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID

add_bonus

Add a one-off bonus record for a user. ADMINISTRATOR or EXECUTIVE only. date and a positive amount are required.

Write · Risk: medium

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
datestringYesBonus date (YYYY-MM-DD)
amountnumberYes
currencystringNoISO currency code, defaults to USD on the server
reasonstringNoe.g. Q4 Performance, Signing, Referral
commentstringNo

update_bonus

Correct an existing bonus record. Only the fields you pass change. ADMINISTRATOR or EXECUTIVE only.

Write · Risk: medium

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
bonusIdstringYesResource ID
datestringNoDate in YYYY-MM-DD format
amountnumberNo
currencystringNo
reasonstringNo
commentstringNo

delete_bonus

Permanently delete a bonus record. ADMINISTRATOR or EXECUTIVE only.

Destructive · Risk: high

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
bonusIdstringYesResource ID

query_job_history

List position changes (title, department, division, location, manager) over time for a user. ADMINISTRATOR and EXECUTIVE see anyone, DEPARTMENT_HEAD sees their own and their departments, EMPLOYEE sees only their own.

Read-only

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID

add_job_history_entry

Add a job history record (promotion, transfer, title change). ADMINISTRATOR or EXECUTIVE only. This is a historical record: department, division, workLocation and reportsTo are free text as they should read in the history, and it does not change the employee's current profile.

Write · Risk: medium

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
effectiveDatestringYesYYYY-MM-DD
jobTitlestringNo
departmentstringNoDepartment name as text
divisionstringNo
workLocationstringNo
reportsTostringNoManager name as text
changeReasonstringNoe.g. Promotion, Transfer

update_job_history_entry

Correct an existing job history record. Only the fields you pass change. ADMINISTRATOR or EXECUTIVE only.

Write · Risk: medium

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
historyIdstringYesResource ID
effectiveDatestringNoDate in YYYY-MM-DD format
jobTitlestringNo
departmentstringNo
divisionstringNo
workLocationstringNo
reportsTostringNo
changeReasonstringNo

delete_job_history_entry

Permanently delete a job history entry. ADMINISTRATOR or EXECUTIVE only.

Destructive · Risk: high

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
historyIdstringYesResource ID

query_employment_status_history

List employment status changes (full-time, part-time, contract, etc.) over time. ADMINISTRATOR and EXECUTIVE see anyone, DEPARTMENT_HEAD sees their own and their departments, EMPLOYEE sees only their own.

Read-only

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID

add_employment_status_change

Record an employment status change in the history (e.g. PARTTIME to FULLTIME). ADMINISTRATOR or EXECUTIVE only. This is a history record and does not change the employee's current profile.

Write · Risk: medium

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
effectiveDatestringYesDate in YYYY-MM-DD format
employmentStatusenum: FULLTIME, PARTTIME, CONTRACT, INTERN, TEMPORARY, SEASONALYesEmployment status
commentstringNo

update_employment_status_change

Correct an existing employment status history entry. Only the fields you pass change. ADMINISTRATOR or EXECUTIVE only.

Write · Risk: medium

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
historyIdstringYesResource ID
effectiveDatestringNoDate in YYYY-MM-DD format
employmentStatusenum: FULLTIME, PARTTIME, CONTRACT, INTERN, TEMPORARY, SEASONALNoEmployment status
commentstringNo

delete_employment_status_change

Permanently delete an employment status history entry. ADMINISTRATOR or EXECUTIVE only.

Destructive · Risk: high

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
historyIdstringYesResource ID

query_equity

List equity grants (stock options, RSUs, SARs, phantom stock) for a user. ADMINISTRATOR or EXECUTIVE only.

Read-only

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID

add_equity_grant

Record an equity grant. ADMINISTRATOR or EXECUTIVE only. grantDate, equityType and a positive grantAmount (number of units) are required.

Write · Risk: high

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
grantDatestringYesDate in YYYY-MM-DD format
equityTypeenum: STOCK_OPTION, RSU, SAR, PHANTOMYes
grantAmountnumberYesNumber of units granted
exercisePricenumberNoExercise / strike price per unit
currencystringNoISO currency code, defaults to USD on the server
vestingSchedulestringNoFree-text vesting schedule (e.g. 4 years, 1 year cliff, monthly)
vestingStartDatestringNoDate in YYYY-MM-DD format
vestingPeriodMonthsintegerNoTotal vesting period in months
cliffMonthsintegerNoCliff period in months
expirationDatestringNoDate in YYYY-MM-DD format
statusstringNoGrant status, defaults to ACTIVE on the server
vestedAmountnumberNo
exercisedAmountnumberNo
commentstringNo

delete_equity_grant

Permanently delete an equity grant record. ADMINISTRATOR or EXECUTIVE only.

Destructive · Risk: high

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
equityIdstringYesResource ID

query_commissions

List commission plans on record for a user, newest first. ADMINISTRATOR or EXECUTIVE only.

Read-only

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID

add_commission

Record a commission plan for a user (its type and rate from an effective date). ADMINISTRATOR or EXECUTIVE only. effectiveDate, commissionType and a positive rate are required.

Write · Risk: medium

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
effectiveDatestringYesDate in YYYY-MM-DD format
commissionTypeenum: PERCENTAGE, FLAT_RATE, TIEREDYes
ratenumberYesPercentage for PERCENTAGE, amount for FLAT_RATE
currencystringNoISO currency code, defaults to USD on the server
frequencystringNoHow often it pays out (e.g. MONTHLY, QUARTERLY)
targetnumberNo
capnumberNo
changeReasonstringNo
commentstringNo

delete_commission

Permanently delete a commission record. ADMINISTRATOR or EXECUTIVE only.

Destructive · Risk: high

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
commissionIdstringYesResource ID

query_dependents

List dependents on file for a user (children, spouse, etc.). The employee themselves, ADMINISTRATOR or EXECUTIVE only.

Read-only

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID

add_dependent

Add a dependent to a user record. The employee themselves, ADMINISTRATOR or EXECUTIVE only. name and relationship are required.

Write · Risk: medium

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
namestringYesFull name of the dependent
relationshipstringYese.g. SPOUSE, CHILD, DOMESTIC_PARTNER, PARENT, OTHER
dateOfBirthstringNoDate in YYYY-MM-DD format
genderstringNo

update_dependent

Update a dependent record. Only the fields you pass change. The employee themselves, ADMINISTRATOR or EXECUTIVE only.

Write

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
depIdstringYesResource ID
namestringNo
relationshipstringNo
dateOfBirthstringNoDate in YYYY-MM-DD format
genderstringNo

delete_dependent

Permanently remove a dependent record. The employee themselves, ADMINISTRATOR or EXECUTIVE only.

Destructive · Risk: medium

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
depIdstringYesResource ID

query_onboarding_instances

List onboarding and offboarding checklists (instances) with their tasks. Filter by userId, type and status. ADMINISTRATOR and EXECUTIVE see all; a DEPARTMENT_HEAD sees their departments, their own, and any they have tasks on; everyone else sees their own and those they have tasks on (only their own tasks on someone else's checklist).

Read-only

ParameterTypeRequiredDescription
userIdstringNoOnly checklists for this employee
typeenum: ONBOARDING, OFFBOARDINGNoONBOARDING or OFFBOARDING
statusenum: NOT_STARTED, IN_PROGRESS, COMPLETEDNo

create_onboarding_instance

Start an onboarding or offboarding checklist for an employee, optionally from a template (task list). The template's tasks are copied with due dates computed from the employee's start date (onboarding) or end date (offboarding). ADMINISTRATOR, EXECUTIVE, or a DEPARTMENT_HEAD for people in their departments. Starting ONBOARDING for a deactivated person is refused (INACTIVE_PERSON); offboarding them is allowed.

Write · Risk: medium

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
templateIdstringNoOnboarding template (task list) ID; omit for an empty checklist
typeenum: ONBOARDING, OFFBOARDINGNoDefaults to ONBOARDING
startDatestringNoDate recorded as the checklist start (YYYY-MM-DD); defaults to now. Task due dates are computed from the employee start/end date, not this.

update_onboarding_instance

Set the status of an onboarding/offboarding checklist (NOT_STARTED, IN_PROGRESS, COMPLETED). Status also updates automatically as tasks are completed. ADMINISTRATOR, EXECUTIVE, or a DEPARTMENT_HEAD for people in their departments.

Write · Risk: medium

ParameterTypeRequiredDescription
instanceIdstringYesResource ID
statusenum: NOT_STARTED, IN_PROGRESS, COMPLETEDYes

delete_onboarding_instance

Permanently delete an onboarding/offboarding checklist and all its tasks. ADMINISTRATOR, EXECUTIVE, or a DEPARTMENT_HEAD for people in their departments.

Destructive · Risk: high

ParameterTypeRequiredDescription
instanceIdstringYesResource ID

query_onboarding_tasks

List the tasks in an onboarding/offboarding checklist with their status, assignee and due date. ADMINISTRATOR, EXECUTIVE, the employee the checklist is for, and anyone with a task on it.

Read-only

ParameterTypeRequiredDescription
instanceIdstringYesResource ID

add_onboarding_task

Add an ad-hoc task to an onboarding/offboarding checklist. title is required. Attach a document template with documentTemplateId so the employee gets their own copy (to sign when requiresSignature is true). ADMINISTRATOR, EXECUTIVE, or a DEPARTMENT_HEAD for people in their departments. An inactive or unknown assignee is refused, as is a document template that is archived or replaced (TEMPLATE_NOT_CURRENT).

Write · Risk: medium

ParameterTypeRequiredDescription
instanceIdstringYesResource ID
titlestringYesTask title
descriptionstringNo
assignedToIdstringNoUser ID of the person responsible
assignedRoleenum: HR, IT, MANAGER, EMPLOYEE, MISCELLANEOUSNoWhich team owns the task (defaults to HR on the server)
categoryenum: DOCUMENTS, EQUIPMENT, ACCESS, TRAINING, OTHERNoTask category (defaults to OTHER on the server)
dueDatestringNoDate in YYYY-MM-DD format
documentTemplateIdstringNoDocument template to attach
requiresSignaturebooleanNoWhether the attached document must be signed

update_onboarding_task

Update a checklist task. A status-only change (PENDING, COMPLETED, SKIPPED) may be made by the task's assignee, or for an unassigned task by an ADMINISTRATOR, EXECUTIVE or the department head; completing a task with an unsigned required document is refused for non-admins. Changing any other field needs ADMINISTRATOR, EXECUTIVE, or a DEPARTMENT_HEAD for people in their departments.

Write

ParameterTypeRequiredDescription
instanceIdstringYesResource ID
taskIdstringYesResource ID
statusenum: PENDING, COMPLETED, SKIPPEDNo
titlestringNo
descriptionstringNo
assignedToIdstringNo
assignedRoleenum: HR, IT, MANAGER, EMPLOYEE, MISCELLANEOUSNoWhich team owns the task (defaults to HR on the server)
categoryenum: DOCUMENTS, EQUIPMENT, ACCESS, TRAINING, OTHERNoTask category (defaults to OTHER on the server)
dueDatestringNoDate in YYYY-MM-DD format

complete_onboarding_task

Mark a checklist task COMPLETED. The task's assignee may do this, or for an unassigned task an ADMINISTRATOR, EXECUTIVE or the department head. If a document that must be signed is attached, non-admins are refused until it is signed.

Write

ParameterTypeRequiredDescription
instanceIdstringYesResource ID
taskIdstringYesResource ID

delete_onboarding_task

Permanently delete a task from an onboarding/offboarding checklist. ADMINISTRATOR, EXECUTIVE, or a DEPARTMENT_HEAD for people in their departments.

Destructive · Risk: medium

ParameterTypeRequiredDescription
instanceIdstringYesResource ID
taskIdstringYesResource ID

query_onboarding_templates

List onboarding/offboarding templates (task lists) the caller can see, with task and usage counts. Filter by type. Administrators see all; others see organization-wide lists plus those for their departments.

Read-only

ParameterTypeRequiredDescription
typeenum: ONBOARDING, OFFBOARDINGNoONBOARDING or OFFBOARDING

create_onboarding_template

Create an onboarding or offboarding template (task list). name is required and must be unique per type and department (409 otherwise). Omit departmentId for an organization-wide list. ADMINISTRATOR, EXECUTIVE, or a DEPARTMENT_HEAD for task lists scoped to their departments. A DEPARTMENT_HEAD's list defaults to their own department.

Write · Risk: medium

ParameterTypeRequiredDescription
namestringYes
typeenum: ONBOARDING, OFFBOARDINGNoDefaults to ONBOARDING
departmentIdstringNoScope the list to one department
iconstringNoIcon name shown next to the list

update_onboarding_template

Update an onboarding/offboarding template (task list). Only the fields you pass change. ADMINISTRATOR, EXECUTIVE, or a DEPARTMENT_HEAD for task lists scoped to their departments. Only administrators may change departmentId.

Write · Risk: medium

ParameterTypeRequiredDescription
templateIdstringYesResource ID
namestringNo
typeenum: ONBOARDING, OFFBOARDINGNoONBOARDING or OFFBOARDING
departmentIdstring or nullNoDepartment ID, or null for organization-wide
iconstringNo
isActivebooleanNo

delete_onboarding_template

Permanently delete an onboarding/offboarding template and its task definitions. Checklists already started from it are kept. ADMINISTRATOR, EXECUTIVE, or a DEPARTMENT_HEAD for task lists scoped to their departments.

Destructive · Risk: high

ParameterTypeRequiredDescription
templateIdstringYesResource ID

query_onboarding_template_tasks

List the task definitions inside an onboarding/offboarding template.

Read-only

ParameterTypeRequiredDescription
templateIdstringYesResource ID

add_onboarding_template_task

Add a task definition to an onboarding/offboarding template. It applies to checklists started from the template afterwards, not to ones already running. ADMINISTRATOR, EXECUTIVE, or a DEPARTMENT_HEAD for task lists scoped to their departments. An inactive assignee or a document template that is archived or replaced (TEMPLATE_NOT_CURRENT) is refused.

Write · Risk: medium

ParameterTypeRequiredDescription
templateIdstringYesResource ID
titlestringYes
descriptionstringNo
assignedToIdstringNoUser ID responsible; when omitted the organization default assignee is used
assignedRoleenum: HR, IT, MANAGER, EMPLOYEE, MISCELLANEOUSNoWhich team owns the task (defaults to HR on the server)
categoryenum: DOCUMENTS, EQUIPMENT, ACCESS, TRAINING, OTHERNoTask category (defaults to OTHER on the server)
dueDateTypeenum: NONE, ON_HIRE, CUSTOMNoNONE, ON_HIRE (due on the start / last day), or CUSTOM (dueDaysFromHire days before/after)
dueDaysFromHireintegerNoDays from the start/end date, used when dueDateType is CUSTOM
dueDaysDirectionenum: BEFORE, AFTERNo
notificationTimingenum: SOON, ON_DUE_DATE, NONENo
targetScopeenum: ALL, SOMENoALL employees the list is used for, or SOME (only targetEmployeeIds)
targetEmployeeIdsstringNoUsed when targetScope is SOME
documentTemplateIdstringNoDocument template each employee receives a copy of
requiresSignaturebooleanNo

update_onboarding_template_task

Update a task definition in an onboarding/offboarding template. Only the fields you pass change. Changing documentTemplateId or requiresSignature is also applied to matching tasks on checklists already started from this template. ADMINISTRATOR, EXECUTIVE, or a DEPARTMENT_HEAD for task lists scoped to their departments.

Write · Risk: medium

ParameterTypeRequiredDescription
templateIdstringYesResource ID
taskDefIdstringYesResource ID
titlestringNo
descriptionstringNo
assignedToIdstringNoUser ID responsible; when omitted the organization default assignee is used
assignedRoleenum: HR, IT, MANAGER, EMPLOYEE, MISCELLANEOUSNoWhich team owns the task (defaults to HR on the server)
categoryenum: DOCUMENTS, EQUIPMENT, ACCESS, TRAINING, OTHERNoTask category (defaults to OTHER on the server)
dueDateTypeenum: NONE, ON_HIRE, CUSTOMNoNONE, ON_HIRE (due on the start / last day), or CUSTOM (dueDaysFromHire days before/after)
dueDaysFromHireintegerNoDays from the start/end date, used when dueDateType is CUSTOM
dueDaysDirectionenum: BEFORE, AFTERNo
notificationTimingenum: SOON, ON_DUE_DATE, NONENo
targetScopeenum: ALL, SOMENoALL employees the list is used for, or SOME (only targetEmployeeIds)
targetEmployeeIdsstringNoUsed when targetScope is SOME
documentTemplateIdstringNoDocument template each employee receives a copy of
requiresSignaturebooleanNo

delete_onboarding_template_task

Permanently delete a task definition from an onboarding/offboarding template. ADMINISTRATOR, EXECUTIVE, or a DEPARTMENT_HEAD for task lists scoped to their departments.

Destructive · Risk: high

ParameterTypeRequiredDescription
templateIdstringYesResource ID
taskDefIdstringYesResource ID

query_onboarding_packets

List new hire welcome packets. ADMINISTRATOR or EXECUTIVE only.

Read-only

No parameters.

get_onboarding_packet

Get full details of a new hire packet (arrival, location, contact, instructions, "Get to Know You" questions, linked task lists). ADMINISTRATOR or EXECUTIVE only.

Read-only

ParameterTypeRequiredDescription
packetIdstringYesResource ID

create_onboarding_packet

Create a new hire welcome packet: arrival time, location, contact person, instructions, linked task lists and "Get to Know You" questions. name is required. ADMINISTRATOR or EXECUTIVE only.

Write · Risk: medium

ParameterTypeRequiredDescription
namestringYes
arrivalTimestringNoArrival time (e.g. "9:00 AM")
locationstringNo
whoToContactIdstringNoUser ID of the contact person (must be active)
otherInstructionsstringNo
linkedTemplateIdsstringNoOnboarding template IDs linked to this packet
sendGetToKnowYoubooleanNoSend the "Get to Know You" questions
getToKnowYouQuestionsstringNo"Get to Know You" questions
getToKnowYouScopeenum: ALL, DEPARTMENT, CUSTOMNoWho receives the answers: ALL, DEPARTMENT or CUSTOM (getToKnowYouIds)
getToKnowYouIdsstringNoDepartment or employee IDs for DEPARTMENT/CUSTOM scope
isDefaultbooleanNo

update_onboarding_packet

Update a new hire packet. Only the fields you pass change. ADMINISTRATOR or EXECUTIVE only.

Write · Risk: medium

ParameterTypeRequiredDescription
packetIdstringYesResource ID
namestringNo
arrivalTimestringNoArrival time (e.g. "9:00 AM")
locationstringNo
whoToContactIdstringNoUser ID of the contact person (must be active)
otherInstructionsstringNo
linkedTemplateIdsstringNoOnboarding template IDs linked to this packet
sendGetToKnowYoubooleanNoSend the "Get to Know You" questions
getToKnowYouQuestionsstringNo"Get to Know You" questions
getToKnowYouScopeenum: ALL, DEPARTMENT, CUSTOMNoWho receives the answers: ALL, DEPARTMENT or CUSTOM (getToKnowYouIds)
getToKnowYouIdsstringNoDepartment or employee IDs for DEPARTMENT/CUSTOM scope
isDefaultbooleanNo

delete_onboarding_packet

Permanently delete a new hire packet. ADMINISTRATOR or EXECUTIVE only.

Destructive · Risk: high

ParameterTypeRequiredDescription
packetIdstringYesResource ID

Clients

5 tools.

query_clients

List the organization's clients (the companies projects are billed to), alphabetically, with project counts. Filter by status or a name search. Returns every match (no paging). DEPARTMENT_HEAD, ADMINISTRATOR and EXECUTIVE only; employees are refused (403).

Read-only

ParameterTypeRequiredDescription
searchstringNoMatches the client name
statusenum: ACTIVE, INACTIVE, ARCHIVEDNo

get_client

Get one client with its contact details and projects. DEPARTMENT_HEAD, ADMINISTRATOR and EXECUTIVE only; employees are refused (403).

Read-only

ParameterTypeRequiredDescription
clientIdstringYesResource ID

create_client

Create a client. The name must be unique in the organization (409 otherwise); status defaults to ACTIVE. DEPARTMENT_HEAD, ADMINISTRATOR and EXECUTIVE only; employees are refused (403).

Write · Risk: medium

ParameterTypeRequiredDescription
namestringYesClient name
emailstring or nullNo
phonestring or nullNo
companystring or nullNo
addressstring or nullNoFull postal address as one text field
notesstring or nullNo
statusenum: ACTIVE, INACTIVE, ARCHIVEDNo

update_client

Update a client. Only the fields passed are changed; null clears a field. A new name must be unique in the organization. Set status INACTIVE or ARCHIVED to retire a client without deleting it. DEPARTMENT_HEAD, ADMINISTRATOR and EXECUTIVE only; employees are refused (403).

Write · Risk: medium

ParameterTypeRequiredDescription
clientIdstringYesResource ID
namestringNo
emailstring or nullNo
phonestring or nullNo
companystring or nullNo
addressstring or nullNoFull postal address as one text field
notesstring or nullNo
statusenum: ACTIVE, INACTIVE, ARCHIVEDNo

delete_client

Permanently delete a client. Refused (400) while the client has any ACTIVE project; its other projects are kept but unlinked from it. Consider update_client with status ARCHIVED instead. DEPARTMENT_HEAD, ADMINISTRATOR and EXECUTIVE only; employees are refused (403).

Destructive · Risk: high

ParameterTypeRequiredDescription
clientIdstringYesResource ID

Notifications

5 tools.

get_unread_notification_count

Get the number of unread notifications for the current user.

Read-only

No parameters.

mark_notification_read

Mark one of the current user's notifications as read.

Write

ParameterTypeRequiredDescription
notificationIdstringYesResource ID

mark_all_notifications_read

Mark every notification as read for the current user.

Write

No parameters.

delete_notification

Delete (dismiss) one of the current user's notifications.

Destructive

ParameterTypeRequiredDescription
notificationIdstringYesResource ID

clear_all_notifications

Delete every notification for the current user. Cannot be undone.

Destructive · Risk: medium

No parameters.


Calendar

8 tools.

get_calendar_status

Show the current user's calendar sync state: connected Google/Outlook integrations, their iCal feeds, and which providers the server has configured.

Read-only

No parameters.

query_calendar_feeds

List the current user's iCal feeds with type, subscription URL, last access and access count. The URL is a private link: anyone holding it can read the feed.

Read-only

No parameters.

create_calendar_feed

Create an iCal subscription URL for the current user, to add to Google Calendar, Outlook or Apple Calendar. feedType PERSONAL (own leave, anyone), APPROVALS (leave awaiting the caller's approval), DEPARTMENT (needs departmentId; ADMINISTRATOR/EXECUTIVE any department, DEPARTMENT_HEAD only their scope), DIRECT_REPORTS (ADMINISTRATOR/EXECUTIVE/DEPARTMENT_HEAD with at least one direct report), ORGANIZATION (ADMINISTRATOR/EXECUTIVE). The returned URL is a private link: anyone holding it can read the feed.

Write

ParameterTypeRequiredDescription
feedTypeenum: PERSONAL, DEPARTMENT, DIRECT_REPORTS, APPROVALS, ORGANIZATIONYes
departmentIdstringNoRequired when feedType is DEPARTMENT
namestringNoFriendly name for the feed

delete_calendar_feed

Delete one of the current user's calendar feeds. Its iCal URL stops working immediately.

Destructive · Risk: medium

ParameterTypeRequiredDescription
feedIdstringYesResource ID

connect_google_calendar

Start the Google Calendar OAuth flow for the current user. Returns authUrl — the user must open it in a browser to grant access.

Read-only

No parameters.

disconnect_google_calendar

Disconnect the current user's Google Calendar integration.

Write · Risk: medium

No parameters.

connect_outlook_calendar

Start the Outlook Calendar OAuth flow for the current user. Returns authUrl — the user must open it in a browser to grant access.

Read-only

No parameters.

disconnect_outlook_calendar

Disconnect the current user's Outlook Calendar integration.

Write · Risk: medium

No parameters.


Performance

37 tools.

query_goals

List a person's performance goals, optionally filtered by status or category. Administrators and executives may read anyone, department heads their own departments, employees only their own.

Read-only

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
statusenum: NOT_STARTED, IN_PROGRESS, COMPLETED, CANCELLEDNo
categorystringNoExact category name (case-insensitive)

create_goal

Set a performance goal for a person. Allowed for executives (anyone, including themselves), administrators (anyone except themselves) and department heads (people in departments they head or manage, not themselves); employees cannot. The person must be an active member (404 otherwise). Progress starts at 0; use update_goal to move it.

Write

ParameterTypeRequiredDescription
userIdstringYesGoal owner
titlestringYes
descriptionstringNo
categorystringNoe.g. Engineering, Sales, Personal
dueDatestringNoDate in YYYY-MM-DD format
statusenum: NOT_STARTED, IN_PROGRESS, COMPLETED, CANCELLEDNoDefault NOT_STARTED
weightnumberNoRelative weight of the goal

update_goal

Update a goal. The goal owner and anyone who may manage their performance can change title, description, status, percentComplete (0-100) and dueDate; category and weight change only for a manager and are ignored for the owner. Setting percentComplete also syncs the status (100 = COMPLETED, 0 = NOT_STARTED, otherwise IN_PROGRESS from NOT_STARTED).

Write

ParameterTypeRequiredDescription
userIdstringYesGoal owner
goalIdstringYesResource ID
titlestringNo
descriptionstringNo
statusenum: NOT_STARTED, IN_PROGRESS, COMPLETED, CANCELLEDNo
percentCompleteintegerNo
dueDatestringNoDate in YYYY-MM-DD format
categorystringNo
weightnumber or nullNo

delete_goal

Permanently delete a goal and all its comments. Allowed for executives (anyone, including themselves), administrators (anyone except themselves) and department heads (people in departments they head or manage, not themselves); employees cannot. The goal owner cannot delete a goal set for them.

Destructive · Risk: medium

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
goalIdstringYesResource ID

query_goal_comments

List the comments on a goal that the caller may read. Comments carry a visibility floor (SHARED, MANAGEMENT, LEADERSHIP); ones above the caller's level are left out. Readable by the owner, their department head, administrators and executives.

Read-only

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
goalIdstringYesResource ID

add_goal_comment

Comment on a goal. Allowed for executives (anyone, including themselves), administrators (anyone except themselves) and department heads (people in departments they head or manage, not themselves); employees cannot. visibility sets who can read it: SHARED (default; the owner too), MANAGEMENT (not the owner) or LEADERSHIP (administrators and executives only, which department heads cannot choose).

Write

ParameterTypeRequiredDescription
userIdstringYesGoal owner
goalIdstringYesResource ID
contentstringYesComment text
visibilityenum: SHARED, MANAGEMENT, LEADERSHIPNo

delete_goal_comment

Permanently delete a goal comment. Allowed for its author, or for someone who may manage the goal owner's performance.

Destructive

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
goalIdstringYesResource ID
commentIdstringYesResource ID

query_one_on_one_series

List the recurring 1:1 series a person takes part in (default: the caller), with both participants, cadence and the next scheduled meeting. Viewing someone else's needs administrator/executive, being their manager, or heading their department.

Read-only

ParameterTypeRequiredDescription
userIdstringNoWhose 1:1s to list (default: the caller)

create_one_on_one_series

Set up a recurring 1:1 between an employee (subjectId) and another person (participantId, default: the subject's department head, then their manager). Allowed for executives (anyone), administrators (anyone but themselves) and department heads (their own departments, not themselves). Both people must be active. Creates the first meeting only (firstMeetingDate, default one week from today in the organization's timezone) and notifies the participants by email. Refused with 409 if the pair already has a series.

Write

ParameterTypeRequiredDescription
subjectIdstringNoEmployee the 1:1 is about (default: the caller)
participantIdstringNoWho they meet with (default: department head, then manager)
frequencyenum: WEEKLY, BIWEEKLY, MONTHLY, ONE_TIMENoMeeting cadence (default WEEKLY)
firstMeetingDatestringNoFirst meeting date (YYYY-MM-DD)
startTimestringNoStart time of day, HH:MM (24-hour)
durationMinutesintegerNoDuration in minutes (default 30)
reviewCycleIdstringNoLink the series to a review cycle

update_one_on_one_series

Update a 1:1 series: cadence, active flag, next meeting date, start time, duration or linked review cycle. Open to the two participants, administrators, executives, the subject's manager and their department head. Reactivating a series whose participant has left is refused.

Write

ParameterTypeRequiredDescription
seriesIdstringYesResource ID
frequencyenum: WEEKLY, BIWEEKLY, MONTHLY, ONE_TIMENoMeeting cadence
isActivebooleanNoPause (false) or resume (true) the series
nextMeetingDatestringNoDate in YYYY-MM-DD format
startTimestringNoStart time of day, HH:MM (24-hour)
durationMinutesintegerNoDuration in minutes (1-480)
reviewCycleIdstringNoReview cycle to link; empty string unlinks

cancel_one_on_one_series

Permanently delete a 1:1 series with ALL its meetings, agenda items and notes, past and future, and remove synced calendar events. This cannot be undone; to pause a series instead, use update_one_on_one_series with isActive false. Allowed for whoever may set up a 1:1 for the subject (executives, administrators for others, department heads for their departments); participants alone cannot. The other participant is notified.

Destructive · Risk: high

ParameterTypeRequiredDescription
seriesIdstringYesResource ID

query_one_on_one_meetings

List the meetings in a 1:1 series, newest first, with agenda and note counts. Open to the two participants, administrators, executives, the subject's manager and their department head.

Read-only

ParameterTypeRequiredDescription
seriesIdstringYesResource ID

schedule_one_on_one_meeting

Add a meeting on a given date to an existing 1:1 series. Set its time or duration afterwards with update_one_on_one_meeting. Open to the two participants, administrators, executives, the subject's manager and their department head.

Write

ParameterTypeRequiredDescription
seriesIdstringYesResource ID
meetingDatestringYesDate in YYYY-MM-DD format

update_one_on_one_meeting

Reschedule a 1:1 meeting or record its outcome: date, start time, duration, or status. Open to the two participants, administrators, executives, the subject's manager and their department head.

Write

ParameterTypeRequiredDescription
seriesIdstringYesResource ID
meetingIdstringYesResource ID
meetingDatestringNoDate in YYYY-MM-DD format
startTimestringNoStart time of day, HH:MM (24-hour)
durationMinutesintegerNoDuration in minutes (1-480)
statusenum: SCHEDULED, COMPLETED, CANCELLED, SKIPPEDNo

query_meeting_agenda

List the agenda items for a 1:1 meeting in order. Open to the two participants, administrators, executives, the subject's manager and their department head.

Read-only

ParameterTypeRequiredDescription
meetingIdstringYesResource ID

add_agenda_item

Add an agenda item to the end of a 1:1 meeting's agenda. The caller is recorded as its author. Open to the two participants, administrators, executives, the subject's manager and their department head.

Write

ParameterTypeRequiredDescription
meetingIdstringYesResource ID
textstringYesAgenda item text

update_agenda_item

Edit an agenda item's text, tick it off (isCompleted) or move it (sortOrder). Open to the two participants, administrators, executives, the subject's manager and their department head.

Write

ParameterTypeRequiredDescription
meetingIdstringYesResource ID
itemIdstringYesResource ID
textstringNo
isCompletedbooleanNo
sortOrderintegerNo

delete_agenda_item

Permanently delete an agenda item. Open to the two participants, administrators, executives, the subject's manager and their department head.

Destructive

ParameterTypeRequiredDescription
meetingIdstringYesResource ID
itemIdstringYesResource ID

query_meeting_notes

List notes on a 1:1 meeting. Private notes are returned only to their author. Open to the two participants, administrators, executives, the subject's manager and their department head.

Read-only

ParameterTypeRequiredDescription
meetingIdstringYesResource ID

add_meeting_note

Add a note to a 1:1 meeting. Mark it private to keep it visible only to yourself. Open to the two participants, administrators, executives, the subject's manager and their department head.

Write

ParameterTypeRequiredDescription
meetingIdstringYesResource ID
contentstringYes
isPrivatebooleanNoPrivate notes are only visible to the author (default: false)

update_meeting_note

Edit a 1:1 meeting note or change whether it is private. Only the note's author may edit it (404 otherwise).

Write

ParameterTypeRequiredDescription
meetingIdstringYesResource ID
noteIdstringYesResource ID
contentstringNo
isPrivatebooleanNo

delete_meeting_note

Permanently delete a 1:1 meeting note. Only the note's author may delete it (404 otherwise).

Destructive

ParameterTypeRequiredDescription
meetingIdstringYesResource ID
noteIdstringYesResource ID

query_performance_cycles

List every performance review cycle in the organization with its timing, scope, status, member count and assessment count. Administrators and executives only (others get 403); use query_active_performance_cycles for the short list of running cycles.

Read-only

No parameters.

query_active_performance_cycles

List review cycles that are ACTIVE and still open today in the organization's timezone (id, name, timing, dates, status only). Callable by anyone who may send documents: administrators, executives and department heads (department heads see only cycles covering someone in their departments).

Read-only

No parameters.

create_performance_cycle

Create a performance review cycle. Administrators and executives only. A FIXED cycle (the default) needs startDate; an ANNIVERSARY cycle uses anniversaryMonths instead of dates. Scope defaults to ALL employees; DEPARTMENT needs departmentId and CUSTOM needs employeeIds (all must be active members, otherwise 400). Status defaults to ACTIVE.

Write · Risk: medium

ParameterTypeRequiredDescription
namestringYesCycle name, e.g. "Annual Review 2026"
typestringNoFree-form cycle type label, e.g. ANNUAL, QUARTERLY (default ANNUAL)
statusenum: DRAFT, ACTIVENoDRAFT (not running, sends no reminders) or ACTIVE
timingenum: FIXED, ANNIVERSARYNoFIXED = a start/end window; ANNIVERSARY = due a number of months after each person's hire date
startDatestringNoWindow start (YYYY-MM-DD). Required when timing is FIXED
endDatestringNoWindow end (YYYY-MM-DD), not before startDate
anniversaryMonthsintegerNoANNIVERSARY timing only: months after hire the review falls due (default 12)
anniversaryRepeatsbooleanNoANNIVERSARY timing only: repeat every interval (default true)
reminderOffsetDaysintegerNoDays before the due date to send reminders, 1-6 values (default 14, 3)
employeeScopeenum: ALL, DEPARTMENT, CUSTOMNoWho the cycle covers: ALL active employees, one DEPARTMENT (needs departmentId), or CUSTOM (needs employeeIds)
departmentIdstringNoDepartment ID, for employeeScope DEPARTMENT
employeeIdsstringNoActive employee IDs, for employeeScope CUSTOM. Supplying this without employeeScope sets the scope to CUSTOM

update_performance_cycle

Update a performance review cycle: name, type, status (DRAFT/ACTIVE), timing, dates, reminders or who it covers. Administrators and executives only. Only the fields you pass change; the current scope is kept when you change only dates or reminders. Adding employees requires them to be active.

Write · Risk: medium

ParameterTypeRequiredDescription
cycleIdstringYesResource ID
namestringNo
typestringNoFree-form cycle type label, e.g. ANNUAL, QUARTERLY (default ANNUAL)
statusenum: DRAFT, ACTIVENoDRAFT (not running, sends no reminders) or ACTIVE
timingenum: FIXED, ANNIVERSARYNoFIXED = a start/end window; ANNIVERSARY = due a number of months after each person's hire date
startDatestringNoWindow start (YYYY-MM-DD). Required when timing is FIXED
endDatestringNoWindow end (YYYY-MM-DD), not before startDate
anniversaryMonthsintegerNoANNIVERSARY timing only: months after hire the review falls due (default 12)
anniversaryRepeatsbooleanNoANNIVERSARY timing only: repeat every interval (default true)
reminderOffsetDaysintegerNoDays before the due date to send reminders, 1-6 values (default 14, 3)
employeeScopeenum: ALL, DEPARTMENT, CUSTOMNoWho the cycle covers: ALL active employees, one DEPARTMENT (needs departmentId), or CUSTOM (needs employeeIds)
departmentIdstringNoDepartment ID, for employeeScope DEPARTMENT
employeeIdsstringNoActive employee IDs, for employeeScope CUSTOM. Supplying this without employeeScope sets the scope to CUSTOM

delete_performance_cycle

Permanently delete a performance review cycle together with every assessment filed under it. Administrators and executives only. This cannot be undone; set status to DRAFT with update_performance_cycle to pause a cycle instead.

Destructive · Risk: high

ParameterTypeRequiredDescription
cycleIdstringYesResource ID

duplicate_performance_cycle

Copy an existing performance cycle (timing, dates, reminders and scope) as a new DRAFT named "Copy of <name>". Optionally rename it and give it new dates in the same call. Administrators and executives only. Activate the copy with update_performance_cycle status ACTIVE.

Write · Risk: medium

ParameterTypeRequiredDescription
cycleIdstringYesCycle to copy
newNamestringNoName for the copy (default "Copy of <name>")
newStartDatestringNoStart date for the copy (YYYY-MM-DD)
newEndDatestringNoEnd date for the copy (YYYY-MM-DD)

query_performance_assessments

List performance assessments, optionally for one review cycle and/or one subject. Administrators and executives see all. Anyone else sees only assessments they are writing plus COMPLETED ones about themselves, with the author hidden on PEER and DIRECT_REPORT feedback; asking for another person returns an empty list.

Read-only

ParameterTypeRequiredDescription
cycleIdstringNoReview cycle ID
userIdstringNoSubject (person being assessed)

create_performance_assessment

Assign an assessment within a review cycle: who is assessed (userId), who writes it (assessorId) and in what capacity. Administrators and executives only. Subject and assessor must be active members (otherwise 404). It starts PENDING; the assessor fills it in with update_performance_assessment.

Write · Risk: medium

ParameterTypeRequiredDescription
reviewCycleIdstringYesReview cycle ID
userIdstringYesSubject (person being assessed)
assessorIdstringYesPerson writing the assessment
assessorTypeenum: SELF, MANAGER, PEER, DIRECT_REPORTNoAssessor relationship (default MANAGER)

update_performance_assessment

Fill in or change an assessment. The assessor (or an administrator/executive) may set status, responses, overallRating and comments; setting status COMPLETED records the completion time. Only administrators and executives may change assessorId, assessorType, userId or reviewCycleId (ignored for others). Anyone else gets 403.

Write

ParameterTypeRequiredDescription
assessmentIdstringYesResource ID
statusenum: PENDING, IN_PROGRESS, COMPLETEDNo
responsesobjectNoAnswers to the template questions, e.g. { question, answer }. Replaces the stored responses
overallRatingnumber or nullNoOverall rating, e.g. 1-5; null clears it
commentsstringNo
assessorIdstringNoAdmin/executive only: reassign to another active member
assessorTypeenum: SELF, MANAGER, PEER, DIRECT_REPORTNoAdmin/executive only
userIdstringNoAdmin/executive only: change the subject (must be active)
reviewCycleIdstringNoAdmin/executive only: move to another cycle

query_performance_templates

List assessment templates (named sets of review questions). Administrators and executives only.

Read-only

No parameters.

create_performance_template

Create an assessment template with at least one question. Administrators and executives only. Names are unique per organization (409 on a duplicate).

Write · Risk: medium

ParameterTypeRequiredDescription
namestringYes
descriptionstringNo
questionsobjectYesQuestions, e.g. { question: "Top accomplishment?", type: "TEXT", required: true }
questions[].questionstringYesQuestion text
questions[].typestringYesAnswer type, e.g. TEXT or RATING
questions[].requiredbooleanYesWhether an answer is required
isActivebooleanNoDefault true

update_performance_template

Update an assessment template. Administrators and executives only. Passing questions REPLACES the whole question list, so send every question you want to keep.

Write · Risk: medium

ParameterTypeRequiredDescription
templateIdstringYesResource ID
namestringNo
descriptionstringNo
questionsobjectNoFull replacement question list
questions[].questionstringYesQuestion text
questions[].typestringYesAnswer type, e.g. TEXT or RATING
questions[].requiredbooleanYesWhether an answer is required
isActivebooleanNo

delete_performance_template

Permanently delete an assessment template. Administrators and executives only.

Destructive · Risk: high

ParameterTypeRequiredDescription
templateIdstringYesResource ID

get_performance_settings

Get the organization's performance settings: who may use goals, cascading goals, goal sharing default and categories, feedback summaries, and 1:1 enablement, default cadence and visibility. Administrators and executives only.

Read-only

No parameters.

update_performance_settings

Update organization-wide performance settings. Administrators and executives only. Only the fields you pass change. goalUsersIds replaces the list of people allowed to set goals when goalUsersScope is SOME; inactive or unknown people being added are dropped.

Write · Risk: medium

ParameterTypeRequiredDescription
goalUsersScopeenum: NONE, ALL, SOMENoWho may use goals
goalUsersIdsstringNoPeople allowed to use goals when goalUsersScope is SOME (full replacement)
cascadingGoalsbooleanNo
goalSharingDefaultenum: PRIVATE, MANAGER, DEPARTMENT, ORGANIZATIONNo
goalCategoriesstringNoGoal category names (full replacement)
includeFeedbackSummariesbooleanNo
oneOnOnesEnabledbooleanNo
oneOnOneDefaultFreqenum: WEEKLY, BIWEEKLY, MONTHLYNo
oneOnOneVisibilityenum: PARTICIPANTS_ONLY, MANAGER_CHAIN, ADMINNo

Training

14 tools.

query_user_training

List a person's training assignments with course details, status (ASSIGNED, IN_PROGRESS, COMPLETED, OVERDUE), due and completed dates. Administrators and executives may read anyone, department heads their own departments, employees only their own.

Read-only

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID

assign_training

Assign a training course to one person, or record one they already completed (status COMPLETED, completedDate defaults to their today). Allowed for administrators and executives (anyone) and department heads (people in departments they head or manage, not themselves). Refused for a deactivated person unless recording a completion (INACTIVE_PERSON), and with 409 ALREADY_ASSIGNED if the course is already assigned to them.

Write · Risk: medium

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
courseIdstringYesTraining course ID
dueDatestringNoDate in YYYY-MM-DD format
statusenum: ASSIGNED, IN_PROGRESS, COMPLETED, OVERDUENoDefault ASSIGNED
completedDatestringNoOnly used when status is COMPLETED
notesstringNo

update_training_assignment

Update a training assignment. Allowed for administrators and executives (anyone) and department heads (people in departments they head or manage, not themselves). Such a manager may change status, dueDate, completedDate, score and notes. The person themselves may only set status IN_PROGRESS or COMPLETED (with an optional completedDate); their other fields are ignored. Use mark_training_complete for the common case.

Write

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
assignmentIdstringYesResource ID
statusenum: ASSIGNED, IN_PROGRESS, COMPLETED, OVERDUENo
dueDatestringNoDate in YYYY-MM-DD format
completedDatestringNoDate in YYYY-MM-DD format
scorenumberNo
notesstringNo

mark_training_complete

Mark a training assignment COMPLETED. The person themselves or a manager may do this. completedDate defaults to now on the server; score and notes are kept only when a manager (administrator, executive or their department head) sends them.

Write

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
assignmentIdstringYesResource ID
completedDatestringNoCompletion day (YYYY-MM-DD); omit to use today
scorenumberNo
notesstringNo

dismiss_training

Permanently delete a training assignment from a person's record (it is not marked complete or skipped; it is removed). Allowed for administrators and executives (anyone) and department heads (people in departments they head or manage, not themselves). Employees cannot. This cannot be undone.

Destructive · Risk: high

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
assignmentIdstringYesResource ID

query_training_courses

List the organization's active training courses with category and assignment counts. Optionally filter by category.

Read-only

ParameterTypeRequiredDescription
categoryIdstringNoOnly courses in this training category

create_training_course

Create a training course in the catalog. Administrators and executives only. When isRequired is true it is assigned immediately to every active person it targets (requiredForType, default ALL). Names are unique (409 on a duplicate).

Write · Risk: medium

ParameterTypeRequiredDescription
namestringYes
descriptionstringNo
categoryIdstringNoTraining category ID
providerstringNo
durationintegerNoDuration in minutes
urlstringNoLink to the training material
frequencyenum: ONE_TIME, EVERY_YEAR, EVERY_2_YEARS, EVERY_3_YEARS, EVERY_5_YEARSNoHow often the course must be retaken
dueDaysFromHireintegerNoDays after hire the course is due
isRequiredbooleanNoRequired courses are assigned automatically to everyone they target
requiredForTypeenum: ALL, DEPARTMENT, ROLE, EMPLOYEESNoWho a required course targets: ALL, one DEPARTMENT (requiredDepartmentId), one ROLE (requiredRole) or specific EMPLOYEES (requiredEmployeeIds)
requiredDepartmentIdstringNoDepartment ID, for requiredForType DEPARTMENT
requiredRoleenum: EMPLOYEE, DEPARTMENT_HEAD, ADMINISTRATOR, EXECUTIVENoRole, for requiredForType ROLE
requiredEmployeeIdsstringNoUser IDs, for requiredForType EMPLOYEES
allowSelfCompletebooleanNoLet assignees mark it complete themselves

update_training_course

Update a training course. Administrators and executives only. Only the fields you pass change. Turning isRequired on assigns it to everyone it targets who does not have it yet. Set isActive false to retire a course without deleting its history.

Write · Risk: medium

ParameterTypeRequiredDescription
courseIdstringYesResource ID
namestringNo
descriptionstringNo
categoryIdstringNoTraining category ID
providerstringNo
durationintegerNoDuration in minutes
urlstringNoLink to the training material
frequencyenum: ONE_TIME, EVERY_YEAR, EVERY_2_YEARS, EVERY_3_YEARS, EVERY_5_YEARSNoHow often the course must be retaken
dueDaysFromHireintegerNoDays after hire the course is due
isRequiredbooleanNoRequired courses are assigned automatically to everyone they target
requiredForTypeenum: ALL, DEPARTMENT, ROLE, EMPLOYEESNoWho a required course targets: ALL, one DEPARTMENT (requiredDepartmentId), one ROLE (requiredRole) or specific EMPLOYEES (requiredEmployeeIds)
requiredDepartmentIdstringNoDepartment ID, for requiredForType DEPARTMENT
requiredRoleenum: EMPLOYEE, DEPARTMENT_HEAD, ADMINISTRATOR, EXECUTIVENoRole, for requiredForType ROLE
requiredEmployeeIdsstringNoUser IDs, for requiredForType EMPLOYEES
allowSelfCompletebooleanNoLet assignees mark it complete themselves
isActivebooleanNo

delete_training_course

Permanently delete a training course AND every assignment of it, including completion records. Administrators and executives only. To retire a course but keep its history, use update_training_course with isActive false.

Destructive · Risk: high

ParameterTypeRequiredDescription
courseIdstringYesResource ID

bulk_assign_training

Assign a training course to many people at once: a list of userIds, or every active member of a department (departmentId, which takes precedence). Administrators and executives only. Inactive or unknown people are dropped and people who already have the course are skipped; the result reports how many were assigned and skipped.

Write · Risk: medium

ParameterTypeRequiredDescription
courseIdstringYesResource ID
userIdsstringNo
departmentIdstringNoAssign to every active member of this department
dueDatestringNoDate in YYYY-MM-DD format
notesstringNo

query_training_categories

List training categories with their course counts.

Read-only

No parameters.

create_training_category

Create a training category. Administrators and executives only. Names are unique (409 on a duplicate).

Write

ParameterTypeRequiredDescription
namestringYes

update_training_category

Rename a training category. Administrators and executives only.

Write

ParameterTypeRequiredDescription
categoryIdstringYesResource ID
namestringYes

delete_training_category

Delete a training category. Its courses are kept and become uncategorised. Administrators and executives only.

Destructive · Risk: medium

ParameterTypeRequiredDescription
categoryIdstringYesResource ID

Benefits

8 tools.

query_benefit_plans

List the organization's active benefit plans (medical, dental, vision, life, disability, retirement, reimbursement, other) with contributions and enrollment counts.

Read-only

No parameters.

create_benefit_plan

Create a benefit plan. Administrators and executives only. Plan names are unique (409 on a duplicate); contributions cannot be negative.

Write · Risk: medium

ParameterTypeRequiredDescription
namestringYes
categoryenum: MEDICAL, DENTAL, VISION, LIFE, DISABILITY, RETIREMENT, REIMBURSEMENT, OTHERYesPlan category
descriptionstringNo
providerstringNoInsurer or provider name
policyNumberstringNo
employeeContributionnumber or nullNoEmployee contribution per period
employerContributionnumber or nullNoEmployer contribution per period
contributionTypeenum: FIXED, PERCENTAGENoWhether contributions are fixed amounts or percentages
currencystringNoISO currency code (default USD)

update_benefit_plan

Update a benefit plan. Administrators and executives only. Only the fields you pass change. Set isActive false to retire a plan without deleting its enrollments.

Write · Risk: medium

ParameterTypeRequiredDescription
planIdstringYesResource ID
namestringNo
categoryenum: MEDICAL, DENTAL, VISION, LIFE, DISABILITY, RETIREMENT, REIMBURSEMENT, OTHERNoPlan category
descriptionstringNo
providerstringNoInsurer or provider name
policyNumberstringNo
employeeContributionnumber or nullNoEmployee contribution per period
employerContributionnumber or nullNoEmployer contribution per period
contributionTypeenum: FIXED, PERCENTAGENoWhether contributions are fixed amounts or percentages
currencystringNoISO currency code (default USD)
isActivebooleanNo

delete_benefit_plan

Permanently delete a benefit plan AND every enrollment in it. Administrators and executives only. To retire a plan but keep enrollment history, use update_benefit_plan with isActive false.

Destructive · Risk: high

ParameterTypeRequiredDescription
planIdstringYesResource ID

query_user_benefits

List a person's benefit enrollments with plan name, category, provider, status, enrollment and termination dates, and employee/employer amounts. Administrators and executives may read anyone, department heads their own departments, employees only their own.

Read-only

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID

enroll_user_in_benefit

Enroll a person in a benefit plan. Administrators and executives only. The person must be active (404 otherwise); refused with 409 if they are already enrolled in that plan.

Write · Risk: medium

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
planIdstringYesBenefit plan ID
statusenum: ELIGIBLE, ENROLLED, WAIVED, TERMINATEDNoDefault ENROLLED
enrollmentDatestringNoDate in YYYY-MM-DD format
employeeAmountnumberNo
employerAmountnumberNo

update_user_benefit_enrollment

Update a benefit enrollment: status, enrollment or termination date, and employee/employer amounts. Administrators and executives only. Only the fields you pass change.

Write · Risk: medium

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
enrollmentIdstringYesResource ID
statusenum: ELIGIBLE, ENROLLED, WAIVED, TERMINATEDNoEnrollment status
enrollmentDatestringNoDate in YYYY-MM-DD format
terminationDatestringNoDate in YYYY-MM-DD format
employeeAmountnumber or nullNo
employerAmountnumber or nullNo

unenroll_user_from_benefit

Permanently delete a benefit enrollment record. Administrators and executives only. To keep the history, set status TERMINATED with a terminationDate via update_user_benefit_enrollment instead.

Destructive · Risk: high

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID
enrollmentIdstringYesResource ID

Documents

21 tools.

query_documents

List documents. EMPLOYEE sees their own folder, DEPARTMENT_HEAD their department scope, ADMINISTRATOR/EXECUTIVE the whole organization. Filter by category, signature status, the person whose folder it is (userId), or a search over title, description and file name.

Read-only

ParameterTypeRequiredDescription
categoryenum: CONTRACT, OFFER_LETTER, SALARY_INCREMENT, PERFORMANCE_REVIEW, POLICY_DOCUMENT, ID_DOCUMENT, CERTIFICATE, TRAINING_MATERIAL, MEDICAL_CERTIFICATE, VISA_DOCUMENT, TAX_DOCUMENT, INSURANCE, TIMESHEET, OTHERNo
statusenum: NOT_REQUIRED, PENDING, SIGNED, DECLINED, EXPIREDNoSignature status
userIdstringNoWhose folder (the document's owner)
searchstringNoMatches title, description or file name
pageintegerNoPage number (1-indexed) (default: 1)
limitintegerNoPage size (max 100) (default: 25)

delete_document

Permanently delete a document, its file and all its signing assignments (not reversible). ADMINISTRATOR/EXECUTIVE may delete any; a DEPARTMENT_HEAD only documents they sent to people in their department scope (never one HR or an administrator sent to their department); anyone, including a head, may delete a document they uploaded that has no signing assignments. Anything else is 403.

Destructive · Risk: high

ParameterTypeRequiredDescription
documentIdstringYesResource ID

get_document_audit_trail

Get the audit trail for a document — views, downloads, signature events and so on, newest first. ADMINISTRATOR or EXECUTIVE for any document; a DEPARTMENT_HEAD only for a document they sent, their own, or one sent to them (never one HR sent to someone in their department); employees get 403.

Read-only

ParameterTypeRequiredDescription
documentIdstringYesResource ID
pageintegerNo(default: 1)
limitintegerNoPage size (max 200) (default: 50)

query_expiring_documents

List documents whose expiry date or signature deadline (for unsigned documents) falls within the next N days, soonest first, with days remaining and an urgency level. Visibility follows the caller: own documents for an employee; for a department head their own documents plus the ones they sent to people in their department scope (not what HR sent there); whole organization for administrators and executives. Documents the caller is still waiting to sign in a signing order are left out.

Read-only

ParameterTypeRequiredDescription
daysintegerNoWindow in days (1-365, default 60) (default: 60)

remind_document_signers

Send a reminder notification to every signer of a document who has not signed yet (status PENDING or VIEWED). ADMINISTRATOR/EXECUTIVE for any document; a DEPARTMENT_HEAD only for documents owned by people in their department scope.

Write · Risk: medium

ParameterTypeRequiredDescription
documentIdstringYesResource ID

query_document_assignments

List document signing assignments. view "my" (default) lists the assignments sent TO the caller (WAITING ones — not yet their turn in a signing order — are hidden unless asked for by status). view "all" lists every assignment in the organization for ADMINISTRATOR/EXECUTIVE, or the ones the caller sent for a DEPARTMENT_HEAD; for anyone else it falls back to "my".

Read-only

ParameterTypeRequiredDescription
viewenum: my, allNo(default: "my")
statusenum: WAITING, PENDING, VIEWED, SIGNED, DECLINED, EXPIREDNo
pageintegerNoPage number (1-indexed) (default: 1)
limitintegerNoPage size (max 100) (default: 25)

get_assignment_stats

Get counts of the caller's own document assignments (pending, overdue, declined and so on). Not organization-wide.

Read-only

No parameters.

assign_document

Send an existing document to up to 50 active people for signature. ADMINISTRATOR/EXECUTIVE may pick anyone in the organization and assign any document; a DEPARTMENT_HEAD only people in their department scope, only a document they sent, their own or one sent to them, and never to themselves (403). People who already have a pending assignment for the document are skipped. Refused when a person is inactive or out of scope, or the plan document quota would be exceeded. For one template sent to many people, use create_bulk_send.

Write · Risk: medium

ParameterTypeRequiredDescription
documentIdstringYesResource ID
userIdsstringYesUser IDs to assign (max 50)
titlestringYesTitle the signers see
messagestringNoMessage to the signers
dueDatestringNoDue date (YYYY-MM-DD)
priorityenum: LOW, NORMAL, HIGH, URGENTNoDefault NORMAL

decline_document_assignment

Decline a signing assignment that was sent to the caller. Only the assignee can decline; a signed or already declined assignment is refused.

Write · Risk: medium

ParameterTypeRequiredDescription
assignmentIdstringYesResource ID
reasonstringNo

query_document_templates

List the current version of each document template. ADMINISTRATOR/EXECUTIVE see all; a DEPARTMENT_HEAD only templates pinned to a department in their scope; employees are refused. Archived templates are listed only when archived is true.

Read-only

ParameterTypeRequiredDescription
categoryenum: CONTRACT, OFFER_LETTER, SALARY_INCREMENT, PERFORMANCE_REVIEW, POLICY_DOCUMENT, ID_DOCUMENT, CERTIFICATE, TRAINING_MATERIAL, MEDICAL_CERTIFICATE, VISA_DOCUMENT, TAX_DOCUMENT, INSURANCE, TIMESHEET, OTHERNo
searchstringNoMatches name or description
archivedbooleanNoList archived templates instead of live ones (default: false)
pageintegerNoPage number (1-indexed) (default: 1)
limitintegerNoPage size (max 100) (default: 25)

get_document_template_versions

Version history of a document template (newest first, from any version id), with how many documents were sent from each version. ADMINISTRATOR, EXECUTIVE or a DEPARTMENT_HEAD who can see the template.

Read-only

ParameterTypeRequiredDescription
templateIdstringYesResource ID

update_document_template

Rename or edit the details of the current version of a document template. Only the fields you provide are changed. The name must stay unique among live templates (case-insensitive). Old versions cannot be edited (404). To amend the PDF itself, a new version must be uploaded in the app.

Write · Risk: medium

ParameterTypeRequiredDescription
templateIdstringYesResource ID
namestringNo
descriptionstring or nullNo
categoryenum: CONTRACT, OFFER_LETTER, SALARY_INCREMENT, PERFORMANCE_REVIEW, POLICY_DOCUMENT, ID_DOCUMENT, CERTIFICATE, TRAINING_MATERIAL, MEDICAL_CERTIFICATE, VISA_DOCUMENT, TAX_DOCUMENT, INSURANCE, TIMESHEET, OTHERNo
defaultDueInDaysinteger or nullNoDefault days until due when sent

archive_document_template

Archive a document template so it can no longer be sent; documents already sent are kept. Reversible with restore_document_template. ADMINISTRATOR, EXECUTIVE, or a DEPARTMENT_HEAD for a template in their scope (their "delete").

Write · Risk: medium

ParameterTypeRequiredDescription
templateIdstringYesResource ID

restore_document_template

Restore an archived document template so it can be sent again. ADMINISTRATOR or EXECUTIVE only. Refused with 409 when another live template already uses the same name.

Write · Risk: medium

ParameterTypeRequiredDescription
templateIdstringYesResource ID

delete_document_template

Permanently delete a document template and its WHOLE version chain (every earlier version too). Documents already sent from it are kept. ADMINISTRATOR or EXECUTIVE only — department heads must use archive_document_template.

Destructive · Risk: high

ParameterTypeRequiredDescription
templateIdstringYesResource ID

send_document_from_template

Create a document from a template and send it for signature. Each signer mapping pairs a template signer role (roleIndex, from the template fields) with an active person. ADMINISTRATOR/EXECUTIVE may pick anyone; a DEPARTMENT_HEAD only people in their department scope. Refused with 409 TEMPLATE_NOT_CURRENT for an archived or replaced template version, and when the plan document quota would be exceeded.

Write · Risk: medium

ParameterTypeRequiredDescription
templateIdstringYesResource ID
signerMappingsobjectYes
signerMappings[].roleIndexintegerYesSigner role index on the template
signerMappings[].userIdstringYesPerson who signs that role
titlestringNoDocument title (defaults to the template name)
messagestringNo
dueDatestringNoDue date (YYYY-MM-DD); defaults from the template

query_bulk_send_jobs

List bulk send jobs (one template sent to many recipients) with their progress. ADMINISTRATOR or EXECUTIVE only.

Read-only

ParameterTypeRequiredDescription
pageintegerNoPage number (1-indexed) (default: 1)
limitintegerNoPage size (max 100) (default: 25)

create_bulk_send

Start a bulk send: one template sent to up to 500 recipients, each matched by email to an active person in the organization (rows without a match are reported as failures in the job, not sent). Runs in the background — check progress with query_bulk_send_jobs. ADMINISTRATOR or EXECUTIVE only. Refused with 409 TEMPLATE_NOT_CURRENT for an archived or replaced template, and when the plan document quota would be exceeded.

Write · Risk: medium

ParameterTypeRequiredDescription
templateIdstringYesResource ID
recipientsobjectYesRecipients (max 500); extra string columns may be mapped to template fields
recipients[].emailstringYes
recipients[].namestringYes
namestringNoJob name (defaults to "Bulk send - <template>")
columnMappingobject (map)NoMaps recipient columns to template fields

query_document_webhooks

List webhooks subscribed to document signing events (secrets are masked). ADMINISTRATOR or EXECUTIVE only.

Read-only

No parameters.

create_document_webhook

Create a webhook that receives document signing events at a public HTTPS URL (max 10 per organization). The server generates the signing secret and returns it in full only in this response — tell the user to store it now. ADMINISTRATOR or EXECUTIVE only.

Write · Risk: medium

ParameterTypeRequiredDescription
urlstringYesPublic HTTPS URL
eventsarray of enum: document.created, document.signed, document.completed, document.declined, document.expired, document.viewed, document.reminder_sentYesEvent types to subscribe to

delete_document_webhook

Delete a document webhook. ADMINISTRATOR or EXECUTIVE only.

Destructive · Risk: medium

ParameterTypeRequiredDescription
webhookIdstringYesResource ID

Admin

94 tools.

get_org_settings

Get the org-wide general settings: name, timezone, business days, leave year start month, default annual and sick allowances, week start day, privacy toggles (calendarViewRestricted, departmentViewRestricted), carry-forward rules and probation reminders.

Read-only

No parameters.

update_org_settings

Update org-wide general settings. ADMINISTRATOR or EXECUTIVE only. Only the fields you pass change. Removing a business day deletes auto-generated scheduled shifts on that weekday from the current week onward. Currency, country and date/time formats are not settable here.

Write · Risk: high

ParameterTypeRequiredDescription
namestringNo
timezonestringNoIANA timezone, e.g. America/Toronto
businessDaysarray of enum: mon, tue, wed, thu, fri, sat, sunNo
leaveYearStartMonthintegerNo
defaultLeaveAllowancenumberNo
defaultSickLeaveAllowancenumberNo
weekStartDayintegerNo0 = Sunday ... 6 = Saturday
calendarViewRestrictedbooleanNo
departmentViewRestrictedbooleanNoWhen true, non-admins only see people in their own department
carryForwardDaysnumberNo
carryForwardHoursnumberNo
carryForwardEligibilityYearsintegerNo
carryForwardExpiresbooleanNo
carryForwardExpiryMonthsinteger or nullNo
dashboardBalanceDisplayenum: ANNUAL, SICK, BOTHNo
calendarBalanceDisplayenum: ANNUAL, SICK, BOTHNo
probationRemindersEnabledbooleanNo
probationReminderRecipientsobjectNoAll four flags are required when this is set
probationReminderRecipients.departmentHeadbooleanYes
probationReminderRecipients.managerbooleanYes
probationReminderRecipients.executivebooleanYes
probationReminderRecipients.administratorbooleanYes

get_branding

Get the org branding settings (brand name, light/dark logos, favicons, custom CSS).

Read-only

No parameters.

update_branding

Update org branding. EXECUTIVE only, and requires the white-label branding add-on (refused with 403 otherwise). Only the fields you pass change; pass null to clear a logo or favicon URL.

Write · Risk: medium

ParameterTypeRequiredDescription
brandNamestringNo
logoLightUrlstring or nullNo
logoDarkUrlstring or nullNo
faviconUrlstring or nullNo
faviconDarkUrlstring or nullNo
customCSSstring or nullNo

get_email_settings

Get the org SMTP settings (host, port, user, from name/address, TLS flags). ADMINISTRATOR or EXECUTIVE only. The password is never returned.

Read-only

No parameters.

update_email_settings

Update the org custom SMTP settings. ADMINISTRATOR or EXECUTIVE only. BookYourPTO replaces the whole configuration, so this tool reads the current settings and merges your changes before saving; fields you omit keep their current values. The host must be a public mail server. smtpPassword is required when the host changes; omit it to keep the stored one.

Write · Risk: high

ParameterTypeRequiredDescription
smtpHoststringNo
smtpPortintegerNo
smtpUserstringNo
smtpPasswordstringNo
emailFromNamestringNo
emailFromAddressstringNo
useSSLbooleanNo
useSTARTTLSbooleanNo
rejectUnauthorizedbooleanNo

send_test_email

Send a test email to the signed-in user through an SMTP configuration, without saving it. ADMINISTRATOR or EXECUTIVE only. Fields you omit are taken from the saved settings; the stored password is only used when the host is unchanged.

Write

ParameterTypeRequiredDescription
smtpHoststringNo
smtpPortintegerNo
smtpUserstringNo
smtpPasswordstringNo
emailFromNamestringNo
emailFromAddressstringNo
useSSLbooleanNo
useSTARTTLSbooleanNo
rejectUnauthorizedbooleanNo

delete_email_settings

Remove the org custom SMTP configuration so email goes through the platform mail server. ADMINISTRATOR or EXECUTIVE only.

Destructive · Risk: high

No parameters.

get_notification_defaults

Get the org-wide notification defaults (digests, product updates, digest scope) and the maximum digest scope employees may choose. ADMINISTRATOR or EXECUTIVE only.

Read-only

No parameters.

update_notification_defaults

Update the org-wide notification defaults that apply to anyone who has not set their own. ADMINISTRATOR or EXECUTIVE only. BookYourPTO stores the whole object, so this tool reads the current defaults and merges your changes; fields you omit keep their values. Set reset=true to return to the system defaults.

Write · Risk: medium

ParameterTypeRequiredDescription
productUpdatesbooleanNo
dailyDigestobjectNoDaily digest email. hourOfDay is 0-23 in the recipient timezone.
dailyDigest.enabledbooleanNo
dailyDigest.hourOfDayintegerNo
weeklyDigestobjectNoWeekly digest email. dayOfWeek is 0 (Sunday) to 6 (Saturday).
weeklyDigest.enabledbooleanNo
weeklyDigest.hourOfDayintegerNo
weeklyDigest.dayOfWeekintegerNo
publicHolidaysOnDigestbooleanNo
digestScopeenum: self, department, managed, organizationNo
documentsobjectNo
documents.uploadedbooleanNo
documents.expiringbooleanNo
birthdayGreetingbooleanNo
requestAlertsenum: all, routedNo
maxDigestScopeenum: organization, department, selfNoWidest digest scope a non-admin may choose
resetbooleanNoDiscard all customisation and use the system defaults

get_personal_notifications

Get the signed-in user notification preferences (digests, digest scope, alerts) and the widest digest scope they may choose.

Read-only

No parameters.

update_personal_notifications

Update the signed-in user notification preferences. Any role. BookYourPTO stores the whole object, so this tool reads the current preferences and merges your changes. A digestScope wider than the org allows (or "managed" with no direct reports) is refused with 403. Set reset=true to fall back to the org defaults.

Write

ParameterTypeRequiredDescription
productUpdatesbooleanNo
dailyDigestobjectNoDaily digest email. hourOfDay is 0-23 in the recipient timezone.
dailyDigest.enabledbooleanNo
dailyDigest.hourOfDayintegerNo
weeklyDigestobjectNoWeekly digest email. dayOfWeek is 0 (Sunday) to 6 (Saturday).
weeklyDigest.enabledbooleanNo
weeklyDigest.hourOfDayintegerNo
weeklyDigest.dayOfWeekintegerNo
publicHolidaysOnDigestbooleanNo
digestScopeenum: self, department, managed, organizationNo
documentsobjectNo
documents.uploadedbooleanNo
documents.expiringbooleanNo
birthdayGreetingbooleanNo
requestAlertsenum: all, routedNo
resetbooleanNoDiscard personal preferences and use the org defaults

get_sso_settings

Get the org SSO (Auth0) configuration. The client secret is never returned, only whether one is set.

Read-only

No parameters.

update_sso_settings

Update SSO (Auth0) settings. EXECUTIVE only, and requires a plan with SSO. Only the fields you pass change. Misconfiguration can lock people out. Auto-created users can start only as EMPLOYEE or DEPARTMENT_HEAD. Public email domains (gmail.com etc.) are refused in allowedDomains, which replaces the whole list when passed.

Write · Risk: high

ParameterTypeRequiredDescription
enabledbooleanNo
auth0Domainstring or nullNo
auth0ClientIdstring or nullNo
auth0ClientSecretstring or nullNoPass null to clear the stored secret
enableGooglebooleanNo
enableMicrosoftbooleanNo
enableGitHubbooleanNo
enableSAMLbooleanNo
allowLocalLoginbooleanNo
enforceSSObooleanNo
autoCreateUsersbooleanNo
defaultRoleenum: EMPLOYEE, DEPARTMENT_HEADNo
defaultDepartmentIdstring or nullNo
allowedDomainsstringNo

query_sso_domains

List SSO domains for the org with their DNS verification status and the TXT record to publish. ADMINISTRATOR or EXECUTIVE only.

Read-only

No parameters.

add_sso_domain

Add a domain to the SSO allow-list; returns the DNS TXT record to publish before verifying. ADMINISTRATOR or EXECUTIVE only. Public email domains and domains verified by another org are refused.

Write · Risk: high

ParameterTypeRequiredDescription
domainstringYes

verify_sso_domain

Check DNS for the verification TXT record of an SSO domain. ADMINISTRATOR or EXECUTIVE only.

Write · Risk: medium

ParameterTypeRequiredDescription
domainIdstringYesResource ID

delete_sso_domain

Remove a domain from the SSO allow-list. ADMINISTRATOR or EXECUTIVE only.

Destructive · Risk: high

ParameterTypeRequiredDescription
domainIdstringYesResource ID

get_slack_integration

Get the org Slack integration: webhookUrl and enabledNotificationTypes. ADMINISTRATOR or EXECUTIVE only.

Read-only

No parameters.

update_slack_integration

Update the org Slack integration. ADMINISTRATOR or EXECUTIVE only. The webhook URL must start with https://hooks.slack.com/. Fields you omit keep their current values, including the webhook URL when you change only the notification types. Pass webhookUrl: null to disconnect. enabledNotificationTypes replaces the whole list of events posted to the channel.

Write · Risk: medium

ParameterTypeRequiredDescription
webhookUrlstring or nullNonull disconnects the integration
enabledNotificationTypesarray of enum: LEAVE_SUBMITTED, LEAVE_APPROVED, LEAVE_REJECTED, LEAVE_CANCELLED, EXPENSE_SUBMITTED, EXPENSE_APPROVED, EXPENSE_REJECTED, EXPENSE_PAID, TIME_ENTRY_APPROVED, TIME_ENTRY_REJECTED, DOCUMENT_UPLOADED, DOCUMENT_SIGNED, APPROVAL_REQUIRED, SYSTEM_ANNOUNCEMENTNo

test_slack_integration

Post a test message to a Slack webhook. ADMINISTRATOR or EXECUTIVE only. Uses the saved org webhook unless webhookUrl is given. Fails with 400 when the message cannot be delivered.

Write

ParameterTypeRequiredDescription
webhookUrlstringNo

get_teams_integration

Get the org Microsoft Teams integration: webhookUrl and enabledNotificationTypes. ADMINISTRATOR or EXECUTIVE only.

Read-only

No parameters.

update_teams_integration

Update the org Microsoft Teams integration. ADMINISTRATOR or EXECUTIVE only. The webhook URL must be a Teams incoming webhook or Power Automate workflow URL. Fields you omit keep their current values, including the webhook URL when you change only the notification types. Pass webhookUrl: null to disconnect. enabledNotificationTypes replaces the whole list of events posted to the channel.

Write · Risk: medium

ParameterTypeRequiredDescription
webhookUrlstring or nullNonull disconnects the integration
enabledNotificationTypesarray of enum: LEAVE_SUBMITTED, LEAVE_APPROVED, LEAVE_REJECTED, LEAVE_CANCELLED, EXPENSE_SUBMITTED, EXPENSE_APPROVED, EXPENSE_REJECTED, EXPENSE_PAID, TIME_ENTRY_APPROVED, TIME_ENTRY_REJECTED, DOCUMENT_UPLOADED, DOCUMENT_SIGNED, APPROVAL_REQUIRED, SYSTEM_ANNOUNCEMENTNo

test_teams_integration

Post a test message to a Microsoft Teams webhook. ADMINISTRATOR or EXECUTIVE only. Uses the saved org webhook unless webhookUrl is given. Fails with 400 when the message cannot be delivered.

Write

ParameterTypeRequiredDescription
webhookUrlstringNo

get_personal_integrations

Get the signed-in user personal Slack and Teams webhook URLs (where their own notifications are posted). Any role.

Read-only

No parameters.

update_personal_integrations

Set or clear the signed-in user personal Slack and Teams webhook URLs. Any role. BookYourPTO clears any URL it is not sent, so this tool reads the current values first; a field you omit keeps its value and null clears it.

Write

ParameterTypeRequiredDescription
slackWebhookUrlstring or nullNoMust start with https://hooks.slack.com/; null clears
teamsWebhookUrlstring or nullNoTeams webhook or Power Automate URL; null clears

query_audit_logs

Query the org-wide audit log, newest first. ADMINISTRATOR or EXECUTIVE only, and requires a plan with audit logs. Filter by action, entity type, acting user or date range (dates are inclusive calendar days). Use this for "who changed X?" / "what happened on Y?" investigations.

Read-only

ParameterTypeRequiredDescription
actionstringNoe.g. CREATE, UPDATE, DELETE, SETTINGS_CHANGE, EXPORT, LOGIN
entityTypestringNoe.g. USER, ORGANIZATION, LEAVE, EXPENSE_REPORT, DOCUMENT
userIdstringNoThe user who performed the action
startDatestringNoDate in YYYY-MM-DD format
endDatestringNoDate in YYYY-MM-DD format
pageintegerNoPage number (1-indexed) (default: 1)
limitintegerNoPage size (max 100) (default: 25)

export_audit_logs

Export the audit log for a date range (inclusive). ADMINISTRATOR or EXECUTIVE only. Returns the entries inline as JSON (default, at most 500 shown) or the CSV text. The export only filters by date; use query_audit_logs to filter by action, entity or user.

Read-only

ParameterTypeRequiredDescription
startDatestringNoDate in YYYY-MM-DD format
endDatestringNoDate in YYYY-MM-DD format
formatenum: json, csvNo(default: "json")

query_signin_logs

Query sign-in attempts, newest first. ADMINISTRATOR or EXECUTIVE only. Filter by user, email (substring), IP (substring), success, or date range (inclusive). Useful for security investigations.

Read-only

ParameterTypeRequiredDescription
userIdstringNo
emailstringNoCase-insensitive substring of the email used
ipAddressstringNoSubstring of the client IP
successbooleanNoFilter by successful or failed sign-ins
startDatestringNoDate in YYYY-MM-DD format
endDatestringNoDate in YYYY-MM-DD format
pageintegerNoPage number (1-indexed) (default: 1)
limitintegerNoPage size (max 100) (default: 25)

export_signin_logs

Export sign-in logs for a date range (inclusive). ADMINISTRATOR or EXECUTIVE only. Returns the entries inline as JSON (default, at most 500 shown) or the CSV text.

Read-only

ParameterTypeRequiredDescription
startDatestringNoDate in YYYY-MM-DD format
endDatestringNoDate in YYYY-MM-DD format
formatenum: json, csvNo(default: "json")

query_leave_transactions

Query the history of leave requests across the org (who requested what, status, approver), newest first. ADMINISTRATOR or EXECUTIVE only. The date range filters on when the request was submitted (inclusive). This is the request log, not a balance ledger.

Read-only

ParameterTypeRequiredDescription
userIdstringNo
statusenum: PENDING, APPROVED, REJECTED, CANCELLED, WITHDRAWNNo
leaveTypeIdstringNo
startDatestringNoDate in YYYY-MM-DD format
endDatestringNoDate in YYYY-MM-DD format
pageintegerNoPage number (1-indexed) (default: 1)
limitintegerNoPage size (max 100) (default: 25)

query_time_tracking_transactions

Query time entries across the org with their source and approval status, newest first. ADMINISTRATOR or EXECUTIVE only. The date range filters on clock-in day (inclusive).

Read-only

ParameterTypeRequiredDescription
userNamestringNoCase-insensitive substring of the first or last name
sourceenum: MANUAL, CLOCK, IMPORT, APINo
approvalStatusenum: PENDING, APPROVED, REJECTEDNo
startDatestringNoDate in YYYY-MM-DD format
endDatestringNoDate in YYYY-MM-DD format
pageintegerNoPage number (1-indexed) (default: 1)
limitintegerNoPage size (max 100) (default: 25)

query_security_violations

List recorded security violations (for example forced sign-outs after an invalid token), newest first. ADMINISTRATOR or EXECUTIVE only. Filter by whether they have been reviewed.

Read-only

ParameterTypeRequiredDescription
reviewedbooleanNo
limitintegerNo(default: 50)
offsetintegerNo(default: 0)

update_security_violation

Mark a security violation as reviewed (or not) and attach review notes. ADMINISTRATOR or EXECUTIVE only. Records the caller as the reviewer.

Write · Risk: medium

ParameterTypeRequiredDescription
violationIdstringYesResource ID
reviewedbooleanNo
notesstringNo

query_phi_access_log

Query the PHI (protected health information) access log, newest first. ADMINISTRATOR or EXECUTIVE only. Filter by the person whose record was accessed (userId) or by resource type. No date filter is available.

Read-only

ParameterTypeRequiredDescription
userIdstringNoThe person whose health record was accessed (not the accessor)
resourceTypestringNo
pageintegerNoPage number (1-indexed) (default: 1)
limitintegerNoPage size (max 100) (default: 25)

get_subscription

Get the current subscription status (plan, seats, billing period, trial info, pending cancellation).

Read-only

No parameters.

change_plan

Switch the active paid subscription to another plan or billing interval (Stripe prorates the change). ADMINISTRATOR or EXECUTIVE only. Only pro and business can be chosen here; Enterprise is arranged by sales. Requires an existing subscription; use create_checkout_session to start one.

Destructive · Risk: high

ParameterTypeRequiredDescription
planenum: pro, businessYes
intervalenum: monthly, yearlyYes
currencyenum: USD, CADYes

cancel_subscription

Cancel the subscription. ADMINISTRATOR or EXECUTIVE only. By default it cancels at the end of the current billing period (reversible with reactivate_subscription until then). immediately=true ends it now with no refund and cannot be reactivated.

Destructive · Risk: high

ParameterTypeRequiredDescription
immediatelybooleanNoEnd the subscription now instead of at period end (default: false)

reactivate_subscription

Undo a pending cancel-at-period-end before the period ends. ADMINISTRATOR or EXECUTIVE only.

Destructive · Risk: high

No parameters.

sync_subscription

Re-read the subscription state from Stripe into the org (recovery after a missed webhook). ADMINISTRATOR or EXECUTIVE only.

Write · Risk: medium

No parameters.

get_usage

Get current resource usage (users, documents, receipts, projects, expense claims) against plan limits.

Read-only

No parameters.

get_usage_breakdown

Get usage attribution per user (who uploaded what, who signed what, etc.). ADMINISTRATOR or EXECUTIVE only.

Read-only

No parameters.

query_invoices

List the org invoices, newest first. ADMINISTRATOR or EXECUTIVE only.

Read-only

ParameterTypeRequiredDescription
pageintegerNoPage number (1-indexed) (default: 1)
limitintegerNoPage size (max 100) (default: 25)

get_invoice_line_items

Get line items for a specific invoice. ADMINISTRATOR or EXECUTIVE only.

Read-only

ParameterTypeRequiredDescription
invoiceIdstringYesResource ID

request_refund

Submit a refund request for review by the BookYourPTO team; nothing is refunded automatically. ADMINISTRATOR or EXECUTIVE only. invoiceId must be a PAID invoice of this org. amount is in cents; omit it for a full refund. Refused while another request from the org is still pending.

Write · Risk: medium

ParameterTypeRequiredDescription
invoiceIdstringNo
amountintegerNoAmount in cents; omit for a full refund
reasonstringYes

query_refund_requests

List the org refund requests with their status, newest first. ADMINISTRATOR or EXECUTIVE only.

Read-only

ParameterTypeRequiredDescription
statusenum: PENDING, APPROVED, DENIED, PROCESSEDNo
pageintegerNoPage number (1-indexed) (default: 1)
limitintegerNoPage size (max 100) (default: 25)

get_billing_alerts

Get active billing alerts (trial ending, payment failed, near a plan limit). Returns an empty list for roles below ADMINISTRATOR.

Read-only

No parameters.

query_addons

List add-ons (currently white-label branding) and whether the org has them, including any end date after removal.

Read-only

No parameters.

toggle_addon

Add or remove an add-on on the active subscription. ADMINISTRATOR or EXECUTIVE only. Adding charges immediately; during a trial it is refused with 409 unless skipTrial=true, which ends the trial and starts paid billing now. Removing keeps the feature until the end of the paid period, with no refund.

Destructive · Risk: high

ParameterTypeRequiredDescription
addOnenum: whiteLabelBrandingYes
actionenum: add, removeYes
skipTrialbooleanNoRequired to add during a trial; ends the trial

create_checkout_session

Create a Stripe Checkout link for starting a paid subscription. ADMINISTRATOR or EXECUTIVE only. The plan is a single line item, so there is no seat count. A trial may apply if the org has not trialled before. Returns a URL the user must open to pay.

Write · Risk: medium

ParameterTypeRequiredDescription
planenum: pro, businessYes
intervalenum: monthly, yearlyNo(default: "monthly")
currencyenum: USD, CADNoDefaults to CAD on the server
couponCodestringNo
addOnsarray of enum: whiteLabelBrandingNo

create_billing_portal_session

Create a Stripe customer portal link for self-service billing (payment method, invoices). ADMINISTRATOR or EXECUTIVE only.

Write

No parameters.

validate_coupon

Check whether a coupon code is valid and what it gives, without applying it.

Write

ParameterTypeRequiredDescription
codestringYes

get_quickbooks_status

Check whether QuickBooks Online is connected for the org. ADMINISTRATOR or EXECUTIVE only.

Read-only

No parameters.

connect_quickbooks

Get the QuickBooks Online authorization URL (authUrl) to start the connection; the user must open it in a browser. ADMINISTRATOR or EXECUTIVE only. Requires a plan with the QuickBooks integration.

Read-only

No parameters.

disconnect_quickbooks

Disconnect QuickBooks Online and stop all syncing. ADMINISTRATOR or EXECUTIVE only.

Destructive · Risk: high

No parameters.

get_quickbooks_settings

Get the QuickBooks sync settings (what syncs, auto-sync, default expense and payment accounts). ADMINISTRATOR or EXECUTIVE only.

Read-only

No parameters.

update_quickbooks_settings

Update QuickBooks sync settings. ADMINISTRATOR or EXECUTIVE only. Only the fields you pass change; an empty string clears an account. Refused with 404 when QuickBooks is not connected. Account ids come from query_quickbooks_accounts.

Write · Risk: medium

ParameterTypeRequiredDescription
syncExpensesbooleanNo
syncTimeEntriesbooleanNo
syncEmployeesbooleanNo
autoSyncbooleanNo
defaultExpenseAccountIdstringNo
defaultExpenseAccountNamestringNo
paymentAccountIdstringNoBank / credit card account bills are paid from
paymentAccountNamestringNo

query_quickbooks_accounts

List the QuickBooks chart of accounts (qboAccounts), bank accounts, and the local expense categories that can be mapped to them. ADMINISTRATOR or EXECUTIVE only.

Read-only

No parameters.

get_qb_account_mappings

Get the expense category to QuickBooks account mappings. ADMINISTRATOR or EXECUTIVE only.

Read-only

No parameters.

update_qb_account_mappings

Save expense category to QuickBooks account mappings. ADMINISTRATOR or EXECUTIVE only. Each entry needs the local category name and the QuickBooks account id and name (from query_quickbooks_accounts).

Write · Risk: medium

ParameterTypeRequiredDescription
mappingsobjectYes
mappings[].localCategorystringYes
mappings[].qboAccountIdstringYes
mappings[].qboAccountNamestringYes

query_quickbooks_customers

List QuickBooks customers (qboCustomers) alongside local clients and projects. ADMINISTRATOR or EXECUTIVE only.

Read-only

No parameters.

sync_qb_customers

Push local clients and/or projects to QuickBooks as customers. ADMINISTRATOR or EXECUTIVE only. Writes into the customer's QuickBooks company.

Write · Risk: medium

ParameterTypeRequiredDescription
typeenum: clients, projects, bothNo(default: "both")

sync_employees_to_quickbooks

Sync employees between BookYourPTO and QuickBooks: "push" sends linked people to QuickBooks, "pull" brings QuickBooks changes back, "both" (default) does each. createUnmatched=true also creates QuickBooks employees for everyone not yet linked. ADMINISTRATOR or EXECUTIVE only.

Write · Risk: medium

ParameterTypeRequiredDescription
directionenum: push, pull, bothNo(default: "both")
createUnmatchedbooleanNo(default: false)

get_qb_employee_mappings

Get the BookYourPTO user to QuickBooks employee links. ADMINISTRATOR or EXECUTIVE only.

Read-only

No parameters.

sync_expenses_to_quickbooks

Push every approved expense report not yet synced to QuickBooks as bills. ADMINISTRATOR or EXECUTIVE only. There is no date filter; it processes the whole unsynced backlog.

Write · Risk: medium

No parameters.

get_expense_sync_status

How many approved expense reports are synced vs unsynced, plus recent sync logs. ADMINISTRATOR or EXECUTIVE only.

Read-only

No parameters.

sync_time_to_quickbooks

Push every approved time entry not yet synced to QuickBooks as time activities. ADMINISTRATOR or EXECUTIVE only. There is no date filter; it processes the whole unsynced backlog.

Write · Risk: medium

No parameters.

preview_leave_liability

Preview the accrued leave liability that sync_leave_liability would post. ADMINISTRATOR or EXECUTIVE only.

Read-only

No parameters.

sync_leave_liability

Post the leave liability as a journal entry in QuickBooks, debiting the expense account and crediting the liability account. ADMINISTRATOR or EXECUTIVE only. Both account ids are required (from query_quickbooks_accounts).

Destructive · Risk: high

ParameterTypeRequiredDescription
expenseAccountIdstringYes
liabilityAccountIdstringYes

get_quickbooks_payroll_summary

Get the payroll summary per linked employee from QuickBooks. ADMINISTRATOR or EXECUTIVE only. No date filter is available.

Read-only

No parameters.

get_quickbooks_sync_history

List QuickBooks sync log entries, newest first, optionally filtered by entity type, status or direction. ADMINISTRATOR or EXECUTIVE only.

Read-only

ParameterTypeRequiredDescription
entityTypeenum: EMPLOYEE, TIME_ACTIVITY, BILL, VENDOR, DEPARTMENT, JOURNAL_ENTRY, CUSTOMER, ACCOUNTNo
statusenum: SUCCESS, FAILED, SKIPPED, PARTIALNo
directionenum: PUSH, PULL, BIDIRECTIONALNo
pageintegerNoPage number (1-indexed) (default: 1)
limitintegerNoPage size (max 100) (default: 25)

change_password

Change the signed-in user password. Requires the current password. The new password must meet the org password policy, must not appear in known breaches and must differ from the current one. It signs out every other session of this account, which can include the session this assistant uses; you may need to reconnect afterwards.

Destructive · Risk: high

ParameterTypeRequiredDescription
currentPasswordstringYes
newPasswordstringYes

check_password_breach

Check whether a candidate password appears in known data breaches (k-anonymity lookup; the password itself is not sent to the breach service). Returns only { breached }. Passwords shorter than 8 characters, and rate-limited calls, always report breached: false.

Write

ParameterTypeRequiredDescription
passwordstringYes

setup_totp

Begin TOTP two-factor setup for the signed-in user. Returns a QR code data URL, the base32 secret and one-time backup codes; finish with confirm_totp. Refused if 2FA is already on.

Write

No parameters.

confirm_totp

Finish TOTP two-factor setup with the first 6-digit code from the authenticator app. It signs out every other session of this account, which can include the session this assistant uses; you may need to reconnect afterwards.

Write · Risk: medium

ParameterTypeRequiredDescription
codestringYes

disable_totp

Turn off TOTP two-factor for the signed-in user and revoke all their trusted devices. Requires the current password; not available to OAuth-only accounts.

Destructive · Risk: high

ParameterTypeRequiredDescription
passwordstringYes

query_trusted_devices

List devices trusted to skip the 2FA prompt for the signed-in user, marking the current one.

Read-only

No parameters.

revoke_trusted_device

Revoke a single trusted device of the signed-in user.

Destructive · Risk: medium

ParameterTypeRequiredDescription
deviceIdstringYesResource ID

revoke_all_trusted_devices

Revoke all trusted devices of the signed-in user. Every device must pass 2FA again on next sign-in.

Destructive · Risk: high

No parameters.

reset_user_2fa

Reset another user's two-factor: clears their TOTP secret, backup codes and trusted devices. ADMINISTRATOR or EXECUTIVE only; only an EXECUTIVE can reset an executive. Refused if the user has no 2FA.

Destructive · Risk: high

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID

resend_credentials

Send a user a password-reset link (valid 1 hour) and sign them out of every session. ADMINISTRATOR or EXECUTIVE only; only an EXECUTIVE can do this for an executive. Reports whether the email was sent. The reset link itself is never returned (it is a credential for another person, and this conversation is stored); if the email was not sent, send the reset again from the Users page in BookYourPTO.

Destructive · Risk: high

ParameterTypeRequiredDescription
userIdstringYesBookYourPTO user ID

request_data_export

Export all personal data the product holds about the signed-in user, returned inline as JSON. Covers only the caller; there is no way to export another person here. Rate limited.

Write

No parameters.

request_deletion_code

Email the signed-in user a 6-digit code that confirms deleting their own account (request_data_deletion) or, for an executive, the organization. Rate limited to a couple of emails every two minutes.

Write · Risk: medium

No parameters.

request_data_deletion

Permanently anonymize a user's account (right to erasure); audit history is kept. Cannot be undone. Deleting your own account needs the emailed code from request_deletion_code. Deleting someone else needs ADMINISTRATOR or EXECUTIVE (no code); only an EXECUTIVE can delete an executive. Refused for the last active executive or the last administrator.

Destructive · Risk: high

ParameterTypeRequiredDescription
userIdstringNoPerson to delete; omit for yourself
codestringNo6-digit code; required when deleting yourself
confirmDeletionliteral: trueYesMust be true; guards against accidental deletion

opt_out_of_processing

Set whether the signed-in user opts out of sharing their data (the doNotShareData privacy flag). optOut=false opts back in. Logged in the audit trail.

Write

ParameterTypeRequiredDescription
optOutbooleanNo(default: true)

query_domains

List custom domains configured for the org (white-label), with status and branding. ADMINISTRATOR or EXECUTIVE only.

Read-only

No parameters.

get_domain

Get one custom domain: verification and SSL status, DNS records to publish, and its branding.

Read-only

ParameterTypeRequiredDescription
domainIdstringYesResource ID

add_custom_domain

Add a custom domain (e.g. hr.acme.com) with the brand shown on it. ADMINISTRATOR or EXECUTIVE only, and changes require the white-label branding add-on (refused with 403 otherwise). Returns the DNS records to configure before verify_domain.

Write · Risk: high

ParameterTypeRequiredDescription
domainstringYesFully qualified domain, e.g. hr.acme.com
brandNamestringYesName shown on the branded login and app
primaryColorstringNoHex colour; defaults to #3B82F6

update_custom_domain_branding

Update the branding served on a custom domain (logos, colours, login page, footer, support links, email sender, custom CSS) or make it the primary domain. ADMINISTRATOR or EXECUTIVE only, and changes require the white-label branding add-on (refused with 403 otherwise). Only the fields you pass change; null clears a field.

Write · Risk: medium

ParameterTypeRequiredDescription
domainIdstringYesResource ID
brandNamestringNo
taglinestring or nullNo
logoLightUrlstring or nullNo
logoDarkUrlstring or nullNo
logoLoginUrlstring or nullNo
faviconUrlstring or nullNo
faviconDarkUrlstring or nullNo
appleTouchIconstring or nullNo
primaryColorstringNo
primaryHoverstringNo
accentColorstring or nullNo
loginBackgroundstring or nullNo
loginWelcomeTextstring or nullNo
hidePoweredBybooleanNo
footerTextstring or nullNo
privacyPolicyUrlstring or nullNo
termsOfServiceUrlstring or nullNo
supportEmailstring or nullNo
supportUrlstring or nullNo
emailFromNamestring or nullNo
emailFromAddressstring or nullNo
emailLogoUrlstring or nullNo
emailFooterTextstring or nullNo
customCSSstring or nullNo
isPrimarybooleanNoMake this the primary domain (unsets the others)

verify_domain

Check DNS for a custom domain's verification records. ADMINISTRATOR or EXECUTIVE only, and changes require the white-label branding add-on (refused with 403 otherwise).

Write · Risk: medium

ParameterTypeRequiredDescription
domainIdstringYesResource ID

request_domain_ssl

Manage the SSL certificate of a verified custom domain: "provision" requests one (default), "check" reports its status, "refresh" re-issues it. ADMINISTRATOR or EXECUTIVE only, and changes require the white-label branding add-on (refused with 403 otherwise).

Write · Risk: medium

ParameterTypeRequiredDescription
domainIdstringYesResource ID
actionenum: check, provision, refreshNo(default: "provision")

get_domain_dns_provider

Detect the DNS provider of a custom domain (Cloudflare, Route 53, etc.) to tailor DNS instructions.

Read-only

ParameterTypeRequiredDescription
domainIdstringYesResource ID

delete_custom_domain

Remove a custom domain from the org; its branding stops being served there. ADMINISTRATOR or EXECUTIVE only, and changes require the white-label branding add-on (refused with 403 otherwise).

Destructive · Risk: high

ParameterTypeRequiredDescription
domainIdstringYesResource ID

create_support_ticket

Open a ticket with the BookYourPTO support team, filed under the signed-in user. ADMINISTRATOR or EXECUTIVE only (403 for anyone else — ask an administrator to open it); at most 5 per 10 minutes. title is 5-200 characters and every text field below needs at least 10 characters. Required fields by type: blank = description; bug = description, stepsToReproduce, expectedBehavior; feature = problemDescription, desiredSolution; security = summary, vulnerabilityDetails, impact, affectedArea, severity.

Write

ParameterTypeRequiredDescription
typeenum: blank, bug, feature, securityYes
titlestringYes
descriptionstringNo
stepsToReproducestringNo
expectedBehaviorstringNo
desktopInfostringNo
problemDescriptionstringNo
desiredSolutionstringNo
alternativesConsideredstringNo
summarystringNo
vulnerabilityDetailsstringNo
proofOfConceptstringNo
impactstringNo
affectedAreaenum: Web App, API, Authentication, Data, OtherNo
severityenum: Critical, High, Medium, LowNo
cweIdstringNo
additionalContextstringNo

System

1 tool.

get_health

Check the MCP server health: API connectivity, auth status, cache size, and uptime.

Read-only

No parameters.


Auth

1 tool.

This tool is registered only when a self-hosted server runs in per-user mode (no OAuth, no shared credentials). OAuth connections never see it.

login

Exchange BookYourPTO email + password for an access token on this connection. Required only when running in per-user mode (no OAuth, no shared credentials). An organization that requires single sign-on refuses password sign-in here (SSO_REQUIRED); instead, sign in to BookYourPTO with SSO in your browser and connect through OAuth, which authorizes the session you are already signed in to.

Destructive · Risk: high

ParameterTypeRequiredDescription
emailstringYesBookYourPTO account email
passwordstringYesBookYourPTO account password