Time Management Tools

Overview

The Time Management tool category gives you two tools. manage_shift covers everything you'd normally do on the My Shifts and All Shifts pages — clocking in and out, recording a shift for a teammate, fixing times, adjusting a pay rate, finalizing for payroll. get_shift_report is the Reports page in a single call: hours and pay totals per agent over any date range.

In the dashboard this feature is called Shifts, and it sits under a menu group called Team — look for Team → Shifts, with All Shifts, My Shifts, Shift Types and Reports inside it. Only the displayed name changed: the permission is still spelled Time Management, the tool category is still Time Management, and the web addresses still say /dashboard/time-management/….

Shift data is also readable through the Data Access Tools — list_records and get_record accept shifts and shift_types as resource types.

Permissions required:Time Management for manage_shift; the Reports sub-permission for get_shift_report. Seeing or changing anyone else's shifts additionally needs the All Shifts sub-permission — the same split as the dashboard pages.

New login permission. Time management tools sit behind their own copilot:time_management scope — a separate checkbox on the login screen when you connect an MCP client. If you connected before these tools existed, reconnect once to grant it.

Your shifts vs everyone's shifts. Shifts carry pay data. Without the All Shifts sub-permission you only ever see and change your own shifts — a colleague's shift answers exactly the same as a shift that doesn't exist. With it, the whole organization is visible, including pay rates and the audit log.

Key Concepts

Finalization is a lock

A finalized shift is payroll — it refuses every change. The single exception: passing finalized: false on its own unlocks it again. Deleting a finalized shift also requires unlocking it first. Finalizing needs the All Shifts sub-permission and a shift that has actually ended.

How pay is calculated

Every shift's pay is hours × the shift type's rate multiplier × the hourly rate snapshotted on the shift when it was created. Changing a member's rate later doesn't rewrite old shifts — admins can override the rate on an individual shift instead. A shift that is still running has no salary yet.

One running shift at a time

Clocking in is refused while you already have a running shift, and agents can only clock into the shift types they've been granted. Admins recording a shift for someone else aren't limited by the type grants.

manage_shift

Clocks in and out, records a shift for any agent, corrects times, comments, pay rate and finalization, or deletes a shift.

Parameters

Parameter	Type	Required	Description
`action`	string	Yes	`"start"`, `"end"`, `"create"`, `"update"`, or `"delete"`.
`id`	string	Conditional	The shift to act on. Required for `update` and `delete`; optional for `end`.
`shiftTypeId`	string	Conditional	Required for `start` and `create`. Find IDs with `list_records` (table: `shift_types`).
`userId`	string	Conditional	`create` only — the agent the shift is for.
`startTime`	string	Conditional	ISO 8601. Required for `create`; changes the start on `update`.
`endTime`	string	No	ISO 8601. Optional on `create` (omit to leave the shift running); sets the end on `update`.
`comments`	string or null	No	A note on the shift. Pass `null` to clear it.
`payRate`	number	No	Hourly rate for this one shift — needs `All Shifts`. New shifts default to the member's rate.
`finalized`	boolean	No	Lock (`true`) or unlock (`false`) the shift for payroll — needs `All Shifts`.

How It Works

Clocking in — action: "start" opens a running shift for you, right now, with the shift type you name. Your current hourly rate is snapshotted onto it.

Clocking out — action: "end" closes your running shift. Admins can pass an id to end someone else's running shift.

Recording a shift — action: "create" writes a complete shift for any agent (needs All Shifts), for payroll backfills and corrections. It's marked as manually created in the audit log.

Correcting a shift — action: "update" changes only the fields you pass. Time and pay-rate corrections flag the shift as edited, which shows as a warning marker in the dashboard. A shift can be at most 31 days long.

Deleting — action: "delete" is permanent and removes the shift's audit log with it. Finalized shifts must be unlocked first.

Everything is audited. Every change writes the same shift log the dashboard shows — who changed what, old and new values — attributed to the signed-in user and marked as coming from Copilot/MCP.

Copilot asks first. In the dashboard Copilot, manage_shift always shows a Confirm button before it runs — it touches payroll data, so it never acts unprompted.

get_shift_report

Aggregates every shift in a date range into payroll and staffing numbers — the same figures as the dashboard's Reports page, without paging through raw shifts.

Parameters

Parameter	Type	Required	Description
`startDate`	string	Yes	ISO date — include shifts starting at or after this moment.
`endDate`	string	No	ISO date — include shifts starting up to this moment. Defaults to now.
`shiftTypeIds`	string array	No	Restrict the report to these shift types.
`userId`	string	No	Restrict the report to one agent.
`includeDaily`	boolean	No	Also return a per-day breakdown.

What It Returns

Per agent: shift count, total hours, average hours per shift, total pay, plus how many shifts are still running, manually edited, or finalized.
Totals: agents, shifts, hours and pay across the whole range.
Per shift type: shifts, hours and pay for each type.
Per day (with includeDaily): summed man-hours next to covered hours — overlapping shifts merged, so you can see whether someone was on duty, not just how much total time was logged. Days are split at UTC midnight.

Shifts that are still running are counted separately and contribute no hours or pay. Pay amounts are plain numbers — the dashboard renders them with a dollar sign.

Example Prompts

"Clock me in for chat duty."
"End my shift."
"I forgot to clock out yesterday — set my shift's end to 6 PM."
"Record an 8-hour shift for Anna last Tuesday."
"Who is clocked in right now?"
"How many hours did each agent work last month, and what do we owe them?"
"Show me the shifts that were manually edited this month."
"Finalize this shift for payroll."
"What was our staffing coverage last week, day by day?"

Common Workflow Patterns

Month-End Payroll

Get the numbers → get_shift_report for the month
Spot what's still open or unfinalized → list_records with table: "shifts", finalized: false
Fix and lock → manage_shift to correct times, then finalized: true

Example prompt: "Run July's shift report, show me any unfinalized shifts, and finalize the ones that look complete."

Fix a Forgotten Clock-Out

Find the running shift → list_records with table: "shifts", running: true
Close it at the right time → manage_shift with endTime

Example prompt: "Find my running shift and end it at yesterday 6 PM."

Staffing Review

Pull the daily breakdown → get_shift_report with includeDaily: true
Compare man-hours to covered hours — a big gap means overlapping shifts; low covered hours mean gaps in coverage

Example prompt: "Show me last week's coverage day by day — were there hours when nobody was on duty?"

Browsing raw shifts is covered by Data Access Tools — filter by agent, shift type, running, finalized or edited state and date range; fetching a single shift also returns its audit log for All Shifts holders. The dashboard side of this feature is described in Shifts.